Skip to main content
Tools

CALM Hub

CALM Hub is the central artifact store and API server for the CALM ecosystem. It provides a versioned, queryable registry for CALM architecture models, patterns, compliance controls, standards, and related assets — enabling teams to publish, discover, and share architecture knowledge across an organisation.

CALM Hub exposes a RESTful HTTP API that powers both the CALM Hub UI visual interface and programmatic integrations such as the MCP endpoint.


Features​

FeatureDescription
Namespace-scoped artefact storeArchitectures, patterns, flows, standards, interfaces, ADRs, and controls organised under user-defined namespaces
Versioned resourcesEvery artefact carries an incrementing version history; compare any two versions via the timeline UI
Multiple storage backendsMongoDB (production), NitriteDB embedded (standalone/development), or a baked-in read-only database (static distribution)
ConventionsVersioned tool settings, such as a C4 mapping, checked against the schema of their type. A namespace names a default, and child namespaces inherit it. See Conventions
Read-only modeServes a pre-seeded, immutable CALM dataset with no external database dependency; mutating requests are rejected with HTTP 405
Scope-based access controlFine-grained OAuth2 scopes (e.g. architectures:read, architectures:all, namespace:admin) enforced per endpoint
OpenAPI / Swagger UIAuto-generated API documentation always available at /q/swagger-ui
MCP serverExperimental Model Context Protocol endpoint at /mcp for AI-agent integrations
Multi-arch container imagesPre-built linux/amd64 and linux/arm64 images for all four variants

Supported Runtimes​

CALM Hub is published as four container image variants, each combining a JVM runtime (JVM vs. GraalVM native binary) with a storage backend (MongoDB vs. NitriteDB read-only).

JVM vs. Native​

JVMNative
Startup time~3 – 5 s< 0.5 s
Memory footprint~200 MB heap~50 – 80 MB RSS
Build time~30 s5 – 15 min (GraalVM Mandrel)
DebuggabilityFull Java toolingLimited (no JVM agents)
PlatformAny JDK 21 hostCompiled per arch (amd64, arm64)

Storage Modes​

ModeBackendExternal dependencyMutating writes
MongoDB (default)External MongoDB 5.0+Yes — QUARKUS_MONGODB_CONNECTION_STRING✅ Yes
Standalone (NitriteDB)Embedded file-based DBNo✅ Yes (file persisted at CALM_STANDALONE_DATA_DIRECTORY)
Read-onlyPre-seeded NitriteDBNo❌ No — HTTP 405 for POST/PUT/DELETE/PATCH, except on a readOnly extension route
GitHub (calm.database.mode=github)Cloned GitHub repositoriesYes — GitHub API❌ No — read-only from Git

In GitHub mode, CALM Hub classifies .json and .md files in each configured repository from content signals (moments or $schema) and from parent directory names (architectures/, patterns/, standards/ or standard-nodes/, flows/, interfaces/, controls/, adrs/, timelines/, decorators/). See GitHub Storage Mode for configuration, sync, versions and access control.

The Four Image Variants​

TagRuntimeStorageUse case
latestJVMMongoDBStandard production deployment
latest-nativeGraalVM nativeMongoDBLow-latency / resource-constrained production
latest-read-only-staticJVMRead-only NitriteDBFast demo/CI; ships the full CALM schema set
latest-read-only-nativeGraalVM nativeRead-only NitriteDBMinimal footprint, self-contained, fast startup

Read-Only Mode​

Overview​

Read-only mode lets you run CALM Hub as a completely self-contained, stateless container — no database to provision, no credentials to manage. The CALM schema data is baked directly into the image.

When CALM_READONLY=true is set:

  1. ReadOnlyRequestFilter intercepts every inbound request before routing. Any HTTP method that mutates state (POST, PUT, DELETE, PATCH) is rejected immediately with HTTP 405 Method Not Allowed and a Allow: GET, HEAD, OPTIONS response header. The extension proxy, form and chat paths are the exception: the filter lets them through, and CALM Hub then allows a method other than GET only on a route that the manifest marks readOnly (see Calling an extension).
  2. NitriteDB is opened with .readOnly(true).autoCommit(false), preventing any accidental writes to the embedded database file.

The MCP endpoint (/mcp) does not go through that filter. Each MCP tool that changes data returns a tool error on a read-only Hub. Hub does this check before the permission check, so a caller without the scope also gets the read-only error. A tool that needs only a read scope still runs, and so do the extension commands that a read-only Hub can run. tools/list does not show the tools that change data, and a read-only Hub registers no extension command for a write route. This applies to all users of a read-only Hub. It is not a filter by user or scope, which Hub does not do (see ADR 0014).

# Run the read-only JVM image — no external dependencies needed
docker run --rm -p 8080:8080 finos/calm-hub:latest-read-only-static

# Test that mutations are blocked
curl -s -o /dev/null -w "%{http_code}" \
-X POST http://localhost:8080/calm/namespaces \
-H 'Content-Type: application/json' -d '{"name":"test"}'
# → 405

The read-only images serve the $id of each name-based document under https://hub.calm.finos.org, because the seeded documents belong to that Hub. To use a different base, add -e CALM_HUB_BASE_URL=<url> to docker run.

How the Read-Only Data Image Layer Works​

The read-only images use a two-stage Docker build to pre-seed the embedded NitriteDB with the full CALM schema dataset at build time:

Stage 1 — seed (JVM, writable)
FROM ubi8/openjdk-21 (static) or ubi9/openjdk-21 (native)
COPY quarkus-app/ + released meta-schemas (npm copy) + controls/ + interfaces/
RUN boot Quarkus in standalone (writable) mode
→ init script POSTs all schemas and controls into NitriteDB
→ graceful SIGTERM flushes and commits the database
→ calmSchemas.db is now ~290–450 KB of real data

Stage 2 — runtime (minimal base image)
COPY --from=seed /data/calmSchemas.db ← baked as an image layer
chmod 0444 ← immutable at filesystem level
ENV CALM_READONLY=true
ENV QUARKUS_PROFILE=standalone
ENV CALM_HUB_BASE_URL=https://hub.calm.finos.org

The resulting image carries the seeded database as a read-only filesystem layer. At runtime the process opens the file in read-only mode, serves the pre-loaded content, and rejects all write requests.

Why the native read-only image uses a JVM for seeding: GraalVM native binaries compiled from NitriteDB cannot reliably write (commit) the H2 MVStore backing file due to Java serialisation requirements that are not fully supported in native mode. The JVM seed stage produces a database file that the native binary can then read correctly (via registered serialisation metadata). The native runtime is only ever used for reads in the read-only image.


UI Customization​

An operator can brand CALM Hub UI, choose what its menus show and add deployment-specific information, with configuration only. Each calm.ui.* property can also be set as an environment variable. If you set none of them, CALM Hub UI uses the CALM name, logo and colours.

ItemWhere it showsProperties
Organisation and application namesHeader, home page, browser tab, search boxescalm.ui.branding.organisation-name, calm.ui.branding.application-name
LogoHeader and home page, in place of the CALM logocalm.ui.branding.logo.light, calm.ui.branding.logo.dark
Brand colourLinks, active tabs and rows, filled badges, focus ringscalm.ui.branding.colour, calm.ui.branding.colour-dark
Menu layoutmenu (default): the hamburger menu. sidebar: a collapsible menu at the left of each page on a wide screen. The browser remembers the collapse choicecalm.ui.navigation.layout
Built-in sectionsExplore sidebar, home pagecalm.ui.navigation.show-namespaces, calm.ui.navigation.show-control-domains
Extensions headingMenu and home pagecalm.ui.navigation.extensions-heading
Start pageThe page that opens at the root URLcalm.ui.navigation.start-page
Environment pillHeader, on every pagecalm.ui.environment.name, calm.ui.environment.colour
Signed-in identityMenucalm.ui.identity.enabled, calm.ui.identity.show-roles
Values and linksMenucalm.ui.items[n].label, .value, .url
CALM_UI_BRANDING_ORGANISATION_NAME="Northstar Financial"
CALM_UI_BRANDING_APPLICATION_NAME="Architecture Hub"
CALM_UI_BRANDING_COLOUR=#0f766e # #rrggbb; COLOUR_DARK sets another colour for the dark theme
CALM_UI_BRANDING_LOGO_LIGHT=/config/branding/logo.svg
CALM_UI_BRANDING_LOGO_DARK=/config/branding/logo-dark.svg
CALM_UI_NAVIGATION_LAYOUT=sidebar # menu | sidebar
CALM_UI_NAVIGATION_SHOW_CONTROL_DOMAINS=false
CALM_UI_NAVIGATION_START_PAGE=/extensions/release-tracker/releases
  • Names can have at most 64 characters, and the extensions heading at most 40.
  • CALM Hub reads each logo from a local file one time, at start up. It does not get images from other servers. A logo is a PNG, JPEG, WebP or SVG file of at most 256 KiB. The file extension must agree with the content. A PNG, JPEG or WebP image can be at most 2048 pixels on each side. An SVG must not have scripts, event attributes, or links to other files or pages. A dark logo needs a light logo. Without a dark logo, the dark theme shows the light logo on a white plate. If the browser cannot show a logo, the UI shows the names, or the CALM logo if you set no name.
  • The UI makes the brand colour darker or lighter where it must, so that text in it has a contrast of 4.5:1 in each theme. Without colour-dark, the dark theme uses colour.
  • To hide a section changes only the menus and the home page. It does not change access: a link to a hidden namespace or control domain still opens for a user who can read it.
  • The extensions heading is "Extensions". If you hide namespaces and control domains, the menu and home page show no heading unless you set one.
  • The start page is /, /search, /namespace/<namespace>, /domain/<domain>, /extensions/<extension-id>/<screen-id> or /chat. The UI opens it only when a user opens the root URL. If the extension screen or chat is not available, or the UI cannot get its settings or the extension list within 3 seconds, the UI shows the home page.
  • The UI gets the logos from GET /api/calm/ui/branding/logo/{light|dark}, which requires authentication.

To white-label CALM Hub, set a name, a logo and a brand colour. They replace the CALM name, logo and colours in the header, the home page, the browser tab title and the search boxes. If you set no name, the tab title stays "CALM", the search boxes name CALM Hub, and the CALM logo shows when the browser cannot show your logo. No setting changes these parts, which still show CALM:

  • The browser tab icon is always the CALM icon.
  • The browser tab title is "CALM" until the UI gets its settings, which requires authentication.
  • The UI shows the CALM name and logo if it cannot get its settings.
  • Some UI messages name CALM Hub, for example on the chat page, in extension forms and screens, and on the Decorators tab. The CALM diagram lens keeps its name.
CALM_UI_ENVIRONMENT_NAME=UAT
CALM_UI_ENVIRONMENT_COLOUR=warning # info | success | warning | error | neutral | #rrggbb
CALM_UI_IDENTITY_ENABLED=true # shows the principal name that CALM Hub sees
CALM_UI_ITEMS_0__LABEL=Support
CALM_UI_ITEMS_0__URL=https://support.example.com
CALM_UI_ITEMS_1__LABEL=Build
CALM_UI_ITEMS_1__VALUE=2026.10.1
  • Each item needs a label and a value, a url, or both. With both, the value is the link text.
  • Use a short environment name, for example DEV, QA or PROD. The header cuts a long name to fit, and cuts it most on a narrow screen. Tap or click the pill to see the full name.
  • CALM Hub does not start if a name, colour, logo, layout, start page or URL is not valid. URLs must be absolute http or https URLs.
  • Identity and roles are off by default. Turn on show-roles only if your role names are safe to show to users.
  • The UI gets these values from GET /api/calm/ui/config, which requires authentication.

Extensions​

An extension adds features to CALM Hub without a fork. It is an HTTP service that CALM Hub calls. The operator installs it with a manifest. CALM Hub reads the manifests at start up. No API adds an extension.

The Hub UI shows the contributions of an extension, the CLI runs its commands (see Running extension commands), and MCP makes a tool for each command (see Extension tools).

PageRead it to
ExtensionsFind an extension and install it
Build and install an extensionFollow a tutorial from the manifest to the UI, CLI and MCP
Extension pointsFind the fields, the context and the limits of each extension point and of commands
Extension blocksWrite the JSON that the UI draws
Extension navigationLink to an architecture, a node or an extension screen, and return to the same place
Decorator viewsDraw decorators on the diagram, with no backend
The C4 extensionSee a diagram lens with its own notation, run as a sidecar
The ea-layers extensionSee a smaller diagram lens, in the ArchiMate® notation
Extension accessLearn the scopes, the identity assertion and the trust model

Put one folder for each extension in calm.extensions.dir, with an extension.json in it. The folder name must equal the manifest id. Hub skips hidden folders and warns about folders without a manifest. A per-id setting for an unknown extension id gives a warning at start up, as a property or as an environment variable.

/etc/calm-hub/extensions/
└── team-services/
└── extension.json
SettingDefaultPurpose
calm.extensions.dirnot setThe folder of manifests. When it is not set, CALM Hub loads only the built-in decorator views
calm.extensions."<id>".enabledtrueSet false to turn off an extension
calm.extensions."<id>".order0Lower values come first in the list. Equal values sort by id
calm.extensions."<id>".backend-urlnot setThe base URL of the extension service. Required for an enabled extension with routes
calm.extensions."<id>".allow-httpfalseAllows a plain http backend that is not on loopback, such as a cluster-internal host. Otherwise the backend must use https, or http on localhost, 127.x.x.x or [::1]
calm.extensions."<id>".send-identitytruefalse sends no identity assertion to the extension, for an open service that answers any caller. CALM Hub then needs no identity keys for it. Allowed only when every route of the extension is a GET or readOnly route. CALM Hub still checks the route scope for the user
calm.extensions."<id>".connect-timeout-secondscalm.extensions.http.connect-timeout-seconds (5)The connect timeout for each call. A value below 1 stops start-up
calm.extensions."<id>".request-timeout-secondscalm.extensions.http.request-timeout-seconds (10)The limit for the whole call. A slow backend gets 504. A value below 1 stops start-up
calm.extensions."<id>".max-request-bytescalm.extensions.http.max-request-bytes (1048576)A larger request body gets 413. A value below 1 stops start-up
calm.extensions."<id>".max-response-bytescalm.extensions.http.max-response-bytes (1048576)A larger reply gets 502. A larger streamed reply ends with an error event. A value below 1 stops start-up
calm.extensions."<id>".max-concurrent-callscalm.extensions.http.max-concurrent-calls (32)The calls to the extension at the same time. One more call gets 503 with Retry-After: 1, so that a slow backend cannot hold every worker thread. A value below 1 stops start-up
calm.extensions."<id>".max-concurrent-streamscalm.extensions.http.max-concurrent-streams (8)The streamed replies of the proxy and MCP from the extension at the same time. Chat replies have their own pool. Each stream holds a worker thread until it ends. One more stream gets 503 with Retry-After: 1. A value below 1 stops start-up
calm.extensions."<id>".max-concurrent-chat-streamscalm.extensions.http.max-concurrent-chat-streams (8)The chat replies from the extension at the same time, so that proxy streams cannot use up the chat. One more chat reply gets 503 with Retry-After: 1. A value below 1 stops start-up
calm.extensions."<id>".max-concurrent-streams-per-usercalm.extensions.http.max-concurrent-streams-per-user (2)The streamed replies of one user from the extension at the same time, in each of the two pools, so that one user cannot hold every slot. With auth off, every caller is the one no-auth user, so all callers share this limit. One more stream gets 503 with Retry-After: 1. A value below 1, or above max-concurrent-streams or max-concurrent-chat-streams, stops start-up
calm.extensions."<id>".stream-idle-timeout-secondscalm.extensions.http.stream-idle-timeout-seconds (30)The longest wait for the next part of a streamed reply. A value below 1 stops start-up
calm.extensions."<id>".max-stream-secondscalm.extensions.http.max-stream-seconds (300)The longest time, from when the backend reply arrives, that CALM Hub keeps the backend connection and the stream slot of a streamed reply. Then CALM Hub closes both, also for a reply that it never sent on. A stream that CALM Hub is sending ends with an error event. A value below 1 stops start-up
calm.extensions.chat-providernot setThe chat that the Hub UI shows: <extension-id>, or <extension-id>/<chat-entry-id> for an extension with more than one chat entry. With no setting, there is no chat
calm.extensions.identity.private-key-locationnot setThe PKCS#8 PEM key that signs the identity assertion: RSA (2048 bits or more, RS256) or P-256 (ES256). Required when an enabled extension that sends identity assertions has routes. A shared secret (HS256) is refused
calm.extensions.identity.public-key-locationsnot setComma-separated PEM public keys for the JWKS. The first is the public key of the signing key. Required when private-key-location is set, and not allowed without it
calm.extensions.identity.ttl-seconds60The lifetime of an assertion, at most 300
calm.extensions.allow-without-authfalseAllows enabled extensions with routes when calm.auth.enabled=false. Only for local development: every caller is then a global admin
CALM_EXTENSIONS_DIR=/etc/calm-hub/extensions
CALM_EXTENSIONS__TEAM_SERVICES__BACKEND_URL=https://team-services.internal
CALM_EXTENSIONS__TEAM_SERVICES__ORDER=10

The manifest declares:

  • id, version, hubApi (now 0), name, and optional description, provider and logo (see Extension logos).
  • routes: every call that the extension can receive, each with an id, method, path, scope, and optional readOnly and hubData (the data that CALM Hub reads for the user and sends as the body, see Let CALM Hub send the data). A read, write or admin scope needs a {namespace} in the path. A domain_* scope needs a {domain}. A path parameter cannot contain a slash, so a route for a CALM Hub resource uses {resourceType}/{resourceId}, not {resource}. When two routes with the same method match a path, the route with more literal segments wins. CALM Hub does not start if two such routes have the same number, for example GET /{namespace}/report and GET /public/{id}.
  • commands: CLI and MCP commands, keyed by name. Each names a route by id.
  • contributes: the UI extension points screen, designer-tab, landing-card, detail-panel, action, form, search-provider and chat, which name a route by id, decorator-views, which CALM Hub draws from decorators with no route, and diagram-lens, a picture of an architecture that CALM Hub draws from a graph reply and a notation. A decorator view id and a lens id must each be unique in all enabled extensions.

The JSON Schema is META-INF/calm-extensions/schema/0/extension.schema.json in the CALM Hub jar. Unknown fields are errors. See the example manifest.

  • CALM Hub does not start if a manifest or a setting is not valid. The error names the file or the setting.
  • GET /api/calm/extensions lists the enabled extensions, for any signed-in user. It never shows the backend URL. On a read-only CALM Hub it leaves out write routes that are not readOnly, and the commands and contributions that use them.

Extension logos​

An extension can show a logo beside its name: in the side menu, on its home page card, above the heading of its screens, in the inspector beside the diagram, and in search and chat. The name always shows as text. Without a logo, while the logo loads, or when the logo does not load, CALM Hub shows the generated marker of the extension.

"logo": { "light": "logo.svg", "dark": "logo-dark.svg" }
FieldRequiredRule
lightYesThe logo for the light theme. In the dark theme, CALM Hub shows it on a light plate when there is no dark file
darkNoThe logo for the dark theme

Each value is a file name in the extension folder, next to extension.json: lowercase letters, digits, ., _ and -, with no path. CALM Hub reads each file at start up and does not start if a file:

  • is not a PNG, JPEG, WebP or SVG file, or does not hold the type of its extension (.png, .jpg, .jpeg, .webp, .svg)
  • is larger than 256 KiB, or is a PNG, JPEG or WebP image with a side larger than 2048 pixels
  • is an SVG file with a DOCTYPE, an entity, a processing instruction, a script, foreignObject or HTML element, an on* attribute, a link or CSS url() that is not a #fragment, an xml:base attribute, an animated link or xml:base, a CSS @import, image-set(), src() or escape

Use a square image that reads at 16 pixels. CALM Hub never fetches a logo from a URL.

The UI reads a logo from GET /api/calm/extensions/<id>/logo/<light|dark>, which needs a signed-in user. The reply has the exact image type, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox, an ETag and Cache-Control: private, no-cache. The UI shows the image only in an img element, from a data: URL. A browser runs no script and loads no other resource in an SVG image. A data: URL has an opaque origin, so an SVG file that is opened as a page cannot read CALM Hub data. If you set a Content-Security-Policy for CALM Hub UI, allow img-src data:. Without it, the UI shows the markers.

Calling an extension​

CALM Hub proxies each declared route at /api/calm/extensions/<id>/api/<route path>. A route with the path / is at /api/calm/extensions/<id>/api/, with the trailing slash. Without it, CALM Hub gives 404, also on a CALM Hub that is not read-only. For each call, CALM Hub:

  • refuses an encoded slash (%2F, in any case, or double-encoded) with 400, and does not call the backend. A backend that decodes %2F before routing would see a path other than the one CALM Hub checked. For the same reason, it refuses an encoded look-alike of / or \ (U+2044, U+2215, U+2216, U+29F5 and U+29F8), each code point whose NFKC form contains / or \ (U+2100, U+2101, U+2105, U+2106, U+FE68, U+FF0F and U+FF3C), and each code point whose NFKC form is only ., %, @ or ; (U+037E, U+2024 to U+2026, U+FE14, U+FE19, U+FE30, U+FE52, U+FE54, U+FE6A, U+FE6B, U+FF05, U+FF0E, U+FF1B and U+FF20). For example, NFKC makes U+2025 .. and U+2100 a/c
  • refuses a matrix parameter (;name=value) with 400, and does not drop it
  • decodes percent-encoded unreserved characters and uppercases other escapes before matching and forwarding. Percent-encoding in a matched literal segment gets 400
  • on a read-only CALM Hub, gives 405, not 400, to a POST, PUT, PATCH or DELETE with %2F, %2E, %5C, %25, %40, .., \, //, @, ; or an encoded look-alike of /, \, ., %, @ or ; in the path. CALM Hub refuses such a path before it finds the route
  • gives 415, before it signs the assertion, to a POST that has no application/json or other +json Content-Type, also when it has no body. A PUT, PATCH or DELETE gets 415 only for a body of another type. Thus a cross-site form or fetch cannot call a route as the user. Those three methods need a CORS preflight, which CALM Hub does not allow cross-site
  • matches the path against the declared routes only, and refuses .., %2e, \, //, @ and their encoded forms
  • checks the route scope with the same rules as the rest of CALM Hub. The namespace or domain comes only from the path
  • on a read-only CALM Hub, allows a method other than GET only on a readOnly route. Its 405, and the 405 for a method that the route does not declare, has an Allow header. It lists only the methods that CALM Hub accepts on that path now, and HEAD with GET, because CALM Hub answers HEAD with the GET route
  • sends only Content-Type, Accept, Accept-Language, If-Match, If-None-Match and its own X-Calm-Hub-Identity assertion. A header value with a line break gets 400. The caller's token and cookies never go to the extension
  • returns only Content-Type (application/json, text/plain or text/event-stream, and for a 4xx reply also application/problem+json and other +json types), Cache-Control, ETag, Retry-After and Vary, and adds Content-Security-Policy: sandbox; default-src 'none'. It returns them only on a reply that it passes on: a backend 503 becomes 502 without Retry-After. It passes on a 304. It does not follow redirects, and does not return Location, because that would name the private backend
  • marks each reply Cache-Control: private, because the reply is for one user. It removes public, and keeps the other directives of the backend. Its own error replies are also private
  • returns 502 or 504, with a generic body, when the backend fails, is slow, replies with 5xx, 401, 407 or a 3xx other than 304, or sends another content type
  • audits every non-readOnly call, including GET, and every chat message of a signed-in user, as entity type EXTENSION with the extension id, route id and assertion jti. The entry has the namespace only for a read, write or admin route, or for a chat message that shares a resource (then also its type, id and version), and the domain only for a domain_* route. Outcomes are SUCCESS, DENIED, FAILURE (a refusal after the scope check, such as 400, 413, 415 or 503, or a returned client error), or UNKNOWN (an upstream failure or unusable reply; the backend may have completed the call). The entry has the jti only when CALM Hub sent the call, and the source IP (the X-Forwarded-For header of the REST or MCP request) when calm.audit.capture-source-ip=true

A 200 text/event-stream reply streams to a caller whose Accept names text/event-stream: CALM Hub sends each event on when it arrives, with only its event and data lines. Other replies are buffered. The stream limits are max-concurrent-streams (max-concurrent-chat-streams for the chat), max-concurrent-streams-per-user, stream-idle-timeout-seconds, max-stream-seconds (from when the reply arrives) and max-response-bytes. At a limit, CALM Hub ends the stream with an error event. When the caller closes the stream, CALM Hub closes the connection to the backend. If the caller left before the backend replied, CALM Hub closes it when the reply arrives. CALM Hub has no time limit for a write to the caller: a caller that stops reading holds a worker thread of CALM Hub until its connection fails, also after the stream limits have freed the slot and closed the backend connection. A HEAD request gets the headers of the stream, and CALM Hub then closes the stream at once.

The route of a chat entry answers only at /api/calm/extensions/<id>/chat/<entry>. The proxy and MCP refuse it with 404.

A form route is not at this path: it gives 404 there. Hub calls it only from POST /api/calm/extensions/<id>/forms/<form>, after it checks the target and the input. That endpoint uses the same scope, read-only, limit and audit rules (see form).

CALM Hub does not audit an extension call that it refuses before the scope check: a 401 for a caller who is not signed in, a 404, a 400 for the path, the namespace or the domain, or a 405.

CALM Hub does not start with an enabled extension that has routes when calm.auth.enabled=false, because every caller is then a global admin. Set calm.extensions.allow-without-auth=true only for local development.

Identity keys​

CALM Hub signs a short-lived JWT for each call to an extension, unless the extension has send-identity=false. It publishes the public keys at GET /api/calm/auth/jwks. This endpoint is public. Set calm.hub.base-url to the URL that the backends expect in iss. When it is not set, iss is http://localhost:8080, and CALM Hub gives a warning at start up if an enabled extension that sends identity assertions has routes. Create a key pair:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out hub-private.pem
openssl pkey -in hub-private.pem -pubout -out hub-public.pem

To change the key with no outage, put the new key first and keep the old public key in the list for at least ttl-seconds:

CALM_EXTENSIONS_IDENTITY_PRIVATE_KEY_LOCATION=/keys/new-private.pem
CALM_EXTENSIONS_IDENTITY_PUBLIC_KEY_LOCATIONS=/keys/new-public.pem,/keys/old-public.pem

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.

For extension authors​

Verify X-Calm-Hub-Identity on each request, and return only what the user may see. See Extension access for the claims, the checks and the trust model, and the example backend.


Docker Hub Images​

All images are published to Docker Hub at finos/calm-hub. The latest tags point to the most recent release. Each release also has its own tags, for example 0.8.0 and 0.8.0-native, which never change. The changes in each release are in the CALM Hub changelog.

docker pull finos/calm-hub:latest
docker pull finos/calm-hub:latest-native
docker pull finos/calm-hub:latest-read-only-static
docker pull finos/calm-hub:latest-read-only-native

GitHub Actions Build Status​

CI Builds​

WorkflowStatus
Integration tests & coverageBuild Calm Hub
Unit test coverageBuild Calm Hub Coverage

Docker Image Publishing​

WorkflowImage tagStatus
JVM image (MongoDB)latestDocker Publish Calm Hub
Native image (MongoDB)latest-nativeDocker Publish Calm Hub (Native)
Read-only JVM imagelatest-read-only-staticDocker Publish Calm Hub (Read-Only Static)
Read-only native imagelatest-read-only-nativeDocker Publish Calm Hub (Read-Only Native)

All docker-publish workflows include an automated smoke test that validates the image before pushing. See smoke-test.sh for the assertion script.


Quick Start​

Read-Only (no dependencies)​

docker run --rm -p 8080:8080 finos/calm-hub:latest-read-only-static
# API: http://localhost:8080/calm/namespaces
# Swagger: http://localhost:8080/q/swagger-ui

With MongoDB​

# Start MongoDB
cd calm-hub/local-dev && docker-compose up -d

# Start CALM Hub (JVM)
cd calm-hub && ../mvnw quarkus:dev

Show your decorators in Hub​

An external service can write decorators with its own service account and ship a views-only manifest. Hub draws the results; the service supplies no browser code.

  1. Give the service account write access to the target namespace. Use that account's credentials with the decorator API, not a user's token. If the decorator type is reserved, the operator must also allow this principal to write that type.
  2. Write decorators with a stable type, architecture version URLs in target, element ids in applies-to, and results in data. A known $schema is validated on write. For a reserved type, PUT the new result to the current decorator id (the id that the last write returned). Hub stores it as a new decorator and keeps the old one in the history.
  3. Put this manifest at <calm.extensions.dir>/scanner/extension.json, then restart Hub:
{
"id": "scanner",
"version": "1.0.0",
"hubApi": 0,
"name": "Security scan",
"contributes": {
"decorator-views": [{
"id": "security-scan",
"match": { "type": "security-scan" },
"label": "Security scan",
"overlay": {
"status": "/result",
"map": { "safe": "ok", "unsafe": "error" },
"default": "info"
}
}]
}
}

No routes or backend URL are needed. See Decorator views for the fields, how Hub draws a view, the legend, and the built-in control-evaluation and deployment views.

Further Reading​