rcf-lite 0.12.0 → 0.14.0

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-keycloak-US-11102",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Discovery is fetched at boot from the realm's well-known endpoint; missing endpoints refuse boot",
+  "asA": "operator wiring a project against a Keycloak realm",
+  "iWant": "the discovery client to read the realm's well-known configuration and populate the endpoint record",
+  "soThat": "the project's other TACs read Keycloak endpoints from the realm's own declaration rather than from hardcoded URLs",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11102-1",
+      "description": "At boot the discovery client fetches `<issuerBaseUrl>/realms/<realm>/.well-known/openid-configuration` and populates the record's endpoint fields from the response.",
+      "given": "a realm-config record with `realmSlug='r1'`, `issuerBaseUrl='http://127.0.0.1:<port>'`, `realmName='example'`, `verificationMode='jwks'` and a local Keycloak container reachable at that base URL",
+      "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"
+    },
+    {
+      "id": "AC-11102-2",
+      "description": "The discovery client refreshes on the record's `discoveryRefreshSeconds` cadence; a refresh failure logs a warning event but does not flip a healthy realm to unhealthy.",
+      "given": "a healthy realm from AC-11102-1 with `discoveryRefreshSeconds=60`",
+      "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"
+    },
+    {
+      "id": "AC-11102-3",
+      "description": "A realm record whose `verificationMode` requires an endpoint the discovery response does not carry refuses boot with a stable-coded error.",
+      "given": "a realm record with `verificationMode='introspection'` pointed at a discovery response whose body omits the `introspection_endpoint` field",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1201-security-auth-keycloak-discovery-client"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-keycloak-US-11103",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "JWT verification against JWKS survives a key rotation the realm publishes",
+  "asA": "operator whose realm rotates its signing keys on the realm's own cadence",
+  "iWant": "the JWT verifier to recognise a token signed with a new key without a process restart",
+  "soThat": "a key rotation is transparent to the running project",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11103-1",
+      "description": "A verified token whose signing kid is present in the cached JWKS passes verification without a fresh JWKS fetch.",
+      "given": "a warm JWKS cache populated by a prior verification against realmSlug='r1' and a new access token signed under the same kid",
+      "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"
+    },
+    {
+      "id": "AC-11103-2",
+      "description": "A token whose kid is not in the cached JWKS triggers exactly one JWKS refresh; verification succeeds when the refresh surfaces the kid and refuses with `KEYCLOAK_JWT_KID_UNKNOWN` when it does not.",
+      "given": "a warm JWKS cache populated by a prior verification and a new access token signed with a kid the realm has rotated to but the cache does not yet carry",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1202-security-auth-keycloak-jwt-verifier"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-keycloak-US-11104",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Expired or forged access tokens are refused with distinct stable-coded reasons",
+  "asA": "operator whose project receives an access token that fails one of the standard invariants",
+  "iWant": "the JWT verifier to refuse the token before it can lift into a Principal",
+  "soThat": "no session is issued and no protected route runs against an unverified identity",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11104-1",
+      "description": "A token whose `exp` claim is in the past is refused with `KEYCLOAK_JWT_EXPIRED` and no session is issued.",
+      "given": "a JWT verifier warm against the realm's JWKS and an access token whose `exp` claim was minted 60 seconds before the test-injected clock's current time",
+      "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"
+    },
+    {
+      "id": "AC-11104-2",
+      "description": "A token signed under a key not published by the realm at any point in the test's window is refused with `KEYCLOAK_JWT_SIGNATURE_INVALID` after exactly one JWKS refresh.",
+      "given": "a JWT verifier and a token signed by a key that was never on any JWKS response the realm returned",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1202-security-auth-keycloak-jwt-verifier"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-keycloak-US-11105",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Opaque-token introspection verifies against the RFC 7662 endpoint and refuses inactive or errored responses",
+  "asA": "operator whose realm client is configured to issue opaque access tokens",
+  "iWant": "the introspection client to verify every access token against the realm's introspection endpoint on the RFC 7662 shape",
+  "soThat": "the mechanism handles opaque-token clients honestly and reflects realm-side revocations in real time",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11105-1",
+      "description": "An opaque access token that the endpoint returns as `active: true` verifies successfully and yields a claim record.",
+      "given": "a realm record with `verificationMode='introspection'` and a local stub introspection responder wired to answer `active: true` with a fixed claim record for the presented token",
+      "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"
+    },
+    {
+      "id": "AC-11105-2",
+      "description": "An opaque access token that the endpoint returns as `active: false` is refused with `KEYCLOAK_INTROSPECTION_INACTIVE`.",
+      "given": "the same realm record and a stub responder configured to answer `active: false` for the presented token (a revoked or expired token)",
+      "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"
+    },
+    {
+      "id": "AC-11105-3",
+      "description": "A non-2xx response from the introspection endpoint refuses the token with `KEYCLOAK_INTROSPECTION_ENDPOINT_ERROR` naming the HTTP status class.",
+      "given": "the same realm record and a stub responder configured to return HTTP 503 for the presented token",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1203-security-auth-keycloak-introspection-client"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-keycloak-US-11106",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The provider-router seam decides realm per request; unknown realms refuse; the notThisIssuer sentinel hands off",
+  "asA": "operator whose deployment routes requests to more than one realm (or hands some requests off to a middleware layer above the mechanism)",
+  "iWant": "the provider-router to make the routing decision once, in a legible place, on a pure function I supply",
+  "soThat": "the routing is observable at one named seam rather than scattered across handlers",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11106-1",
+      "description": "A routeFn that returns `{ realmSlug: 'r2', verificationMode: 'jwks' }` for a request marker causes the mechanism to verify against realm `r2` rather than the default realm.",
+      "given": "two realm records `r1` and `r2` and a project-authored routeFn that returns `{ realmSlug: 'r2', verificationMode: 'jwks' }` when the request carries a marker the routeFn is coded to inspect (the marker is the project's own concern; the blueprint does not name it)",
+      "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"
+    },
+    {
+      "id": "AC-11106-2",
+      "description": "A routeFn returning a realmSlug not present in the realm-config list refuses the request with `KEYCLOAK_REALM_UNKNOWN`.",
+      "given": "the two-realm configuration from AC-11106-1 and a routeFn that returns `{ realmSlug: 'r99', verificationMode: 'jwks' }`",
+      "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"
+    },
+    {
+      "id": "AC-11106-3",
+      "description": "A routeFn returning the sentinel `notThisIssuer` returns that sentinel to the caller and does not attempt any verification.",
+      "given": "the two-realm configuration and a routeFn that returns the string `'notThisIssuer'`",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1204-security-auth-keycloak-provider-router",
+    "TAC-1202-security-auth-keycloak-jwt-verifier"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-keycloak-US-11107",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Roles lift from the realm's client-roles or realm-roles claim path onto the Principal",
+  "asA": "operator whose realm client publishes role assignments on either the per-client or the realm-wide claim path",
+  "iWant": "the role adapter to populate the reduced Principal's `roles[]` from the path the realm record declares",
+  "soThat": "handler code paths read roles from the Principal without knowing the Keycloak claim shape",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11107-1",
+      "description": "A realm record with `roleClaimShape='client-roles'` lifts `resource_access.<clientId>.roles` onto `Principal.roles`.",
+      "given": "a verified access token whose payload carries `resource_access: { my-client: { roles: ['admin', 'editor'] } }` and a realm record with `clientId='my-client'` and `roleClaimShape='client-roles'`",
+      "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"
+    },
+    {
+      "id": "AC-11107-2",
+      "description": "A verified token whose expected claim path is absent yields an empty `Principal.roles`, not a refusal.",
+      "given": "a verified access token whose payload does not carry a `resource_access.<clientId>.roles` field and a realm record with `roleClaimShape='client-roles'`",
+      "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"
+    },
+    {
+      "id": "AC-11107-3",
+      "description": "A verified token whose expected claim path is present but not an array of strings is refused with `KEYCLOAK_ROLES_MALFORMED`.",
+      "given": "a verified access token whose payload carries `resource_access.my-client.roles = 'admin'` (a string, not an array) and a realm record with `roleClaimShape='client-roles'`",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1205-security-auth-keycloak-role-adapter"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-keycloak-US-11108",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Refresh rotates the stored refresh token; realm invalid_grant invalidates the session",
+  "asA": "operator whose session has been active long enough for the access token to expire",
+  "iWant": "the flow controller to refresh through the realm's token endpoint and honour the realm's rotation model",
+  "soThat": "the session continues without a re-sign-in until the realm signals invalidation",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11108-1",
+      "description": "A refresh call rotates the stored refresh token: the pre-refresh value is discarded and the realm's new value is stored.",
+      "given": "a session issued from US-11101 whose access token has been marked expired by the test-injected clock and whose stored refresh token is `rt-old`",
+      "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"
+    },
+    {
+      "id": "AC-11108-2",
+      "description": "A 400 `invalid_grant` on refresh invalidates the session handle and emits a `keycloak.refresh_invalidated` audit event.",
+      "given": "the same session and a stored refresh token the realm is configured to refuse (a revoked token; the local Keycloak container's realm has revoke-on-refresh-reuse or a reuse-token detection turned on, or the test-injected mock returns 400 invalid_grant for the presented token)",
+      "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"
+    },
+    {
+      "id": "AC-11108-3",
+      "description": "A realm configuration that does not return a refresh token is supported; no refresh call is attempted and the session lives out its own project-lifetime.",
+      "given": "a realm record whose client configuration is set to omit refresh_token (a bearer-only client, or a client with refresh tokens disabled)",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1202-security-auth-keycloak-jwt-verifier"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "security-auth-keycloak-US-11109",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The reduced Principal is what handlers read; provider tokens never surface on request.auth",
+  "asA": "operator building a handler behind the mechanism's session-verify middleware",
+  "iWant": "request.auth to carry only the reduced Principal, never a Keycloak access token, id_token, or refresh token",
+  "soThat": "no handler code path can accidentally reason about the realm's raw token surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11109-1",
+      "description": "A verified request in opaque-handle mode exposes only the reduced Principal on `request.auth`.",
+      "given": "a session issued from US-11101 (opaque-handle mode) and a project route wired behind the session-verify middleware",
+      "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"
+    },
+    {
+      "id": "AC-11109-2",
+      "description": "A verified request in stateless mode exposes only the reduced Principal on `request.auth`; no server-side session record was created.",
+      "given": "a realm record with `sessionMode='stateless'` and `bearerSource='authorization-header'` and a request carrying a valid Keycloak-minted JWT in the Authorization header",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1202-security-auth-keycloak-jwt-verifier",
+    "TAC-1205-security-auth-keycloak-role-adapter"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-keycloak-US-11110",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-out invalidates the project session; realm end-session is a per-record option",
+  "asA": "operator who has signed in through the project's Keycloak-backed sign-in surface",
+  "iWant": "a sign-out request to clear my project session server-side and, when the realm record declares it, redirect to the realm's end-session endpoint",
+  "soThat": "the next request from this browser is unauthenticated regardless of what the realm still holds",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11110-1",
+      "description": "A POST to the sign-out route invalidates the session handle server-side and clears the session cookie in the browser.",
+      "given": "a session issued from US-11101 (opaque-handle mode) and a project route at `POST /auth/sign-out` wired to the flow controller",
+      "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"
+    },
+    {
+      "id": "AC-11110-2",
+      "description": "When a realm record sets `providerLogout: 'redirect'` and discovery has `end_session_endpoint`, sign-out returns a 302 to that endpoint.",
+      "given": "a realm record whose declaration sets `providerLogout: 'redirect'`, a discovery response carrying `end_session_endpoint`, and a session issued against that realm",
+      "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"
+    },
+    {
+      "id": "AC-11110-3",
+      "description": "A realm record with `providerLogout: 'redirect'` whose discovery response omits `end_session_endpoint` refuses boot with `KEYCLOAK_LOGOUT_NOT_DECLARED`.",
+      "given": "a realm-config record whose `providerLogout` is `'redirect'` pointed at a discovery document that lacks the `end_session_endpoint` field",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1201-security-auth-keycloak-discovery-client"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-keycloak-US-11111",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-011",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Fail-safe boot postures behave per the record's bootPosture field",
+  "asA": "operator whose realm may be unreachable at project boot",
+  "iWant": "the discovery client to follow the posture the record declares (strict, deferred, standby)",
+  "soThat": "my project's boot behaviour reflects a paper-trailed decision rather than a hidden retry constant",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11111-1",
+      "description": "Under `bootPosture: strict` a discovery fetch failure terminates the process with `KEYCLOAK_DISCOVERY_UNREACHABLE` and no listener is left running.",
+      "given": "a realm record with `bootPosture: 'strict'` pointed at an issuer base URL that returns HTTP connection-refused for the discovery path",
+      "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"
+    },
+    {
+      "id": "AC-11111-2",
+      "description": "Under `bootPosture: deferred` the process starts, the realm is marked unhealthy, and a backoff refresh loop populates the record on the first success.",
+      "given": "a realm record with `bootPosture: 'deferred'`, `deferredRetryCapSeconds=30`, and an issuer base URL whose discovery path returns 503 for the first three fetch attempts and 200 with a valid discovery response for the fourth",
+      "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"
+    },
+    {
+      "id": "AC-11111-3",
+      "description": "Under `bootPosture: standby` the process starts, the realm is unhealthy, and a project-invoked refresh brings it healthy.",
+      "given": "a realm record with `bootPosture: 'standby'` and a discovery endpoint that would return 200 if fetched but the standby posture holds the client off",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1201-security-auth-keycloak-discovery-client"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "security-auth-keycloak-US-11112",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-012",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Live cloud-realm smoke ACs are accountBound and skip cleanly when the realm is unreachable",
+  "asA": "operator running the project's CI pipeline without live cloud-realm credentials configured",
+  "iWant": "the runtime-verify layer to skip the live-realm smoke ACs with a stable-coded reason",
+  "soThat": "CI does not fail and the honest coverage state is on the record",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11112-1",
+      "description": "Every TC bound to a runtime-verify AC that targets a live cloud-hosted realm carries an `accountBound` flag; the runtime-verify runner honours the flag by skipping and emitting a stable-coded reason.",
+      "given": "a project scratch tree with this blueprint applied, one project-authored TC bound to AC-11112-2 flagged `accountBound`, and no live cloud-realm credentials in the runtime environment",
+      "when": "`rcf audit coverage --strict` reports the coverage state and the runtime-verify runner is invoked",
+      "then": "the coverage report lists the AC as covered by a TC whose latest run outcome is `skipped` with reason `KEYCLOAK_LIVE_REALM_UNREACHABLE`; the pipeline exit code is 0; the audit log records one `keycloak.accountbound_skip` event carrying the AC id and the missing-credential class",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-11112-2",
+      "description": "A live cloud-hosted-realm smoke against a project-owned Keycloak deployment completes a full authorisation-code + PKCE round-trip and issues a project session whose Principal carries the deployment's realm slug.",
+      "given": "live cloud-realm credentials configured in the runtime environment and the project's redirect URI registered at the realm's admin console (operator-authored, out of the blueprint's mechanism reach)",
+      "when": "the operator drives a real browser through the sign-in surface at the live realm",
+      "then": "the flow completes; a project session cookie is set with the same shape as AC-11101-3; `request.auth.provider` equals the live realm's declared realmSlug; the project-authored TC for this AC records a `pass` outcome",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1201-security-auth-keycloak-discovery-client",
+    "TAC-1202-security-auth-keycloak-jwt-verifier"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-keycloak-US-11113",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The local Keycloak container stands up under a project harness and the discovery client verifies against it",
+  "asA": "operator running the project's runtime-verify pass in CI without any cloud dependency",
+  "iWant": "the project harness to bring up a local Keycloak container against the vendor's official image and the discovery client to reach it within a bounded startup window",
+  "soThat": "runtime-verify against a real Keycloak realm is free of cloud cost and free of external-account dependency",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11113-1",
+      "description": "A project harness following the local-container asset stands up a Keycloak container against the vendor's official image with placeholder credentials from an operator-controlled environment source; the container is reachable on its published port within `containerStartupTimeoutSeconds` (default 120).",
+      "given": "a harness following `assets/local-container/keycloak-bootstrap.md` with the operator-pinned stable tag on `quay.io/keycloak/keycloak` and admin credentials from an operator-controlled environment file that is not committed to the repository",
+      "when": "the harness starts the container as part of a runtime-verify session",
+      "then": "the container is running within the timeout; a discovery HTTP GET on `<containerBase>/realms/example/.well-known/openid-configuration` returns 200 with a JSON body carrying the standard OIDC endpoints; the placeholder admin credentials never appear in a committed file or in an audit event; the harness's environment file is listed in the project's `.gitignore` shape and the test verifies the file is not tracked by git",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-11113-2",
+      "description": "The seeded realm carries only placeholder shapes; no real client id, no real client secret, no real user data, and no realm name matching a project-owned deployment appears in the seed file the harness applies.",
+      "given": "the realm seed the harness applies (either via `kc.sh import` or via the admin REST API after startup)",
+      "when": "the seed file is inspected on disk before application",
+      "then": "the realm name equals the placeholder value declared in the asset (or a project-chosen renamed placeholder); the client id is the seed's placeholder value; the client secret is not present in the seed file (the harness sets it after client creation and stores it in the operator's environment file); user credentials are placeholders; every leakage grep the project runs (real domain names, real client secrets, real realm ids, real user emails) against the seed file returns zero",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1201-security-auth-keycloak-discovery-client"
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/security-auth-keycloak/docs/topics.md

@@ -0,0 +1,74 @@
+# security-auth-keycloak blueprint coordination vocabulary
+
+This file is the security-auth-keycloak half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | security-auth-keycloak contribution | Composition intent |
+|---|---|---|
+| `authModel` | ADR-1201-security-auth-keycloak-auth-model | Deliberate conflict on the same string minted by `security-auth-magic-link` (ADR-501), `security-auth-clerk` (ADR-1001), `security-auth-oauth2` (ADR-1101), the client half of `application-spa` (ADR-205), and the server half of `application-api-rest` (ADR-302). This blueprint's shape is delegated identity to a Keycloak realm the operator runs, federated through OIDC authorisation-code + PKCE, with per-realm verification mode (JWKS or introspection). A composing blueprint that holds a different opinion on the authentication model contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the project's authentication model for both the client tier and the server tier, with a resolution recorded on `manifest.resolutions[]` or via `--resolve authModel=project:<ADR-id>` on the add |
+
+The security-auth-keycloak blueprint claims one global topic. Every other contribution is scope-local (ADR-1202 through ADR-1206 name the verification-mode choice, the provider-routing seam, the session-vs-token contract, the JWKS rotation-cache lifetime, and the refresh-and-sign-out posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, security-auth-clerk, security-auth-oauth2, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camelCase, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`auth`, `authentication`, `identityProvider`, `keycloakProvider` are all wrong when `authModel` already exists).
+
+## The deliberate authModel conflict, restated
+
+This blueprint is the vendor-committed Keycloak shape of the `authModel` decision. Three other shipped auth-family blueprints hold different shapes on the same topic:
+
+- `security-auth-magic-link` (ADR-501): passwordless magic-link with server-issued opaque cookie sessions. Local-first, no third-party identity dependency.
+- `security-auth-clerk` (ADR-1001): hosted identity via Clerk; the vendor owns the sign-in surface, credential storage, MFA, and account recovery; the project owns a middleware boundary against Clerk's session-verification.
+- `security-auth-oauth2` (ADR-1101): delegated identity via OAuth2 authorisation-code + PKCE against any project-configured IdP. Vendor-neutral; the project drops in the provider it wants.
+- `security-auth-keycloak` (ADR-1201, this blueprint): delegated identity to a Keycloak realm the operator runs, federated through OIDC. Vendor-committed; larger ops footprint; full self-hosted control.
+
+Composing any two of these on one project raises a `globalAdrTopic` conflict on `authModel` at `rcf define blueprint add`. The four documented resolutions apply: adopt the incoming, keep the existing, author a project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add. The composition-precedent (SPA + REST on `errorEnvelope` and `authModel`) is the same pattern the client half and the server half of the wire contract have already established; the auth-family blueprints follow it.
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19, extended by round-2 outcomes 2026-08-30 for the four-digit ADR/TAC suffix widening); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 11101-11113 sit at the LOW end of the 11101-11899 band on purpose. A project-side story that mechanically derives from a security-auth-keycloak REQ id into the number `11113` would collide against security-auth-keycloak-US-11113 in this package; the band leaves headroom at the HIGH end (US 11181-11899) so a project's own stories anchored to security-auth-keycloak REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+The ADR/TAC suffix block 1201-1299 is the third block in the four-digit suffix space; `security-auth-clerk` opened the door at 1001-1099 and `security-auth-oauth2` took 1101-1199. Every shipped blueprint continues to load, validate, and audit against this shape without a schema change: rcf-schemas 0.5.0 `adrId` and `tacId` patterns are `^ADR-\d{3,}(-[a-z0-9]+...)?$` (three-digit minimum, unbounded above); four-digit and higher suffixes validate verbatim. The registry table above records the growth for a downstream author reaching for the next block.
+
+## Provider-aware install-design shape (plain language, no named second issuer)
+
+The blueprint is Keycloak-committed. What the install design is AWARE of is that a project may deploy this mechanism in an environment where a receiving system's request stream also carries tokens issued by another OAuth2 or OIDC server. This shape is NOT a claim about the blueprint's mechanism reach - the blueprint verifies against Keycloak realms only, and refuses to name any specific second issuer. The shape lives at the seam where a project's OWN middleware decides which issuer is authoritative for a request:
+
+- TAC-1204 (the provider router) contributes the pure-function contract `route(request) -> { realmSlug, verificationMode } | 'notThisIssuer'`. A project with only Keycloak wires it to a constant; a project with two Keycloak realms wires it to inspect a project-chosen request feature; a project with Keycloak alongside a non-Keycloak issuer returns the sentinel and the project's own middleware chain above owns what happens next.
+- REQ-004 (the introspection path) speaks the RFC 7662 shape whether the issuer is Keycloak or another conforming server. The blueprint reaches only for the endpoint declared on the realm's discovery; a project that has chosen to consult a non-Keycloak issuer at introspection is a project-level ADR conversation, not a mechanism change here.
+
+The blueprint refuses to encode:
+
+- A specific second issuer's name, product, or integration.
+- A specific request marker (a header name, a path prefix, a claim, a subdomain shape) the routing function would inspect.
+- A specific dual-issuer deployment shape (a docker-compose recipe, a Kubernetes topology, a load-balancer rule).
+- A specific standards-suite reference the ratified reshape ruling excluded from this blueprint.
+
+A project that has one Keycloak realm inherits the seam at zero cost (constant routeFn). A project that has two Keycloak realms pays one function call per request. A project with an issuer above this blueprint's reach pays one function call per request and owns the routing policy on its own ADR.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `authModel` exactly as spelled here when your blueprint holds an opinion on the project's authentication model; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- Verification-mode choice (ADR-1202), provider-routing seam (ADR-1203), session-vs-token contract (ADR-1204), JWKS rotation-cache lifetime (ADR-1205), and refresh-and-sign-out posture (ADR-1206) are scope-local. A composing blueprint that holds an opinion on any of them authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate authentication-model variations.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint), `sessionStore` (unclaimed; a future session-persistence-committed blueprint's natural global). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.