rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-auth-clerk/guide/security-auth-clerk.md

@@ -0,0 +1,71 @@
+# Security auth Clerk blueprint guide
+
+## What it is
+
+A Clerk-committed authentication floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a hosted-identity pattern: how the project delegates identity to Clerk, how it verifies the resulting session cookie on the server, how it reduces the verified claims into a stable Principal shape, how the authorisation adapter maps Clerk roles and organisation memberships onto project-defined verbs, how sign-in strategy sits as a config surface rather than a hard-coded choice, how sign-out honours Clerk-side revocation within a bounded window, how rate-limiting and anti-enumeration are delegated to Clerk, how user and organisation provisioning stays read-only from the runtime's perspective, and how runtime-verify acceptance criteria acknowledge that Clerk-reachable behaviour cannot be faked.
+
+Concretely, the blueprint ships nine requirements, eleven user stories (twenty-five acceptance criteria), four architecture components, and five architecture decision records. One ADR is `scope: global` on the `authModel` topic; the other four are scope-local operational ADRs (middleware-boundary shape, authorisation-adapter contract, claims-mapping discipline, session-lifecycle posture) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a Clerk SDK version pin. The SDK's package version is a project-package-manifest concern; the blueprint fixes the shape of the boundary (the `verify(request)` contract, the `__session` cookie name, the reduced Principal shape) and lets the project pick which Clerk SDK major it builds against.
+
+Not an MFA policy. Clerk owns MFA at the hosted identity surface; the blueprint delegates MFA to Clerk's configuration and does not encode an MFA strategy or enforcement rule at the project's runtime. A project with a hard MFA-for-all-admins requirement configures that on the Clerk dashboard.
+
+Not a user or organisation mirror. Clerk is authoritative for identity state. A project that needs to mirror Clerk state into a local table for query purposes (a per-user preferences row, a per-organisation audit log) does so through a project-authored Clerk-webhook consumer; that consumer is out of scope for the blueprint's default. A project that includes one adds one project-authored TAC and one scope-local ADR alongside this blueprint's contributions.
+
+Not a project-side rate limiter or anti-enumeration defence. Clerk applies its own throttling and enumeration defences at the identity surface; the blueprint requires that the project does not layer a second, competing rate limiter on top of the sign-in flow.
+
+Not an OAuth2-provider-list blueprint. A project that wants direct OAuth2 against a specific set of social providers, without a hosted identity vendor, reaches for the future `security-auth-oauth2` sibling blueprint when it ships. A project that wants a self-hosted OIDC surface reaches for the future `security-auth-keycloak` sibling. Both conflict with this blueprint on `authModel` by design.
+
+Not the sign-in UI. Clerk hosts the sign-in surface (either fully hosted at Clerk's domain or embedded through Clerk's components). The blueprint's job is to wire the surface into a project route and to verify the resulting session on the server; the pixels of the sign-in form are Clerk's.
+
+## When to reach for it
+
+Reach for the security-auth-clerk blueprint when:
+
+- The project needs user accounts, sessions, sign-in UX, and account recovery, and the operator's preference is to buy that surface from a hosted vendor rather than build it.
+- The project's operator wants a straightforward path to enterprise-shaped features (SAML, SCIM, organisation memberships, roles) without owning the identity infrastructure that supports them.
+- The team is small enough that owning the identity surface (email deliverability, MFA rollout, breach-check integration, session persistence) is a distraction from the product.
+- The project's compliance posture accepts a hosted identity vendor; a project subject to data-residency constraints that Clerk's regions do not satisfy is on the wrong blueprint.
+- The project already uses (or plans to use) Clerk's dashboard for user administration and does not want a second admin surface.
+
+## When it does not fit
+
+Do not reach for the security-auth-clerk blueprint when:
+
+- The project cannot depend on a hosted third-party identity surface (data-residency constraints, an air-gapped deployment, a compliance regime that requires self-hosted identity). Reach for `security-auth-keycloak` when it ships, or supersede ADR-1001 with a project-level ADR and pick a self-hosted vendor whose adapter the project authors.
+- The project's identity surface is genuinely trivial (one operator, no organisations, no roles). A passwordless magic-link floor (`security-auth-magic-link`) is honestly a smaller machine at that scale; this blueprint's provider dependency and pricing tier are overkill.
+- The project wants direct OAuth2 against a specific set of social providers and nothing else, with no hosted identity vendor. `security-auth-oauth2` will cover that shape when it ships; picking this blueprint plus Clerk's OAuth strategies is valid but is a bigger machine than a project that only wants "sign in with GitHub" needs.
+- The project cannot accept the `accountBound` runtime-verify posture (runtime tests that skip when Clerk is unreachable, rather than pass on a fake). Every hosted-identity blueprint carries this posture; a project that needs offline test independence is on the wrong blueprint family.
+
+An earlier round-1 pass shipped `security-auth-magic-link` as the generic-auth blueprint; the round-2 pass introduces the vendor-committed siblings (this blueprint for Clerk, plus the reserved `security-auth-oauth2` and `security-auth-keycloak`). The composition-precedent is `application-spa` + `application-api-rest` on the `errorEnvelope` and `authModel` topics: siblings on the same topic conflict on purpose and expect a project-level ADR resolution.
+
+## What a good outcome looks like
+
+A project applies the blueprint on a fresh tree, provisions a Clerk development instance, stores the publishable and secret keys in the secrets manifest under placeholder-named entries (`CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`), chooses its `signInStrategy` primary and alternates, realises the four TACs in project-authored FBSes (one framework-specific middleware shim, one authorisation-adapter with a project verb-to-role mapping, one session verifier over the Clerk SDK, one claims mapper), and lands on a deployed application where:
+
+- The sign-in surface renders Clerk's hosted (or embedded) sign-in UI; the operator signs in and lands on the app with a `__session` cookie in their browser.
+- Every request to a protected route arrives at the middleware, which verifies the cookie against Clerk and attaches `request.auth = { principalId, roles, organisationIds, claims }` before the handler runs.
+- Every handler that gates on identity calls `can(request.auth, verb, subject?)` or `assert(request.auth, verb, subject?)` on the authorisation adapter; no handler reads `request.auth.roles` or `request.auth.claims` directly.
+- Role-based UI slots on rendered pages appear or disappear per the adapter's decision; the corresponding server-side handler enforces the same verb through `assert`.
+- The Clerk SDK is imported by two modules in the project (the middleware wiring and the session verifier). A source-tree scan confirms the boundary.
+- The operator signs out; a subsequent request replaying the pre-sign-out cookie is refused by the middleware within the `revocationCheckIntervalMs` window declared on ADR-1005.
+- The sign-in flow has no project-authored rate limiter; Clerk's own throttling is the observed behaviour under a burst of attempts.
+- User and organisation management happens on the Clerk dashboard (or on a project-authored provisioning script directory that runs outside the request lifecycle); the runtime never mutates Clerk identity state.
+- The runtime-verify test surface marks Clerk-reachable ACs as `accountBound` and, when the CI runner has Clerk reachable, they pass against the development instance; when the CI runner does not, they skip with `AUTH_CLERK_UNREACHABLE`, not pass silently.
+
+## Operator decisions that remain open after apply
+
+- Vendor choice (Clerk default per ADR-1001, or a superseding project-level ADR selecting Auth0, WorkOS, Cognito, or a project-authored hosted-identity adapter). Blueprint owns the boundary on both sides; project owns the vendor when it supersedes.
+- `signInStrategy` primary and alternates (email link, email code, password, phone code, OAuth against named providers, SAML). Blueprint owns the shape; project owns the choice; Clerk dashboard owns the enablement.
+- Verb-to-role mapping table (project vocabulary; every downstream `can` and `assert` call speaks in these verbs). Blueprint owns the adapter shape; project owns the mapping.
+- Organisation scoping policy (whether to scope every resource by `organisationId` or leave organisation membership as a flat role decoration). Blueprint owns the adapter's optional-subject shape; project owns the choice.
+- `revocationCheckIntervalMs` (30 seconds default per ADR-1005, or a shorter window at the cost of a per-request Clerk round trip, or a longer window up to the session's declared expiry). Blueprint owns the shape and the ceiling; project owns the number.
+- Clerk plan tier (development, production, per-user pricing). Blueprint owns none of this; the operator picks per project needs.
+- Provisioning-script directory location (`scripts/provisioning/` by convention on AC-9110-1, or a project-declared equivalent). Blueprint owns that provisioning is not a request handler; project owns where the scripts live.
+- Whether to layer a project-authored Clerk-webhook consumer (for user-created, session-ended, or organisation-membership-changed events). Blueprint's default omits it; a project that adds one authors one TAC and one ADR alongside this blueprint's contributions.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Clerk is a paid vendor beyond the development tier; the operator budgets for it. The `accountBound` runtime-verify posture means the CI runner needs Clerk reachability to actually verify the runtime-verify ACs; a CI runner without outbound network for that vendor either skips those ACs (which the ship gate flags) or the operator wires a preview Clerk instance for CI to reach. The middleware boundary discipline (`request.auth` and `can`/`assert` everywhere) is a code-review load on every new handler; a project that lets the discipline slip loses the vendor-swap-safety the blueprint is buying. The `revocationCheckIntervalMs` window is a stated trade between per-request cost and sign-out prompt-ness; the operator picks a number that reflects the project's actual policy, not the blueprint's default forever. The read-only provisioning posture forces the operator to run Clerk mutations outside the request lifecycle; a project that wants a per-request user-create call is on a different pattern and should think again. The blueprint says nothing about MFA policy, about pricing, about SLA, or about vendor-lock exit; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.

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"
+}