rcf-lite 0.12.0 → 0.14.0

package/blueprints/security-auth-keycloak/README.md

@@ -0,0 +1,56 @@
+# Security auth Keycloak blueprint (v1.0.0)
+
+The twelfth content blueprint on the rcf-build-lite blueprint mechanism, category `security`. A Keycloak-committed sibling to `security-auth-magic-link`, `security-auth-clerk`, and `security-auth-oauth2` on the `authModel` global topic. Identity is delegated to a Keycloak realm the operator runs; the project owns the discovery client, the token verifier (JWKS or introspection per realm), the role adapter, the provider-routing seam, and the optional application session on top. Targeted at rcf-lite projects that have committed to a self-hosted Keycloak realm (or are running one already) and want the Keycloak-shaped decisions the vendor-neutral `security-auth-oauth2` sibling deliberately does not fix.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/security-auth-keycloak
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `security` category; `rcf define blueprint remove security-auth-keycloak` cleanly removes an unreferenced application.
+
+Composing with `security-auth-magic-link`, `security-auth-clerk`, `security-auth-oauth2`, or any other blueprint contributing `scope: global` on `authModel` (which includes `application-spa` and `application-api-rest`) raises a `globalAdrTopic` conflict at add time. The four documented resolutions apply (adopt the incoming, keep the existing, project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add). See `docs/topics.md` for the deliberate-conflict statement.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `security`, and the 36 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 12 REQs, 13 USs (34 ACs), 5 TACs, 6 ADRs, all schema-valid and namespaced (`security-auth-keycloak-REQ-001` prefix family; `ADR-1201-security-auth-keycloak-auth-model` suffix family) |
+| Local-container bootstrap | `assets/local-container/keycloak-bootstrap.md` | Shape a project harness follows to stand up the vendor's official image; no compose file lifted from any real deployment |
+| Realm-config record | `assets/realm-skeleton/realm-config-shape.md` | The plain data-record shape a project maintains per realm; placeholder secrets only |
+| Verifier middleware wiring | `assets/middleware/verifier-wiring.md` | HTTP-framework-agnostic Node middleware chain wiring the mechanism's five factories |
+| Provider-router seam | `assets/provider-router/router-shape.md` | The pure-function contract a project's routing decision satisfies; generic OAuth2/OIDC vocabulary; no named second issuer |
+| Mock introspection responder | `assets/mock-introspection/mock-introspection-shape.md` | RFC 7662 shape the harness stands up for the introspection-mode verify path |
+| Guide | `guide/security-auth-keycloak.md` | Operator-facing: when to use it, when not, promotion signals, cost honesty |
+| Coordination vocabulary | `docs/topics.md` | The global topic string and the shared id-band registry |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the Keycloak realm as identity source, the OIDC discovery contract, the JWKS-with-rotation-cache verification path, the RFC 7662 introspection path, the provider-routing seam, the Keycloak client-roles / realm-roles claim shape, the refresh-and-sign-out posture inherited from the realm, the session-vs-token separation, the local-first stand-up shape, the fail-safe boot postures, the runtime-verify posture with accountBound cloud smokes); the implementing agent derives the HOW-tasks (FBS) in the host project.
+
+Deliberately not contributed: the OAuth2 authorisation-code flow controller itself (a project either draws it from the sibling `security-auth-oauth2` blueprint or authors one above this blueprint's five TACs; the Keycloak-committed decisions here bind the flow controller's provider adapter to a Keycloak realm and no more); a specific HTTP framework adapter (the middleware wiring is framework-agnostic; framework adapters are a project responsibility); a specific session-record store (opaque-handle mode injects it; in-memory is the reference default; a persistence-composed project points at a table); MFA specifics (Keycloak owns MFA at the realm surface); real realm data (a placeholder `example` realm name is the shape; no lifted config); any specific second identity provider (the provider-routing seam is generic; the blueprint does not name a second issuer, per the ratified reshape ruling).
+
+## The one global decision
+
+ADR-1201-security-auth-keycloak-auth-model ships `scope: global` on topic `authModel`. This is the project's single decision on how identity is proven, where credentials live, and what the wire credential looks like. Composing with `security-auth-magic-link`, `security-auth-clerk`, `security-auth-oauth2`, `application-spa`, `application-api-rest`, or any future `security-auth-*` blueprint conflicts here by design and expects a project-level ADR resolution. The composition-precedent (SPA + REST on `errorEnvelope` and `authModel`) is the same pattern the auth-family blueprints follow.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, and the AC id band allocation (security-auth-keycloak owns US 11101-11899 with US 11101-11113 in use, ADR/TAC suffix block 1201-1299; the third blueprint to sit in the four-digit ADR/TAC suffix space after security-auth-clerk (1001-1099) and security-auth-oauth2 (1101-1199)).
+
+## Quality bar
+
+Authorisation-code + PKCE (S256) as the sole flow; JWT verification via realm JWKS with a rotation cache defended by TTL and by kid-miss single-refresh; RFC 7662 introspection as the alternate verification mode selected per realm record; provider-routing seam expressed as a project-authored pure function; role extraction from Keycloak's `client-roles` or `realm-roles` claim path per record declaration; refresh rotation honours the realm's declared model (revoke-on-reuse tightened by the realm; soft rotation permitted where the operator has declared it); sign-out invalidates the project session with realm-side end-session opt-in per record; session-vs-token separation with opaque-handle sessions (default) or stateless bearer verification (opt-in) per realm; fail-safe boot posture declared per realm (strict / deferred / standby); runtime-verify against a local Keycloak container with cloud-tenant smokes marked accountBound and skipped with a stable-coded reason when credentials are unavailable. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+Three named gaps at v1.0.0. First, AC-11112-2 (the live cloud-realm smoke against a project-owned Keycloak deployment or a managed Keycloak service) is `accountBound` and depends on operator-provided cloud-realm credentials plus a redirect URI registration at the deployment's admin console; those steps sit outside the blueprint's mechanism reach. The project's ship gate reads the honest coverage: the AC is covered by a project-authored TC whose latest outcome is `skipped` with reason `KEYCLOAK_LIVE_REALM_UNREACHABLE` when credentials are absent, and `pass` when the operator has driven the smoke. The `accountBound` skip does not fail CI and does not count as coverage passed for a project auditing its cloud-realm readiness; the ship-gate operator reads the AC and drives the smoke themselves before promoting a build past staging. The local Keycloak container path (REQ-009, US-11101 through US-11104, US-11107, US-11108, US-11110, US-11111) is NOT accountBound: the vendor's official container image runs standalone under a project's harness and the mechanism verifies against it end-to-end at every runtime-verify pass. Second, every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed application (redirect-inspection for the authorise URL shape, token-exchange-request inspection for the PKCE verifier presentation, response-cookie inspection for the session-cookie contract, `request.auth` shape inspection for the Principal reduction, mock-introspection response substitution for the opaque-token classes, JWKS mutation for the JWT refusal classes, session-record store inspection for refresh-token rotation, cookie-clear inspection for sign-out, `Location`-header inspection for realm-side sign-out redirect). A project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. Third, the flow controller itself (the state machine that mints the pending-flow record, builds the authorisation redirect, and drives the callback) is NOT contributed by this blueprint at v1.0.0: a project either composes the vendor-neutral sibling `security-auth-oauth2` (which contributes TAC-1101-security-auth-oauth2-flow-controller) and points its provider-adapter at a Keycloak realm through this blueprint's discovery client and verifier, or the project authors a project-side flow controller above this blueprint's five TACs. The two composition paths are equally valid; the blueprint documents both in the guide.
+
+## Composition intent (deliberate)
+
+- Applying this blueprint on top of `security-auth-magic-link`, `security-auth-clerk`, `security-auth-oauth2`, `application-spa`, or `application-api-rest` raises a `globalAdrTopic` conflict on `authModel`. That is intended: one project has one authentication model, and the surfacing is the mechanism's promise. Resolution paths are documented on `docs/topics.md`.
+- Sibling PRs open or recently merged at this pass: `blueprint/security-auth-oauth2` (band 10101-10899 US, 1101-1199 ADR/TAC). Zero id-band overlap.

package/blueprints/security-auth-keycloak/assets/local-container/keycloak-bootstrap.md

@@ -0,0 +1,54 @@
+# Keycloak local-container bootstrap: shape (not a compose file lift)
+
+Shape a project stands up to satisfy REQ-009's local-first posture. The container is real Keycloak on the wire; the discovery client, the JWT verifier, and the introspection client cannot tell it apart from a cloud-hosted realm for the purpose of the state machine and the verification paths.
+
+The blueprint does NOT ship a `docker-compose.yaml` file, a `Dockerfile`, or a container-orchestration recipe from any real deployment. The notes below name the shape a project's harness follows; the harness itself lives on the project.
+
+## Image
+
+The vendor's official image is `quay.io/keycloak/keycloak`. The operator pins the currently-supported stable tag at the moment they set the harness up (the vendor's release cadence moves; the pin belongs on the project's tooling, not on this blueprint). A harness that reads the pin from a project environment file is the recommended pattern.
+
+## Startup command shape
+
+Development-mode startup is what the harness invokes; the vendor documents it as `kc.sh start-dev`. The harness passes:
+
+- `KC_HOSTNAME=127.0.0.1` (or a hostname the project's test suite reaches over)
+- `KC_HTTP_ENABLED=true` (development-mode is fine over plain HTTP; production is the operator's own concern and not this asset's shape)
+- `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` read from a project environment file the harness controls (placeholders only; never committed)
+- A published port the harness records for the `issuerBaseUrl` on the realm-config record
+
+The container is standalone; no external database is required in development mode (Keycloak's default embedded H2 covers a scratch service).
+
+## Realm seed (placeholder-only)
+
+The harness applies a realm-configuration seed either through the vendor's `kc.sh import` path (mounting a realm-export file) or through the admin REST API after startup. The seed carries:
+
+- Realm name: `example` (a generic placeholder; the operator picks a stable name for their project)
+- One client: `example-client`
+  - `Access Type: confidential`
+  - `Client authentication: on`
+  - `Standard flow (authorisation code): on`
+  - `Direct access grants: off`
+  - `Redirect URIs: <project-callback-url>` (the project's callback route on the test process)
+  - `PKCE Code Challenge Method: S256`
+  - `Access Token Signature Algorithm: RS256` (JWKS mode) or issued opaque (introspection mode)
+- One role assignment shape:
+  - Client roles when `roleClaimShape: 'client-roles'` (recommended default)
+  - Realm roles when `roleClaimShape: 'realm-roles'`
+- One or two test users (placeholder usernames and passwords; never committed)
+
+Nothing in this seed shape names a real deployment; the operator either accepts the `example` names or renames them for their own project.
+
+## Wiring notes for the project
+
+- The harness records `<issuerBaseUrl>` (the container's public URL) and passes it as the `issuerBaseUrl` field on the realm-config record.
+- The realm name (`realmName` field on the record) matches the seed's realm name.
+- The `clientId` and `clientSecret` on the record match the seeded client's fields; the secret comes from the admin surface after client creation and lives in an operator-controlled environment file, never in a committed record.
+- A harness that tears down the container between test suites is fine and preferred; Keycloak's development-mode startup is fast enough to run per-suite when the project's suite structure warrants it.
+- A harness that keeps a shared team-level container running is also fine; each project's harness applies its own seed on start.
+
+## Alternate stand-up paths
+
+- A persistent scratch service the operator runs once (a system-installed Keycloak, a team-shared container, a devcontainer) is fine; the harness records the discovered endpoints and the mechanism does not care whether the realm is per-suite or persistent.
+- A Kubernetes namespace with Keycloak deployed via the vendor's operator (or via a chart the operator maintains) is fine; the mechanism sees a discovery endpoint and populates the record.
+- The blueprint does not commit to any of these paths; the shape above is the contract, not the tooling.

package/blueprints/security-auth-keycloak/assets/middleware/verifier-wiring.md

@@ -0,0 +1,93 @@
+# Verifier middleware wiring: HTTP-framework-agnostic shape
+
+A record-only shape for the middleware chain a project wires above the mechanism. Not production code; a project's own HTTP framework is what turns this into concrete request handlers.
+
+The mechanism's public surface is three factory functions and one router:
+
+```
+const discoveryClient = createDiscoveryClient({
+  realmConfig,
+  httpFetch,
+  clock,
+  auditSink,
+  retryScheduler
+});
+
+const jwtVerifier = createJwtVerifier({
+  discoveryClient,
+  httpFetch,
+  clock,
+  auditSink
+});
+
+const introspectionClient = createIntrospectionClient({
+  discoveryClient,
+  httpFetch,
+  clock,
+  auditSink
+});
+
+const providerRouter = createProviderRouter({
+  routeFn,
+  realmConfig,
+  auditSink
+});
+
+const roleAdapter = createRoleAdapter({
+  realmConfig,
+  auditSink
+});
+```
+
+## Request-time chain
+
+```
+async function verifyRequest(request) {
+  const decision = providerRouter.route(request);
+  if (decision === 'notThisIssuer') {
+    return { status: 'notThisIssuer' };
+  }
+  const record = realmConfig.get(decision.realmSlug);
+  if (record === undefined) {
+    return { status: 'refused', code: 'KEYCLOAK_REALM_UNKNOWN' };
+  }
+  const health = discoveryClient.health(decision.realmSlug);
+  if (health !== 'healthy') {
+    return { status: 'refused', code: 'KEYCLOAK_REALM_UNAVAILABLE' };
+  }
+  const token = extractToken(request, record);
+  if (token === null) {
+    return { status: 'refused', code: 'KEYCLOAK_TOKEN_MISSING' };
+  }
+  const verified =
+    decision.verificationMode === 'jwks'
+      ? await jwtVerifier.verify(decision.realmSlug, token)
+      : await introspectionClient.verify(decision.realmSlug, token);
+  if (verified.ok === false) {
+    return { status: 'refused', code: verified.code };
+  }
+  const principal = roleAdapter.principalFrom(decision.realmSlug, verified.claims);
+  if (principal.ok === false) {
+    return { status: 'refused', code: principal.code };
+  }
+  request.auth = principal.reduced;
+  return { status: 'verified' };
+}
+```
+
+`extractToken(request, record)` reads the bearer source per `sessionMode`: opaque-handle mode reads the session cookie and swaps it for the stored access token from the session record; stateless mode reads directly from the `bearerSource` field.
+
+## Wiring a specific framework
+
+The mechanism does not ship framework adapters at v1; a project on Express, Fastify, Hono, or the vendor's Workers runtime writes a one-file adapter that calls `verifyRequest` and produces the framework's response shape for the refusal classes above. Every framework adapter is a thin wrapper; the state machine is what this file names.
+
+## Sign-in and sign-out routes
+
+The sign-in initiation and callback routes are the flow controller's territory (a project either authors them above this blueprint's five TACs, or draws them from the sibling `security-auth-oauth2` blueprint's flow controller and adapts the state machine to the Keycloak record). The sign-out route is one line: invalidate the session handle if opaque-handle mode; clear the cookie; consult the realm record's `providerLogout` field to decide whether to return a 302 to `end_session_endpoint`.
+
+## What this file does NOT commit
+
+- No specific HTTP framework
+- No specific session-record store implementation
+- No specific httpFetch (the platform's `fetch` is the reference default; a project's harness substitutes in tests)
+- No specific audit sink; a project points at its own event pipeline

package/blueprints/security-auth-keycloak/assets/mock-introspection/mock-introspection-shape.md

@@ -0,0 +1,62 @@
+# Mock introspection responder: shape
+
+A local stub responder a project stands up to satisfy US-11105's runtime-verify posture for `verificationMode: 'introspection'` without running a second Keycloak realm configured for opaque tokens.
+
+The mock is real RFC 7662 on the wire: same request shape, same response shape, same content-type. The introspection client cannot tell it apart from a real Keycloak introspection endpoint for the purpose of the state machine and the response handling.
+
+A project may implement the mock in-process (a small Node HTTP server the test harness starts and tears down), against an existing library, or as a persistent scratch service. The shape below is what the harness expects, not what a specific library commits to.
+
+## Introspection endpoint (`POST /introspect`)
+
+Accepts:
+
+```
+Content-Type: application/x-www-form-urlencoded
+Authorization: Basic <base64(clientId:clientSecret)>
+
+token=<opaque-token>
+```
+
+Returns (per RFC 7662):
+
+```
+Content-Type: application/json
+
+{
+  "active": true,
+  "sub": "<opaque-subject-id>",
+  "aud": "<clientId>",
+  "iss": "<issuer>",
+  "exp": <epoch-seconds>,
+  "scope": "openid profile email",
+  "resource_access": {
+    "<clientId>": {
+      "roles": ["admin", "editor"]
+    }
+  },
+  "realm_access": {
+    "roles": []
+  }
+}
+```
+
+## Test-controllable knobs (per-token)
+
+- Return `active: false` on demand (for AC-11105-2)
+- Return HTTP 503 on demand (for AC-11105-3)
+- Return HTTP 400 on demand (for endpoint-error edge cases)
+- Return an `active: true` response with a claim record shaped for either `client-roles` or `realm-roles` (for US-11107)
+- Return an `active: true` response with a malformed `roles` field (for AC-11107-3)
+
+## Wiring notes
+
+- The mock listens on `127.0.0.1:<random-port>` and the harness passes the port to the realm-config record's `introspection_endpoint` (either directly or through a discovery-response substitution).
+- The mock's `clientSecret` is a placeholder the harness controls; the real realm's secret never appears here.
+- A per-test-suite instance is fine and preferred; state does not have to persist.
+- A project may substitute a second local Keycloak realm configured for opaque tokens if it prefers a real Keycloak surface; the mechanism cannot tell the difference and does not care.
+
+## What this asset does NOT commit
+
+- No library or package version. The shape is the contract; the implementation is a project responsibility.
+- No specific `sub` value, no specific role vocabulary, no specific issuer string. The examples above are placeholders.
+- No real `clientId` or `clientSecret`. The mock trusts whatever basic-auth pair the harness gives it, or refuses per the harness's test-driven behaviour.

package/blueprints/security-auth-keycloak/assets/provider-router/router-shape.md

@@ -0,0 +1,71 @@
+# Provider router: seam shape
+
+Generic-vocabulary shape a project's own middleware invokes to answer one question: for THIS request, which realm record is authoritative (or does the routing hand off entirely)?
+
+The blueprint stays Keycloak-committed. This asset describes the SHAPE of the routing function; it does NOT name any specific second issuer, any specific request feature, or any specific deployment topology.
+
+## The pure function
+
+```
+type RouteDecision =
+  | { realmSlug: string, verificationMode: 'jwks' | 'introspection' }
+  | 'notThisIssuer';
+
+type RouteFn = (request: RequestLike) => RouteDecision;
+```
+
+`RequestLike` is what the project's HTTP framework exposes at the middleware boundary. The blueprint does not commit to a specific shape (Express's `req`, Fastify's `request`, Hono's `c.req`, Workers' `Request`); the routeFn adapts to whatever the project's framework provides.
+
+## Single-realm deployment
+
+```
+const routeFn = () => ({ realmSlug: 'r1', verificationMode: 'jwks' });
+```
+
+The reference wiring includes this constant-realmSlug default for the common single-realm case. The overhead is one function call per request and one config-record lookup; the payoff is that the same seam exists in every deployment shape, so upgrading from single-realm to multi-realm is a routeFn swap, not a code rewrite.
+
+## Multi-realm deployment (two Keycloak realms)
+
+```
+const routeFn = (request) => {
+  const marker = readMarker(request); // project-specific: header, path prefix, claim, or other
+  if (marker === undefined) {
+    return { realmSlug: 'r1', verificationMode: 'jwks' }; // project's declared default
+  }
+  return { realmSlug: marker, verificationMode: 'jwks' };
+};
+```
+
+The MARKER is the project's own concern. The blueprint refuses to name it: a project might use a header, a request-path prefix, a preflight claim, a tenant slug from a subdomain, or something else entirely. The routeFn inspects the request and picks; the mechanism honours the pick.
+
+## Deployment where routing hands off
+
+```
+const routeFn = (request) => {
+  if (isThisMechanismsResponsibility(request)) {
+    return { realmSlug: 'r1', verificationMode: 'jwks' };
+  }
+  return 'notThisIssuer';
+};
+```
+
+A project whose middleware chain also verifies tokens from another OAuth2/OIDC issuer above this blueprint's mechanism reach returns the sentinel `notThisIssuer` when the request is not for this mechanism to verify. The caller (the project's own middleware) is responsible for what happens next; the mechanism does not know and does not care.
+
+The blueprint does NOT contribute an ADR that fixes what a project puts in `isThisMechanismsResponsibility`. That is the project-level decision the ratified reshape ruling reserves for the project. The seam is the mechanism's contribution; the routing policy is the project's.
+
+## Why the sentinel exists
+
+Without it, the mechanism would have to guess: either refuse the request (which would break a deployment where a token from another issuer is expected on that path) or trust it (which would break the security posture). The sentinel makes the hand-off explicit and paper-trailed; the routeFn is where a reviewer looks to see which requests this mechanism owns.
+
+## What the routeFn must NOT do
+
+- Perform any HTTP request. The routeFn is pure; network I/O belongs on the verifiers, not the router.
+- Read or mutate the session-record store. That is the session-bridge's territory.
+- Name a specific second issuer inside the shipped mechanism. A project that has one names it on a project-level ADR whose scope is the project, not the blueprint.
+
+## What the routeFn MAY do
+
+- Read request fields (headers, path, method, cookies, query parameters).
+- Consult a project-authored in-process lookup (a tenant registry the project maintains, a rules table the operator loaded at boot).
+- Return a stable realmSlug per request feature that maps to a realm record.
+- Return the sentinel when the project's middleware chain owns the decision above this mechanism.

package/blueprints/security-auth-keycloak/assets/realm-skeleton/realm-config-shape.md

@@ -0,0 +1,55 @@
+# Realm-config record: shape
+
+The plain data record a project maintains per configured realm. TAC-1201 validates the shape at boot; TAC-1202, TAC-1203, and TAC-1205 read from it on the hot path.
+
+All fields below are declared with placeholder or example values; a project populates them from a realm the operator runs. The `clientSecret` is server-only and NEVER committed - the record reads it from `security-secrets-management` (when composed) or from the process environment at boot.
+
+```
+{
+  realmSlug: 'r1',
+  issuerBaseUrl: 'http://127.0.0.1:8080',
+  realmName: 'example',
+  clientId: 'example-client',
+  clientSecret: '<PLACEHOLDER_CLIENT_SECRET>',
+  verificationMode: 'jwks',
+  roleClaimShape: 'client-roles',
+  scopes: ['openid', 'profile', 'email'],
+  redirectUri: '<PLACEHOLDER_PROJECT_CALLBACK_URL>',
+  providerLogout: 'none',
+  sessionMode: 'opaque-handle',
+  bearerSource: null,
+  jwksCacheTtlSeconds: 900,
+  introspectionCacheTtlSeconds: 0,
+  bootPosture: 'strict',
+  deferredRetryCapSeconds: 300,
+  discoveryRefreshSeconds: 3600,
+  enabled: true
+}
+```
+
+## Field notes
+
+- `realmSlug` is a project-local stable slug; it appears in `principalId` derivations and in every audit event. Short and lowercase; do not use the operator's realm name here (that is `realmName`).
+- `issuerBaseUrl` is the URL prefix Keycloak reports as the realm's issuer, up to but not including `/realms/<realm>`. The discovery client appends `/realms/<realmName>/.well-known/openid-configuration`.
+- `verificationMode` is `'jwks'` (default) or `'introspection'`. See ADR-1202.
+- `roleClaimShape` is `'client-roles'` (reads `resource_access.<clientId>.roles`) or `'realm-roles'` (reads `realm_access.roles`). See REQ-006 and TAC-1205.
+- `providerLogout` is `'none'` (default; sign-out clears the project session only) or `'redirect'` (sign-out returns a 302 to the realm's `end_session_endpoint`). A record with `'redirect'` on a realm whose discovery lacks `end_session_endpoint` refuses boot. See REQ-010 and ADR-1206.
+- `sessionMode` is `'opaque-handle'` (the default; server-side session record + opaque cookie) or `'stateless'` (per-request bearer verification, no session record). See ADR-1204.
+- `bearerSource` is required when `sessionMode='stateless'`: `'authorization-header'` or `'cookie:<name>'`.
+- `jwksCacheTtlSeconds` is 900 by default; the record may raise (up to 86400) or lower (down to 60). See ADR-1205.
+- `introspectionCacheTtlSeconds` is 0 by default (no cache); the record may raise for high-issuance realms. See TAC-1203.
+- `bootPosture` is `'strict'` (default), `'deferred'`, or `'standby'`. See REQ-011 and TAC-1201.
+- `discoveryRefreshSeconds` is the background refresh cadence (default 3600); a failure at refresh logs a warning and does not flip a healthy realm to unhealthy.
+- `enabled: false` marks the record as configured but not routed to; the provider-router skips disabled records.
+
+## Multiple realms
+
+A project may declare N realm records. Each carries its own `realmSlug` and its own set of the fields above. The provider-router (TAC-1204) uses a project-authored `routeFn` to decide which realmSlug a request routes to. A project with only one realm passes a constant `routeFn`; the reference wiring ships that constant.
+
+## Rejection classes at boot
+
+- Missing required field: `KEYCLOAK_RECORD_INCOMPLETE` naming the field.
+- `verificationMode='introspection'` on a discovery without `introspection_endpoint`: `KEYCLOAK_DISCOVERY_MISSING_ENDPOINT`.
+- `providerLogout='redirect'` on a discovery without `end_session_endpoint`: `KEYCLOAK_LOGOUT_NOT_DECLARED`.
+- `sessionMode='stateless'` without `bearerSource`: `KEYCLOAK_BEARER_SOURCE_MISSING`.
+- `jwksCacheTtlSeconds` outside `[60, 86400]`: `KEYCLOAK_JWKS_TTL_OUT_OF_RANGE`.

package/blueprints/security-auth-keycloak/blueprint.json

@@ -0,0 +1,49 @@
+{
+  "slug": "security-auth-keycloak",
+  "version": "1.0.0",
+  "category": "security",
+  "contributions": [
+    { "id": "security-auth-keycloak-REQ-001", "kind": "req", "path": "requirements/security-auth-keycloak-req-001.json" },
+    { "id": "security-auth-keycloak-REQ-002", "kind": "req", "path": "requirements/security-auth-keycloak-req-002.json" },
+    { "id": "security-auth-keycloak-REQ-003", "kind": "req", "path": "requirements/security-auth-keycloak-req-003.json" },
+    { "id": "security-auth-keycloak-REQ-004", "kind": "req", "path": "requirements/security-auth-keycloak-req-004.json" },
+    { "id": "security-auth-keycloak-REQ-005", "kind": "req", "path": "requirements/security-auth-keycloak-req-005.json" },
+    { "id": "security-auth-keycloak-REQ-006", "kind": "req", "path": "requirements/security-auth-keycloak-req-006.json" },
+    { "id": "security-auth-keycloak-REQ-007", "kind": "req", "path": "requirements/security-auth-keycloak-req-007.json" },
+    { "id": "security-auth-keycloak-REQ-008", "kind": "req", "path": "requirements/security-auth-keycloak-req-008.json" },
+    { "id": "security-auth-keycloak-REQ-009", "kind": "req", "path": "requirements/security-auth-keycloak-req-009.json" },
+    { "id": "security-auth-keycloak-REQ-010", "kind": "req", "path": "requirements/security-auth-keycloak-req-010.json" },
+    { "id": "security-auth-keycloak-REQ-011", "kind": "req", "path": "requirements/security-auth-keycloak-req-011.json" },
+    { "id": "security-auth-keycloak-REQ-012", "kind": "req", "path": "requirements/security-auth-keycloak-req-012.json" },
+    { "id": "security-auth-keycloak-US-11101", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11101.json" },
+    { "id": "security-auth-keycloak-US-11102", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11102.json" },
+    { "id": "security-auth-keycloak-US-11103", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11103.json" },
+    { "id": "security-auth-keycloak-US-11104", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11104.json" },
+    { "id": "security-auth-keycloak-US-11105", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11105.json" },
+    { "id": "security-auth-keycloak-US-11106", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11106.json" },
+    { "id": "security-auth-keycloak-US-11107", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11107.json" },
+    { "id": "security-auth-keycloak-US-11108", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11108.json" },
+    { "id": "security-auth-keycloak-US-11109", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11109.json" },
+    { "id": "security-auth-keycloak-US-11110", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11110.json" },
+    { "id": "security-auth-keycloak-US-11111", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11111.json" },
+    { "id": "security-auth-keycloak-US-11112", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11112.json" },
+    { "id": "security-auth-keycloak-US-11113", "kind": "us", "path": "user-stories/security-auth-keycloak-us-11113.json" },
+    { "id": "TAC-1201-security-auth-keycloak-discovery-client", "kind": "tac", "path": "tacs/tac-1201-security-auth-keycloak-discovery-client.json" },
+    { "id": "TAC-1202-security-auth-keycloak-jwt-verifier", "kind": "tac", "path": "tacs/tac-1202-security-auth-keycloak-jwt-verifier.json" },
+    { "id": "TAC-1203-security-auth-keycloak-introspection-client", "kind": "tac", "path": "tacs/tac-1203-security-auth-keycloak-introspection-client.json" },
+    { "id": "TAC-1204-security-auth-keycloak-provider-router", "kind": "tac", "path": "tacs/tac-1204-security-auth-keycloak-provider-router.json" },
+    { "id": "TAC-1205-security-auth-keycloak-role-adapter", "kind": "tac", "path": "tacs/tac-1205-security-auth-keycloak-role-adapter.json" },
+    {
+      "id": "ADR-1201-security-auth-keycloak-auth-model",
+      "kind": "adr",
+      "path": "adrs/adr-1201-security-auth-keycloak-auth-model.json",
+      "scope": "global",
+      "topic": "authModel"
+    },
+    { "id": "ADR-1202-security-auth-keycloak-verification-mode-choice", "kind": "adr", "path": "adrs/adr-1202-security-auth-keycloak-verification-mode-choice.json" },
+    { "id": "ADR-1203-security-auth-keycloak-provider-routing-seam", "kind": "adr", "path": "adrs/adr-1203-security-auth-keycloak-provider-routing-seam.json" },
+    { "id": "ADR-1204-security-auth-keycloak-session-vs-token-contract", "kind": "adr", "path": "adrs/adr-1204-security-auth-keycloak-session-vs-token-contract.json" },
+    { "id": "ADR-1205-security-auth-keycloak-jwks-rotation-cache-lifetime", "kind": "adr", "path": "adrs/adr-1205-security-auth-keycloak-jwks-rotation-cache-lifetime.json" },
+    { "id": "ADR-1206-security-auth-keycloak-refresh-and-sign-out-posture", "kind": "adr", "path": "adrs/adr-1206-security-auth-keycloak-refresh-and-sign-out-posture.json" }
+  ]
+}

package/blueprints/security-auth-keycloak/contributions/adrs/adr-1201-security-auth-keycloak-auth-model.json

@@ -0,0 +1,35 @@
+{
+  "adrId": "ADR-1201-security-auth-keycloak-auth-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "A Keycloak realm is the project's identity source; federation is OIDC authorisation-code + PKCE with per-realm verification mode",
+  "context": "A project has one authentication model; the client tier, the server tier, and every operator surface must reason against it. The security-auth-keycloak blueprint contributes a vendor-committed shape of that model: identity, sign-in surface, credential storage, MFA, and account recovery live at a Keycloak realm the operator runs; the project owns the discovery client, the token verifier (JWKS or introspection depending on the realm's client configuration), the role adapter, the provider-router seam, and the optional application session on top. Every other auth-family blueprint (security-auth-magic-link, security-auth-clerk, security-auth-oauth2) contributes its own decision on this topic; blueprint composition surfaces the pairing at add time for the operator to reconcile into one project-level model. That surfacing is intended.",
+  "decision": "The project's authentication model is delegated identity to a Keycloak realm the operator runs, federated through OAuth2 authorisation-code with PKCE (RFC 7636, S256), with the realm's OIDC endpoints resolved through discovery (REQ-002). Every access token the project receives from the realm is verified either through JWKS (default, REQ-003) or through the RFC 7662 introspection endpoint (opt-in per realm, REQ-004); the verification mode is a per-realm-record field. Roles are read from Keycloak's client-roles or realm-roles claim path per the realm's configuration (REQ-006); the project's own handlers see only the reduced Principal. The application session posture on top of the verified token stream is either an opaque-handle session cookie (the default, mirroring the sibling blueprints' opaque-handle contract) or stateless bearer verification per request; the operator picks one per realm record (REQ-008). Refresh follows the realm's rotation model (REQ-007). Sign-out invalidates the project session; realm-side sign-out is a project option (REQ-010). Fail-safe boot follows a declared posture (REQ-011). Runtime-verify binds against a local Keycloak container; live cloud-tenant smokes are accountBound (REQ-012). The blueprint contributes a provider-routing seam (REQ-005) that a project's own middleware may use to route requests to one of several issuers; the seam is described in generic OAuth2/OIDC vocabulary and does not itself commit the blueprint to any specific second issuer.",
+  "consequences": "The project owns the discovery client, the token verifier, the role adapter, the session-bridge (opaque-handle mode) or the bearer verifier (stateless mode), the provider-router seam, and the optional local-container harness for runtime-verify; the realm owns the sign-in surface, the credential storage, MFA, account recovery, refresh-token issuance policy, role assignments, and the whole admin console. A realm swap is a discovery-record refresh plus (if the client configuration changed) a re-choice of `verificationMode`; the project's code path does not change. Composing with another auth-family blueprint conflicts on this topic by design; the expected resolution is one project-level ADR that fixes the identity surface and the credential shape for the whole project. The local-container runtime-verify posture makes CI honest without demanding cloud-realm credentials; a project that has a cloud realm wires it on top and the accountBound smokes light up. Every path that produces or consumes a session record (opaque-handle mode) or that reads a bearer token (stateless mode) flows through one narrow set of modules the ship gate compels.",
+  "alternativesConsidered": [
+    {
+      "name": "Vendor-neutral OAuth2 authorisation-code + PKCE (security-auth-oauth2)",
+      "summary": "The sibling blueprint's model: keep the flow (authorisation-code + PKCE) but do not commit to a vendor; let the project drop in any conforming IdP through a fixed provider-abstraction record.",
+      "reasonNotChosen": "Right choice for projects that are not committed to a single vendor. This blueprint is for projects that have committed to Keycloak: they want the Keycloak-shaped decisions (JWKS vs introspection, client-roles vs realm-roles, local-container stand-up, RP-initiated logout through the realm's end_session_endpoint) fixed at the mechanism layer so the project code path can name a Keycloak realm rather than an abstract provider record."
+    },
+    {
+      "name": "Hosted identity vendor with vendor-committed shape (security-auth-clerk)",
+      "summary": "The Clerk sibling: Clerk hosts the sign-in surface, the credential storage, MFA, account recovery; the project runs a middleware boundary against Clerk's session-verification API.",
+      "reasonNotChosen": "Valid for projects that want a hosted-identity fast lane. This blueprint targets the operator who wants self-hosted control over the realm and the admin surface, or who has an existing Keycloak deployment they cannot displace. The Clerk lane trades vendor commitment for less operator work; the Keycloak lane trades operator work for full self-hosted control."
+    },
+    {
+      "name": "Passwordless magic-link with server-issued opaque cookie sessions (security-auth-magic-link)",
+      "summary": "The magic-link sibling's model: mint a single-use token on POST /login, deliver by email, verify on GET /login/verify, issue an opaque-handle session cookie.",
+      "reasonNotChosen": "Valid for projects with no third-party identity dependency and the willingness to own the whole authentication surface in-house. This blueprint delegates that surface entirely to the realm; the trade against magic-link is running a Keycloak realm rather than an in-process principal registry."
+    },
+    {
+      "name": "Hand-wire the Keycloak flow inside the project without a mechanism-level record",
+      "summary": "Keep the Keycloak URLs, client id, secret, and JWKS knowledge inline in project code; no discovery, no per-realm record, no injected verifier.",
+      "reasonNotChosen": "Cheap on day one and expensive on day thirty: the realm URL layout changes, the client configuration changes to opaque tokens, the operator introduces a second realm, or the deployment moves to a different hostname. Every one of those is a code edit rather than a record refresh; the injected verifier + discovery record shape pays back the abstraction cost by the second such change."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/adrs/adr-1202-security-auth-keycloak-verification-mode-choice.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1202-security-auth-keycloak-verification-mode-choice",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Verification mode is a per-realm-record choice between JWKS (default) and RFC 7662 introspection",
+  "context": "Keycloak clients issue either JWT access tokens (verifiable off-line against the realm's JWKS) or opaque access tokens (verifiable only through the RFC 7662 introspection endpoint). The choice is made at the Keycloak client configuration layer (Access Token Signature vs Bearer-only clients using opaque handles) and each has legitimate operational reasons. A blueprint that fixes one mode fights half the deployments. A blueprint that lets a project mix modes at random inside one realm record blurs the mechanism.",
+  "decision": "The realm record carries a `verificationMode` field with two legal values: `jwks` (the default) and `introspection`. The verifier reads the field once per verification and dispatches to the JWT verifier (TAC-1202) or the introspection client (TAC-1203) accordingly. A single realm record carries a single mode; a project whose realm has both kinds of clients declares one realm record per client and routes through the provider-router seam (REQ-005). The default is JWKS because JWKS is cheap on the hot path and matches the more common Keycloak client configuration; introspection is opt-in per record.",
+  "consequences": "The verifier stays single-branched inside one realm record. The role adapter (TAC-1205) reads roles from the verified claims in both modes (the introspection response body is claim-shaped identically to the id_token payload for role-carrying paths). The operator's mode choice is legible on the record and does not require a code path change to swap; a realm reconfigured from JWT to opaque tokens is a `verificationMode` field flip on the record plus a discovery re-fetch (introspection_endpoint appears on discovery in both modes but its use only matters in introspection mode). Runtime-verify covers both modes; the JWKS path binds against a real local Keycloak container and the introspection path binds against a local stub responder (or a second local realm configured for opaque tokens, per project preference).",
+  "alternativesConsidered": [
+    {
+      "name": "JWKS only (fix the mode at the mechanism layer)",
+      "summary": "Refuse to support introspection at all; every client must be configured to issue JWTs.",
+      "reasonNotChosen": "Excludes deployments that legitimately prefer opaque tokens (some regulated environments require server-side revocation reflection with no JWT-in-flight window). Fixing a mode at the mechanism boundary is exactly the vendor-lock this blueprint is designed to accept for Keycloak specifically, not for token shape."
+    },
+    {
+      "name": "Introspection only (fix the mode at the mechanism layer)",
+      "summary": "Every access token is verified through the introspection endpoint on every request.",
+      "reasonNotChosen": "Trades a documented performance property for one policy uniformity. Introspection is one HTTP round-trip per verification against the realm; the hot-path cost is unacceptable on any deployment where the JWKS-cached path would satisfy the operator's revocation posture."
+    },
+    {
+      "name": "Auto-detect the mode from the token shape at first receipt",
+      "summary": "Peek at the token; if it parses as a JWT with valid header, run JWKS; otherwise run introspection.",
+      "reasonNotChosen": "The mode is not the token's decision to make; it is the realm operator's. Auto-detect makes the mechanism reason about the operator's realm configuration in code rather than on the record, and a realm reconfigured mid-deployment would flip modes without a paper trail. Naming the choice on the record makes it observable and reviewable."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/adrs/adr-1203-security-auth-keycloak-provider-routing-seam.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1203-security-auth-keycloak-provider-routing-seam",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "A provider-routing seam is contributed at one named point in the request chain; the seam is described in generic OAuth2/OIDC vocabulary and does not commit to any second issuer",
+  "context": "A project may sit in a deployment where a receiving system's request stream carries tokens issued by more than one server. Two Keycloak realms is one shape; a Keycloak realm alongside a project-authored second-issuer path (a corporate OIDC provider the operator declares separately, a second Keycloak realm on a different hostname, an internal service-to-service issuer) is another. The blueprint stays vendor-committed to Keycloak; it does not know, and refuses to encode, what the second issuer is. What the blueprint does know is that a deployment with more than one issuer needs the routing decision made in exactly one legible place, not scattered across handlers where the ship gate cannot see it.",
+  "decision": "The blueprint contributes TAC-1204, the provider-router, as the seam a project's own middleware invokes on every authenticated request. The seam's contract is a pure function: `route(request) -> { realmSlug, verificationMode } | notThisIssuer`. A project with only Keycloak configured wires the seam to a constant realmSlug and the mechanism is single-branched. A project with two Keycloak realms wires the seam to inspect a request feature (a header the project's middleware layer already reads, a request-path prefix the project owns, a preflight claim the project extracts elsewhere) and picks the realmSlug. A project with Keycloak plus a non-Keycloak issuer wires the seam to return `notThisIssuer` when the routing decision hands off to a middleware layer above this blueprint's mechanism reach; the middleware layer above is the project's own concern, not the blueprint's. The blueprint refuses to name the header, the path, the claim, or the second issuer; the ratified reshape ruling forbids naming a specific dual-provider deployment shape, and the seam contract respects that.",
+  "consequences": "A project that has one Keycloak realm pays zero cost for the seam: the wiring is a constant. A project that has two Keycloak realms wires the routing once and every request passes through it observably. A project that has Keycloak alongside another issuer has one named point where the choice is made, which is a paper-trailed decision the ship gate can see. The trade against a hard-coded assumption (only Keycloak, only one realm, always JWKS mode) is one function call on the request path; that cost is trivial and the observability payoff scales with deployment complexity. The blueprint never names a second issuer; a project that has one owns that decision on a project-level ADR whose `related-reqs` cites this ADR.",
+  "alternativesConsidered": [
+    {
+      "name": "Refuse to contribute any routing seam; assume Keycloak is the only issuer forever",
+      "summary": "The mechanism reads every access token against the single configured realm; a request carrying a token from a different issuer refuses uniformly.",
+      "reasonNotChosen": "Bakes an assumption into the mechanism that the ratified reshape ruling names as the exact deployment shape the blueprint must be aware of. A project with a second issuer would either hand-wire the choice above the mechanism (invisible) or push it into every handler (unmaintainable). The seam is cheap and makes the decision legible."
+    },
+    {
+      "name": "Name a specific second-issuer integration in the mechanism (e.g., `providerLayer: 'keycloak' | 'other'`)",
+      "summary": "Ship an ADR (and the router TAC) that names the second issuer's shape.",
+      "reasonNotChosen": "Fights the ratified reshape ruling. The candidate that minted this blueprint originally proposed naming a specific dual-provider deployment, and the ruling stripped that; the seam stays in vendor-neutral OAuth2/OIDC vocabulary. A project that has a second issuer names it on its own ADR, not on the blueprint's."
+    },
+    {
+      "name": "Publish the seam as a per-issuer array and let the project fill it with N records",
+      "summary": "The blueprint declares a `configuredIssuers: []` array; each record is a full realm-record (or a similar shape); the router iterates.",
+      "reasonNotChosen": "Turns the seam from a decision point into a data structure; the mechanism ends up owning the routing algorithm as well as the data, which is exactly the responsibility the ADR is trying to keep on the project side. The pure-function contract keeps the algorithm the project's concern."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/adrs/adr-1204-security-auth-keycloak-session-vs-token-contract.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1204-security-auth-keycloak-session-vs-token-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Keycloak owns tokens; the project chooses opaque-handle session or stateless bearer per realm record",
+  "context": "Keycloak's ownership of the token stream is not negotiable within this blueprint's vendor commitment; the realm mints access, id, and refresh tokens and the project verifies them. What the project can choose is the shape of any application session it layers on top. The vendor-neutral sibling committed to opaque-handle sessions uniformly because it could not rely on the underlying provider for revocation; a Keycloak-committed blueprint has the realm's revocation clock available and can honestly support a stateless posture where the operator prefers it.",
+  "decision": "The realm record carries a `sessionMode` field with two legal values: `opaque-handle` (the default) and `stateless`. Under `opaque-handle`, the session-bridge issues an opaque-handle cookie (`Secure`, `HttpOnly`, `SameSite=Lax`); the server-side session record stores the Keycloak-minted access token, id_token, and (if issued) refresh token keyed by the handle; the browser never holds a provider-minted token; the reduced Principal is what handlers read from `request.auth`. Under `stateless`, no server-side session record is kept; every request re-verifies the access token from a bearer source the operator declares on the record (`bearerSource: 'authorization-header' | 'cookie:<name>'`); the reduced Principal is derived per request from the verified token and no session cookie is issued by the mechanism (a project may still issue its own out-of-band session for unrelated reasons, but the auth mechanism does not). Provider tokens are never exposed on `request.auth` in either mode; only the reduced Principal (`principalId`, `provider`, `email?`, `roles[]`, `organisationIds[]`) crosses outward.",
+  "consequences": "The reference wiring is opaque-handle: it works out of the box on any Node HTTP framework, matches the sibling blueprints' pattern, and gives the project cheap sign-out (one delete on the session record). The stateless posture matches deployments where the operator has committed to bearer-per-request verification (a service tier, a public API surface behind an API gateway that itself terminates the browser session, a strict-no-cookie environment). Naming the mode on the record makes the trade a paper-trailed decision. The two modes are not composable per realm record; a project that needs both patterns on different routes declares two realm records (potentially against the same realm) with distinct `sessionMode` values and routes through the provider-router seam.",
+  "alternativesConsidered": [
+    {
+      "name": "Opaque-handle only (mirror the sibling blueprints uniformly)",
+      "summary": "Every session is server-side; no stateless posture.",
+      "reasonNotChosen": "Fights the operational reason a project might choose Keycloak in the first place. A deployment on a stateless service tier that wants Keycloak-issued JWTs verified per request and no cookie shape is a legitimate posture; refusing it in the mechanism would drive that project to hand-wire the verification outside the blueprint and lose the ship-gate observability."
+    },
+    {
+      "name": "Stateless only (JWT in cookie, browser holds the JWT)",
+      "summary": "Every request carries the Keycloak-minted JWT in a cookie; no server-side session record.",
+      "reasonNotChosen": "Leaks the provider token surface into every browser side-channel; a compromised cookie is a lifted Keycloak token whose only revocation clock is the realm's expiry timer. Opaque-handle is the safer default for the common small-project deployment shape."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}