rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Refresh tokens rotate on every exchange and revoke the whole chain on reuse",
+  "description": "When the provider issues a refresh token alongside the access token, the flow-controller stores it server-side keyed by the project session handle (never in a cookie the browser holds, never in the client tier). On refresh, the controller presents the current refresh token to the provider, replaces its stored copy with the new refresh token the provider returns, and updates the associated access-token record. Detecting the same refresh-token value on a second refresh attempt (a `refresh_token_reuse` signal) revokes the entire chain: the current session handle is invalidated, every stored refresh token that shares the same chain root is cleared, and one structured audit event `oauth2.refresh_token_reuse` is emitted carrying the provider `id`, the session handle hash, and the detection timestamp; no token value is emitted. A provider that does not issue refresh tokens for a given configuration is a supported posture: the project session lives out its own lifecycle (REQ-008) without a refresh chain.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "Refresh-token rotation with reuse detection is the standard hardening for the class of attacks where an attacker exfiltrates a refresh token: as soon as either party redeems the token again, the identity chain is broken and the honest party (or the attacker) is refused. Storing refresh tokens server-side (rather than round-tripping through the browser) means an XSS or a malicious extension cannot lift them from the client tier. Naming reuse detection as an audit event with a stable code makes the detection legible to project ops without requiring a bespoke log-mining pipeline.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:07-refresh"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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`.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "The mandated shape is the invariant: project sessions clear on sign-out. Provider-side sign-out is a legitimate but variable concern (some deployments want a full downstream logout, others want the provider to keep the user signed in for other applications on the same tenant); mandating one posture would fight half the deployments. The declared config with fail-fast on missing endpoint catches the misconfiguration where a project believes it is doing provider-side sign-out and silently is not.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:08-sign-out"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-009",
+  "prdId": "PRD-001",
+  "title": "Two or more providers may be configured; the project selects one per sign-in",
+  "description": "A project may declare N providers on the provider-config module. When N > 1, the flow controller reads the requested provider id from the sign-in initiation (a `provider` query parameter on `GET /auth/sign-in` in the reference wiring) and refuses the request when the id is missing, unknown, or disabled. The provider-selector TAC (TAC-1104) renders a sign-in surface listing the configured providers by their operator-visible `label`, each linking to `/auth/sign-in?provider=<id>`; a project that wants a bespoke selector surface substitutes its own by wiring the same query-parameter contract on its own route. There is no fallback default provider; a missing `provider` on an N>1 configuration returns a stable-coded refusal, not the first entry in the list. When N == 1, the selector short-circuits: any request to `/auth/sign-in` without a `provider` parameter initiates the flow against the single configured provider.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A multi-provider blueprint that silently picks a default provider is a foot-gun: an operator who removes the first configured provider then finds every sign-in redirect changing shape without a config file diff. Requiring an explicit `provider` id on N>1 configurations makes the choice observable at the URL layer, which is the layer projects reason about. Single-provider projects get the short-circuit so they never write a query parameter that only exists because a second provider might one day be added.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:09-multi-provider"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-010",
+  "prdId": "PRD-001",
+  "title": "Runtime verification uses a project-authored mock OIDC provider; live vendors are accountBound",
+  "description": "Runtime-verify ACs on this blueprint bind against a mock OIDC provider the project stands up in the same process space (or an adjacent process the test harness spawns and tears down). The mock is real OIDC on the wire: it publishes a discovery document, a JWKS with a signing key it holds, an `/authorize` endpoint that returns a code against a stored pending request, a `/token` endpoint that redeems the code with PKCE-verifier check, a `/userinfo` endpoint that returns a fixed claim record, and an `endSessionEndpoint`. The mock is authored by the project (from the shape shipped in `assets/mock-provider/`) or drawn from an existing library; the blueprint does not commit a specific implementation to the project tree. ACs that require a smoke test against a live public IdP (Google, GitHub, Microsoft, corporate SSO) are `accountBound`: the runtime-verify layer marks them with an `accountBound` flag and a stable-coded skip reason (`OAUTH2_LIVE_PROVIDER_UNREACHABLE`) when live credentials are not present; the CI pipeline does not fail on a skipped `accountBound` AC, and the ship gate reads the honest coverage.",
+  "category": "functional",
+  "domain": "verification",
+  "priority": "must",
+  "rationale": "A blueprint that only verifies against live vendors is unrunnable in CI without a set of secret credentials the blueprint has no honest way to demand of every consumer. A blueprint that only verifies against a fake and never touches a real vendor misses the whole class of vendor-quirk failures. The pattern here is the pattern the sibling clerk blueprint took at the vendor tier: fake the mechanism (a real OIDC surface stood up locally) so the state machine, the PKCE binding, the id_token verification, and the session-bridge round-trip are gated by real runtime facts; mark the live-vendor smokes as `accountBound` so a project that has the credentials wires them and the project that does not can still ship with an honest known-gap statement in its README.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:10-verify-posture"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/tacs/tac-1101-security-auth-oauth2-flow-controller.json

@@ -0,0 +1,61 @@
+{
+  "tacId": "TAC-1101-security-auth-oauth2-flow-controller",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "OAuth2 authorisation-code + PKCE flow controller",
+  "purpose": "The state machine that owns every step of the delegated-identity flow: mint an authorisation redirect (state, nonce, PKCE code_verifier); accept the callback; verify state, code, and (for OIDC) id_token; exchange the code for tokens; hand the resolved identity to the session-bridge; expose the sign-out route. Every provider goes through this one module; provider variation lives on the provider record, not in the state machine.",
+  "responsibilities": [
+    "Mint one pending-flow record per sign-in initiation carrying state, nonce, code_verifier, provider id, requested redirect target, and minted-at timestamp; store server-side in an integrity-checked one-time store (AC-10101-1, AC-10102-1, AC-10102-2, AC-10102-3).",
+    "Build the authorisation redirect with response_type=code, code_challenge, code_challenge_method=S256, state, nonce (OIDC), and the provider-declared scopes; return a 302 to the provider's authorizeUrl (AC-10101-1, AC-10103-1).",
+    "Accept the callback: look up the pending-flow by state, refuse on unknown/expired/consumed, and consume the record atomically on successful callback (AC-10102-1, AC-10102-2, AC-10102-3).",
+    "Exchange the code at the provider's tokenUrl with grant_type=authorization_code and the stored code_verifier; refuse on non-2xx with stable-coded OAUTH2_TOKEN_EXCHANGE_FAILED naming the provider response class (AC-10101-2, AC-10103-2, AC-10104-1).",
+    "Verify the id_token when the provider declared OIDC: signature against JWKS, iss equality against declared issuer, aud containment of client_id, exp in the future, nonce equality against stored nonce; refuse-fast when id_token is absent for an OIDC-declared provider (AC-10105-1, AC-10105-2, AC-10105-3, AC-10105-4).",
+    "Hand the resolved identity to the session-bridge (TAC-1103) and emit the session cookie on the callback response (AC-10101-3).",
+    "Rotate refresh tokens on every refresh call; detect refresh-token reuse and revoke the chain (AC-10107-1, AC-10107-2, AC-10107-3).",
+    "Serve the sign-out route: invalidate the session server-side, clear the cookie, and emit an optional redirect to the provider's endSessionEndpoint when the provider record sets providerLogout='redirect' (AC-10108-1, AC-10108-2, AC-10108-3).",
+    "Refuse a sign-in initiation whose provider id is missing on N>1 configuration or unknown on any configuration with stable-coded OAUTH2_PROVIDER_UNKNOWN (AC-10109-2).",
+    "Emit exactly one structured audit event per state transition (id_token_verified, id_token_refused, token_exchange_failed, refresh_token_reuse, accountbound_skip, provider_config_refused); no field may carry a token value, a cookie value, or a substring of either (AC-10105-1, AC-10105-2, AC-10107-2, AC-10108-3, AC-10110-1)."
+  ],
+  "internalStructure": "One factory function producing the controller closure over an injected provider adapter (TAC-1102), an injected session-bridge (TAC-1103), an injected pending-flow store, an injected refresh-token store, an injected clock, and an injected audit sink. The state machine is a linear sequence of pure-ish steps: mint pending-flow -> redirect; on callback, look up pending-flow -> verify state -> token exchange -> id_token verify (OIDC) -> hand to session-bridge -> respond. Every I/O boundary (HTTP call to the provider, store read/write, audit emit) is a named injected port; the test harness substitutes an in-process mock at each port.",
+  "interfaces": [
+    {
+      "name": "providerAdapter",
+      "kind": "read-api",
+      "description": "The provider adapter (TAC-1102) resolving a provider record by id, returning `{ authorizeUrl, tokenUrl, userinfoUrl, issuer, jwksUri, clientId, clientSecret, scopes, redirectUri, providerKind, endSessionEndpoint?, providerLogout? }` and exposing a JWKS-fetching port for id_token verification."
+    },
+    {
+      "name": "sessionBridge",
+      "kind": "read-write-api",
+      "description": "The session-bridge (TAC-1103) exposing `issue(principal, providerTokens) -> { handle, cookie }` and `verify(handle) -> { valid, principal?, refreshToken? }` and `invalidate(handle) -> void`."
+    },
+    {
+      "name": "pendingFlowStore",
+      "kind": "read-write-api",
+      "description": "Server-side one-time store keyed by state, exposing `put(state, record)`, `takeOnce(state) -> record | absent`, and TTL-based eviction. In-memory in the reference wiring; a project may inject a persistence-backed implementation."
+    },
+    {
+      "name": "refreshTokenStore",
+      "kind": "read-write-api",
+      "description": "Server-side store keyed by session handle, exposing `put(handle, refreshToken)`, `rotate(handle, oldToken, newToken)`, `reuseDetect(handle, presentedToken) -> { reuse: boolean, chainRoot?: string }`, and `clearChain(chainRoot)`."
+    },
+    {
+      "name": "clock",
+      "kind": "read-api",
+      "description": "Injected time source returning epoch seconds; the test harness substitutes a controllable clock for TTL and expiry-window checks."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with `{ event, providerId, sessionHandleHash?, reasonClass?, at }`; never invoked with a token value or a cookie value."
+    }
+  ],
+  "dependencies": [
+    { "name": "OAuth2 provider adapter", "kind": "tac", "tacId": "TAC-1102-security-auth-oauth2-provider-adapter", "description": "Provider record resolution and JWKS fetch." },
+    { "name": "OAuth2 session-bridge", "kind": "tac", "tacId": "TAC-1103-security-auth-oauth2-session-bridge", "description": "Session issue, verify, invalidate." }
+  ],
+  "tradeoffs": "Fixing the flow at the controller and pushing every provider variation onto the record shape costs the project a small piece of boot-time work (declaring the provider record fields for each vendor) and buys the project one code path across every vendor for the state machine. Storing the pending-flow and the refresh-token chain on server-side stores rather than a browser cookie costs the project a small piece of state per pending sign-in and per active session; it buys the project defence against a category of front-channel exfiltration attacks against the PKCE verifier and the refresh chain. Injecting the clock costs the project one line of wiring; it buys the test harness clean TTL-and-expiry testing without real sleeps.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,33 @@
+{
+  "tacId": "TAC-1102-security-auth-oauth2-provider-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "OAuth2 provider adapter",
+  "purpose": "The pluggable seam that turns a project-authored provider record into the resolved shape the flow controller uses on every step. Owns per-record validation at boot, provider lookup by id at flow initiation, and the JWKS fetching port the id_token verifier reads through. Does NOT own the state machine and does NOT own session issue; those are the flow controller (TAC-1101) and the session-bridge (TAC-1103) respectively.",
+  "responsibilities": [
+    "Load the provider-config module at boot and validate every record: required fields present, `flow=authorisation-code-pkce`, `providerKind` in {`oidc`, `oauth2-only`}, OIDC providers carry `issuer` and `jwksUri`, records with `providerLogout='redirect'` carry `endSessionEndpoint` (AC-10108-3, AC-10109-2, REQ-002, REQ-008).",
+    "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)."
+  ],
+  "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": [
+    {
+      "name": "providerConfig",
+      "kind": "read-api",
+      "description": "The project-authored provider-config module exposing `list() -> record[]`. Each record is a plain object with the fields declared in REQ-002 and REQ-008. Server-tier records carry `clientSecret`; client-tier records carry a redacted placeholder."
+    },
+    {
+      "name": "httpFetch",
+      "kind": "read-api",
+      "description": "The process's HTTP-fetch port used for JWKS fetch; injected so the test harness can substitute an in-process mock that returns the mock provider's JWKS."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "Fixing the record shape and validating at boot fails fast on misconfigured providers rather than at the moment a real operator tries to sign in; the trade is a slightly larger boot-time surface for the operator to fix and a much smaller failure window at operate time. Caching JWKS costs the process a small piece of memory per provider and buys the id_token verifier a cheap read on every callback; the TTL and the miss-refresh path bound the staleness at `jwksCacheTtlSeconds + one callback`. Not owning the state machine keeps this TAC's surface narrow enough that a new provider vendor is a config-record write, not a code change here.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,51 @@
+{
+  "tacId": "TAC-1103-security-auth-oauth2-session-bridge",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "OAuth2 session-bridge",
+  "purpose": "The single point where a resolved provider identity crosses into the project's session vocabulary. Owns the derivation of the reduced Principal shape, the issue-and-verify contract for the project session cookie, the storage of the provider tokens (access, id, refresh) associated with the session, and the invalidation on sign-out. Every downstream code path that reads `request.auth` reads what this bridge lifted; nothing downstream sees the provider's raw claim shape.",
+  "responsibilities": [
+    "Derive `principalId` as a stable string composed from `{provider.id, sub}` (OIDC) or `{provider.id, userinfo.id}` (oauth2-only); refuse an identity with a missing subject with `OAUTH2_SUBJECT_MISSING` (AC-10106-1, AC-10109-1).",
+    "Populate the reduced Principal with `principalId`, `provider`, optional `email`, empty `roles[]`, empty `organisationIds[]`; expose a project-authored `enrichPrincipal(principal) -> principal` hook if the config declares one; refuse to expose provider tokens on the Principal (AC-10106-1, AC-10106-3).",
+    "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)."
+  ],
+  "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": [
+    {
+      "name": "sessionRecordStore",
+      "kind": "read-write-api",
+      "description": "Project-supplied store exposing `put(handle, record)`, `get(handle) -> record | absent`, `delete(handle)`, and `purgeExpired(now)`. In-memory is the reference default; a persistence-data-sqlite-composed project points this at a table."
+    },
+    {
+      "name": "refreshTokenStore",
+      "kind": "read-write-api",
+      "description": "Shared with the flow controller: exposes `put(handle, refreshToken)`, `clearChain(chainRoot)`."
+    },
+    {
+      "name": "randomBytes",
+      "kind": "read-api",
+      "description": "Cryptographic random-byte source used to mint session handles; a 128-bit-or-more entropy budget is expected."
+    },
+    {
+      "name": "clock",
+      "kind": "read-api",
+      "description": "Injected time source; the same clock the flow controller uses."
+    },
+    {
+      "name": "enrichPrincipal",
+      "kind": "callback",
+      "description": "Optional project-authored hook called on the reduced Principal to add `roles` and `organisationIds` from project-side sources. A no-op default is applied when the config does not declare one."
+    }
+  ],
+  "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." }
+  ],
+  "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",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/tacs/tac-1104-security-auth-oauth2-provider-selector.json

@@ -0,0 +1,29 @@
+{
+  "tacId": "TAC-1104-security-auth-oauth2-provider-selector",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "OAuth2 provider selector",
+  "purpose": "The optional sign-in UX for projects configured with more than one provider. Renders a list of the configured providers by their operator-visible `label` and routes each choice to `/auth/sign-in?provider=<id>`. Optional at wire time: a project may substitute a bespoke selector surface as long as it honours the query-parameter contract on the sign-in route.",
+  "responsibilities": [
+    "Read the provider-config list at request time and render one item per provider record whose `enabled` field is true (or absent, defaulting to enabled) (AC-10109-1).",
+    "Render each item as a link (or a form-post button, per the wiring shim's declared class) whose target is `/auth/sign-in?provider=<id>`; render the item's operator-visible `label` as the visible text (AC-10109-1).",
+    "Short-circuit when N==1: a request to the selector route with a single-provider configuration returns a 302 to `/auth/sign-in?provider=<the-single-id>` instead of rendering a list (REQ-009).",
+    "Refuse to render on an empty provider-config list with a stable-coded error page code `OAUTH2_NO_PROVIDERS_CONFIGURED`; this is a boot-time refusal in the reference wiring, not a run-time page (REQ-009)."
+  ],
+  "internalStructure": "One factory function producing a request-handler closure over an injected `providerConfig` module. The reference wiring is framework-agnostic and returns a plain HTML string; framework shims (an Express handler, a Fastify handler, a Workers fetch wrapper) are one-file adapters colocated with this TAC's module directory. A project that wants a React or Vue rendering substitutes its own selector surface that hits the same query-parameter contract.",
+  "interfaces": [
+    {
+      "name": "providerConfig",
+      "kind": "read-api",
+      "description": "The provider-config module (same source as TAC-1102 reads); exposes `list() -> record[]` and the enabled flag."
+    }
+  ],
+  "dependencies": [
+    { "name": "OAuth2 provider adapter", "kind": "tac", "tacId": "TAC-1102-security-auth-oauth2-provider-adapter", "description": "Reads the same provider-config the adapter validates at boot." }
+  ],
+  "tradeoffs": "A first-party selector surface makes the multi-provider posture visible without a project-side page implementation; the cost is one rendering path the blueprint owns and a small piece of style the project may want to override. Substituting a bespoke selector is a plain wire swap on the sign-in route; the query-parameter contract is the seam, not the rendering. Not owning the sign-in initiation logic (that belongs to the flow controller) keeps this TAC's surface small: it is a route that renders a list and links; the state machine is elsewhere.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,47 @@
+{
+  "usId": "security-auth-oauth2-US-10101",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A complete authorisation-code + PKCE round-trip issues a project session",
+  "asA": "operator signing in through the project's OAuth2 sign-in surface",
+  "iWant": "the browser to be redirected to the provider's authorise endpoint, to be redirected back with a code, and to end up holding a project session cookie",
+  "soThat": "the project treats me as authenticated on subsequent requests without re-presenting credentials to the provider",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10101-1",
+      "description": "The initial GET on the project's sign-in route redirects to the provider's authorise endpoint with `response_type=code`, a non-empty `code_challenge`, `code_challenge_method=S256`, and a `state` value not present in any prior redirect within the test's observation window.",
+      "given": "a project wired to a mock OIDC provider through the provider-config module and a browser that hits GET `/auth/sign-in?provider=<id>`",
+      "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"
+    },
+    {
+      "id": "AC-10101-2",
+      "description": "The callback with a valid code and matching state redeems the code at the provider's token endpoint using the PKCE verifier and receives an access token plus (for OIDC) an id_token.",
+      "given": "the mock provider has minted an authorisation code for the pending flow keyed by the state value from AC-10101-1",
+      "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"
+    },
+    {
+      "id": "AC-10101-3",
+      "description": "The callback completes with a Secure HttpOnly session cookie whose value is a project-issued opaque handle, not a provider token.",
+      "given": "AC-10101-2 has completed",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1101-security-auth-oauth2-flow-controller",
+    "TAC-1102-security-auth-oauth2-provider-adapter",
+    "TAC-1103-security-auth-oauth2-session-bridge"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-oauth2-US-10102",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A callback with a state that does not match a pending flow is refused",
+  "asA": "operator whose browser has been redirected to the callback endpoint with a state value the project's pending-flow store never issued",
+  "iWant": "the callback to be refused before any token exchange",
+  "soThat": "an attacker who guesses or replays a state value cannot force the project to redeem a code they control",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10102-1",
+      "description": "A callback whose state value has no corresponding pending-flow record is refused with a stable-coded response and no token-exchange call.",
+      "given": "the pending-flow store is empty and a request is dispatched to the callback route with `state=<random-value>&code=<random-value>`",
+      "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"
+    },
+    {
+      "id": "AC-10102-2",
+      "description": "A callback that presents a state value from a pending flow already consumed on a prior successful exchange is refused with the same shape.",
+      "given": "a successful flow from US-10101 has consumed state value `s1`",
+      "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"
+    },
+    {
+      "id": "AC-10102-3",
+      "description": "A callback whose state maps to a pending-flow record older than the configured TTL is refused with a stable-coded response.",
+      "given": "a pending-flow record for state `s2` was minted `pendingFlowTtlSeconds + 60` seconds before the callback (simulated by advancing the flow-controller's clock through the test-injected clock port)",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1101-security-auth-oauth2-flow-controller"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-oauth2-US-10103",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A PKCE verifier mismatch at the token exchange terminates the flow",
+  "asA": "operator whose callback presents a valid state and code but whose stored PKCE verifier no longer matches the challenge the provider recorded",
+  "iWant": "the flow to terminate with a distinct stable-coded error before any session issue",
+  "soThat": "an attacker who has captured a code cannot redeem it without the verifier bound to the original request",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10103-1",
+      "description": "The token exchange POST always carries the verifier stored on the pending-flow record; no code path constructs a token exchange without one.",
+      "given": "a successful sign-in flow through the mock provider",
+      "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"
+    },
+    {
+      "id": "AC-10103-2",
+      "description": "The mock provider's token endpoint returning `invalid_grant` on a verifier mismatch causes the flow to terminate without a session issue.",
+      "given": "the mock provider is configured to reject the token exchange with a 400 `invalid_grant` for a specific test callback",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1101-security-auth-oauth2-flow-controller"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-oauth2-US-10104",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "An expired or already-consumed authorisation code is refused",
+  "asA": "operator whose callback presents a code the provider has already invalidated",
+  "iWant": "the flow to terminate cleanly with a stable-coded error",
+  "soThat": "no session is issued against a code that no longer proves possession",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10104-1",
+      "description": "The mock provider returning `invalid_grant` on an expired code causes the flow to terminate without a session issue.",
+      "given": "the mock provider is configured to expire a specific code after one second and the callback is dispatched after two seconds (test-injected clock)",
+      "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"
+    },
+    {
+      "id": "AC-10104-2",
+      "description": "A callback that presents a code from a pending-flow already consumed on a prior successful exchange is refused before the token endpoint is called.",
+      "given": "a successful flow has consumed state `s3` and code `c3`",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1101-security-auth-oauth2-flow-controller"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,55 @@
+{
+  "usId": "security-auth-oauth2-US-10105",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The id_token is verified against the provider's JWKS and refused on any invariant failure",
+  "asA": "operator signing in through an OIDC-declared provider",
+  "iWant": "the flow controller to verify the id_token's signature, issuer, audience, expiry, and nonce before any session issue",
+  "soThat": "a forged or replayed id_token cannot be turned into a project session",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10105-1",
+      "description": "A valid id_token from the mock OIDC provider passes verification: signature valid against JWKS, iss equals the provider's issuer, aud contains the client_id, exp in the future, nonce equals the pending-flow's stored nonce.",
+      "given": "a successful sign-in flow through the mock OIDC provider",
+      "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"
+    },
+    {
+      "id": "AC-10105-2",
+      "description": "An id_token signed by an unknown key is refused with a distinct stable-coded reason and no session issue.",
+      "given": "the mock provider is configured to sign one token exchange with a key not published on JWKS",
+      "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"
+    },
+    {
+      "id": "AC-10105-3",
+      "description": "An id_token whose iss does not equal the provider's declared issuer is refused with a distinct stable-coded reason.",
+      "given": "the mock provider is configured to mint a token whose `iss` claim is a URL other than the declared `issuer`",
+      "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"
+    },
+    {
+      "id": "AC-10105-4",
+      "description": "A missing id_token in a response from a provider declared as OIDC terminates the flow with a distinct stable-coded reason.",
+      "given": "the mock provider is configured to omit the `id_token` field from one token response and remains declared as `providerKind: oidc`",
+      "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"
+    }
+  ],
+  "tacIds": [
+    "TAC-1101-security-auth-oauth2-flow-controller",
+    "TAC-1102-security-auth-oauth2-provider-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-oauth2-US-10106",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A session issued after code exchange grants access to a protected route",
+  "asA": "operator holding a project session cookie issued by the flow controller",
+  "iWant": "a subsequent request to a project route wired behind the session-verify middleware to see the resolved Principal",
+  "soThat": "the project reasons about my identity without a fresh sign-in",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10106-1",
+      "description": "A request to a protected route carrying a valid session cookie sees a resolved Principal on the request.",
+      "given": "the session cookie from US-10101 and a project route wired behind the session-verify middleware from TAC-1103",
+      "when": "the request is dispatched",
+      "then": "the middleware attaches `request.auth` carrying `principalId`, `provider`, `email` (if the provider returned one), `roles` (empty array by default), and `organisationIds` (empty array by default); `principalId` is a stable string derived from `{ provider.id, sub }` (OIDC) or `{ provider.id, userinfo.id }` (oauth2-only)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10106-2",
+      "description": "A request to a protected route without a session cookie, or with an invalidated handle, is refused before the route handler runs.",
+      "given": "a project route wired behind the session-verify middleware",
+      "when": "a request is dispatched with no session cookie, then with a cookie whose value has been tampered by a single byte",
+      "then": "the middleware treats each request as unauthenticated; the route handler is not invoked; the response is a 4xx (or a redirect to the sign-in route, per the wiring shim's declared class); no `request.auth` is attached in either case",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10106-3",
+      "description": "The session-bridge does not expose provider tokens on `request.auth`.",
+      "given": "the session cookie from US-10101 and a protected route",
+      "when": "the request is dispatched and the resolved `request.auth` object is inspected for keys",
+      "then": "the object contains only the fields named in AC-10106-1; no `accessToken`, `idToken`, `refreshToken`, or provider-raw-claims field is exposed",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1103-security-auth-oauth2-session-bridge"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-oauth2-US-10107",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Refresh-token exchange rotates the stored token; a reused token revokes the chain",
+  "asA": "operator whose session has been active long enough for the access token to expire",
+  "iWant": "the flow controller to transparently refresh the stored access token using the stored refresh token",
+  "soThat": "the session continues without a re-sign-in until the project's session lifetime expires",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10107-1",
+      "description": "The refresh-token exchange rotates the stored refresh token: the pre-refresh value is discarded and the provider's new value is stored on the session record.",
+      "given": "a session issued from US-10101 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",
+      "then": "the flow controller issues a POST to the provider's `tokenUrl` with `grant_type=refresh_token` and `refresh_token=rt-old`; the provider returns a new `access_token` and 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-10107-2",
+      "description": "A second refresh attempt presenting the pre-rotation value revokes the session and emits a `refresh_token_reuse` audit event.",
+      "given": "the session and refresh-token-rotation from AC-10107-1 have completed and `rt-old` is captured in the test",
+      "when": "the test injects a refresh call presenting `rt-old` at the flow controller",
+      "then": "the flow controller invalidates the session handle, clears every stored refresh token that shares the same chain root, and emits one structured audit event `oauth2.refresh_token_reuse` carrying the provider id, the session-handle hash, and the detection timestamp; the event carries no token value; the next protected-route request with the original cookie is refused as unauthenticated",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10107-3",
+      "description": "A provider that does not return a refresh token on the token exchange is a supported configuration; no refresh-related record is stored.",
+      "given": "a mock provider configuration that omits `refresh_token` on the token response",
+      "when": "the sign-in completes and the session record is inspected",
+      "then": "the session record's refresh-token slot is empty; the flow controller does not attempt a refresh call on any subsequent request against this session; the session's own project-lifetime expiry (per the session-bridge) is the sole grant duration",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1101-security-auth-oauth2-flow-controller",
+    "TAC-1103-security-auth-oauth2-session-bridge"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}