rcf-lite 0.26.0 → 0.27.0

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

@@ -0,0 +1,117 @@
+{
+  "usId": "security-auth-keycloak-US-11116",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-015",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Discovery and account-console interactions each emit one structured audit event on the fixed allow-list",
+  "asA": "operator running the runtime-verify suite against the discovery client and the account-console verification",
+  "iWant": "every named interaction on those two families to write one structured event carrying only the allow-list fields",
+  "soThat": "the audit stream stays free of token material and a reviewer can decide at a glance whether an event field is inside the blueprint's contract",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11116-1",
+      "description": "A completed discovery fetch for realm `alpha` emits exactly one `keycloak.discovery` audit event carrying `family=keycloak.discovery`, `outcome=verified`, `realmSlug=alpha`, and `at`; no other field appears.",
+      "given": "a realm-config record for `alpha` whose issuer is reachable and whose discovery document responds 200",
+      "when": "the discovery client fetches the realm's OIDC discovery document at boot",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.discovery` and `outcome=verified`; no token value, no client secret, no raw claim record, and no substring of any of the above appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    },
+    {
+      "id": "AC-11116-2",
+      "description": "A refused account-console verification against an unreachable `accountConsoleUrl` emits exactly one `keycloak.account_console` audit event carrying `outcome=refused` and `reasonClass=account_console_unreachable`.",
+      "given": "a realm-config record for `alpha` whose `accountConsoleUrl` returns 404 to an unauthenticated GET",
+      "when": "the discovery client verifies the account console URL at boot",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.account_console`, `outcome=refused`, and `reasonClass=account_console_unreachable`; no token value, no client secret, no raw claim record, and no substring of any of the above appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    },
+    {
+      "id": "AC-11116-3",
+      "description": "A transient discovery failure followed by a successful retry emits exactly one refusal event and one verified event on the `keycloak.discovery` family, in order.",
+      "given": "a realm-config record for `alpha` whose discovery endpoint returns 503 on the first attempt and 200 on the second",
+      "when": "the discovery client retries per its documented retry posture and completes the fetch",
+      "then": "the audit sink records exactly two events in order: one `keycloak.discovery` event with `outcome=refused` and `reasonClass=upstream_unavailable`, then one `keycloak.discovery` event with `outcome=verified`; no additional event is written for the retry itself",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    },
+    {
+      "id": "AC-11116-4",
+      "description": "A sink failure during the emission of a `keycloak.discovery` event does not mask the underlying discovery outcome; the mechanism records a `keycloak.audit_sink_failed` warning event and the discovery outcome is unchanged.",
+      "given": "a realm-config record for `alpha` whose discovery responds 200 and an audit sink whose write throws",
+      "when": "the discovery client emits the completion event",
+      "then": "the discovery outcome remains `verified` (boot proceeds); the mechanism records a `keycloak.audit_sink_failed` warning event carrying the realm slug and a reason-class string; no token value or raw claim record appears; the original refusal or verification result is not masked",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    },
+    {
+      "id": "AC-11116-5",
+      "description": "A repeated identical discovery fetch of the same reachable realm (a scheduled `discoveryRefreshSeconds` refresh, or a second explicit fetch) is idempotent: each fetch call emits exactly one `keycloak.discovery` audit event with `outcome=verified`; two consecutive fetches produce two events (count is one per fetch call, never a deduplicated event).",
+      "given": "a realm-config record for `alpha` whose issuer is reachable and whose discovery document responds 200 on every attempt, and a completed first fetch already on record",
+      "when": "the discovery client performs a second discovery fetch against the same realm",
+      "then": "the audit sink records exactly one additional event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.discovery` and `outcome=verified`; the total count of `keycloak.discovery` verified events across the two fetches is exactly two; no additional event is written and no earlier event is mutated",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    },
+    {
+      "id": "AC-11116-6",
+      "description": "A boot-time discovery fetch against a realm-config record whose `realmSlug` is a non-empty string (the credential that binds the fetch to a realm principal) emits a `keycloak.discovery` event that records that principal in the `realmSlug` field; a fetch attempted against a realm-config record whose `realmSlug` is missing or the empty string is refused before any network call with exactly one `keycloak.discovery` event carrying `outcome=refused` and `reasonClass=missing_realm_credential`, and no realm principal string leaks into any other field.",
+      "given": "two realm-config records: record A for `alpha` whose `realmSlug` is `alpha` and whose discovery document responds 200; record B whose `realmSlug` is the empty string",
+      "when": "the discovery client attempts a discovery fetch against each record in turn",
+      "then": "the audit sink records exactly one `keycloak.discovery` event for record A with `outcome=verified` and `realmSlug=alpha` (the `realmSlug` field is the payload field that records the realm principal), and exactly one `keycloak.discovery` event for record B with `outcome=refused` and `reasonClass=missing_realm_credential`; no network call is issued for record B and no principal string appears in any other field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    },
+    {
+      "id": "AC-11116-7",
+      "description": "An account-console verification against a realm-config record whose `realmSlug` is present (a valid realm credential) but whose `accountConsoleUrl` origin differs from the discovered issuer origin (the record lacks the origin-scope the mechanism requires) is refused with exactly one `keycloak.account_console` event carrying `outcome=refused` and `reasonClass=account_console_malformed`; the event records the refusal reason and the realm principal, and the underlying account-console verification is not carried out.",
+      "given": "a realm-config record for `alpha` with `realmSlug=alpha` whose discovered issuer origin is `https://issuer.example` and whose `accountConsoleUrl` origin is `https://other.example`",
+      "when": "the discovery client verifies the account console URL at boot",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.account_console`, `outcome=refused`, `reasonClass=account_console_malformed`, and `realmSlug=alpha`; the `credentialSelfService` capability is not bound to the realm",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1201-security-auth-keycloak-discovery-client",
+        "field": "responsibilities.discoveryAudit"
+      }
+    }
+  ],
+  "tacIds": [
+    "TAC-1201-security-auth-keycloak-discovery-client"
+  ],
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "description": "Applying agent sets: no project-parameterised values on this story; every AC is `fixed`. AC-set sufficiency (7a inline note per blueprint-authoring.md §7a): the credential scenario class is bound by AC-6 (a realm-config record with a non-empty `realmSlug` is the credential the discovery fetch is bound to, and the `realmSlug` payload field records the realm principal; a missing credential is refused with `reasonClass=missing_realm_credential`). The permission scenario class is bound by AC-7 (a realm-config record whose `accountConsoleUrl` origin does not match the discovered issuer origin lacks the origin scope the mechanism requires and is refused with `reasonClass=account_console_malformed`)."
+}

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

@@ -0,0 +1,117 @@
+{
+  "usId": "security-auth-keycloak-US-11117",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-016",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "JWT verify calls each emit one structured audit event on the fixed allow-list",
+  "asA": "operator running the runtime-verify suite against the JWT verifier",
+  "iWant": "every verify call to write one structured `keycloak.jwt` event carrying only the allow-list fields",
+  "soThat": "the audit stream stays free of token material and every refusal has a stable reasonClass a reviewer can gate on",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11117-1",
+      "description": "A verified JWT emits exactly one `keycloak.jwt` audit event carrying `outcome=verified` and the caller's realm slug; no token value appears.",
+      "given": "a JWT signed by realm `alpha`'s current signing key whose `iss`, `aud`, and `exp` claims match the configured verification record",
+      "when": "the JWT verifier verifies the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.jwt` and `outcome=verified`; no access token, id token, refresh token, introspection response body, client secret, raw claim record, or substring of any of the above appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    },
+    {
+      "id": "AC-11117-2",
+      "description": "A JWT whose `exp` timestamp is in the past emits exactly one `keycloak.jwt` audit event carrying `outcome=refused` and `reasonClass=expired`; the reasonClass is the single value bound to that input, not one of a set.",
+      "given": "a JWT signed by realm `alpha`'s current signing key whose `iss` and `aud` claims match the configured verification record and whose `exp` timestamp is in the past",
+      "when": "the JWT verifier verifies the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.jwt`, `outcome=refused`, and `reasonClass=expired`; the event carries `realmSlug=alpha`; no token or claim material appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    },
+    {
+      "id": "AC-11117-3",
+      "description": "A JWKS-refresh retry on `signature_invalid` before re-verifying emits exactly one refused event and, on a successful second verify, one verified event; no third event is written for the retry itself.",
+      "given": "a JWT whose signature does not verify against the cached JWKS but does verify against the freshly-refreshed JWKS (a key-rollover window)",
+      "when": "the JWT verifier refuses on cache, refreshes the JWKS per its documented posture, and re-verifies",
+      "then": "the audit sink records exactly two events in order: one `keycloak.jwt` event with `outcome=refused` and `reasonClass=signature_invalid`, then one `keycloak.jwt` event with `outcome=verified`; the retry itself is not recorded as a distinct event",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    },
+    {
+      "id": "AC-11117-4",
+      "description": "A sink failure during the emission of a `keycloak.jwt` event does not mask the underlying verify outcome; the mechanism records a `keycloak.audit_sink_failed` warning event and the verify outcome is unchanged.",
+      "given": "a valid JWT against realm `alpha` and an audit sink whose write throws",
+      "when": "the JWT verifier emits the completion event",
+      "then": "the verifier's return value still reports the underlying refusal or verification result unchanged; the mechanism records a `keycloak.audit_sink_failed` warning event carrying the realm slug and a reason-class string; no token value or raw claim record appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    },
+    {
+      "id": "AC-11117-5",
+      "description": "Verifying the same well-formed JWT twice within its `exp` window is idempotent: each verify call emits exactly one `keycloak.jwt` audit event with `outcome=verified`; two consecutive verify calls produce two events (count is one per verify call, never a deduplicated event).",
+      "given": "a JWT signed by realm `alpha`'s current signing key whose `iss`, `aud`, and `exp` claims match the configured verification record, verified once already",
+      "when": "the JWT verifier verifies the same token a second time",
+      "then": "the audit sink records exactly one additional event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.jwt` and `outcome=verified`; the total count of `keycloak.jwt` verified events across the two verifies is exactly two; the verify's return value is unchanged between calls",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    },
+    {
+      "id": "AC-11117-6",
+      "description": "A JWT with a valid signature and a matching `iss` claim, but whose `aud` claim does not match the audience the configured verification record requires (the credential is valid for a different audience scope than this mechanism permits), is refused: the audit sink records exactly one `keycloak.jwt` event with `outcome=refused` and `reasonClass=audience_mismatch`; the audience mismatch is the permission-scope refusal that records the refusal reason.",
+      "given": "a JWT signed by realm `alpha`'s current signing key whose `iss` claim is `https://issuer.example/realms/alpha` (matching the verification record) and whose `aud` claim is `other-service` (the verification record requires `aud=alpha-api`), and whose `exp` timestamp is in the future",
+      "when": "the JWT verifier verifies the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.jwt`, `outcome=refused`, and `reasonClass=audience_mismatch`; the event carries `realmSlug=alpha`; no token or claim material appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    },
+    {
+      "id": "AC-11117-7",
+      "description": "A JWT with a valid signature whose `iss` claim does not match the issuer the configured verification record requires emits exactly one `keycloak.jwt` audit event with `outcome=refused` and `reasonClass=issuer_mismatch`; the reasonClass is the single value bound to that input, not one of a set.",
+      "given": "a JWT signed by realm `alpha`'s current signing key whose `iss` claim is `https://other.example/realms/other` (the verification record expects `https://issuer.example/realms/alpha`), whose `aud` claim matches the record, and whose `exp` timestamp is in the future",
+      "when": "the JWT verifier verifies the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.jwt`, `outcome=refused`, and `reasonClass=issuer_mismatch`; the event carries `realmSlug=alpha`; no token or claim material appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1202-security-auth-keycloak-jwt-verifier",
+        "field": "responsibilities.jwtAudit"
+      }
+    }
+  ],
+  "tacIds": [
+    "TAC-1202-security-auth-keycloak-jwt-verifier"
+  ],
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "description": "Applying agent sets: no project-parameterised values on this story; every AC is `fixed`. AC-set sufficiency (7a inline note per blueprint-authoring.md §7a): the credential scenario class is bound by AC-1 (a JWT signed by the realm's current key with matching `iss`, `aud` and unexpired `exp` is the credential and the event records the realm-scoped identity via the `realmSlug` payload field). The permission scenario class is bound by AC-6 (a JWT with a valid signature and matching `iss` but a mismatched `aud` is a valid credential lacking the required audience scope and is refused with `reasonClass=audience_mismatch`). The REQ-016 named refusal reasons are each bound to a concrete AC: `expired` on AC-2, `signature_invalid` on AC-3, `audience_mismatch` on AC-6, `issuer_mismatch` on AC-7."
+}

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

@@ -0,0 +1,117 @@
+{
+  "usId": "security-auth-keycloak-US-11118",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-017",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Token introspection calls each emit one structured audit event on the fixed allow-list",
+  "asA": "operator running the runtime-verify suite against the introspection client",
+  "iWant": "every introspect call to write one structured `keycloak.introspection` event carrying only the allow-list fields",
+  "soThat": "the audit stream stays free of the introspection response body and every refusal carries a stable reasonClass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11118-1",
+      "description": "An introspect call whose response is `active: true` emits exactly one `keycloak.introspection` event carrying `outcome=verified` and the caller's realm slug.",
+      "given": "a token whose introspection endpoint response is a `200 { active: true, ... }` against realm `alpha`",
+      "when": "the introspection client introspects the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.introspection` and `outcome=verified`; the introspection response body, the token value, the client secret, and any substring of the above are not present in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    },
+    {
+      "id": "AC-11118-2",
+      "description": "An introspect call whose response is a 2xx `active: false` emits exactly one `keycloak.introspection` audit event with `outcome=refused` and `reasonClass=inactive`.",
+      "given": "a token whose introspection endpoint response is a 2xx `{ active: false }` against realm `alpha`",
+      "when": "the introspection client introspects the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.introspection`, `outcome=refused`, and `reasonClass=inactive`; the introspection response body is not present in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    },
+    {
+      "id": "AC-11118-3",
+      "description": "A transient introspection failure followed by a successful retry emits exactly one refused event with `reasonClass=upstream_error` and one verified event on the `keycloak.introspection` family, in order; the retry itself is not a distinct event.",
+      "given": "a token whose introspection endpoint returns 503 on the first attempt and 200 with `active: true` on the second",
+      "when": "the introspection client retries per its documented posture and completes the call",
+      "then": "the audit sink records exactly two events in order: one `keycloak.introspection` event with `outcome=refused` and `reasonClass=upstream_error`, then one `keycloak.introspection` event with `outcome=verified`; no additional event is written for the retry itself",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    },
+    {
+      "id": "AC-11118-4",
+      "description": "A sink failure during the emission of a `keycloak.introspection` event does not mask the underlying introspection outcome; the mechanism records a `keycloak.audit_sink_failed` warning event and the introspection outcome is unchanged.",
+      "given": "an introspect call whose response is `active: true` and an audit sink whose write throws",
+      "when": "the introspection client emits the completion event",
+      "then": "the client's return value still reports the underlying introspection result unchanged; the mechanism records a `keycloak.audit_sink_failed` warning event carrying the realm slug and a reason-class string; the introspection response body does not appear",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    },
+    {
+      "id": "AC-11118-5",
+      "description": "An introspect call whose response is a non-2xx status emits exactly one `keycloak.introspection` audit event with `outcome=refused` and `reasonClass=upstream_error`.",
+      "given": "a token whose introspection endpoint responds with a 5xx status against realm `alpha`",
+      "when": "the introspection client introspects the token",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.introspection`, `outcome=refused`, and `reasonClass=upstream_error`; the introspection response body is not present in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    },
+    {
+      "id": "AC-11118-6",
+      "description": "Introspecting the same active token twice is idempotent: each introspect call emits exactly one `keycloak.introspection` audit event with `outcome=verified`; two consecutive introspect calls produce two events (count is one per introspect call, whether the second call is served from the introspection cache or not).",
+      "given": "a token whose introspection endpoint response is a 2xx `{ active: true }` on both attempts, and one completed introspect call already on record",
+      "when": "the introspection client introspects the same token a second time",
+      "then": "the audit sink records exactly one additional event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.introspection` and `outcome=verified`; the total count of `keycloak.introspection` verified events across the two calls is exactly two; the caller's return value is unchanged between the two calls",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    },
+    {
+      "id": "AC-11118-7",
+      "description": "An introspect call whose introspection endpoint responds with `401 Unauthorized` to the mechanism's client credentials (the client is authenticated but not authorised to call introspection on this realm; the credential lacks the required permission scope) emits exactly one `keycloak.introspection` event with `outcome=refused` and `reasonClass=client_forbidden`; the introspection response body does not appear.",
+      "given": "a realm-config record for `alpha` whose introspection endpoint responds `401 Unauthorized` to the configured `clientId`",
+      "when": "the introspection client introspects any token against realm `alpha`",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.introspection`, `outcome=refused`, and `reasonClass=client_forbidden`; the introspection response body is not present in any field; no client secret appears",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1203-security-auth-keycloak-introspection-client",
+        "field": "responsibilities.introspectionAudit"
+      }
+    }
+  ],
+  "tacIds": [
+    "TAC-1203-security-auth-keycloak-introspection-client"
+  ],
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "description": "Applying agent sets: no project-parameterised values on this story; every AC is `fixed`. AC-set sufficiency (7a inline note per blueprint-authoring.md §7a): the credential scenario class is bound by AC-1 (a 2xx `{ active: true }` introspection response is the credential and the event records the realm-scoped identity via the `realmSlug` payload field). The permission scenario class is bound by AC-7 (an introspect call whose upstream returns `401 Unauthorized` names a valid client credential lacking the required permission scope on this realm and is refused with `reasonClass=client_forbidden`)."
+}

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

@@ -0,0 +1,117 @@
+{
+  "usId": "security-auth-keycloak-US-11119",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-018",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Provider-router routing decisions and sessionInventory operations each emit one structured audit event on the fixed allow-list",
+  "asA": "operator running the runtime-verify suite against the provider router and the sessionInventory surface",
+  "iWant": "every routing decision and every sessionInventory operation to write one structured event carrying only the allow-list fields",
+  "soThat": "the audit stream stays free of session material and every refusal has a stable reasonClass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11119-1",
+      "description": "A routing decision that returns a realm record emits exactly one `keycloak.route` event carrying `outcome=verified` and the routed realmSlug; a sessionInventory `list()` emits exactly one `keycloak.session_inventory` event carrying `outcome=verified` and the caller's realmSlug.",
+      "given": "an authenticated caller in realm `alpha` and a project-authored routing function that returns the `alpha` realm record",
+      "when": "the provider router routes the request and the caller then calls `sessionInventory.list()`",
+      "then": "the audit sink records two events in order: one `keycloak.route` event with `outcome=verified` and `realmSlug=alpha`, then one `keycloak.session_inventory` event with `outcome=verified` and `realmSlug=alpha`; each event's own-property keys are drawn from `{family, outcome, reasonClass, realmSlug, sessionIdPrefix, at}` and no request-content field appears",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    },
+    {
+      "id": "AC-11119-2",
+      "description": "A sessionInventory operation from an unauthenticated caller emits exactly one `keycloak.session_inventory` event with `outcome=refused` and `reasonClass=unauthenticated`; the operation itself refuses without side effect.",
+      "given": "a request with no verified session",
+      "when": "any sessionInventory operation is invoked",
+      "then": "the audit sink records exactly one event with `family=keycloak.session_inventory`, `outcome=refused`, and `reasonClass=unauthenticated`; no session record is created, updated, or removed; no cookie or full session id appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    },
+    {
+      "id": "AC-11119-3",
+      "description": "A sessionInventory `revoke(sessionId)` that first refuses on `unknown_session` and then succeeds on a subsequent call for a valid session id emits exactly one refused event and one verified event on the `keycloak.session_inventory` family, in order; the retry itself is not a distinct event.",
+      "given": "an authenticated caller who first calls `sessionInventory.revoke(unknownSessionId)` and then calls `sessionInventory.revoke(validSessionId)`",
+      "when": "the two calls run in sequence",
+      "then": "the audit sink records exactly two events in order: one `keycloak.session_inventory` event with `outcome=refused` and `reasonClass=unknown_session`, then one `keycloak.session_inventory` event with `outcome=verified` and the caller's realmSlug; each event carries a `sessionIdPrefix` no longer than eight characters",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    },
+    {
+      "id": "AC-11119-4",
+      "description": "A sink failure during the emission of a `keycloak.route` event does not mask the underlying routing decision; the mechanism records a `keycloak.audit_sink_failed` warning event and the routing outcome is unchanged.",
+      "given": "a routing decision that returns the `alpha` realm record and an audit sink whose write throws",
+      "when": "the provider router emits the routing event",
+      "then": "the routing decision returned to the caller is unchanged (the routed realm record or the sentinel `notThisIssuer`); the mechanism records a `keycloak.audit_sink_failed` warning event carrying the realm slug and a reason-class string; no request-content field appears",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    },
+    {
+      "id": "AC-11119-5",
+      "description": "A `sessionInventory.revoke(sessionId)` call for a valid session id from an authenticated caller in realm `alpha` emits exactly one `keycloak.session_inventory` audit event carrying `outcome=verified`, the caller's realmSlug, and a `sessionIdPrefix` of the revoked session; count is exactly one event per revoke-one invocation.",
+      "given": "an authenticated caller in realm `alpha` and a valid non-current sessionId belonging to that caller",
+      "when": "the caller invokes `sessionInventory.revoke(validSessionId)`",
+      "then": "the audit sink records exactly one event whose own-property keys are drawn from `{family, outcome, realmSlug, sessionIdPrefix, at}` with `family=keycloak.session_inventory`, `outcome=verified`, and `realmSlug=alpha`; `sessionIdPrefix` is a substring of length no greater than eight characters; no cookie value and no full session id appears in any field; the target session is invalidated on the provider",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    },
+    {
+      "id": "AC-11119-6",
+      "description": "A `sessionInventory.revokeAllExceptCurrent()` call from an authenticated caller emits exactly one `keycloak.session_inventory` audit event carrying `outcome=verified`, the caller's realmSlug, and a `sessionIdPrefix` for the retained current session; count is exactly one event per revoke-all-except-current invocation, regardless of how many other sessions were invalidated.",
+      "given": "an authenticated caller in realm `alpha` with three active sessions (one current, two non-current)",
+      "when": "the caller invokes `sessionInventory.revokeAllExceptCurrent()`",
+      "then": "the audit sink records exactly one event whose own-property keys are drawn from `{family, outcome, realmSlug, sessionIdPrefix, at}` with `family=keycloak.session_inventory`, `outcome=verified`, and `realmSlug=alpha`; `sessionIdPrefix` names the retained current session and is a substring of length no greater than eight characters; no cookie value and no full session id appears in any field; the two non-current sessions are invalidated on the provider and the current session remains valid",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    },
+    {
+      "id": "AC-11119-7",
+      "description": "A repeated `sessionInventory.revoke(sessionId)` for the same session id is idempotent: the first call emits one verified event and invalidates the session, the second call emits one refused event with `reasonClass=unknown_session` (the session has already been invalidated) with no additional side effect; count is exactly one event per revoke call across both invocations.",
+      "given": "an authenticated caller in realm `alpha` who has just successfully revoked sessionId `S1` (AC-11119-5 result on record)",
+      "when": "the caller invokes `sessionInventory.revoke(S1)` a second time",
+      "then": "the audit sink records exactly one additional event whose own-property keys are drawn from `{family, outcome, reasonClass, realmSlug, sessionIdPrefix, at}` with `family=keycloak.session_inventory`, `outcome=refused`, and `reasonClass=unknown_session`; the total count of `keycloak.session_inventory` events across the two revoke calls is exactly two (one verified, one refused); the session state on the provider is unchanged by the second call",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1204-security-auth-keycloak-provider-router",
+        "field": "responsibilities.routeAndSessionAudit"
+      }
+    }
+  ],
+  "tacIds": [
+    "TAC-1204-security-auth-keycloak-provider-router"
+  ],
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "description": "Applying agent sets: no project-parameterised values on this story; every AC is `fixed`. AC-set sufficiency (7a inline note per blueprint-authoring.md §7a): the credential scenario class is bound by AC-1 (an authenticated caller in a realm records the realm-scoped identity on both the route and the session_inventory event). The permission scenario class is bound by AC-2 (an unauthenticated caller's sessionInventory invocation refuses with `reasonClass=unauthenticated` and no side effect). Interaction coverage: route-decided AC-1, session-listed AC-1, revoke-one AC-5 (AC-3 also observes revoke-one inside a mixed sequence), revoke-all-except-current AC-6, unauthenticated AC-2."
+}

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

@@ -0,0 +1,103 @@
+{
+  "usId": "security-auth-keycloak-US-11120",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-keycloak-REQ-019",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Role-adapter reads each emit one structured audit event on the fixed allow-list",
+  "asA": "operator running the runtime-verify suite against the role adapter",
+  "iWant": "every read call to write one structured `keycloak.roles` event carrying only the allow-list fields",
+  "soThat": "the audit stream stays free of raw claim records and every malformed-claim refusal carries a stable reasonClass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-11120-1",
+      "description": "A read on a well-formed claim emits exactly one `keycloak.roles` audit event with `outcome=verified` and the caller's realmSlug.",
+      "given": "a verified claim record whose expected role path is an array of strings, in realm `alpha`",
+      "when": "the role adapter reads the roles from the claim record",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.roles` and `outcome=verified`; no raw claim record and no token material appears in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+        "field": "responsibilities.rolesAudit"
+      }
+    },
+    {
+      "id": "AC-11120-2",
+      "description": "A read where the expected path is present but the value is not an array of strings emits exactly one refused event with `reasonClass=malformed`.",
+      "given": "a verified claim record whose expected role path is present as a scalar value or an array of non-string values, in realm `alpha`",
+      "when": "the role adapter reads the roles from the claim record",
+      "then": "the audit sink records exactly one event with `family=keycloak.roles`, `outcome=refused`, and `reasonClass=malformed`; the raw claim record does not appear in any field; the reduced roles array is not populated",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+        "field": "responsibilities.rolesAudit"
+      }
+    },
+    {
+      "id": "AC-11120-3",
+      "description": "A caller whose claim record was malformed on a first read and well-formed on a second read (a claim refresh) emits exactly one refused event and one verified event on the `keycloak.roles` family, in order; the retry itself is not a distinct event.",
+      "given": "a caller whose first claim read is malformed and whose second claim read (after a re-verify) is well-formed",
+      "when": "the role adapter reads twice in sequence",
+      "then": "the audit sink records exactly two events in order: one `keycloak.roles` event with `outcome=refused` and `reasonClass=malformed`, then one `keycloak.roles` event with `outcome=verified`; no additional event is written for the retry itself",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+        "field": "responsibilities.rolesAudit"
+      }
+    },
+    {
+      "id": "AC-11120-4",
+      "description": "A sink failure during the emission of a `keycloak.roles` event does not mask the underlying read outcome; the mechanism records a `keycloak.audit_sink_failed` warning event and the read outcome is unchanged.",
+      "given": "a verified claim record whose expected role path is well-formed and an audit sink whose write throws",
+      "when": "the role adapter emits the completion event",
+      "then": "the read's return value (the reduced roles array or the refusal) is unchanged; the mechanism records a `keycloak.audit_sink_failed` warning event carrying the realm slug and a reason-class string; the raw claim record does not appear in any field",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+        "field": "responsibilities.rolesAudit"
+      }
+    },
+    {
+      "id": "AC-11120-5",
+      "description": "Reading roles twice from the same well-formed verified claim record is idempotent: each read emits exactly one `keycloak.roles` audit event with `outcome=verified`; two consecutive reads produce two events (count is one per read call).",
+      "given": "a verified claim record whose expected role path is an array of strings in realm `alpha`, and one completed read already on record",
+      "when": "the role adapter reads the roles from the same claim record a second time",
+      "then": "the audit sink records exactly one additional event whose own-property keys are exactly `{family, outcome, realmSlug, at}` with `family=keycloak.roles` and `outcome=verified`; the total count of `keycloak.roles` verified events across the two reads is exactly two; the reduced roles array returned by the second read is identical to the first",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+        "field": "responsibilities.rolesAudit"
+      }
+    },
+    {
+      "id": "AC-11120-6",
+      "description": "A read on a claim record whose expected role path is absent (the caller's credential carries no granted role and so no operation is permitted through this mechanism) emits exactly one `keycloak.roles` audit event with `outcome=refused` and `reasonClass=roles_absent`; the reduced roles array is not populated and no operation is authorised downstream.",
+      "given": "a verified claim record in realm `alpha` whose expected role path is not present on the record",
+      "when": "the role adapter reads the roles from the claim record",
+      "then": "the audit sink records exactly one event whose own-property keys are exactly `{family, outcome, reasonClass, realmSlug, at}` with `family=keycloak.roles`, `outcome=refused`, and `reasonClass=roles_absent`; the raw claim record does not appear in any field; the reduced roles array is not populated",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-1205-security-auth-keycloak-role-adapter",
+        "field": "responsibilities.rolesAudit"
+      }
+    }
+  ],
+  "tacIds": [
+    "TAC-1205-security-auth-keycloak-role-adapter"
+  ],
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "description": "Applying agent sets: no project-parameterised values on this story; every AC is `fixed`. AC-set sufficiency (7a inline note per blueprint-authoring.md §7a): the credential scenario class is bound by AC-1 (a verified claim record is the credential and the event records the realm-scoped identity via the `realmSlug` payload field). The permission scenario class is bound by AC-6 (a claim record whose expected role path is absent carries no granted role, so the mechanism refuses with `reasonClass=roles_absent` and populates no reduced roles array)."
+}

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

@@ -71,7 +71,7 @@ Shipping this doc set costs the project 12 REQs, 13 USs (34 ACs), 5 TACs, and 6
 - The project needs delegated identity that is not vendor-committed (a small project that wants to plug in Google or GitHub without running a realm). Demote to `security-auth-oauth2`: supersede ADR-1201 with a project-level ADR pointing at oauth2's authModel; apply `security-auth-oauth2`.
 - The project's audience needs a passwordless-magic-link posture (regulated environment, no third-party identity dependency). Demote to `security-auth-magic-link`.
 
-## Provider-aware install-design shape (Baz-reshape, restated)
+## Provider-aware install-design shape (operator reshape, restated)
 
 The blueprint stays Keycloak-committed. What the blueprint does NOT do is assume Keycloak is the only issuer the receiving system will ever consult. Two shapes make this explicit: