Extension Access
This page gives who can call an extension, what CALM Hub tells the extension about the caller, and what CALM Hub trusts. For the settings, see Extensions.
Who can call a route
Each route in the manifest has a scope. CALM Hub checks it on each call, from the UI, the CLI,
MCP or any other client, with the same rules as for its own resources (see
CALM Hub Entitlements).
| Scope | The caller must | Path |
|---|---|---|
authenticated | Be signed in | Any |
read | Read the namespace and each of its parent namespaces | Has {namespace} |
write | Write the namespace or one of its parent namespaces | Has {namespace} |
admin | Administer the namespace or one of its parent namespaces | Has {namespace} |
domain_read, domain_write, domain_admin | Have that permission on the domain | Has {domain} |
global_admin | Be a global admin | Any |
- CALM Hub takes the namespace and the domain only from the path, never from the query or the body.
- A signed-out caller gets
401. A signed-in caller without the scope gets403. CALM Hub does not call the backend. - On a read-only Hub, only
GETandreadOnlyroutes run. Any other call to a declared route gets405. APOST,PUT,PATCHorDELETEwith%2F,%2E,%5C,%25,%40,..,\,//,@,;or an encoded look-alike of/,\,.,%,@or;in the path also gets405, not400. - CALM Hub refuses an encoded slash (
%2F, also double-encoded) in a route path with400, and does not call the backend. It also refuses an encoded look-alike of/,\,.,%,@or;, such as%EF%BC%8F(U+FF0F) or%E2%80%A5(U+2025), and each code point whose NFKC form contains/or\, such as%E2%84%80(U+2100,a/c). A backend that normalises Unicode (NFKC) before it routes can read these as a slash or as... - CALM Hub refuses a matrix parameter (
;name=value) in a route path with400, and does not drop it. - CALM Hub gives
415to aPOSTwith noapplication/jsonor other+jsonContent-Type, also when it has no body, and to a body of another type for the other methods. It does this before it signs the assertion. Thus a cross-site form or fetch cannot call a route as the user. An MCP tool call does not get this check, because CALM Hub sends JSON for it. But a tool call needs theMcp-Session-Idof an initialised session, which a cross-site page cannot read. This is not true whenquarkus.mcp.server.http.streamable.auto-init=true, or in dev mode, wherequarkus.mcp.server.dev-mode.dummy-initistrueby default: then a call with no session runs too. GET /api/calm/extensionsand the blocks schema also need a signed-in user.GET /api/calm/auth/jwksis public.
Public read
With calm.auth.allow-public-read=true, a signed-out visitor still gets 401 on each extension
route, also on a read or authenticated route. Public read means that each signed-in user can
read every namespace. CALM Hub's own resources work the same way.
Authentication off
With calm.auth.enabled=false, every caller is one shared principal and a global admin. Thus CALM
Hub does not start with an enabled extension that has routes, unless
calm.extensions.allow-without-auth=true. Use that setting only for local development.
The identity assertion
CALM Hub never sends the caller's token or cookies to the extension. For each call, it sends a JWT
that it signs, in the X-Calm-Hub-Identity header. The public keys are at
GET /api/calm/auth/jwks.
| Claim | Value |
|---|---|
iss | The CALM Hub base URL (calm.hub.base-url) |
aud | The extension id |
sub | The user. When auth is none, one shared principal |
auth | none, oidc or proxy |
iat, exp | Issue and expiry time. The lifetime is calm.extensions.identity.ttl-seconds, by default 60 seconds |
jti | A unique id for this call. The audit log records it for a route that is not readOnly. Hub does not audit readOnly routes |
htm, htp | The method, and the path and query relative to the backend URL. CALM Hub sorts the query by name |
hubApi, route, scope | The manifest hubApi, the route id, and the route scope |
ns | The namespace that CALM Hub checked. Only for a read, write or admin route |
dom | The domain that CALM Hub checked. Only for a domain_read, domain_write or domain_admin route |
bdh | The base64url SHA-256 of the request body. Only when there is a body |
Verify it
Verify each request with the JWKS only:
- the header
typiscalm-ext+jwt, andalgisRS256orES256and equals thealgof the key with thatkid. Load the JWKS again for an unknownkid - the signature is valid
issis the CALM Hub base URL,audis your extension id,expis not past, andiatis not in the futurehtmis the request method, andhtpis the path and query that you received, relative to the backend URL. For example, with the backend URLhttps://svc.internal/base, a request for/base/screenhas thehtp/screenbdhis the SHA-256 of the body that you received, and is absent when there is no body- each
jtiis used one time
identity.mjs
does these checks with no dependencies. The tutorial
gives the reason for each check.
What Hub checks
For a read, write or admin route, CALM Hub checked the route scope for ns, and nothing
more. For a domain_* route, it checked the scope for dom. For another scope, CALM Hub did not
check a namespace or a domain, and does not send ns or dom: do not trust a namespace or a
domain from the path. It does not check the query, the body, or the UI context. If your extension
reads data with a service account, return only what sub may see in ns.
With calm.auth.allow-public-read=true, each signed-in user can read every namespace. Thus on a
read route, ns does not mean that sub has a grant on the namespace.
Write the routes
- A
GETroute must change nothing, also when it is notreadOnly. UsePOST,PUT,PATCHorDELETEfor a change. TheContent-Typerule does not apply toGET, so a cross-site link can send aGETas the user, for example through a front proxy with a session cookie. - Route strictly, on the exact path that you received. Do not ignore a trailing slash or the case of
a literal, and do not decode
%2Fbefore you route. Otherwise your backend can run a route other than the one that CALM Hub checked the scope for. Therouteclaim names the route that CALM Hub matched. - CALM Hub sends
If-MatchandIf-None-Match, and returnsETag, so a conditional write works. It does not returnLocation, because that would name your private backend URL. Return the identifier in the body.
When the extension calls CALM Hub
CALM Hub refuses its own assertion as a credential. An extension that calls CALM Hub uses its own service account, with the fewest grants that it needs.
Trust model
Extension manifests are trusted operator configuration, as application.properties is. CALM Hub
reads them one time at start-up, and nothing changes them at runtime. No API adds an extension.
CALM Hub checks the manifests for usual mistakes at start-up, but it does not defend against a bad manifest: for example a schema that is made to be slow, or a backend URL to a bad host. To fix such a problem, correct the manifest.
CALM Hub bounds only the cost that a caller controls:
| Limit | Default |
|---|---|
| Request body | 1 MiB, then 413 |
| Reply body | 1 MiB, then 502 |
| Connect and request timeouts | 5 and 10 seconds, then 504 |
| Calls at the same time to one extension | 32, then 503 |
| MCP arguments | 1 MiB of JSON, and patterns that match in linear time |
The MCP extension tools page gives the MCP rules.
In proxy-auth mode, any client that reaches CALM Hub directly can set Remote-User. Make CALM Hub
listen only on loopback or behind the proxy.