rcf-lite 0.26.0 → 0.28.0

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-013",
+  "prdId": "PRD-001",
+  "title": "Password change, reset and recovery are delegated to the realm's Keycloak account console",
+  "description": "The blueprint contributes the `credentialSelfService` capability by resolving and exposing the realm's Keycloak account console (`<issuerBaseUrl>/realms/<realm>/account`) as the sole self-service surface for password change, password reset, account recovery, and MFA enrolment. No project route renders a credential-change form of its own. The realm-config record declares an `accountConsoleUrl` field that the discovery client verifies on boot (the URL responds with a 2xx from an unauthenticated GET); a realm whose account console is disabled or unreachable is refused at boot with `KEYCLOAK_ACCOUNT_CONSOLE_UNREACHABLE`. The project exposes a project-authored `getCredentialSelfServiceUrl()` helper that returns the resolved account console URL for the current realm; a project page linking to self-service reads that helper rather than hard-coding a URL.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A capability declaration without a delegated-self-service contract lets a consumer bind against `credentialSelfService` and render a self-service link that either resolves to nothing or lands on a broken realm surface. Naming the realm-config field and the boot-time verification is what makes the capability observable at apply time.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:13-credential-self-service"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+    "field": "responsibilities.accountConsoleUrl"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-014",
+  "prdId": "PRD-001",
+  "title": "The caller's active project sessions are enumerable, revocable one at a time, and revocable in bulk-except-current",
+  "description": "The blueprint contributes the `sessionInventory` capability against its own project-issued session store (the opaque-handle session store the session-vs-token contract chooses when the record is in opaque-handle mode). An authenticated caller can list their active project sessions, revoke one non-current session by id, and revoke every active session except the one making the call. Each list row carries `{ sessionId, deviceLabel, lastActive, currentSession }`; the interface shape is inherited by reference from `security-auth-clerk` `TAC-1003` `interfaces.sessionInventory` and is not restated on keycloak. Every operation refuses an unauthenticated caller with `SESSION_INVENTORY_UNAUTHENTICATED`; every operation emits one structured audit event carrying operation, session id prefix and wall-clock timestamp; no field carries a full session id or a raw Keycloak token.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A capability declaration without a REQ backing the surface leaves consumers to bind against a contract keycloak never wrote down. The cross-blueprint reference keeps the interface shape single-owner (clerk's TAC-1003) while letting each auth blueprint fulfil the capability against its own session store.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:14-session-inventory"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+    "field": "responsibilities.sessionInventory"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-015",
+  "prdId": "PRD-001",
+  "title": "Discovery-client and account-console interactions emit one structured audit event per named interaction",
+  "description": "The discovery client and the account-console verification (both on TAC-1201) emit exactly one structured audit event per named interaction from the `keycloak.discovery` and `keycloak.account_console` families. Every event carries fields drawn from the fixed allow-list `family` (one of `keycloak.discovery`, `keycloak.account_console`), `outcome`, `reasonClass?`, `realmSlug`, `at`. No event may carry a token value (access token, id token, refresh token, introspection response body), a client secret, a raw claim record, or a substring of any of the above. The audit sink is contributed by the composed observability blueprint (or by a project-authored sink under the same interface); a sink failure logs a `keycloak.audit_sink_failed` warning event and never masks the underlying refusal. The other keycloak-side surfaces (JWT verifier, introspection client, provider router, sessionInventory, role adapter) each carry their own audit contract on the TAC that owns the surface (REQ-016 through REQ-019); the token-exclusion rule and the sink-failure posture named here apply verbatim to each of them.",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "The five TACs each require structured audit events with slightly different fields; without a cross-cutting REQ naming the allow-list and the token-exclusion rule, a reviewer cannot decide whether a new event field is inside the blueprint's contract. The REQ also anchors the sink-failure posture the guide implies but never states at REQ level.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:15-audit-surface"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+    "field": "responsibilities.discoveryAudit"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-016",
+  "prdId": "PRD-001",
+  "title": "JWT verifier interactions emit one structured audit event per named interaction",
+  "description": "The JWT verifier emits exactly one structured audit event per verify call from the `keycloak.jwt` family (verified, refused with reasonClass in `expired`, `issuer_mismatch`, `audience_mismatch`, `signature_invalid`). Every event carries fields drawn from the fixed allow-list `family` (`keycloak.jwt`), `outcome`, `reasonClass?`, `realmSlug`, `at`. No event may carry a token value (access token, id token, refresh token, introspection response body), a client secret, a raw claim record, or a substring of any of the above. The audit sink is the same one REQ-015 names; sink-failure posture is inherited verbatim (a sink failure logs a `keycloak.audit_sink_failed` warning event and never masks the underlying refusal).",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A single cross-cutting audit REQ pointing at one TAC hides ownership when the delivery is spread across TACs. Each TAC that emits an audit family owns its own REQ so a reviewer can see the ownership at a glance and so a future author changing an audit family finds the single REQ that governs it.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:15-audit-surface"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+    "field": "responsibilities.jwtAudit"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-017",
+  "prdId": "PRD-001",
+  "title": "Introspection client interactions emit one structured audit event per named interaction",
+  "description": "The introspection client emits exactly one structured audit event per introspect call from the `keycloak.introspection` family (verified on `active: true`, refused on `active: false` or non-2xx). Every event carries fields drawn from the fixed allow-list `family` (`keycloak.introspection`), `outcome`, `reasonClass?`, `realmSlug`, `at`. No event may carry a token value (access token, id token, refresh token, introspection response body), a client secret, a raw claim record, or a substring of any of the above. The audit sink is the same one REQ-015 names; sink-failure posture is inherited verbatim (a sink failure logs a `keycloak.audit_sink_failed` warning event and never masks the underlying refusal).",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A single cross-cutting audit REQ pointing at one TAC hides ownership when the delivery is spread across TACs. Each TAC that emits an audit family owns its own REQ so a reviewer can see the ownership at a glance and so a future author changing an audit family finds the single REQ that governs it.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:15-audit-surface"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+    "field": "responsibilities.introspectionAudit"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-018",
+  "prdId": "PRD-001",
+  "title": "Provider-router routing decisions and sessionInventory operations emit one structured audit event per named interaction",
+  "description": "The provider router and the sessionInventory surface (both on TAC-1204) emit exactly one structured audit event per named interaction from the `keycloak.route` and `keycloak.session_inventory` families (route decided, session listed, session revoked one, sessions revoked all-except-current, refused when unauthenticated). Every event carries fields drawn from the fixed allow-list `family` (one of `keycloak.route`, `keycloak.session_inventory`), `outcome`, `reasonClass?`, `realmSlug`, `sessionIdPrefix?`, `at`. No event may carry a token value (access token, id token, refresh token, introspection response body), a client secret, a raw claim record, or a substring of any of the above. The audit sink is the same one REQ-015 names; sink-failure posture is inherited verbatim (a sink failure logs a `keycloak.audit_sink_failed` warning event and never masks the underlying refusal).",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A single cross-cutting audit REQ pointing at one TAC hides ownership when the delivery is spread across TACs. Each TAC that emits an audit family owns its own REQ so a reviewer can see the ownership at a glance and so a future author changing an audit family finds the single REQ that governs it.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:15-audit-surface"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+    "field": "responsibilities.routeAndSessionAudit"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-keycloak-REQ-019",
+  "prdId": "PRD-001",
+  "title": "Role-adapter interactions emit one structured audit event per named interaction",
+  "description": "The role adapter emits exactly one structured audit event per read call from the `keycloak.roles` family (read on a well-formed claim, refused with reasonClass `malformed` when the expected path is present but not an array of strings). Every event carries fields drawn from the fixed allow-list `family` (`keycloak.roles`), `outcome`, `reasonClass?`, `realmSlug`, `at`. No event may carry a token value (access token, id token, refresh token, introspection response body), a client secret, a raw claim record, or a substring of any of the above. The audit sink is the same one REQ-015 names; sink-failure posture is inherited verbatim (a sink failure logs a `keycloak.audit_sink_failed` warning event and never masks the underlying refusal).",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A single cross-cutting audit REQ pointing at one TAC hides ownership when the delivery is spread across TACs. Each TAC that emits an audit family owns its own REQ so a reviewer can see the ownership at a glance and so a future author changing an audit family finds the single REQ that governs it.",
+  "tags": [
+    "blueprint:security-auth-keycloak",
+    "category:15-audit-surface"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+    "field": "responsibilities.rolesAudit"
+  }
+}

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

@@ -14,7 +14,9 @@
     "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."
+    "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.",
+    "Verify each realm record's `accountConsoleUrl` on boot with an unauthenticated GET returning 2xx; refuse with `KEYCLOAK_ACCOUNT_CONSOLE_UNREACHABLE` on non-2xx or connection failure; refuse with `KEYCLOAK_ACCOUNT_CONSOLE_MALFORMED` when the URL's origin differs from the discovered issuer origin; a null `accountConsoleUrl` is legal and leaves the realm without a `credentialSelfService` binding (AC-11114-1, AC-11114-4, AC-11114-5).",
+    "Audit each discovery fetch and each account-console verification as one `keycloak.discovery` or `keycloak.account_console` audit event on the allow-list REQ-015 declares (`family`, `outcome`, `reasonClass?`, `realmSlug`, `at`); the token-exclusion rule and sink-failure posture inherit from REQ-015 (discoveryAudit)."
   ],
   "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": [
@@ -47,5 +49,5 @@
   "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"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

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

@@ -12,7 +12,8 @@
     "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)."
+    "Refuse a JWKS fetch failure at verification time with `KEYCLOAK_JWKS_UNREACHABLE`; the token is refused, not silently trusted (AC-11103-2).",
+    "Audit each verify call as one `keycloak.jwt` audit event on the allow-list REQ-016 declares (`family`, `outcome`, `reasonClass?`, `realmSlug`, `at`); the token-exclusion rule and sink-failure posture inherit from REQ-015 (jwtAudit)."
   ],
   "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": [
@@ -38,7 +39,12 @@
     }
   ],
   "dependencies": [
-    { "name": "Discovery client", "kind": "tac", "tacId": "TAC-1201-security-auth-keycloak-discovery-client", "description": "Reads the realm's discovered endpoints." }
+    {
+      "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",

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

@@ -11,7 +11,8 @@
     "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)."
+    "Emit one structured audit event `keycloak.introspection_verified` on a 2xx `active: true` carrying realmSlug and no token value (AC-11105-1).",
+    "Audit each introspect call as one `keycloak.introspection` audit event on the allow-list REQ-017 declares (`family`, `outcome`, `reasonClass?`, `realmSlug`, `at`); the token-exclusion rule and sink-failure posture inherit from REQ-015 (introspectionAudit)."
   ],
   "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": [
@@ -37,7 +38,12 @@
     }
   ],
   "dependencies": [
-    { "name": "Discovery client", "kind": "tac", "tacId": "TAC-1201-security-auth-keycloak-discovery-client", "description": "Provides the introspection endpoint from discovery." }
+    {
+      "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",

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

@@ -10,7 +10,9 @@
     "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."
+    "Emit one structured audit event per routing decision `keycloak.route_decided` carrying realmSlug (or the string `notThisIssuer`) and no request-content field.",
+    "Expose `sessionInventory` for the authenticated caller against the project's Keycloak session store (list, revoke-one, revoke-all-except-current); the interface shape is owned by `TAC-1003-security-auth-clerk-session-verifier` `interfaces.sessionInventory` and referenced by that owner id (AC-11115-1, AC-11115-2, AC-11115-3, AC-11115-4, AC-11115-5).",
+    "Audit each routing decision and each sessionInventory operation as one `keycloak.route` or `keycloak.session_inventory` audit event on the allow-list REQ-018 declares (`family`, `outcome`, `reasonClass?`, `realmSlug`, `sessionIdPrefix?`, `at`); the token-exclusion rule and sink-failure posture inherit from REQ-015 (routeAndSessionAudit)."
   ],
   "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": [

package/blueprints/security-auth-keycloak/contributions/tacs/tac-1205-security-auth-keycloak-role-adapter.json

@@ -10,7 +10,8 @@
     "Read roles from the verified claim record at the path declared by `roleClaimShape`: `client-roles` reads from `resource_access.<clientId>.roles`; `realm-roles` reads from `realm_access.roles` (AC-11107-1).",
     "Populate the reduced Principal's `roles[]` with the resulting string list, or an empty array when the path is absent (not a refusal - the project's authoriser above the Principal decides whether an empty roles set is acceptable) (AC-11107-2).",
     "Refuse a claim record whose expected path is present but not an array of strings with `KEYCLOAK_ROLES_MALFORMED`; emit `keycloak.roles_refused` carrying realmSlug and reason class (AC-11107-3).",
-    "Never remap or transform Keycloak role strings; a project that maps them onto its own project-role vocabulary authors an `enrichPrincipal` hook the session-bridge invokes after the role adapter has populated the raw roles."
+    "Never remap or transform Keycloak role strings; a project that maps them onto its own project-role vocabulary authors an `enrichPrincipal` hook the session-bridge invokes after the role adapter has populated the raw roles.",
+    "Audit each roles read as one `keycloak.roles` audit event on the allow-list REQ-019 declares (`family`, `outcome`, `reasonClass?`, `realmSlug`, `at`); the token-exclusion rule and sink-failure posture inherit from REQ-015 (rolesAudit)."
   ],
   "internalStructure": "One factory function producing an adapt closure over the realmConfig record (for the record's `roleClaimShape` and `clientId`). The read is a plain object-path lookup; the shape checks are structural.",
   "interfaces": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11101.json

@@ -16,7 +16,8 @@
       "when": "the request is dispatched and the response is inspected",
       "then": "the response is a 302 whose `Location` starts with the realm's discovered `authorization_endpoint`; the query carries `response_type=code`, `code_challenge` matching `^[A-Za-z0-9_-]{43,128}$`, `code_challenge_method=S256`, a `state` value distinct from any prior observed value in the test collector; no `response_type=token` or `access_type=implicit` is present",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11101-2",
@@ -25,7 +26,8 @@
       "when": "the browser follows the realm's redirect back to the project's callback route",
       "then": "the flow controller issues a POST to the realm's `token_endpoint` whose body carries `grant_type=authorization_code`, the returned `code`, `client_id`, `code_verifier` (matching the stored verifier), and `redirect_uri`; the response is a 2xx carrying `access_token` and `id_token`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11101-3",
@@ -34,7 +36,8 @@
       "when": "the browser inspects the response cookie jar",
       "then": "a session cookie declared by the project's session-cookie name is set with `Secure`, `HttpOnly`, `SameSite=Lax`; the cookie value does not equal the access_token, the id_token, or any refresh_token returned by the realm; the reduced Principal on the next protected-route request carries `principalId` derived from `{realmSlug, sub}` and `provider` equal to the realmSlug",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11102.json

@@ -16,7 +16,8 @@
       "when": "the process boots and the discovery client runs its boot-time fetch",
       "then": "the record has fields `authorizeUrl`, `tokenUrl`, `userinfoUrl`, `jwksUri`, `introspectionEndpoint`, `endSessionEndpoint`, and `issuer` populated from the discovery response; a `keycloak.realm_healthy` audit event is emitted carrying `realmSlug='r1'`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11102-2",
@@ -25,7 +26,12 @@
       "when": "the test-injected clock advances 61 seconds and the discovery endpoint is momentarily made to return a 503 for one request",
       "then": "the refresh attempt is observed against the test-injected httpFetch; a `keycloak.discovery_refused` warning-class audit event is emitted; the realm's health stays `healthy` and the previous endpoint record continues to serve; the next successful refresh emits `keycloak.discovery_refreshed`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "interfaces.httpFetch.name"
+      },
+      "disposition": "fixed"
     },
     {
       "id": "AC-11102-3",
@@ -34,7 +40,8 @@
       "when": "the discovery client's boot fetch completes",
       "then": "the process terminates with error code `KEYCLOAK_DISCOVERY_MISSING_ENDPOINT` naming the realmSlug and the missing field `introspection_endpoint`; no listener is left running; the audit log records one `keycloak.discovery_refused` event carrying realmSlug and reason class `missing-endpoint`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11103.json

@@ -16,7 +16,12 @@
       "when": "the verifier is invoked",
       "then": "the verifier consumes the token successfully; no fresh JWKS fetch is observed against the test-injected httpFetch for the duration of this verification; the audit log records no `keycloak.jwks_refreshed` event",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "interfaces.httpFetch.name"
+      },
+      "disposition": "fixed"
     },
     {
       "id": "AC-11103-2",
@@ -25,7 +30,12 @@
       "when": "the verifier is invoked twice in the same test: once with the realm's fresh JWKS available on the injected httpFetch, once with the httpFetch instrumented to return a JWKS still missing the kid",
       "then": "the first invocation triggers one JWKS refresh (observed on the injected httpFetch), succeeds verification, emits `keycloak.jwks_refreshed`; the second invocation triggers one JWKS refresh, refuses the token with `KEYCLOAK_JWT_KID_UNKNOWN`, emits one `keycloak.jwt_refused` event carrying realmSlug and reason class `kid-unknown`; a third invocation with the same second-token does NOT trigger a further JWKS refresh within the TTL window",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "interfaces.httpFetch.name"
+      },
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11104.json

@@ -16,7 +16,8 @@
       "when": "the verifier is invoked",
       "then": "the response is a 4xx with body error code `KEYCLOAK_JWT_EXPIRED`; no session cookie is set on the response; the audit log records one `keycloak.jwt_refused` event carrying realmSlug and reason class `expired` and no token value",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11104-2",
@@ -25,7 +26,12 @@
       "when": "the verifier is invoked",
       "then": "the verifier observes one JWKS refresh against the injected httpFetch, then refuses the token with `KEYCLOAK_JWT_SIGNATURE_INVALID`; no session cookie is set; the audit log records one `keycloak.jwt_refused` event carrying realmSlug and reason class `signature`; the reason class is `signature`, not `kid-unknown` (the kid appears in JWKS; the signature under that kid does not verify)",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "interfaces.httpFetch.name"
+      },
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11105.json

@@ -16,7 +16,8 @@
       "when": "the introspection client is invoked on the token",
       "then": "the client issues a POST to the record's `introspection_endpoint` with body `token=<opaque-value>`, `Content-Type: application/x-www-form-urlencoded`, and `Authorization: Basic <base64(clientId:clientSecret)>`; the response body is parsed as JSON; the claim record from the response is returned to the caller; the audit log records one `keycloak.introspection_verified` event carrying realmSlug and no token value",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11105-2",
@@ -25,7 +26,8 @@
       "when": "the introspection client is invoked",
       "then": "the response is a 4xx with body error code `KEYCLOAK_INTROSPECTION_INACTIVE`; no session cookie is set; the audit log records one `keycloak.introspection_refused` event carrying realmSlug and reason class `inactive`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11105-3",
@@ -34,7 +36,8 @@
       "when": "the introspection client is invoked",
       "then": "the response is a 4xx with body error code `KEYCLOAK_INTROSPECTION_ENDPOINT_ERROR` and a `detail` field naming the status class as `5xx`; no session cookie is set; the audit log records one `keycloak.introspection_refused` event carrying realmSlug and reason class `endpoint-error`; the mechanism does not fall back to a permissive posture",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11106.json

@@ -16,7 +16,12 @@
       "when": "a request carrying the marker is dispatched through the mechanism",
       "then": "the verifier resolves against `r2`'s JWKS, not `r1`'s; the reduced Principal's `provider` field equals `'r2'`; the audit log records one `keycloak.route_decided` event carrying `realmSlug='r2'`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "interfaces.routeFn.name"
+      },
+      "disposition": "fixed"
     },
     {
       "id": "AC-11106-2",
@@ -25,7 +30,12 @@
       "when": "a request is dispatched",
       "then": "the response is a 4xx with body error code `KEYCLOAK_REALM_UNKNOWN`; no verifier is invoked against any realm; the audit log records one `keycloak.route_decided` event followed by one `keycloak.jwt_refused` (or equivalent) event with reason class `unknown-realm`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "interfaces.routeFn.name"
+      },
+      "disposition": "fixed"
     },
     {
       "id": "AC-11106-3",
@@ -34,7 +44,12 @@
       "when": "a request is dispatched through the mechanism",
       "then": "the mechanism returns the sentinel `notThisIssuer` to its caller (the project's own middleware chain); no JWKS fetch, no introspection call, and no session verification is observed; the audit log records one `keycloak.route_decided` event carrying `realmSlug='notThisIssuer'`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "interfaces.routeFn.name"
+      },
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11107.json

@@ -16,7 +16,8 @@
       "when": "the role adapter is invoked on the verified claim record",
       "then": "the resulting reduced Principal's `roles[]` equals `['admin', 'editor']` in insertion order; no other role source is consulted; no `keycloak.roles_refused` event is emitted",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11107-2",
@@ -25,7 +26,8 @@
       "when": "the role adapter is invoked",
       "then": "the reduced Principal's `roles[]` equals `[]`; no error class is emitted; the audit log records no `keycloak.roles_refused` event; the mechanism does not decide whether an empty roles set is acceptable - that is the project's authoriser above the Principal",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11107-3",
@@ -34,7 +36,8 @@
       "when": "the role adapter is invoked",
       "then": "the response is a 4xx with body error code `KEYCLOAK_ROLES_MALFORMED`; the reduced Principal is not produced; the audit log records one `keycloak.roles_refused` event carrying realmSlug and reason class `malformed`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11108.json

@@ -16,7 +16,8 @@
       "when": "the next protected-route request triggers the flow controller's refresh path against the local realm",
       "then": "the flow controller issues a POST to the realm's `token_endpoint` with `grant_type=refresh_token` and `refresh_token=rt-old`; the realm returns a 2xx carrying a new `access_token` and a new `refresh_token=rt-new`; the session record now stores `rt-new` and no other refresh-token value; the pre-refresh `rt-old` is not present in the session record or the audit log",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11108-2",
@@ -25,7 +26,8 @@
       "when": "the flow controller invokes the refresh path",
       "then": "the flow controller invalidates the session handle, clears the associated refresh-token chain, and emits one structured audit event `keycloak.refresh_invalidated` carrying realmSlug and session-handle-hash and no token value; the next protected-route request with the original cookie is refused as unauthenticated",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11108-3",
@@ -34,7 +36,8 @@
       "when": "the sign-in from US-11101 completes and the access-token expiry passes on the test-injected clock",
       "then": "the session record's refresh-token slot is empty; the flow controller does not attempt a refresh call; the session's own project-lifetime expiry (per the session-bridge, in opaque-handle mode) is the sole grant duration; a protected-route request past the project-lifetime expiry is refused as unauthenticated",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11109.json

@@ -16,7 +16,8 @@
       "when": "the request is dispatched and the resolved `request.auth` object is inspected for keys",
       "then": "the object contains exactly `principalId`, `provider`, `email`, `roles`, `organisationIds`; no `accessToken`, `idToken`, `refreshToken`, or raw-claims field is present; `principalId` is a stable string starting with the realmSlug followed by a colon",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11109-2",
@@ -25,7 +26,8 @@
       "when": "the request is dispatched",
       "then": "the mechanism verifies the token, populates the reduced Principal, and does not create a session-record entry (the session-record store's `put` port is not invoked); `request.auth` carries only the fields listed in AC-11109-1; no `Set-Cookie` is emitted by the mechanism on this response",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11110.json

@@ -16,7 +16,8 @@
       "when": "the browser dispatches the sign-out request",
       "then": "the response clears the session cookie (`Set-Cookie` with the cookie name, empty value, `Max-Age=0`, `HttpOnly`, `Secure`, `SameSite=Lax`); the session-record store no longer holds a record for the pre-signout session handle; the next protected-route request replaying the pre-signout cookie value is refused as unauthenticated",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11110-2",
@@ -25,7 +26,8 @@
       "when": "the sign-out route is invoked",
       "then": "the response status is 302; the `Location` header equals the discovered `end_session_endpoint` with the configured `post_logout_redirect_uri` and, when the id_token is available on the session record, the `id_token_hint` query parameter carrying the raw id_token; the session cookie is cleared on the same response; the session record is deleted",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11110-3",
@@ -34,7 +36,8 @@
       "when": "the discovery client's boot fetch completes",
       "then": "the process terminates with error code `KEYCLOAK_LOGOUT_NOT_DECLARED` naming the realm slug; no listener is left running; the audit log records one `keycloak.discovery_refused` event carrying realmSlug and reason class `logout-endpoint-missing`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-keycloak/contributions/user-stories/security-auth-keycloak-us-11111.json

@@ -16,7 +16,8 @@
       "when": "the process boots and the discovery client runs its boot-time fetch",
       "then": "the process exits with error code `KEYCLOAK_DISCOVERY_UNREACHABLE` naming the realm slug and the fetch-failure class; no listener is bound; the audit log records one `keycloak.discovery_refused` event with reason class `unreachable`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-11111-2",
@@ -25,7 +26,12 @@
       "when": "the process boots and the retry loop runs against the test-injected clock and retryScheduler",
       "then": "the process is bound on its listener; requests routed to the realm through the provider-router refuse with `KEYCLOAK_REALM_UNAVAILABLE` while the realm is unhealthy; the audit log records `keycloak.realm_unhealthy` at boot and `keycloak.realm_healthy` on the fourth attempt's success; the retryScheduler observes exponential backoff bounded by the 30-second cap",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "interfaces.retryScheduler.name"
+      },
+      "disposition": "fixed"
     },
     {
       "id": "AC-11111-3",
@@ -34,7 +40,12 @@
       "when": "the process boots, then a project-authored admin route invokes `discoveryClient.refresh('r1')` after boot",
       "then": "at boot the realm is `unhealthy` and no refresh loop is running; on the admin-route invocation the discovery client fetches, populates the record, marks the realm `healthy`, and emits `keycloak.realm_healthy`; no `keycloak.discovery_refused` events are emitted for this realm during the standby window before the refresh",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "interfaces.discoveryClient.name"
+      },
+      "disposition": "fixed"
     }
   ],
   "tacIds": [