rcf-lite 0.12.0 → 0.13.0

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

package/blueprints/security-auth-keycloak/contributions/adrs/adr-1205-security-auth-keycloak-jwks-rotation-cache-lifetime.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1205-security-auth-keycloak-jwks-rotation-cache-lifetime",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "JWKS cache TTL is 900 seconds by default with kid-miss refresh; the operator raises or lowers on the realm record",
+  "context": "JWKS caching sits on the hot path of JWT verification: too short a TTL means unnecessary network round-trips against the realm on every verification; too long a TTL means a key rotation the realm has published takes too long to reach the verifier, which either delays revocation or produces silent verification failures when the old key ages out and no cached entry exists for the new one. Two mechanisms defend against the second failure mode: a TTL that bounds the maximum staleness, and a kid-miss refresh that recovers when the realm has rotated inside the TTL window.",
+  "decision": "The default TTL for a cached JWKS response is 900 seconds (15 minutes). The realm record MAY declare `jwksCacheTtlSeconds` to raise or lower this; values below 60 are refused at boot (the network amplification would be self-defeating) and values above 86400 are refused at boot (staleness beyond a day risks losing rotations for too long). Every verification path first consults the cache; on a kid-miss (the token's `kid` does not appear in the cached JWKS), the verifier triggers exactly one refresh from `jwks_uri`; if the refresh succeeds and the new JWKS carries the kid, verification proceeds; if the refresh succeeds and the new JWKS still does not carry the kid, the token is refused with `KEYCLOAK_JWT_KID_UNKNOWN`; if the refresh itself fails, the token is refused with `KEYCLOAK_JWKS_UNREACHABLE`. A kid-miss triggers at most one refresh per token verification; a flood of unknown-kid tokens does not multiply into a flood of JWKS fetches.",
+  "consequences": "A key rotation the realm has published propagates within one TTL window at the worst case and within one verification at the best case (a kid-miss refresh recovers immediately). The trade against a shorter TTL (say 60 seconds) is the network round-trip cost; against a longer TTL (say 3600 seconds) is the maximum staleness window. The one-refresh-per-verification cap defends the realm's JWKS endpoint against a token-based amplification attack. The refuse-on-unknown-kid-after-refresh posture is what catches genuine forgery attempts (an attacker who signs with a key the realm never published sees exactly one JWKS refresh and then a stable-coded refusal).",
+  "alternativesConsidered": [
+    {
+      "name": "No cache; fetch JWKS on every verification",
+      "summary": "Every request triggers one JWKS fetch.",
+      "reasonNotChosen": "Trivial to implement and unacceptable in production. The realm's JWKS endpoint would carry a request rate equal to the project's verification rate; on a small project that is fine and on any larger deployment it is untenable."
+    },
+    {
+      "name": "Cache forever; refresh only on kid-miss",
+      "summary": "No TTL; only a token whose kid is unknown triggers a refresh.",
+      "reasonNotChosen": "Loses the bound-staleness property. A realm that has rotated but that has not yet issued a token under the new key (a common state for the first few minutes after rotation) leaves the verifier holding a cache no signal will refresh. The TTL is the belt against that class of missed-rotation state."
+    },
+    {
+      "name": "Push-based invalidation (webhook the realm calls into the project)",
+      "summary": "The realm notifies the project when JWKS rotates.",
+      "reasonNotChosen": "Not a Keycloak feature at v1 of this blueprint; would require project-authored plumbing on both sides. A pull-with-TTL model is the standard shape and Keycloak matches it verbatim."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/adrs/adr-1206-security-auth-keycloak-refresh-and-sign-out-posture.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1206-security-auth-keycloak-refresh-and-sign-out-posture",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Refresh follows the realm's rotation model; sign-out clears the project session and offers realm-side end-session as a per-record option",
+  "context": "Two operational decisions sit adjacent to the identity flow: how refresh tokens rotate, and how sign-out relates to the realm session. Keycloak's admin surface already exposes controls for both (revoke-refresh-token, refresh-token-max-reuse, and the RP-initiated logout endpoint on the realm's discovery), so the blueprint's role is to honour the realm's declared behaviour rather than to layer a second policy.",
+  "decision": "Refresh: the flow controller presents the current stored refresh token on every refresh call; a 2xx response replaces the stored value with the new one; a 4xx `invalid_grant` on refresh is treated as a session-invalidation signal and the flow controller invalidates the session handle, clears the associated refresh-token chain, and emits `keycloak.refresh_invalidated`. The blueprint does NOT layer a reuse-detection policy above what the realm already does; the realm's `Revoke Refresh Token` and `Refresh Token Max Reuse` settings ARE the mechanism, and the blueprint's role is to fail cleanly when the realm signals invalidation. Sign-out: a POST to the project's sign-out route invalidates the project session handle (opaque-handle mode) or clears the bearer-source cookie (stateless mode); the response clears the session cookie in either case. When the realm record sets `providerLogout: 'redirect'` and the discovery record carries `end_session_endpoint`, the sign-out response is a 302 to that endpoint with `id_token_hint` carrying the raw id_token stored on the session (opaque-handle) or the last-verified id_token the operator's bearer source has cached (stateless). A record that sets `providerLogout: 'redirect'` on a realm whose discovery does not publish `end_session_endpoint` is refused at boot.",
+  "consequences": "Refresh behaviour is legible from the realm's admin console; a project that wants stricter reuse detection tightens the realm setting rather than editing project code. Sign-out is one delete on the session record (opaque-handle mode) or one cookie-clear (stateless mode); the realm-side end-session is opt-in and paper-trailed on the record. The trade against re-implementing rotation policy above the realm is that a realm configured to allow reuse permissively will not be tightened by the project's mechanism; that is intended - the operator authored the realm and the project honours it, not the other way around. A boot refusal on `providerLogout: 'redirect'` without `end_session_endpoint` catches the misconfiguration where a project believes it is doing realm-side sign-out and silently is not.",
+  "alternativesConsidered": [
+    {
+      "name": "Enforce reuse-detection in the blueprint regardless of realm setting",
+      "summary": "The flow controller tracks the previous refresh-token value; presenting it twice revokes the chain even when the realm would not.",
+      "reasonNotChosen": "Fights the realm's declared policy. A project whose operator has deliberately relaxed reuse behaviour for their environment should not be quietly tightened by the mechanism; the realm is the source of truth for that class of decision."
+    },
+    {
+      "name": "Mandate realm-side sign-out on every project sign-out",
+      "summary": "Every sign-out redirects to `end_session_endpoint` regardless of the record's `providerLogout` field.",
+      "reasonNotChosen": "Fights half the deployments. Some operators legitimately want the realm session to persist across a project sign-out (the operator's other applications on the same realm stay signed in); mandating realm-side sign-out here would drive that operator to disable the sign-out route entirely, which is worse than the per-record posture."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-001",
+  "prdId": "PRD-001",
+  "title": "A Keycloak realm is the identity source; the project federates through OIDC authorisation-code with PKCE",
+  "description": "The project's authentication model is delegated identity to a Keycloak realm the operator runs (locally at development time, in a project-owned deployment at operate time). Identity is proven by a completed OAuth2 authorisation-code round-trip with PKCE (RFC 7636, S256) against the realm's OIDC endpoints; the id_token issued by the realm carries the authenticated subject. The wire vocabulary is OIDC on top of OAuth2 and the flow shape is authorisation-code + PKCE; the vendor commitment is Keycloak. The blueprint contributes Keycloak-shaped decisions the vendor-neutral sibling `security-auth-oauth2` deliberately does not fix: a Keycloak realm as the concrete issuer, a Keycloak client with a chosen verification mode (JWT via JWKS, or opaque via the RFC 7662 introspection endpoint), the Keycloak claim shape for client roles, and the local-first stand-up shape through the vendor's official container image.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Two commitments only make sense together. Fixing the flow shape (authorisation-code + PKCE) keeps the state machine legible and defends against front-channel code interception; fixing the vendor (Keycloak) lets the project reason about a concrete realm surface, a concrete admin console, and a concrete container image at operate time. A project that wants vendor-neutrality picks the sibling; a project that has committed to running a Keycloak realm gets the Keycloak-shaped decisions the sibling deliberately leaves open.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:01-flow-shape"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-002",
+  "prdId": "PRD-001",
+  "title": "OIDC discovery against the Keycloak realm's well-known endpoint drives the endpoint record",
+  "description": "The project reads the realm's discovery document from `<issuerBaseUrl>/realms/<realm>/.well-known/openid-configuration` at boot (or at a cached refresh cadence when the operator prefers a background refresh) and populates the realm record's endpoint fields from it: `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`, `introspection_endpoint`, `end_session_endpoint`, `issuer`. The record shape the project maintains carries `{ realmSlug, issuerBaseUrl, realmName, clientId, clientSecret (server-only), verificationMode ('jwks' | 'introspection'), roleClaimShape ('client-roles' | 'realm-roles'), scopes[], redirectUri, providerLogout ('redirect' | 'none') }`. A realm whose discovery fetch fails at boot follows the fail-safe posture in REQ-011; a realm whose discovery response omits any endpoint the chosen `verificationMode` depends on is refused at boot with a stable-coded error naming the missing field.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Keycloak publishes discovery as a matter of course; a project that reads it at boot inherits the realm's current endpoint shape without having to encode a Keycloak URL layout in project code. A realm operator who moves the deployment or reshapes the URL path (a valid Keycloak configuration option through the realm's `hostname-*` settings) does not require a project code change; the discovery pull refreshes the record. Fail-fast on missing endpoints catches an operator who has enabled JWKS-mode against a client whose realm does not publish `jwks_uri` (a rare misconfiguration but a real one).",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:02-discovery"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-003",
+  "prdId": "PRD-001",
+  "title": "JWT verification via JWKS with a rotation cache is the default verification mode",
+  "description": "When the realm record's `verificationMode` is `jwks` (the default), the JWT verifier reads the realm's public key set from the `jwks_uri` on the discovery record and validates every access token (and every id_token) against it before any session issue or downstream authorisation check. Verification checks: signature valid under a key from JWKS resolved by the token's `kid`; `iss` equality against the discovery record's `issuer`; `aud` containment of the record's `clientId` (or, for realm-scoped tokens whose `azp` names the client, `azp` equality); `exp` in the future by at least one second; `nbf` not in the future; `iat` in the past by no more than `idTokenMaxAgeSeconds` (default 3600). The JWKS is cached by realm slug with a TTL declared on `jwksCacheTtlSeconds` (default 900, see ADR-1205); a `kid` miss triggers exactly one refresh before refusing the token, so a key rotation the realm has published propagates without a process restart. Cache entries are refreshed on TTL expiry from the head of the queue; no verification path blocks on JWKS fetch when a cached entry is still valid.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "JWKS-based verification is cheap on the hot path and keeps the realm the sole custodian of signing material. A rotation cache with kid-miss refresh means the realm can roll keys on its own cadence and the project keeps verifying without downtime, without the project code path knowing anything about rotation timing. Fail-safe on kid-miss (one refresh, then refuse) prevents an attacker from flooding an unknown-kid token to force unbounded JWKS fetches.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:03-jwt-verify"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Opaque-token introspection via the RFC 7662 endpoint is the alternate verification mode",
+  "description": "When the realm record's `verificationMode` is `introspection`, the verifier calls the realm's `introspection_endpoint` on every presented access token, presenting the record's `clientId` and `clientSecret` via HTTP basic auth per RFC 7662 section 2.1. A response with `active: true` is treated as verified and the response's claim record is the identity source; a response with `active: false` or a non-2xx status refuses the token with a stable-coded reason. Introspection is expensive on the hot path (one HTTP round-trip per verification) so the mode is opt-in per realm record; the introspection response MAY be short-lived cached under the record's `introspectionCacheTtlSeconds` (default 0 for no cache; the operator raises it when their realm's issuance rate makes the round-trip cost visible). This is the seam that lets the receiving system co-exist with another OAuth2 or OIDC provider a project's own middleware layer routes to: an introspection endpoint speaks the same RFC 7662 shape whether the issuer is Keycloak or some other conforming server, so a project may reach for the introspection path where its middleware has chosen to consult a non-Keycloak issuer without changing the vocabulary this blueprint owns.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "Some Keycloak client configurations issue opaque tokens rather than JWTs, and some projects prefer introspection for the stronger revocation guarantee (a JWT is valid until expiry; an introspection endpoint reflects revocations in real time). Making mode a per-record field keeps the mechanism symmetric across the two verification paths and lets a project mix modes across realms if the deployment has more than one. The RFC 7662 shape is standards-tracked and generic; the seam is described in that vocabulary rather than as an integration to any specific non-Keycloak issuer.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:04-introspection"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-005",
+  "prdId": "PRD-001",
+  "title": "A provider-routing seam lets a project's middleware decide which issuer to consult per request",
+  "description": "The blueprint contributes a provider-router seam (TAC-1204) that a project's own middleware layer invokes on every authenticated request to answer one question: for this request, which configured realm record (or, at the operator's option, which other OAuth2/OIDC issuer the project may have declared elsewhere in its own middleware chain) is the authoritative source of identity? The seam is a pure function on the request shape: `route(request) -> { realmSlug, verificationMode }` or the sentinel `notThisIssuer` when the routing decision hands off to a middleware layer above this blueprint's mechanism reach. The seam does NOT itself name any second issuer; the blueprint is Keycloak-committed and the seam's role is to make explicit the ONE point in the request-processing chain where a project that has chosen to consult two issuers can wire that decision. A project that has only Keycloak configured wires the seam to a constant realmSlug and the mechanism is unchanged. The routing decision is expressed in generic OAuth2/OIDC vocabulary (a header the middleware layer inspects, a request-path prefix, a claim on a preflight token) and refuses to embed any concrete deployment shape.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A project may sit in a deployment where a receiving system's request stream carries tokens issued by more than one server. The blueprint stays vendor-committed to Keycloak: it does not name a second issuer, it does not describe a specific dual-provider integration, and it does not contribute an ADR that fixes what the second issuer is. What it does contribute is the seam a project's own middleware needs when it holds that decision: the SHAPE of the routing function and the exact seam location in the request-processing chain. Naming this seam explicitly, in generic vocabulary, is the ratified provider-aware install-design shape; without it, a project that had that need would hand-wire the decision somewhere in its handlers where the ship gate cannot see it, and every downstream reader of the codebase would guess where the routing lived.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:05-provider-routing"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Role extraction reads from Keycloak's client-roles or realm-roles claim shape",
+  "description": "Keycloak places roles on two claim families the operator selects between when configuring the client: `resource_access.<clientId>.roles` (per-client roles, the recommended default) and `realm_access.roles` (realm-wide roles). The realm record's `roleClaimShape` field declares which family this client uses (`client-roles` or `realm-roles`); the role adapter (TAC-1205) reads roles from that path on every verified token and populates the reduced Principal's `roles[]` array with the resulting string list. A token whose expected claim path is absent yields an empty `roles[]` (not a refusal); a project that wants stricter behaviour (a specific claim path must be present, or a specific role must be present, or the request is refused) authors a project-side authoriser above the reduced Principal and does not push that policy into the mechanism. The role adapter does not remap Keycloak role strings into project-defined role vocabulary; that remapping is a project-level concern and belongs on a project-authored ADR whose `related-reqs` cites this REQ.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Every project that uses Keycloak with role-based access must decide once whether its client is a per-client roles client or a realm-roles client; that decision is a Keycloak configuration and it lives on the realm record. Pushing role extraction to a single named adapter with a small surface keeps the project's handler code path free of Keycloak claim-shape knowledge and makes the role source observable in one place. Not remapping role strings inside the mechanism keeps the mechanism generic; a project that maps Keycloak roles onto its own project-role vocabulary does that once in an enrich-Principal hook the session-bridge invokes.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:06-roles"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Refresh-token rotation follows the realm's configured rotation model",
+  "description": "Keycloak issues refresh tokens with a per-realm rotation configuration; the operator chooses at the realm layer whether refresh-token reuse is a hard fail (rotation with revoke-on-reuse) or a soft rotation (return a new refresh but let the old one live to expiry). The blueprint's refresh handler presents the current stored refresh token on every refresh call to the realm's `token_endpoint` with `grant_type=refresh_token`, replaces the stored value with the new one on a 2xx response, and treats a 4xx `invalid_grant` on refresh as a session-invalidation signal: the project session handle is invalidated server-side, the associated refresh-token chain is cleared, and one structured audit event `keycloak.refresh_invalidated` is emitted carrying the realm slug and the session-handle hash; no token value is emitted. The blueprint does NOT re-implement reuse-detection above the realm's own model: if the realm is configured to detect reuse and revoke, the realm's `invalid_grant` response IS the signal; if the realm is configured to allow soft rotation, that is the operator's declared risk posture and the blueprint honours it. This deliberately differs from the vendor-neutral sibling's stricter uniform posture; Keycloak owns the rotation model at the realm layer.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "The vendor-neutral sibling mandates rotation-with-reuse-detection because it cannot rely on the underlying provider to enforce it; Keycloak already enforces the operator's chosen model at the realm, so the blueprint's role is to honour the realm's decision rather than to layer a second policy on top. The operator's authority stops at the realm; overriding it in project code would fight the operator's own configuration.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:07-refresh"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-008",
+  "prdId": "PRD-001",
+  "title": "Session-vs-token separation: Keycloak owns tokens; the project may issue an app session on top",
+  "description": "Keycloak is the token authority: it mints the access token, the id_token, and the refresh token; the browser never holds a project-minted JWT and the browser never holds a Keycloak refresh token. The project MAY layer an application session on top of the verified token stream: the reference wiring issues an opaque-handle session cookie whose server-side record stores the Keycloak-minted tokens keyed by the handle (mirroring the vendor-neutral sibling's opaque-handle posture, and following the composition pattern where the session-record store injects). The alternate posture the operator MAY declare is `sessionMode: 'stateless'` on the realm record, in which case no server-side session record is kept and every request re-verifies the access token from a bearer header (or a cookie carrying the token verbatim, per the operator's declared bearer source). The two postures are not composable per realm record; the operator picks one. The reduced Principal (`principalId`, `provider`, `email?`, `roles[]`, `organisationIds[]`) is the only claim shape the project's own handlers ever see; provider tokens are inaccessible from `request.auth` in both modes.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Keycloak's authority over token issuance is a vendor commitment; the blueprint's authority is over what the project builds around that stream. Two postures serve two operator populations: a stateful session-record wiring (the reference default) matches small projects that want a single opaque cookie and cheap sign-out, and a stateless bearer posture matches deployments where the project can accept per-request verification cost and wants to avoid a session store. Both postures gate provider tokens behind the mechanism boundary so no handler code path reads a Keycloak-minted token directly.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:08-session-vs-token"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-009",
+  "prdId": "PRD-001",
+  "title": "Local-first stand-up uses Keycloak's official container image; no realm data is committed",
+  "description": "The blueprint's local-first posture stands up a Keycloak realm from the vendor's official container image (`quay.io/keycloak/keycloak`; the operator pins the currently-supported stable tag at boot time and updates on the vendor's own upgrade cadence). The container is started in development mode with placeholder admin credentials the harness reads from a project environment file (never committed) and a realm-configuration seed the harness applies through the vendor's `kc.sh import` path or through the admin REST API. The seed carries a placeholder realm name (`example`), a placeholder client id, and placeholder role assignments; nothing that appears in the seed matches any real deployment. The reference asset under `assets/local-container/` names the shape a project's harness follows; the blueprint does not lift a specific compose file, a specific realm name, or a specific client id from any deployment. A project may substitute a persistent scratch service, a shared team-level container, or an alternate stand-up path (a system-installed Keycloak, a devcontainer, a Kubernetes namespace) as long as the resulting realm satisfies the discovery-endpoint shape and the client-configuration expectations REQ-002 and REQ-003 (or REQ-004) name.",
+  "category": "functional",
+  "domain": "verification",
+  "priority": "must",
+  "rationale": "Keycloak is self-hostable and the vendor publishes a container image designed for exactly this purpose; a project that wants runtime-verify against a real realm can stand one up per test suite and tear it down without paying for a cloud tenant. Committing to the official image (with an operator-chosen tag) keeps the mechanism upgradeable on the vendor's cadence rather than pinning a specific version in the blueprint. Placeholder-only seeds keep the blueprint's tree free of any deployment-shaped signal.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:09-local-stand-up"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-010.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-010",
+  "prdId": "PRD-001",
+  "title": "Sign-out invalidates the project session; Keycloak session-end is an operator-declared option",
+  "description": "A POST to the project's sign-out route invalidates the project session handle server-side and clears the session cookie (opaque-handle mode) or clears the bearer-source cookie (stateless mode); the next request from the browser is unauthenticated regardless of what the realm still holds. Provider-side sign-out through the realm's `end_session_endpoint` (RP-Initiated Logout, OIDC section) is NOT mandated: a realm record whose `providerLogout` field is `'redirect'` and whose `end_session_endpoint` is present on the discovery record causes the sign-out response to return a 302 to that endpoint after clearing the project session, with the `id_token_hint` query parameter carrying the raw id_token stored on the session record (opaque-handle mode) or the id_token the operator's declared bearer source has produced (stateless mode). A record that sets `providerLogout: 'redirect'` on a realm whose discovery omits `end_session_endpoint` is refused at boot with a stable-coded error naming the realm slug.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "The project-session invariant is `sign-out clears the project session`; RP-initiated logout is a legitimate but variable operator preference (some deployments want a full realm sign-out, others want the realm session to persist for the operator's other applications on the same realm). Declaring the posture on the realm record with a fail-fast on missing endpoint catches misconfiguration where the project believes it is signing out at the realm and silently is not.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:10-sign-out"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-011.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-011",
+  "prdId": "PRD-001",
+  "title": "Fail-safe boot when the realm is unreachable follows a declared posture",
+  "description": "A realm record declares a `bootPosture` field with three legal values: `strict` (default), `deferred`, and `standby`. Under `strict`, a discovery fetch failure at boot terminates the process with a stable-coded error naming the realm slug and the fetch failure class (`KEYCLOAK_DISCOVERY_UNREACHABLE`, `KEYCLOAK_DISCOVERY_MALFORMED`, `KEYCLOAK_DISCOVERY_TIMEOUT`); no listener is left running. Under `deferred`, the process starts, the affected realm is marked `unhealthy`, requests routed to that realm through the provider-router (REQ-005) refuse with `KEYCLOAK_REALM_UNAVAILABLE` and the discovery client (TAC-1201) attempts one exponential-backoff refresh loop bounded by `deferredRetryCapSeconds` (default 300); success populates the record and the realm goes `healthy`. Under `standby`, the process starts, the affected realm is marked `unhealthy` in the same way, and the discovery client stays quiet until a project-authored trigger (an admin route, a scheduled probe, an operator signal) calls `refresh(realmSlug)`; the operator opts in to standby only when the deployment demands manual control. A realm's health transitions are emitted as structured audit events `keycloak.realm_healthy` and `keycloak.realm_unhealthy` carrying the realm slug and the current class.",
+  "category": "functional",
+  "domain": "reliability",
+  "priority": "must",
+  "rationale": "A project deployed alongside a self-hosted realm inherits the realm's uptime characteristics. `strict` is the safest default for a small project (crash-loop until the realm is up, obvious to whoever wired the deployment); `deferred` matches deployments that want the process to survive a realm restart and self-heal; `standby` matches deployments where the operator wants to control when the process reaches the realm (for example, a migration window where a partial realm is not usable). Naming the posture on the record makes the choice a paper-trailed decision rather than a hidden retry constant.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:11-fail-safe-boot"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/requirements/security-auth-keycloak-req-012.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-keycloak-REQ-012",
+  "prdId": "PRD-001",
+  "title": "Runtime verification binds against a local Keycloak container; cloud-tenant smokes are accountBound",
+  "description": "Runtime-verify ACs on this blueprint bind against a local Keycloak realm the project stands up per REQ-009 (or an equivalent locally-runnable realm the project already operates). The local realm is real Keycloak on the wire: discovery, JWKS, `token_endpoint`, `introspection_endpoint`, and `end_session_endpoint` all speak the standards-tracked shapes the verifier and the flow controller consume. ACs that require a smoke test against a project-owned cloud-hosted Keycloak deployment or a managed Keycloak service are `accountBound`: the runtime-verify runner marks them with an `accountBound` flag and a stable-coded skip reason (`KEYCLOAK_LIVE_REALM_UNREACHABLE`) when the project does not have live deployment credentials in the runtime environment; the CI pipeline does not fail on a skipped accountBound AC, and the ship gate reads the honest coverage. A project that has live credentials wires them and the accountBound smokes light up. The introspection-mode AC (US-11105) similarly binds against a local stub introspection responder shipped as a shape in `assets/mock-introspection/`; a project may substitute a second local Keycloak realm configured for opaque tokens or an equivalent implementation.",
+  "category": "functional",
+  "domain": "verification",
+  "priority": "must",
+  "rationale": "Keycloak is self-hostable; the local-container path is the honest runtime-verify surface and needs no external account. Cloud-hosted realm smokes are still valuable for a project that operates one but are not achievable in every CI environment, so the accountBound posture keeps CI honest without demanding a cloud realm every consumer maintains. The introspection stub covers the shape of the alternate verification mode without demanding a second Keycloak container per test suite (though a project may run one if it prefers a real endpoint).",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:12-verify-posture"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/tacs/tac-1201-security-auth-keycloak-discovery-client.json

@@ -0,0 +1,51 @@
+{
+  "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Keycloak realm discovery client",
+  "purpose": "The module that fetches, validates, and caches the OIDC discovery document for every configured realm record. Owns the boot-time discovery fetch, the fail-safe posture per REQ-011, the refresh cadence, and the endpoint-projection onto the realm record the other TACs read. Does NOT own token verification and does NOT own request routing; those are TAC-1202/TAC-1203 and TAC-1204 respectively.",
+  "responsibilities": [
+    "Fetch `<issuerBaseUrl>/realms/<realm>/.well-known/openid-configuration` at boot for every realm record; parse the response; populate the record's endpoint fields from the response (AC-11102-1, AC-11102-2).",
+    "Refuse boot under `bootPosture: strict` on any fetch failure with a stable-coded error naming the realm slug and the failure class (`KEYCLOAK_DISCOVERY_UNREACHABLE`, `KEYCLOAK_DISCOVERY_MALFORMED`, `KEYCLOAK_DISCOVERY_TIMEOUT`) (AC-11111-1).",
+    "Under `bootPosture: deferred`, mark the affected realm `unhealthy`, run an exponential-backoff refresh loop bounded by `deferredRetryCapSeconds`, and flip to `healthy` on the first success (AC-11111-2).",
+    "Under `bootPosture: standby`, mark the affected realm `unhealthy` and expose a `refresh(realmSlug)` method the project's admin surface calls (AC-11111-3).",
+    "Verify that the discovery response carries the endpoints the record's `verificationMode` depends on: `jwks_uri` when mode is `jwks`, `introspection_endpoint` when mode is `introspection`; refuse boot with `KEYCLOAK_DISCOVERY_MISSING_ENDPOINT` on absence (AC-11102-3).",
+    "Verify that a record whose `providerLogout` is `'redirect'` maps to a discovery response that carries `end_session_endpoint`; refuse boot with `KEYCLOAK_LOGOUT_NOT_DECLARED` on absence (AC-11110-2, related to REQ-010).",
+    "Refresh the discovery document at the realm record's `discoveryRefreshSeconds` cadence (default 3600) in a background loop; a refresh failure logs a warning event but does not flip a healthy realm to unhealthy - the failure is transient by policy (AC-11102-2).",
+    "Emit structured audit events `keycloak.realm_healthy`, `keycloak.realm_unhealthy`, `keycloak.discovery_refreshed`, `keycloak.discovery_refused` carrying the realm slug; no field carries a client secret."
+  ],
+  "internalStructure": "One factory function producing a discovery-client closure over an injected `realmConfig` module (a plain data-record set the project maintains), an injected `httpFetch` port (the process HTTP client), an injected `clock`, an injected `auditSink`, and an injected `retryScheduler` used by the deferred posture. The internal cache is a Map keyed by realmSlug whose value is `{ endpoints, fetchedAt, health }`; refresh replaces atomically.",
+  "interfaces": [
+    {
+      "name": "realmConfig",
+      "kind": "read-api",
+      "description": "The project-authored realm-config module exposing `list() -> record[]`. Each record is a plain object with `{ realmSlug, issuerBaseUrl, realmName, clientId, clientSecret, verificationMode, roleClaimShape, scopes, redirectUri, providerLogout, sessionMode, bearerSource?, jwksCacheTtlSeconds?, introspectionCacheTtlSeconds?, bootPosture, deferredRetryCapSeconds?, discoveryRefreshSeconds? }`."
+    },
+    {
+      "name": "httpFetch",
+      "kind": "read-api",
+      "description": "Process HTTP-fetch port used for discovery pulls; test harness substitutes an in-process mock or points at a local Keycloak container."
+    },
+    {
+      "name": "clock",
+      "kind": "read-api",
+      "description": "Injected time source for TTL and refresh-cadence bookkeeping."
+    },
+    {
+      "name": "retryScheduler",
+      "kind": "callback",
+      "description": "Exponential-backoff scheduler used under bootPosture: deferred; caps the retry envelope at deferredRetryCapSeconds and reports success or exhaustion."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with `{ event, realmSlug, class?, at }`; never invoked with a clientSecret or a token value."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "Fixing discovery at boot and refreshing on a fixed cadence trades a small piece of background work for the guarantee that the realm's URL layout can change under the process without a code edit. Three fail-safe postures let the operator pick their preferred crash-loop / self-heal / manual-control shape; the trade against a single hardcoded posture is one record field and a small policy branch. Emitting audit events on health transitions makes an unhealthy realm legible in the project's own log stream rather than only in the realm's operations surface.",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/tacs/tac-1202-security-auth-keycloak-jwt-verifier.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Keycloak JWT verifier",
+  "purpose": "The verifier the mechanism uses when the realm record's `verificationMode` is `jwks`. Owns the JWKS fetch cache with kid-miss refresh, the signature check, the standard-claims validation, and the extraction of the verified claim record the role adapter reads. Does NOT own the token stream (that is the flow controller in the sibling blueprints' vocabulary, delegated here to a project-side authorisation-code state machine that a project either authors above this blueprint or draws from the vendor-neutral sibling if composed).",
+  "responsibilities": [
+    "Fetch and cache the realm's JWKS by realmSlug; TTL is the record's `jwksCacheTtlSeconds` (default 900); refresh from the head of the cache queue at expiry (AC-11103-1).",
+    "Verify signature against a key resolved by `kid`; on a kid-miss trigger exactly one JWKS refresh; refuse the token with `KEYCLOAK_JWT_KID_UNKNOWN` when the refresh does not surface the kid (AC-11103-2).",
+    "Validate the standard claim set: `iss` equals the record's discovered issuer; `aud` contains the record's `clientId` OR `azp` equals it; `exp` in the future by at least one second; `nbf` not in the future; `iat` in the past by no more than `idTokenMaxAgeSeconds` (AC-11104-1).",
+    "Refuse with `KEYCLOAK_JWT_EXPIRED`, `KEYCLOAK_JWT_ISSUER_MISMATCH`, `KEYCLOAK_JWT_AUDIENCE_MISMATCH`, or `KEYCLOAK_JWT_SIGNATURE_INVALID` per failure class; emit one structured audit event `keycloak.jwt_refused` carrying realmSlug, reasonClass, and no token value (AC-11104-2).",
+    "Return the verified claim record `{ sub, email?, azp, iss, aud, exp, iat, resource_access?, realm_access?, plus other realm-declared claims }` to the caller; the caller (the role adapter, the session-bridge in opaque-handle mode, the bearer verifier in stateless mode) consumes from that record (AC-11101-3).",
+    "Refuse a JWKS fetch failure at verification time with `KEYCLOAK_JWKS_UNREACHABLE`; the token is refused, not silently trusted (AC-11103-2)."
+  ],
+  "internalStructure": "One factory function producing a verify closure over the injected discovery-client (TAC-1201, which exposes the record's discovered endpoints), an injected `httpFetch` port for JWKS, an injected clock, and an injected auditSink. The JWKS cache is a Map keyed by realmSlug whose value is `{ keys[], fetchedAt }`; the crypto is either the process's Web Crypto (Node 20+) or a project-injected primitive.",
+  "interfaces": [
+    {
+      "name": "discoveryClient",
+      "kind": "read-api",
+      "description": "TAC-1201's exported endpoint-record accessor: `endpoints(realmSlug) -> { issuer, jwksUri, ... }`."
+    },
+    {
+      "name": "httpFetch",
+      "kind": "read-api",
+      "description": "Process HTTP-fetch port; shared with the discovery client."
+    },
+    {
+      "name": "clock",
+      "kind": "read-api",
+      "description": "Injected time source for TTL and expiry checks."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink; never invoked with a token value."
+    }
+  ],
+  "dependencies": [
+    { "name": "Discovery client", "kind": "tac", "tacId": "TAC-1201-security-auth-keycloak-discovery-client", "description": "Reads the realm's discovered endpoints." }
+  ],
+  "tradeoffs": "TTL-plus-kid-miss caching is the standard shape for JWKS verification; the trade against a shorter TTL is one background refresh per window; against a longer TTL is a bounded staleness window. Refusing on a kid-miss after one refresh defends against amplification while still recovering from a rotation the realm has published. Fixed refusal codes make failure classes observable in the audit stream without a runtime taxonomy the operator has to learn.",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/tacs/tac-1203-security-auth-keycloak-introspection-client.json

@@ -0,0 +1,45 @@
+{
+  "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Keycloak introspection client (RFC 7662)",
+  "purpose": "The verifier the mechanism uses when the realm record's `verificationMode` is `introspection`. Owns the RFC 7662 request shape (HTTP basic auth with `clientId:clientSecret`, `token` form parameter), the response handling, the optional short-lived cache, and the extraction of the verified claim record the role adapter reads.",
+  "responsibilities": [
+    "Issue a POST to the record's `introspection_endpoint` with `Content-Type: application/x-www-form-urlencoded`, `Authorization: Basic <base64(clientId:clientSecret)>`, and body `token=<the-access-token>` (AC-11105-1).",
+    "Parse the response body as JSON per RFC 7662; a response with `active: true` yields the claim record; a response with `active: false` refuses the token with `KEYCLOAK_INTROSPECTION_INACTIVE` (AC-11105-2).",
+    "Refuse a non-2xx response with `KEYCLOAK_INTROSPECTION_ENDPOINT_ERROR` naming the HTTP status class; emit `keycloak.introspection_refused` carrying realmSlug and status class (AC-11105-3).",
+    "Cache the response when the record's `introspectionCacheTtlSeconds` is greater than zero; cache key is a stable hash of the token value (SHA-256 hex prefix, never the token) so the cache does not carry token strings; default TTL is 0 (no cache); AC-11105-1 covers the uncached path.",
+    "Emit one structured audit event `keycloak.introspection_verified` on a 2xx `active: true` carrying realmSlug and no token value (AC-11105-1)."
+  ],
+  "internalStructure": "One factory function producing an introspect closure over the discovery client (for the endpoint), an injected `httpFetch`, an injected clock, and an injected auditSink. The optional cache is a Map keyed by the token-hash whose value is `{ claims, cachedAt }`; entries evict on TTL expiry from the read path.",
+  "interfaces": [
+    {
+      "name": "discoveryClient",
+      "kind": "read-api",
+      "description": "TAC-1201's exported endpoint-record accessor for `introspection_endpoint`."
+    },
+    {
+      "name": "httpFetch",
+      "kind": "read-api",
+      "description": "Process HTTP-fetch port."
+    },
+    {
+      "name": "clock",
+      "kind": "read-api",
+      "description": "Injected time source."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink; never invoked with a token value."
+    }
+  ],
+  "dependencies": [
+    { "name": "Discovery client", "kind": "tac", "tacId": "TAC-1201-security-auth-keycloak-discovery-client", "description": "Provides the introspection endpoint from discovery." }
+  ],
+  "tradeoffs": "The introspection round-trip is expensive on the hot path; the optional cache lets an operator on a high-issuance realm claw back some of the cost at the price of a bounded revocation-reflection delay. Hashing the token as the cache key defends against a leaked cache dump: nothing on disk (or in a warmed memory dump) is a token; the hash cannot be exchanged. Refusing on non-2xx keeps the mechanism from falling back to a permissive posture when the endpoint is misbehaving.",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/contributions/tacs/tac-1204-security-auth-keycloak-provider-router.json

@@ -0,0 +1,37 @@
+{
+  "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Provider router (issuer-selection seam)",
+  "purpose": "The named seam a project's own middleware invokes on every authenticated request to decide which realm record (or, at the operator's option, the sentinel `notThisIssuer` when the middleware layer above hands the decision off) is authoritative for the request. Does NOT own token verification and does NOT itself name any second issuer.",
+  "responsibilities": [
+    "Expose `route(request) -> { realmSlug, verificationMode } | notThisIssuer` as a pure function on the request shape; the function is injected by the project and the reference wiring provides a constant-realm implementation for the common single-realm deployment (AC-11106-1).",
+    "Refuse a routing decision that names a realmSlug not present in the realmConfig list with `KEYCLOAK_REALM_UNKNOWN`; the mechanism does not silently fall back to a default realm (AC-11106-2).",
+    "Honour the `notThisIssuer` sentinel by returning it verbatim to the caller (the project's own middleware chain); the mechanism does not decide what a caller does with the sentinel (AC-11106-3).",
+    "Emit one structured audit event per routing decision `keycloak.route_decided` carrying realmSlug (or the string `notThisIssuer`) and no request-content field."
+  ],
+  "internalStructure": "One factory function producing a router closure over an injected `routeFn` (the project-authored pure function) and an injected realmConfig list. The reference wiring is a constant-realm `routeFn` that returns the first configured realmSlug for every request; a multi-realm project supplies its own routeFn. The routeFn is the seam the ratified reshape ruling names in generic vocabulary; the blueprint refuses to inspect specific request features or to name any second issuer.",
+  "interfaces": [
+    {
+      "name": "routeFn",
+      "kind": "callback",
+      "description": "Pure function `(request) -> { realmSlug, verificationMode } | 'notThisIssuer'`. Project-authored; the blueprint's reference wiring provides a constant-realm default for single-realm projects."
+    },
+    {
+      "name": "realmConfig",
+      "kind": "read-api",
+      "description": "Same source TAC-1201 reads: the project-authored realm-config module."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink; never carries request content."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The seam is one function call and one config-record lookup on every request; the cost is negligible and the observability payoff scales with deployment complexity. Refusing to name a second issuer keeps the blueprint faithful to the ratified reshape ruling; a project that has one names it on a project-level ADR whose scope names the second issuer explicitly. Refusing an unknown realmSlug rather than falling back to a default matches the sibling's multi-provider-routing posture: no silent defaults.",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}