rcf-lite 0.26.0 → 0.27.0

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

@@ -1,7 +1,14 @@
 {
   "slug": "security-auth-keycloak",
-  "version": "1.2.0",
+  "version": "1.4.1",
   "category": "security",
+  "requiresAppliedCapabilities": {
+    "capabilities": [
+      "authorisationCodeFlow"
+    ],
+    "allowSkipFlag": "allow-no-auth-yet",
+    "refusalMessageId": "security-auth-keycloak-flow-required"
+  },
   "capabilities": [
     "principalDirectory",
     "roleModel",
@@ -190,6 +197,99 @@
       "id": "ADR-1206-security-auth-keycloak-refresh-and-sign-out-posture",
       "kind": "adr",
       "path": "adrs/adr-1206-security-auth-keycloak-refresh-and-sign-out-posture.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-013",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-013.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11114",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11114.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-014",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-014.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11115",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11115.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-015",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-015.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-016",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-016.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-017",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-017.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-018",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-018.json"
+    },
+    {
+      "id": "security-auth-keycloak-REQ-019",
+      "kind": "req",
+      "path": "requirements/security-auth-keycloak-req-019.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11116",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11116.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11117",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11117.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11118",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11118.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11119",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11119.json"
+    },
+    {
+      "id": "security-auth-keycloak-US-11120",
+      "kind": "us",
+      "path": "user-stories/security-auth-keycloak-us-11120.json"
+    }
+  ],
+  "elicits": [
+    {
+      "id": "boot-posture",
+      "prompt": "How should the blueprint behave when a realm's OIDC discovery is not reachable at boot?",
+      "kind": "enum",
+      "default": "strict",
+      "options": [
+        "strict",
+        "deferred",
+        "standby"
+      ]
+    },
+    {
+      "id": "verification-mode",
+      "prompt": "How should the blueprint verify tokens for a given realm?",
+      "kind": "enum",
+      "default": "jwks",
+      "options": [
+        "jwks",
+        "introspection"
+      ]
     }
   ]
 }

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

@@ -2,7 +2,7 @@
   "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.",
+  "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. This blueprint composes over `security-auth-oauth2` for the authorisation-code + PKCE flow controller (TAC-1101) and the session-bridge (TAC-1103); keycloak contributes the discovery client, JWT verifier, introspection client, provider router, role adapter, and its own `sessionInventory` and `credentialSelfService` surfaces on top of that flow. The composition prerequisite is declared machine-readably by the blueprint's `blueprint.json:requiresAppliedCapabilities` gate on the `authorisationCodeFlow` capability (provided by `security-auth-oauth2` or a superseding flow-owner); a project that applies keycloak without an applied provider of `authorisationCodeFlow` is refused at apply time with a stable-coded error naming both blueprint slugs, and the override lives at `--allow-no-auth-yet` for staged-scaffolding runs.",
   "category": "functional",
   "domain": "authentication",
   "priority": "must",
@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1201-security-auth-keycloak-auth-model"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+    "field": "responsibilities.discovery"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+    "field": "responsibilities.jwksCacheTtlSeconds"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+    "field": "responsibilities.introspection"
+  }
 }

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

@@ -2,7 +2,7 @@
   "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.",
+  "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 whose signature and return shape are owned by `TAC-1204-security-auth-keycloak-provider-router` `responsibilities.route` (returning the routed realm record 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 record 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",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+    "field": "responsibilities.route"
+  }
 }

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

@@ -2,7 +2,7 @@
   "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.",
+  "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. The `roles[]` field on the reduced Principal is the sole role vocabulary the project reads; the role adapter is the mechanism by which the blueprint contributes the `roleModel` capability into the applied capability set. The reduced Principal produced by the role adapter is also the blueprint's `principalDirectory` contribution: no other read-side surface on the project answers \"who is the caller\".",
   "category": "functional",
   "domain": "authentication",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+    "field": "responsibilities.roles"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1206-security-auth-keycloak-refresh-and-sign-out-posture"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1204-security-auth-keycloak-session-vs-token-contract"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1201-security-auth-keycloak-auth-model"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1206-security-auth-keycloak-refresh-and-sign-out-posture"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+    "field": "responsibilities.bootPosture"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-31T00:00:00Z",
-  "updatedAt": "2026-08-31T00:00:00Z"
+  "updatedAt": "2026-08-31T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1201-security-auth-keycloak-auth-model"
+  }
 }

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": [