rcf-lite 0.26.0 → 0.28.0

package/blueprints/security-auth-oauth2/contributions/probes/real-account-authorisation-code-flow.mjs

@@ -0,0 +1,93 @@
+// Real-account authorisation-code-flow probe for security-auth-
+// oauth2. Runs the RFC 6749 code flow with RFC 7636 PKCE against a
+// real, commercial OAuth 2.0 authorisation server when the estate
+// has one wired.
+//
+// This estate does NOT have a live commercial IdP available. The
+// probe honest-skips when the gate variables are not set, and when
+// credentials ARE supplied the probe explicitly reports that the
+// live-provider branch is not yet implemented and returns a FAIL
+// per rule (never a misleading pass).
+//
+// capability: authorisationCodeFlow.
+// Anchor: AC-10110-2 (a live public-provider smoke
+//   against a real IdP completes a full authorisation-code + PKCE
+//   round-trip and issues a project session).
+// accountBound: true.
+
+import { DECLARED_ENV, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcId = 'security-auth-oauth2-AC-10110-2';
+export const capability = 'authorisationCodeFlow';
+export const accountBound = true;
+
+const SECOND_TIER_VARS = ['OAUTH2_ISSUER_URL', 'OAUTH2_CLIENT_ID', 'OAUTH2_CLIENT_SECRET', 'OAUTH2_REDIRECT_URI'];
+
+function gateResult(varName, value) {
+  // Distinguishes unset from set-but-not-true per rule 4 of the master brief.
+  if (value === undefined || value === '') {
+    return { kind: 'unset', reason: varName };
+  }
+  if (value !== 'true') {
+    return { kind: 'set-not-true', reason: `${varName}_SET_NOT_TRUE`, observedValue: value };
+  }
+  return { kind: 'true' };
+}
+
+export default async function runProbe() {
+  const gate = gateResult('CI_HAS_OAUTH2_PROVIDER', process.env.CI_HAS_OAUTH2_PROVIDER);
+  if (gate.kind === 'unset') {
+    return {
+      results: [accountBoundSkippedResult(anchorAcId, capability, 'CI_HAS_OAUTH2_PROVIDER')],
+      extra: {
+        accountBoundSkipped: true,
+        reason: 'CI_HAS_OAUTH2_PROVIDER',
+        envDeclared: [...DECLARED_ENV],
+        note: 'No live commercial OAuth 2.0 IdP is available in this estate. Local shipped-shape evidence is authorisation-code-flow-shape against the fixture mock. The live branch reads AMBER on criterion e until an IdP is wired.',
+      },
+    };
+  }
+  if (gate.kind === 'set-not-true') {
+    return {
+      results: [{
+        anchorAcId, capability, verdict: 'fail',
+        detail: `AC-10110-2 gate: CI_HAS_OAUTH2_PROVIDER is set to "${gate.observedValue}" (not the string "true"). Gate refuses this shape; set the variable to the exact string "true" to run the live branch.`,
+        evidence: { gate: 'CI_HAS_OAUTH2_PROVIDER', observedValue: gate.observedValue, expected: 'true', status: 400 },
+      }],
+      extra: { gateMisconfigured: true, gate: 'CI_HAS_OAUTH2_PROVIDER', envDeclared: [...DECLARED_ENV] },
+    };
+  }
+
+  // Second-tier variable check: one result row per unset variable
+  // per rule 4 of the master brief.
+  const unsetRows = [];
+  for (const v of SECOND_TIER_VARS) {
+    if (!process.env[v]) {
+      unsetRows.push({
+        anchorAcId, capability, verdict: 'pass', accountBoundSkipped: true, reason: v,
+        detail: `accountBoundSkipped: ${v} unset. AC-10110-2 requires a live public provider; set ${v} to run the live branch.`,
+      });
+    }
+  }
+  if (unsetRows.length > 0) {
+    return {
+      results: unsetRows,
+      extra: { accountBoundSkipped: true, unsetVars: unsetRows.map((r) => r.reason), envDeclared: [...DECLARED_ENV] },
+    };
+  }
+
+  // Credentials present but the live branch is not implemented in
+  // this estate. Return FAIL with an explicit named-not-implemented
+  // detail (never a misleading pass).
+  return {
+    results: [{
+      anchorAcId, capability, verdict: 'fail',
+      detail: 'AC-10110-2 live branch is NOT IMPLEMENTED. Every gate variable is set, but the estate has no wired live commercial IdP and no round-trip code has been authored. Supplying credentials does not silently pass; the branch must be implemented before this result flips to pass. Local shipped-shape evidence is authorisation-code-flow-shape against the fixture mock; the live branch remains AMBER until an IdP is wired.',
+    }],
+    extra: {
+      envDeclared: [...DECLARED_ENV],
+      liveBranchImplemented: false,
+      note: 'implement round-trip against OAUTH2_ISSUER_URL/OAUTH2_CLIENT_ID/OAUTH2_CLIENT_SECRET/OAUTH2_REDIRECT_URI here when a live IdP is added to the estate',
+    },
+  };
+}

package/blueprints/security-auth-oauth2/contributions/probes/run-authorisation-code-flow-shape.mjs

@@ -0,0 +1,4 @@
+import runProbe from './authorisation-code-flow-shape.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'fixture', image: 'in-process mock RFC 6749 + RFC 7636 server on 127.0.0.1', healthy: true };
+runShim('authorisation-code-flow-shape', engine, runProbe);

package/blueprints/security-auth-oauth2/contributions/probes/run-pkce-challenge-shape.mjs

@@ -0,0 +1,4 @@
+import runProbe from './pkce-challenge-shape.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'fixture', image: 'fixture PKCE helper (local)', healthy: true };
+runShim('pkce-challenge-shape', engine, runProbe);

package/blueprints/security-auth-oauth2/contributions/probes/run-provider-adapter-shape.mjs

@@ -0,0 +1,4 @@
+import runProbe from './provider-adapter-shape.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'fixture', image: 'fixture provider-adapter (local)', healthy: true };
+runShim('provider-adapter-shape', engine, runProbe);

package/blueprints/security-auth-oauth2/contributions/probes/run-real-account-authorisation-code-flow.mjs

@@ -0,0 +1,4 @@
+import runProbe from './real-account-authorisation-code-flow.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'oauth2-provider' /* live-provider branch is honest-skip; slug AMBER */, image: 'commercial OAuth 2.0 authorisation server (or skipped)', healthy: true };
+runShim('real-account-authorisation-code-flow', engine, runProbe);

package/blueprints/security-auth-oauth2/contributions/probes/run-session-bridge-shape.mjs

@@ -0,0 +1,4 @@
+import runProbe from './session-bridge-shape.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'fixture', image: 'fixture session-bridge (local)', healthy: true };
+runShim('session-bridge-shape', engine, runProbe);

package/blueprints/security-auth-oauth2/contributions/probes/session-bridge-shape.mjs

@@ -0,0 +1,78 @@
+// Session-bridge shape probe. Conformance-only. Every row records
+// anchorAcId=null with a limitation naming the shipped AC whose
+// request/cookie property the local bridge observation does not
+// exercise. The integration harness follow-up is the surface where
+// the AC-level properties become observable.
+//
+// capability: sessionInventory. engine: fixture. accountBound: false.
+
+import { pathToFileURL } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { deClaim } from './probe-utils.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_SRC = resolve(HERE, '..', '..', '..', '..', 'packages', 'rcf-lite', 'test', 'fixtures', 'security-auth-oauth2', 'src');
+
+export const anchorAcId = null;
+export const capability = 'sessionInventory';
+export const accountBound = false;
+
+const LIM_P = 'security-auth-oauth2-AC-10106-1: probe returns a bridged session object; the AC states request.auth carries a Principal on a protected request, needs the integration harness (the auth integration harness follow-up).';
+const LIM_LEAK = 'security-auth-oauth2-AC-10106-3: probe inspects the bridge return; the AC states request.auth on a protected request does not expose provider tokens, needs the integration harness (the auth integration harness follow-up).';
+const LIM_H = 'security-auth-oauth2-AC-10101-3: probe inspects a bridge handle string; the AC states the session cookie carries an opaque project handle, needs a real cookie set at the response, needs the integration harness (the auth integration harness follow-up).';
+const LIM_INV = 'security-auth-oauth2-AC-10106-2: probe uses malformed provider inputs; the AC states a request lacking a valid handle is refused before session issue, needs the integration harness (the auth integration harness follow-up).';
+
+export default async function runProbe() {
+  const { bridgeSession } = await import(pathToFileURL(resolve(FIXTURE_SRC, 'provider-adapter.mjs')).href);
+  const results = [];
+
+  const good = bridgeSession({
+    tokenResponse: { access_token: 'tok-abc', expires_in: 3600, scope: 'openid profile' },
+    userinfo: { sub: 'user-123', email: 'u@example.com' },
+  });
+  results.push(deClaim({
+    capability,
+    verdict: good.ok && good.session && good.session.principalId === 'user-123' ? 'pass' : 'fail',
+    detail: `bridge returns session with principalId: ok=${good.ok} principalId=${good.session && good.session.principalId}`,
+    evidence: { adapterReturn: good },
+  }, { ac: 'security-auth-oauth2-AC-10106-1', limitation: LIM_P }));
+
+  const sessionKeys = good.ok ? Object.keys(good.session) : [];
+  const providerTokenLeaks = sessionKeys.filter((k) => /^(access|refresh|id)_?[Tt]oken$/.test(k));
+  results.push(deClaim({
+    capability,
+    verdict: good.ok && providerTokenLeaks.length === 0 ? 'pass' : 'fail',
+    detail: `bridge return omits provider tokens: sessionKeys=${JSON.stringify(sessionKeys)} leaks=${JSON.stringify(providerTokenLeaks)}`,
+    evidence: { sessionKeys, providerTokenLeaks },
+  }, { ac: 'security-auth-oauth2-AC-10106-3', limitation: LIM_LEAK }));
+
+  const handleOk = good.ok
+    && typeof good.session.handle === 'string'
+    && good.session.handle.length >= 20
+    && !good.session.handle.includes('tok-abc');
+  results.push(deClaim({
+    capability,
+    verdict: handleOk ? 'pass' : 'fail',
+    detail: `bridge handle is opaque and not derived from access_token: handleLen=${good.session && good.session.handle && good.session.handle.length}`,
+    evidence: { handlePrefix: good.session && good.session.handle && good.session.handle.slice(0, 4), handleLen: good.session && good.session.handle && good.session.handle.length },
+  }, { ac: 'security-auth-oauth2-AC-10101-3', limitation: LIM_H }));
+
+  const missingSub = bridgeSession({ tokenResponse: { access_token: 'tok-abc' }, userinfo: {} });
+  results.push(deClaim({
+    capability,
+    verdict: !missingSub.ok && /userinfo\.sub/.test(missingSub.error) ? 'pass' : 'fail',
+    detail: `bridge refuses missing userinfo.sub: ok=${missingSub.ok} error=${JSON.stringify(missingSub.error)}`,
+    evidence: { adapterReturn: missingSub },
+  }, { ac: 'security-auth-oauth2-AC-10106-2', limitation: LIM_INV }));
+
+  const missingTok = bridgeSession({ tokenResponse: {}, userinfo: { sub: 'x' } });
+  results.push(deClaim({
+    capability,
+    verdict: !missingTok.ok && /access_token/.test(missingTok.error) ? 'pass' : 'fail',
+    detail: `bridge refuses missing access_token: ok=${missingTok.ok} error=${JSON.stringify(missingTok.error)}`,
+    evidence: { adapterReturn: missingTok },
+  }, { ac: 'security-auth-oauth2-AC-10106-2', limitation: LIM_INV }));
+
+  return { results, extra: {} };
+}

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

@@ -2,7 +2,7 @@
   "reqId": "security-auth-oauth2-REQ-001",
   "prdId": "PRD-001",
   "title": "Authorisation-code flow with PKCE is the sole delegated-identity flow",
-  "description": "The project's authentication model is delegated identity via OAuth2 authorisation-code flow (RFC 6749 section 4.1) hardened with Proof Key for Code Exchange (RFC 7636). The implicit flow, the resource-owner password credentials flow, and the client credentials flow are refused at the flow-controller boundary. The `response_type` on the authorisation request is fixed to `code`; the token exchange is a back-channel POST that presents the `code_verifier`. The mechanism is vendor-neutral: any provider that speaks authorisation-code + PKCE plugs in through the provider-abstraction contract; no provider name appears in the flow controller's code path.",
+  "description": "The project's authentication model is delegated identity via OAuth2 authorisation-code flow (RFC 6749 section 4.1) hardened with Proof Key for Code Exchange (RFC 7636). This blueprint publishes the flow to consumers under the capability token `authorisationCodeFlow` (declared on `blueprint.json:capabilities[]`); a superseding blueprint that owns the flow and the session-bridge declares the same token to remain composable with keycloak and its siblings. The implicit flow, the resource-owner password credentials flow, and the client credentials flow are refused at the flow-controller boundary. The `response_type` on the authorisation request is fixed to `code`; the token exchange is a back-channel POST that presents the `code_verifier`. The mechanism is vendor-neutral: any provider that speaks authorisation-code + PKCE plugs in through the provider-abstraction contract; no provider name appears in the flow controller's code path. The redirect to the provider's `authorizeUrl` is the mechanism by which the blueprint contributes the `hostedIdentityUi` capability: no project route renders a credential-input form of its own; the browser lives at the provider's hosted sign-in surface for every credential moment, and the project sees only the callback plus the code exchange. Runtime behaviour is asserted by `US-10101` and its refusal-path siblings (`US-10102`, `US-10103`, `US-10104`).",
   "category": "functional",
   "domain": "authentication",
   "priority": "must",
@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1101-security-auth-oauth2-auth-model"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1102-security-auth-oauth2-provider-adapter",
+    "field": "responsibilities.providerConfig"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1101-security-auth-oauth2-flow-controller",
+    "field": "responsibilities.state"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1103-security-auth-oauth2-pkce-discipline"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1101-security-auth-oauth2-flow-controller",
+    "field": "responsibilities.id_token"
+  }
 }

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

@@ -2,7 +2,7 @@
   "reqId": "security-auth-oauth2-REQ-006",
   "prdId": "PRD-001",
   "title": "Session issue after code exchange goes through one bridge",
-  "description": "After a successful token exchange (and id_token verification for OIDC providers), the flow controller passes the resolved identity to the session-bridge (TAC-1103). The bridge translates the provider identity into a reduced `Principal` shape: `principalId` (a stable in-process id derived from the provider's `sub` claim under an OIDC provider, or the provider's userinfo `id` field under an `oauth2-only` provider, joined to the provider's `id` slug so two providers cannot collide on the same underlying sub), `provider` (the provider `id`), `email` (if the provider returned one), `roles` (an empty array by default; a project-authored bridge extension may enrich), `organisationIds` (empty by default; project-authored bridge extension may enrich). The bridge then issues a project session (opaque-handle cookie is the reference shape; the storage seam is delegated). No downstream code path reasons about the provider's raw claim shape, provider tokens, or refresh material; only the reduced `Principal` and the session handle cross the bridge outward.",
+  "description": "After a successful token exchange (and id_token verification for OIDC providers), the flow controller passes the resolved identity to the session-bridge (TAC-1103). The bridge translates the provider identity into a reduced `Principal` shape: `principalId` (a stable in-process id derived from the provider's `sub` claim under an OIDC provider, or the provider's userinfo `id` field under an `oauth2-only` provider, joined to the provider's `id` slug so two providers cannot collide on the same underlying sub), `provider` (the provider `id`), `email` (if the provider returned one), `roles` (an empty array by default; a project-authored bridge extension may enrich), `organisationIds` (empty by default; project-authored bridge extension may enrich). The bridge then issues a project session (opaque-handle cookie is the reference shape; the storage seam is delegated). No downstream code path reasons about the provider's raw claim shape, provider tokens, or refresh material; only the reduced `Principal` and the session handle cross the bridge outward. The reduced `Principal` from the session-bridge is what the blueprint contributes as the `principalDirectory` capability: no other read-side surface on the project answers \"who is the caller\"; every project code path that reasons about identity reasons against the fields on this Principal, and the applied capability set exposes the token so consumer blueprints can bind against it.",
   "category": "functional",
   "domain": "authentication",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1103-security-auth-oauth2-session-bridge",
+    "field": "responsibilities.sessionRecordStore"
+  }
 }

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

@@ -14,5 +14,8 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-1105-security-auth-oauth2-refresh-token-posture"
+  }
 }

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

@@ -2,7 +2,7 @@
   "reqId": "security-auth-oauth2-REQ-008",
   "prdId": "PRD-001",
   "title": "Sign-out invalidates the project session; provider-side sign-out is a project option",
-  "description": "The blueprint mandates one sign-out shape: a project route (`POST /auth/sign-out` in the reference wiring) that invalidates the project session handle server-side and clears the session cookie on the response. Every subsequent request presenting the cleared cookie or the invalidated handle is treated as unauthenticated. Provider-side sign-out (RP-Initiated Logout, RFC-drafted for OIDC; provider-specific for OAuth2-only providers) is a project-authored option NOT mandated by the blueprint: a project that wants a downstream provider session cleared on sign-out sets `providerLogout: 'redirect'` on the provider record, and the flow controller emits a redirect to the provider's declared `endSessionEndpoint` after clearing the project session. A provider whose declaration omits `endSessionEndpoint` and whose record is set to `providerLogout: 'redirect'` is refused at boot with `OAUTH2_LOGOUT_NOT_DECLARED`.",
+  "description": "The blueprint mandates one sign-out shape: a project route (`POST /auth/sign-out` in the reference wiring) that invalidates the project session handle server-side and clears the session cookie on the response. Every subsequent request presenting the cleared cookie or the invalidated handle is treated as unauthenticated. Provider-side sign-out (RP-Initiated Logout, RFC-drafted for OIDC; provider-specific for oauth2-only providers) is a project-authored option NOT mandated by the blueprint: a project that wants a downstream provider session cleared on sign-out sets `providerLogout: 'redirect'` on the provider record, and the flow controller emits a redirect to the provider's declared `endSessionEndpoint` after clearing the project session. A provider whose declaration omits `endSessionEndpoint` and whose record is set to `providerLogout: 'redirect'` is refused at boot with `OAUTH2_LOGOUT_NOT_DECLARED`.",
   "category": "functional",
   "domain": "authentication",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1101-security-auth-oauth2-flow-controller",
+    "field": "responsibilities.endSessionEndpoint"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-08-30T00:00:00Z",
-  "updatedAt": "2026-08-30T00:00:00Z"
+  "updatedAt": "2026-08-30T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1104-security-auth-oauth2-provider-selector",
+    "field": "responsibilities.providerConfig"
+  }
 }

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

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

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-oauth2-REQ-011",
+  "prdId": "PRD-001",
+  "title": "Role sources and role mapping are declared per provider; the reduced Principal carries the resulting roles array",
+  "description": "The blueprint contributes the `roleModel` capability by naming the provider-record `roleSources[]` field (an ordered list of claim paths the session-bridge reads: for example `[\"realm_access.roles\", \"resource_access.<clientId>.roles\", \"groups\"]`) and an optional project-authored principal-enrichment hook whose signature is owned by `TAC-1103-security-auth-oauth2-session-bridge` `interfaces.enrichPrincipal`. The session-bridge walks each `roleSources[]` path against the verified claim record (id_token for OIDC providers, userinfo for oauth2-only providers) and populates `roles[]` with the union of the string values found; a path that resolves to a non-string non-array-of-strings shape is refused with `OAUTH2_ROLES_MALFORMED` and the session is not issued. The blueprint mandates that authorisation decisions above the middleware read `principal.roles[]` and never a raw provider claim; project routes that need role-based gating do so through a project-authored predicate that takes the reduced Principal.",
+  "category": "functional",
+  "domain": "authorisation",
+  "priority": "must",
+  "rationale": "A capability declaration for `roleModel` on a blueprint whose default behaviour is an empty roles array leaves consumers to gate on a token the provider blueprint never wrote a contract for. Naming `roleSources[]` and the malformed-claim refusal is what turns the token into an apply-time observable.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:11-role-model"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1103-security-auth-oauth2-session-bridge",
+    "field": "responsibilities.roles"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "reqId": "security-auth-oauth2-REQ-012",
+  "prdId": "PRD-001",
+  "title": "Password change, reset, recovery and account management are delegated to the provider's self-service surface",
+  "description": "The blueprint contributes the `credentialSelfService` capability by resolving and exposing the provider record's `accountUrl` field (a URL the provider documents for account, password and recovery self-service; for example Google's https://myaccount.google.com, GitHub's https://github.com/settings/security). The provider adapter verifies at boot that every enabled provider record carries `accountUrl` as an absolute https URL under the provider's documented origin (or an explicit `null` when the provider offers no self-service surface); a provider that declares `credentialSelfService` support without an `accountUrl` is refused with `OAUTH2_ACCOUNT_URL_MISSING`. The project exposes `getCredentialSelfServiceUrl(principal)` that returns the resolved URL for the principal's provider; a project page linking to self-service reads that helper rather than hard-coding a URL. No project route renders a credential-change form of its own.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A capability declaration for `credentialSelfService` on an OAuth2/OIDC blueprint whose sign-in is already delegated makes little sense unless the account-management surface is also delegated by contract; naming the `accountUrl` field and the boot-time verification is what turns the capability into a bind-able surface.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:12-credential-self-service"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-09T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-1102-security-auth-oauth2-provider-adapter",
+    "field": "responsibilities.accountUrl"
+  }
+}

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

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

package/blueprints/security-auth-oauth2/contributions/tacs/tac-1102-security-auth-oauth2-provider-adapter.json

@@ -11,7 +11,8 @@
     "Refuse boot on a malformed record with a stable-coded error naming the provider id and the missing or invalid field; audit event `oauth2.provider_config_refused` carries provider id and reason class (AC-10108-3).",
     "Expose `resolve(providerId) -> record | absent`; return `absent` for an unknown id and let the flow controller emit OAUTH2_PROVIDER_UNKNOWN (AC-10109-2).",
     "Expose `fetchJwks(providerId) -> { keys[] }` with a cache keyed by provider id whose TTL is `jwksCacheTtlSeconds` (default 900); refresh on cache miss or on a verifier hint that a key is unknown (AC-10105-1, AC-10105-2).",
-    "Never expose `clientSecret` on the client-tier record form; the client-tier record carries a redacted placeholder and the server-tier record carries the real value (REQ-002)."
+    "Never expose `clientSecret` on the client-tier record form; the client-tier record carries a redacted placeholder and the server-tier record carries the real value (REQ-002).",
+    "Validate each enabled provider record's `accountUrl` at boot: an absolute https URL under the provider's documented self-service origin, or an explicit `null` when the provider carries `credentialSelfService: false`; refuse with `OAUTH2_ACCOUNT_URL_MISSING` on a `credentialSelfService: true` record lacking `accountUrl`, or `OAUTH2_ACCOUNT_URL_ORIGIN` on an origin mismatch (AC-10113-1, AC-10113-3, AC-10113-4)."
   ],
   "internalStructure": "One factory function producing an adapter closure over an injected `providerConfig` module (a plain data record set) and an injected `httpFetch` port (the process's HTTP client, either the platform's `fetch` or an injected mock in tests). The JWKS cache is a Map keyed by provider id whose value is `{ keys[], fetchedAt }`; TTL eviction is on read. The validator is a pure function invoked once at boot per record.",
   "interfaces": [

package/blueprints/security-auth-oauth2/contributions/tacs/tac-1103-security-auth-oauth2-session-bridge.json

@@ -12,7 +12,9 @@
     "Issue an opaque-handle session cookie: mint a cryptographically random handle, store the session record `{ handle, principal, providerId, accessToken, idToken, refreshToken?, issuedAt, expiresAt }` in the session-record store, and emit `Set-Cookie` with `HttpOnly`, `Secure`, `SameSite=Lax` (AC-10101-3, AC-10106-1).",
     "Verify a presented handle at the middleware boundary: lookup, expiry check, tampered-value refusal, populate `request.auth` on success, refuse otherwise; do not renew a tampered cookie (AC-10106-1, AC-10106-2).",
     "Invalidate on sign-out: delete the session record, clear the associated refresh-token chain, emit the cookie-clear header (AC-10108-1).",
-    "Delegate the session-record store to a project-authored implementation (in-memory for the reference wiring; SQLite for `persistence-data-sqlite`-composed projects; D1 for `persistence-data-d1`-composed projects); do not embed a store implementation (REQ-006)."
+    "Delegate the session-record store to a project-authored implementation (in-memory for the reference wiring; SQLite for `persistence-data-sqlite`-composed projects; D1 for `persistence-data-d1`-composed projects); do not embed a store implementation (REQ-006).",
+    "Populate `roles[]` on the reduced Principal by walking each path named on the provider record's `roleSources[]` against the verified claim record; take the union of the resulting string values; refuse with `OAUTH2_ROLES_MALFORMED` when a named path resolves to a value that is neither string nor array-of-strings (AC-10112-1, AC-10112-2, AC-10112-3, AC-10112-4).",
+    "Expose `sessionInventory` against the session-record store (list, revoke-one, revoke-all-except-current); the interface shape is owned by `TAC-1003-security-auth-clerk-session-verifier` `interfaces.sessionInventory` and referenced by that owner id; a revoke clears the associated refresh-token chain per REQ-007 (AC-10114-1, AC-10114-2, AC-10114-3, AC-10114-4, AC-10114-5)."
   ],
   "internalStructure": "One factory function producing an issue/verify/invalidate closure over an injected `sessionRecordStore`, an injected `refreshTokenStore` (shared with the flow controller), an injected `randomBytes` port for handle minting, an injected clock, and an injected `enrichPrincipal` hook (or a no-op default). The session-record shape is a plain object; the store's on-disk shape is the project's concern.",
   "interfaces": [
@@ -43,7 +45,12 @@
     }
   ],
   "dependencies": [
-    { "name": "OAuth2 flow controller", "kind": "tac", "tacId": "TAC-1101-security-auth-oauth2-flow-controller", "description": "The bridge is invoked by the controller at the end of a successful callback; the bridge does not initiate flows." }
+    {
+      "name": "OAuth2 flow controller",
+      "kind": "tac",
+      "tacId": "TAC-1101-security-auth-oauth2-flow-controller",
+      "description": "The bridge is invoked by the controller at the end of a successful callback; the bridge does not initiate flows."
+    }
   ],
   "tradeoffs": "Deriving `principalId` from `{provider.id, subject}` prevents accidental cross-provider identity merging; the trade is that a project that wants such merging must author an explicit identity-merge policy in its enrichPrincipal hook. Storing provider tokens on the server-side session record rather than the browser cookie carries a small per-session storage cost and buys the project one code path for revocation on sign-out and refresh-token reuse; the tokens never appear in a place the browser can leak them. Exposing an `enrichPrincipal` hook without prescribing a role-source lets a project reach for its own claim-mapping vocabulary without the blueprint committing to one.",
   "createdAt": "2026-08-30T00:00:00Z",

package/blueprints/security-auth-oauth2/contributions/user-stories/security-auth-oauth2-us-10101.json

@@ -16,7 +16,8 @@
       "when": "the request is dispatched and the response is inspected",
       "then": "the response is a 302 to the provider's declared `authorizeUrl`; the location query carries `response_type=code`, `code_challenge` (matches `^[A-Za-z0-9_-]{43,128}$`), `code_challenge_method=S256`, a `state` value distinct from any previously observed value in the test's collector; no `access_type=implicit` or `response_type=token` is present",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10101-2",
@@ -25,7 +26,8 @@
       "when": "the browser follows the provider's redirect back to the project's callback route",
       "then": "the flow controller issues a POST to the provider's `tokenUrl` whose body carries `grant_type=authorization_code`, the returned `code`, `client_id`, `code_verifier` (matching the pending-flow record), and `redirect_uri`; the response is a 2xx with `access_token`; for an OIDC provider the response additionally carries an `id_token`",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10101-3",
@@ -34,7 +36,8 @@
       "when": "the browser inspects the response cookie jar",
       "then": "a session cookie declared by the project's session-cookie name (per config) is set with `Secure`, `HttpOnly`, and `SameSite=Lax`; the cookie value does not equal the access token, the id_token, or any refresh token returned by the provider; the value matches the opaque-handle shape declared by the session-bridge",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-oauth2/contributions/user-stories/security-auth-oauth2-us-10102.json

@@ -16,7 +16,8 @@
       "when": "the request reaches the flow controller",
       "then": "the response is a 4xx with body error code `OAUTH2_STATE_UNKNOWN`; the mock provider's `tokenUrl` records zero request attempts for this state value; no session cookie is set on the response",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10102-2",
@@ -25,7 +26,8 @@
       "when": "a subsequent callback request is dispatched with the same `state=s1` value",
       "then": "the response is a 4xx with body error code `OAUTH2_STATE_ALREADY_CONSUMED`; the mock provider's `tokenUrl` records zero new request attempts for this state; no session cookie is set on the response",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10102-3",
@@ -34,7 +36,8 @@
       "when": "the callback for `s2` is dispatched",
       "then": "the response is a 4xx with body error code `OAUTH2_STATE_EXPIRED`; the pending-flow record has been evicted from the store; no session cookie is set on the response",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-oauth2/contributions/user-stories/security-auth-oauth2-us-10103.json

@@ -16,7 +16,8 @@
       "when": "the flow controller's outbound token-exchange request is inspected before it leaves the process",
       "then": "the request body contains a `code_verifier` field whose value equals the verifier stored on the pending-flow record for the state; the request body carries no `code_challenge_method` field (verifier is presented, method is provider-remembered from authorise)",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10103-2",
@@ -25,7 +26,8 @@
       "when": "the callback reaches the flow controller",
       "then": "the response is a 4xx with body error code `OAUTH2_TOKEN_EXCHANGE_FAILED` naming the provider response class as `invalid_grant`; no session cookie is set on the response; the pending-flow record for this state has been evicted",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-oauth2/contributions/user-stories/security-auth-oauth2-us-10104.json

@@ -16,7 +16,8 @@
       "when": "the callback reaches the flow controller",
       "then": "the response is a 4xx with body error code `OAUTH2_TOKEN_EXCHANGE_FAILED` naming the provider response class as `invalid_grant`; no session cookie is set on the response",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10104-2",
@@ -25,7 +26,8 @@
       "when": "a subsequent callback request is dispatched with `state=s3&code=c3`",
       "then": "the response is a 4xx with body error code `OAUTH2_STATE_ALREADY_CONSUMED`; the mock provider's `tokenUrl` records zero new request attempts for this state; no session cookie is set on the response",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [

package/blueprints/security-auth-oauth2/contributions/user-stories/security-auth-oauth2-us-10105.json

@@ -16,7 +16,8 @@
       "when": "the flow controller invokes its verifier module on the returned id_token",
       "then": "the verifier returns `{ valid: true, claims: { iss, aud, sub, exp, nonce } }`; the flow proceeds to session issue; the audit log records one `oauth2.id_token_verified` event carrying provider id and no token value",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10105-2",
@@ -25,7 +26,8 @@
       "when": "the callback reaches the flow controller",
       "then": "the response is a 4xx with body error code `OAUTH2_ID_TOKEN_SIGNATURE_INVALID`; no session cookie is set; the audit log records one `oauth2.id_token_refused` event carrying provider id, reason class `signature`, and no token value",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10105-3",
@@ -34,7 +36,8 @@
       "when": "the callback reaches the flow controller",
       "then": "the response is a 4xx with body error code `OAUTH2_ID_TOKEN_ISSUER_MISMATCH`; no session cookie is set; the audit log records one `oauth2.id_token_refused` event carrying provider id, reason class `issuer`, and no token value",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-10105-4",
@@ -43,7 +46,8 @@
       "when": "the callback reaches the flow controller",
       "then": "the response is a 4xx with body error code `OAUTH2_MISSING_ID_TOKEN`; no session cookie is set; the audit log records one `oauth2.id_token_refused` event carrying provider id, reason class `missing`, and no token value",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [