rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-auth-oauth2/assets/mock-provider/mock-oidc-shape.md

@@ -0,0 +1,55 @@
+# Mock OIDC provider bootstrap: shape (not a library commitment)
+
+Shape a project stands up to satisfy REQ-010's runtime-verify posture. The mock is real OIDC on the wire; the flow controller cannot tell it apart from a live IdP for the purpose of the state machine, PKCE binding, id_token verification, and session-bridge round-trip.
+
+A project may implement the mock in-process (a small Node HTTP server the test harness starts and tears down), against an existing library (Node has `node-oidc-provider` and equivalents; the blueprint does not commit a version), or as a persistent scratch service. The shape below is what the test harness expects, not what a specific library commits to.
+
+## Discovery document (`GET /.well-known/openid-configuration`)
+
+```
+{
+  issuer: 'http://127.0.0.1:<port>',
+  authorization_endpoint: 'http://127.0.0.1:<port>/authorize',
+  token_endpoint: 'http://127.0.0.1:<port>/token',
+  userinfo_endpoint: 'http://127.0.0.1:<port>/userinfo',
+  jwks_uri: 'http://127.0.0.1:<port>/jwks',
+  end_session_endpoint: 'http://127.0.0.1:<port>/end-session',
+  response_types_supported: ['code'],
+  code_challenge_methods_supported: ['S256'],
+  subject_types_supported: ['public'],
+  id_token_signing_alg_values_supported: ['RS256']
+}
+```
+
+## JWKS (`GET /jwks`)
+
+A JSON Web Key Set with one RSA public key. The mock holds the corresponding private key and signs id_tokens with it. The test harness can rotate the JWKS mid-test to exercise AC-10105-2 (signature invalid).
+
+## Authorize (`GET /authorize`)
+
+Accepts `response_type=code`, `client_id`, `redirect_uri`, `state`, `code_challenge`, `code_challenge_method=S256`, `nonce`, `scope=openid profile email`. Stores a pending record keyed by the code it mints. Redirects to `redirect_uri` with `code=<minted>&state=<passed>`.
+
+## Token (`POST /token`)
+
+Accepts `grant_type=authorization_code` with `code`, `code_verifier`, `client_id`, `redirect_uri`. Verifies the `code_verifier` against the pending record's stored challenge. Mints:
+
+- `access_token`: opaque
+- `id_token`: signed JWT with `iss`, `aud=client_id`, `sub`, `nonce=<from-authorize>`, `iat`, `exp`
+- `refresh_token`: opaque, rotates on `grant_type=refresh_token`
+
+Also accepts `grant_type=refresh_token` with `refresh_token` and rotates. Test-controllable knobs (per-code): return `invalid_grant` on demand (for AC-10103-2, AC-10104-1), omit `id_token` (for AC-10105-4), mint id_token with wrong `iss` (for AC-10105-3), mint id_token signed by an unpublished key (for AC-10105-2), return the same `refresh_token` twice to simulate reuse (for AC-10107-2).
+
+## Userinfo (`GET /userinfo`)
+
+Accepts `Authorization: Bearer <access_token>`. Returns a fixed claim record `{ sub, email }`. Used by `providerKind: 'oauth2-only'` records; OIDC-declared providers rely on the id_token for identity.
+
+## End session (`GET /end-session`)
+
+Accepts `post_logout_redirect_uri` and `id_token_hint`. Returns 302 to the `post_logout_redirect_uri` after invalidating any local session state the mock holds.
+
+## Wiring notes for the project
+
+- The mock listens on `127.0.0.1:<random-port>` and the harness passes the port to the provider record's endpoints. `redirect_uri` on the record points at the project's callback route.
+- The mock's private key stays in the harness process; nothing off-machine holds it. The public JWKS is what the flow-controller's verifier reads.
+- The mock does NOT need to persist state; a fresh instance per test suite is fine and preferred.
+- The blueprint does NOT commit a specific library. If a project wants a persistent scratch service (a container the CI stands up once), that is also fine; the shape above is the contract.

package/blueprints/security-auth-oauth2/assets/provider-selector/list-shape.md

@@ -0,0 +1,27 @@
+# Provider selector: list-shape rendering
+
+The reference rendering TAC-1104 emits when the project has N>1 configured providers. Framework-agnostic HTML string; a project on React, Vue, or another rendering pipeline substitutes its own selector surface as long as it honours the query-parameter contract on `/auth/sign-in?provider=<id>`.
+
+## Rendered shape (illustrative, not a template lock)
+
+```
+<main data-selector="oauth2-providers">
+  <h1>Sign in</h1>
+  <ul>
+    <li><a href="/auth/sign-in?provider=google">Sign in with Google</a></li>
+    <li><a href="/auth/sign-in?provider=github">Sign in with GitHub</a></li>
+    <li><a href="/auth/sign-in?provider=corporate-sso">Sign in with Corporate SSO</a></li>
+  </ul>
+</main>
+```
+
+## Query-parameter contract
+
+- `GET /auth/sign-in?provider=<id>` initiates a flow against the named provider.
+- `GET /auth/sign-in` with N==1 short-circuits to the single provider.
+- `GET /auth/sign-in` with N>1 renders this selector (or the project's replacement).
+- Any `provider=<unknown-id>` is refused with `OAUTH2_PROVIDER_UNKNOWN` (AC-10109-2).
+
+## Substituting a bespoke selector
+
+A project that wants a branded rendering replaces the route handler that TAC-1104 provides; the substituted handler reads the same `providerConfig` module and renders however it wants, then links each choice to `/auth/sign-in?provider=<id>`. The state machine downstream is unchanged. There is no other seam to observe: the contract is the query parameter.

package/blueprints/security-auth-oauth2/assets/providers/generic-oidc-discovery.md

@@ -0,0 +1,31 @@
+# Generic OIDC (discovery-driven) provider record
+
+A sample provider record shape for any OIDC provider that publishes an RFC 8414 or OIDC Core discovery document. Populate the endpoints from `<issuer>/.well-known/openid-configuration` at boot; the operator or the project code writes a one-off populator that fetches discovery and returns the record on this shape.
+
+```
+{
+  id: '<OPERATOR_CHOSEN_STABLE_SLUG>',
+  label: '<OPERATOR_CHOSEN_LABEL>',
+  authorizeUrl: '<DISCOVERY.authorization_endpoint>',
+  tokenUrl: '<DISCOVERY.token_endpoint>',
+  userinfoUrl: '<DISCOVERY.userinfo_endpoint>',
+  issuer: '<DISCOVERY.issuer>',
+  jwksUri: '<DISCOVERY.jwks_uri>',
+  endSessionEndpoint: '<DISCOVERY.end_session_endpoint>',
+  clientId: '<PLACEHOLDER_CLIENT_ID>',
+  clientSecret: '<PLACEHOLDER_CLIENT_SECRET>',
+  scopes: ['openid', 'profile', 'email'],
+  redirectUri: '<PLACEHOLDER_PROJECT_CALLBACK_URL>',
+  flow: 'authorisation-code-pkce',
+  providerKind: 'oidc',
+  providerLogout: 'redirect',
+  enabled: true
+}
+```
+
+Notes for the operator:
+- Discovery is a single fetch at boot; the populator caches the result or writes the record verbatim onto the config module.
+- `providerLogout: 'redirect'` is safe when `endSessionEndpoint` is present; if the discovery document omits it, drop `providerLogout` to `'none'` or the adapter refuses boot per AC-10108-3.
+- `id` is a project-local stable slug the operator chooses; it appears in `principalId` derivations and in the `?provider=<id>` query parameter, so keep it short and lowercase.
+
+Do NOT commit the real `clientSecret` in the record; read it from `security-secrets-management` (when composed) or the process environment at boot.

package/blueprints/security-auth-oauth2/assets/providers/github-oauth2-only.md

@@ -0,0 +1,31 @@
+# GitHub (oauth2-only) provider record
+
+A sample provider record shape for GitHub as an OAuth2-only provider. GitHub does not currently issue an id_token on the token exchange; the flow controller resolves identity through the `userinfoUrl` on this record. All fields are placeholders; the operator populates them from a project registered at the provider's console.
+
+```
+{
+  id: 'github',
+  label: 'Sign in with GitHub',
+  authorizeUrl: 'https://github.com/login/oauth/authorize',
+  tokenUrl: 'https://github.com/login/oauth/access_token',
+  userinfoUrl: 'https://api.github.com/user',
+  issuer: null,
+  jwksUri: null,
+  clientId: '<PLACEHOLDER_GITHUB_CLIENT_ID>',
+  clientSecret: '<PLACEHOLDER_GITHUB_CLIENT_SECRET>',
+  scopes: ['read:user', 'user:email'],
+  redirectUri: '<PLACEHOLDER_PROJECT_CALLBACK_URL>',
+  flow: 'authorisation-code-pkce',
+  providerKind: 'oauth2-only',
+  endSessionEndpoint: null,
+  providerLogout: 'none',
+  enabled: true
+}
+```
+
+Notes for the operator:
+- `providerKind: 'oauth2-only'` means the flow controller does not attempt id_token verification for this provider; identity is resolved through the userinfo endpoint. That is the correct posture for GitHub at v1.
+- `issuer` and `jwksUri` are null because GitHub does not publish OIDC discovery. If GitHub adds OIDC support in the future the record migrates to `providerKind: 'oidc'` with the two fields populated; the flow controller's behaviour changes automatically.
+- The scopes list is the minimum for identity plus verified email; a project that reaches for repository APIs adds scopes here.
+
+Do NOT commit the real `clientSecret` in the record; read it from `security-secrets-management` (when composed) or the process environment at boot.

package/blueprints/security-auth-oauth2/assets/providers/google-oidc.md

@@ -0,0 +1,31 @@
+# Google (OIDC) provider record
+
+A sample provider record shape for Google as an OIDC provider. All fields are placeholders; the operator populates them from a project registered at the provider's console.
+
+```
+{
+  id: 'google',
+  label: 'Sign in with Google',
+  authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+  tokenUrl: 'https://oauth2.googleapis.com/token',
+  userinfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+  issuer: 'https://accounts.google.com',
+  jwksUri: 'https://www.googleapis.com/oauth2/v3/certs',
+  clientId: '<PLACEHOLDER_GOOGLE_CLIENT_ID>',
+  clientSecret: '<PLACEHOLDER_GOOGLE_CLIENT_SECRET>',
+  scopes: ['openid', 'profile', 'email'],
+  redirectUri: '<PLACEHOLDER_PROJECT_CALLBACK_URL>',
+  flow: 'authorisation-code-pkce',
+  providerKind: 'oidc',
+  endSessionEndpoint: null,
+  providerLogout: 'none',
+  enabled: true
+}
+```
+
+Notes for the operator:
+- The `clientId` and `clientSecret` come from a project registered at the provider's console; the redirect URI must match one of the registered URIs for the project or the token exchange refuses.
+- `endSessionEndpoint` is null because Google does not currently expose an RP-initiated logout endpoint; leaving `providerLogout: 'none'` clears only the project session on sign-out. A project that wants a full downstream logout drives the operator to the provider's account page.
+- The scopes list is the minimum for identity; a project reaching for additional Google APIs adds scopes here and the token exchange returns access tokens scoped to what was granted.
+
+Do NOT commit the real `clientSecret` in the record; read it from `security-secrets-management` (when composed) or the process environment at boot.

package/blueprints/security-auth-oauth2/assets/session-bridge/opaque-handle-shape.md

@@ -0,0 +1,59 @@
+# Session-bridge: opaque-handle session-record shape
+
+Record-only reference for the shape TAC-1103's session-bridge issues and reads. Not production code; a project authors its own persistence-backed implementation against this shape (or points at an in-memory store for the reference wiring).
+
+## Session record
+
+```
+{
+  handle: '<random-192-bit-opaque-string>',
+  principal: {
+    principalId: '<provider.id>:<sub-or-userinfo-id>',
+    provider: '<provider.id>',
+    email: '<optional-email>',
+    roles: [],
+    organisationIds: []
+  },
+  providerId: '<provider.id>',
+  accessToken: '<opaque-provider-access-token>',
+  idToken: '<optional-signed-jwt-oidc-only>',
+  refreshToken: '<optional-opaque-provider-refresh-token>',
+  chainRoot: '<initial-handle-of-the-refresh-chain>',
+  issuedAt: 1700000000,
+  expiresAt: 1700028800
+}
+```
+
+## Reduced Principal (attached to `request.auth`)
+
+```
+{
+  principalId: 'google:117340098374012345678',
+  provider: 'google',
+  email: 'operator@example.invalid',
+  roles: [],
+  organisationIds: []
+}
+```
+
+Notes:
+- The reduced Principal is the ONLY object downstream code reads from `request.auth`. Access tokens, id tokens, and refresh tokens live on the session record and never appear on `request.auth`.
+- `principalId` includes the provider slug on purpose: a user signed in through two providers is two principals unless the project's `enrichPrincipal` hook says otherwise (identity merging is a project-level policy decision, not a mechanism decision).
+- `chainRoot` is the initial session handle for a refresh chain; refresh-token rotation preserves the same chainRoot so reuse detection can revoke every session that shares the chain in one call.
+- `roles` and `organisationIds` are empty arrays by default; a project's `enrichPrincipal` hook populates them from project-side sources.
+
+## Cookie header shape (issued on callback)
+
+```
+Set-Cookie: <sessionCookieName>=<handle>; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=<sessionExpirySeconds>
+```
+
+The `<sessionCookieName>` is a project config value (default `app_session`); the `<handle>` is the session record's `handle` field; `<sessionExpirySeconds>` is the project config value (default 28800, 8 hours). The cookie value is neither the access token, the id_token, nor a refresh token.
+
+## Cookie header shape (issued on sign-out)
+
+```
+Set-Cookie: <sessionCookieName>=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0
+```
+
+Setting `Max-Age=0` on the same-named cookie with the same `Path` clears it in the browser; the session-record store deletes the record in the same request; a subsequent replay of the pre-signout cookie is unauthenticated.

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

@@ -0,0 +1,44 @@
+{
+  "slug": "security-auth-oauth2",
+  "version": "1.0.0",
+  "category": "security",
+  "contributions": [
+    { "id": "security-auth-oauth2-REQ-001", "kind": "req", "path": "requirements/security-auth-oauth2-req-001.json" },
+    { "id": "security-auth-oauth2-REQ-002", "kind": "req", "path": "requirements/security-auth-oauth2-req-002.json" },
+    { "id": "security-auth-oauth2-REQ-003", "kind": "req", "path": "requirements/security-auth-oauth2-req-003.json" },
+    { "id": "security-auth-oauth2-REQ-004", "kind": "req", "path": "requirements/security-auth-oauth2-req-004.json" },
+    { "id": "security-auth-oauth2-REQ-005", "kind": "req", "path": "requirements/security-auth-oauth2-req-005.json" },
+    { "id": "security-auth-oauth2-REQ-006", "kind": "req", "path": "requirements/security-auth-oauth2-req-006.json" },
+    { "id": "security-auth-oauth2-REQ-007", "kind": "req", "path": "requirements/security-auth-oauth2-req-007.json" },
+    { "id": "security-auth-oauth2-REQ-008", "kind": "req", "path": "requirements/security-auth-oauth2-req-008.json" },
+    { "id": "security-auth-oauth2-REQ-009", "kind": "req", "path": "requirements/security-auth-oauth2-req-009.json" },
+    { "id": "security-auth-oauth2-REQ-010", "kind": "req", "path": "requirements/security-auth-oauth2-req-010.json" },
+    { "id": "security-auth-oauth2-US-10101", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10101.json" },
+    { "id": "security-auth-oauth2-US-10102", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10102.json" },
+    { "id": "security-auth-oauth2-US-10103", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10103.json" },
+    { "id": "security-auth-oauth2-US-10104", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10104.json" },
+    { "id": "security-auth-oauth2-US-10105", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10105.json" },
+    { "id": "security-auth-oauth2-US-10106", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10106.json" },
+    { "id": "security-auth-oauth2-US-10107", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10107.json" },
+    { "id": "security-auth-oauth2-US-10108", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10108.json" },
+    { "id": "security-auth-oauth2-US-10109", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10109.json" },
+    { "id": "security-auth-oauth2-US-10110", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10110.json" },
+    { "id": "security-auth-oauth2-US-10111", "kind": "us", "path": "user-stories/security-auth-oauth2-us-10111.json" },
+    { "id": "TAC-1101-security-auth-oauth2-flow-controller", "kind": "tac", "path": "tacs/tac-1101-security-auth-oauth2-flow-controller.json" },
+    { "id": "TAC-1102-security-auth-oauth2-provider-adapter", "kind": "tac", "path": "tacs/tac-1102-security-auth-oauth2-provider-adapter.json" },
+    { "id": "TAC-1103-security-auth-oauth2-session-bridge", "kind": "tac", "path": "tacs/tac-1103-security-auth-oauth2-session-bridge.json" },
+    { "id": "TAC-1104-security-auth-oauth2-provider-selector", "kind": "tac", "path": "tacs/tac-1104-security-auth-oauth2-provider-selector.json" },
+    {
+      "id": "ADR-1101-security-auth-oauth2-auth-model",
+      "kind": "adr",
+      "path": "adrs/adr-1101-security-auth-oauth2-auth-model.json",
+      "scope": "global",
+      "topic": "authModel"
+    },
+    { "id": "ADR-1102-security-auth-oauth2-provider-abstraction-contract", "kind": "adr", "path": "adrs/adr-1102-security-auth-oauth2-provider-abstraction-contract.json" },
+    { "id": "ADR-1103-security-auth-oauth2-pkce-discipline", "kind": "adr", "path": "adrs/adr-1103-security-auth-oauth2-pkce-discipline.json" },
+    { "id": "ADR-1104-security-auth-oauth2-session-bridge-shape", "kind": "adr", "path": "adrs/adr-1104-security-auth-oauth2-session-bridge-shape.json" },
+    { "id": "ADR-1105-security-auth-oauth2-refresh-token-posture", "kind": "adr", "path": "adrs/adr-1105-security-auth-oauth2-refresh-token-posture.json" },
+    { "id": "ADR-1106-security-auth-oauth2-multi-provider-routing", "kind": "adr", "path": "adrs/adr-1106-security-auth-oauth2-multi-provider-routing.json" }
+  ]
+}

package/blueprints/security-auth-oauth2/contributions/adrs/adr-1101-security-auth-oauth2-auth-model.json

@@ -0,0 +1,35 @@
+{
+  "adrId": "ADR-1101-security-auth-oauth2-auth-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "OAuth2 authorisation-code with PKCE against a pluggable external IdP is the project's authentication model",
+  "context": "A project has one authentication model; the client tier, the server tier, and every operator surface must reason against it. The security-auth-oauth2 blueprint contributes a vendor-neutral shape of that model: identity, sign-in UX, credential storage, MFA, and account recovery live at an external IdP the project selects (Google, GitHub, Microsoft, Okta, Auth0, a corporate ADFS-fronted OIDC, a self-hosted node-oidc-provider); the project owns the flow controller, the provider-adapter seam, the session-bridge, and the sign-in UX composition. A client-tier blueprint (application-spa), a server-tier blueprint (application-api-rest), and every other auth-family blueprint (security-auth-magic-link, security-auth-clerk, security-auth-keycloak when it ships) contribute their own decisions on this topic; blueprint composition surfaces the pairing at add time for the operator to reconcile into one project-level model. That surfacing is intended.",
+  "decision": "The project's authentication model is delegated identity via OAuth2 authorisation-code flow (RFC 6749 section 4.1) hardened with PKCE (RFC 7636, S256). Identity is proven by a completed round-trip against a project-configured IdP whose declaration satisfies the provider-abstraction contract (REQ-002). The wire credential the browser holds is a project-issued opaque-handle session cookie (`Secure`, `HttpOnly`, `SameSite=Lax`) whose value is neither the provider's access token, the id_token, nor a refresh token; provider tokens are stored server-side on the session record and never round-trip through the browser. For OIDC-declared providers the id_token is verified against the provider's JWKS on every callback (REQ-005). Refresh tokens rotate on every exchange with reuse detection (REQ-007). Sign-out invalidates the project session server-side; provider-side sign-out is an operator-declared option (REQ-008). Multi-provider composition is supported and expressed at the query-parameter layer (REQ-009). Runtime-verify binds the state machine and the identity-lift against a project-authored mock OIDC provider; live-vendor smokes are accountBound (REQ-010).",
+  "consequences": "The project owns the flow controller, the provider adapter, the session-bridge, and (optionally) the provider selector; the external IdP owns everything else on the identity surface. IdP swap is a provider-record write plus a JWKS-and-endpoint refresh; the flow controller and the session-bridge do not change. Composing with another auth-family blueprint (magic-link, Clerk, Keycloak) conflicts on this topic by design; the expected resolution is one project-level ADR that fixes the identity surface and the credential shape for the whole project. The mock-OIDC-provider runtime-verify posture keeps CI honest without demanding live-vendor credentials in every environment; a project that has live-vendor credentials wires them on top and the accountBound smokes light up. Every path that produces or consumes a session cookie flows through one narrow set of modules the ship gate compels.",
+  "alternativesConsidered": [
+    {
+      "name": "Passwordless magic-link with server-issued opaque cookie sessions",
+      "summary": "The security-auth-magic-link blueprint's model: mint a single-use token on POST /login, deliver by email, verify on GET /login/verify, issue an opaque-handle session cookie.",
+      "reasonNotChosen": "Valid for projects that want no third-party identity dependency and are willing to own the principal registry, the email adapter, the rate-limiter, and the anti-enumeration posture. The trade against OAuth2 is running that whole surface in-house; a project that has a compelling reason to keep identity local (or that has no willing external IdP) takes that trade. This blueprint occupies the other end: identity is delegated, the local surface is small."
+    },
+    {
+      "name": "Hosted identity vendor with vendor-committed shape (Clerk)",
+      "summary": "The security-auth-clerk blueprint's model: Clerk hosts the sign-in surface, the credential storage, MFA, account recovery; the project runs a middleware boundary against Clerk's session-verification API.",
+      "reasonNotChosen": "Valid for projects that want the hosted-identity fast lane and are willing to commit to one vendor. The trade against OAuth2-generic is that Clerk (or the equivalent) does more of the work at the cost of a vendor commitment; OAuth2-generic keeps the mechanism vendor-neutral and asks the project to run the flow controller and the session-bridge. Projects that want the hosted lane take the sibling blueprint; projects that need vendor neutrality take this one."
+    },
+    {
+      "name": "Self-hosted OIDC via Keycloak with vendor-committed shape",
+      "summary": "The forthcoming security-auth-keycloak blueprint's model: run a Keycloak instance, federate through the OIDC authorization-code flow, wire the middleware boundary against Keycloak's realm.",
+      "reasonNotChosen": "Valid for projects with existing ops capacity and a hard multi-tenant IdP requirement. The trade is running the Keycloak container plus a realm configuration; small rcf-lite projects rarely need it day one. A Keycloak project on this blueprint's contract is one provider record; a Keycloak project on the vendor-committed blueprint is a richer opinion on the realm surface. The choice belongs to the project's ops posture."
+    },
+    {
+      "name": "Direct social sign-in with one hard-coded provider (Google-only, GitHub-only)",
+      "summary": "Skip the provider abstraction and wire the flow directly against one vendor's URL surface.",
+      "reasonNotChosen": "Cheap on day one and expensive on day thirty when the project needs a second provider or an operator wants to swap. Every code path branches on the vendor's claim shape and the vendor's cookie names; the abstraction cost is paid over months of rework. This blueprint pays the abstraction cost up front."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/adrs/adr-1102-security-auth-oauth2-provider-abstraction-contract.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1102-security-auth-oauth2-provider-abstraction-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The provider-abstraction contract is a fixed record shape, not a per-vendor code path",
+  "context": "A blueprint that spans N provider vendors either scales through an abstraction seam or drifts into per-vendor branches inside the state machine. The proposal that minted this blueprint (round-2 proposal, review outcomes) calls this out explicitly: the authoring effort is in getting the seam right; get it wrong and the blueprint becomes either over-generic (an empty interface no one can implement without inventing every field) or under-generic (a code path per vendor with `if provider.id === 'google'` branches inside the flow controller). Neither serves a project that wants to swap or compose providers.",
+  "decision": "The provider abstraction is a plain data record, not an object with methods. Every provider a project drops in declares `{ id, label, authorizeUrl, tokenUrl, userinfoUrl, issuer?, jwksUri?, clientId, clientSecret, scopes[], redirectUri, flow: 'authorisation-code-pkce', providerKind: 'oidc' | 'oauth2-only', endSessionEndpoint?, providerLogout?: 'redirect' | 'none' | absent, enabled?: boolean }`. The provider adapter (TAC-1102) validates every record at boot; the flow controller (TAC-1101) reads fields from the record on every step; nothing in the state machine branches on the provider's vendor name. Vendor-specific quirks that do not fit the record shape (Google's `hd` claim, GitHub's per-org enforcement, Microsoft's tenant scoping) are the responsibility of vendor-specific companion blueprints if demand arrives; the v1 contract is deliberately narrow.",
+  "consequences": "Adding a provider is a config-record write, not a code edit. A project may compose N providers on one deployment; the code path is identical for each. The trade is that vendor-specific claims (Google's `hd`, Microsoft's tenant `tid`) are inaccessible through the reduced Principal unless the project authors an `enrichPrincipal` hook; that is the intended posture. A vendor whose surface diverges from the record shape (an obscure IdP that omits the standard scopes-and-endpoints vocabulary) is a project-level ADR conversation, not a mechanism change here.",
+  "alternativesConsidered": [
+    {
+      "name": "Object interface with methods (`buildAuthorizeUrl`, `exchangeCode`, `verifyIdToken`)",
+      "summary": "Every provider implements a class that overrides the interface.",
+      "reasonNotChosen": "Pushes the state machine into every provider; the flow controller becomes a passthrough. That inverts the intended locus of control: the state machine is the point of consistency, and putting per-provider code in the flow shape means every provider re-implements the invariants. The record shape puts consistency in one place."
+    },
+    {
+      "name": "Discovery-only (read RFC 8414 metadata at boot)",
+      "summary": "Read `/.well-known/oauth-authorization-server` per provider and let the discovery document declare the endpoints.",
+      "reasonNotChosen": "Fine for providers that publish discovery; useless for the ones that do not, and there are enough of both to matter. The record shape accepts a discovery-driven boot loader as an implementation choice on the project side: a project may fetch discovery at boot and populate the record; the mechanism above the record does not change."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/adrs/adr-1103-security-auth-oauth2-pkce-discipline.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1103-security-auth-oauth2-pkce-discipline",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "PKCE is mandatory on every authorisation-code exchange and the S256 method is the sole accepted challenge",
+  "context": "PKCE (RFC 7636) protects the authorisation-code flow against code interception. The mechanism defines two challenge methods: `plain` (the verifier is used as the challenge unchanged) and `S256` (the challenge is BASE64URL(SHA256(verifier))). `plain` erodes the protection to nil in the presence of any component that can observe the challenge on the wire; the specification recommends S256 for that reason. A blueprint that accepts `plain` when a provider offers it is a foot-gun in every environment where the front channel is not fully trusted.",
+  "decision": "Every authorisation redirect this blueprint mints declares `code_challenge_method=S256`. The flow controller refuses to construct a redirect without a challenge and refuses to accept a callback whose stored pending-flow does not carry a matching S256-derived challenge for the verifier the token exchange presents. A provider whose configuration would require `plain` (or that does not enforce PKCE binding at all) is a project-level ADR conversation, not a config-flag flip: the operator supersedes this ADR with a project-level ADR that accepts the erosion for their specific environment, or the operator picks a different provider.",
+  "consequences": "The state machine is single-branched on PKCE: mint verifier, derive S256 challenge, store verifier, present verifier on token exchange. The mechanism is stable across every provider that speaks the RFC correctly. A provider that refuses PKCE (or accepts `plain` and does not enforce the binding on the server side) is caught either at boot (when the record is misconfigured) or at operate time (when the token exchange fails); either way the failure is loud, not silent.",
+  "alternativesConsidered": [
+    {
+      "name": "Accept `plain` when a provider declares only `plain` support",
+      "summary": "Match the provider's declared method to keep more providers usable.",
+      "reasonNotChosen": "Trades a documented security property for provider breadth. A provider that only supports `plain` is a provider whose security posture is worse than the blueprint's claimed floor; accepting them silently means the floor is a lie."
+    },
+    {
+      "name": "Make the challenge method a project-config flag",
+      "summary": "Let the operator declare the method per provider.",
+      "reasonNotChosen": "Turns a load-bearing security invariant into a config knob the operator can flip without a paper trail. A project-level ADR is the right shape for making the trade explicit."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/adrs/adr-1104-security-auth-oauth2-session-bridge-shape.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1104-security-auth-oauth2-session-bridge-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Provider tokens live server-side; the browser holds an opaque handle only",
+  "context": "The session-bridge chooses between two shapes that both work as sign-in ceremonies. The first: the browser holds an opaque server-issued handle, and provider tokens (access, id, refresh) live on a server-side record keyed by the handle. The second: the browser holds a JWT or a similar structured credential the provider issued, and the server re-verifies on every request. The rcf-lite tier this blueprint targets is small greenfield projects with one deployable and a session-record store that is either in-memory (for a scratch project) or a small table on a persistence blueprint (SQLite or D1). At that tier the opaque-handle shape reads simpler, hides the provider token graph from the browser, and makes sign-out a single delete against the server-side store.",
+  "decision": "The session-bridge issues an opaque-handle cookie; provider tokens (access, id, refresh) are stored on the server-side session record keyed by the handle. The cookie value is neither the access token, the id_token, nor a refresh token; nothing exposed on `request.auth` is a provider token; nothing rendered into the client tier is a provider token. The reduced Principal (`principalId`, `provider`, `email?`, `roles[]`, `organisationIds[]`) is the only claim shape downstream code sees. `principalId` is derived from `{provider.id, subject}` so a user signed in through two providers is two principals unless the project's `enrichPrincipal` hook declares otherwise.",
+  "consequences": "Sign-out is one delete; refresh-token reuse detection is one lookup; a compromised session record has server-side revocation as an option. The trade is a server-side store per session; that store is a project responsibility (in-memory in the reference wiring; a table on a composed persistence blueprint otherwise). A project whose deployable count grows beyond one and whose sessions must be shared across processes is naturally led to a persistence-backed session store; the composition path is clean because the session-bridge injects the store.",
+  "alternativesConsidered": [
+    {
+      "name": "JWT-in-cookie (browser holds a project-signed JWT)",
+      "summary": "The cookie value is a signed JWT the browser round-trips on every request; the session-bridge verifies signature and reads the claims.",
+      "reasonNotChosen": "Common at scale where a stateless server is a hard constraint; carries no server-side revocation without a companion revocation-list mechanism, and puts identity claims on a token the browser holds (a footprint an XSS can lift). The rcf-lite tier does not need the statelessness enough to pay those costs."
+    },
+    {
+      "name": "Provider access token as the cookie",
+      "summary": "The browser holds the provider's access token directly.",
+      "reasonNotChosen": "Leaks the vendor's token surface into every browser side-channel, ties revocation to the vendor's clock, and rules out multi-provider composition (a single cookie shape cannot represent N provider tokens at once)."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/adrs/adr-1105-security-auth-oauth2-refresh-token-posture.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1105-security-auth-oauth2-refresh-token-posture",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Refresh tokens rotate on every exchange and revoke the chain on reuse detection",
+  "context": "Refresh tokens live longer than access tokens; the operational purpose is to keep a session alive without a re-sign-in when the short-lived access token expires. The failure mode this ADR addresses is refresh-token theft: an attacker who lifts a refresh token from anywhere it lives can hold identity indefinitely if the token is not rotated. The industry pattern (RFC 6749 section 10.4; the OAuth 2.0 Security BCP) is rotation-with-reuse-detection: every exchange returns a new refresh token, the previous value is discarded, and the same value seen twice revokes the whole chain.",
+  "decision": "The flow controller rotates refresh tokens on every exchange: the current stored value is replaced by the provider's newly-returned value; the previous value is discarded and not retained anywhere except transiently in the exchange call itself. Presenting the same refresh-token value a second time is a `refresh_token_reuse` signal: the flow controller invalidates the session handle, clears every stored refresh token that shares the chain root, and emits one structured audit event 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 is a supported posture: the session lives out its own project-lifetime and no refresh path is exercised.",
+  "consequences": "The trade against a bare posture is a small piece of chain-tracking state (which handles share a chain root) and the audit surface for reuse detection; the win is that a lifted refresh token is a bounded-window attack rather than an unbounded one. A provider that does not respect rotation (returns the same refresh-token value on consecutive exchanges) presents as reuse against this blueprint and revokes the chain; that is the correct posture and any provider that violates rotation is a project-level ADR conversation.",
+  "alternativesConsidered": [
+    {
+      "name": "No rotation (keep the same refresh token across exchanges)",
+      "summary": "The initial refresh token is used until the provider revokes it.",
+      "reasonNotChosen": "Loses the whole point of the reuse-detection defence. Simpler; strictly worse."
+    },
+    {
+      "name": "Rotate but do not revoke on reuse",
+      "summary": "Rotate on every exchange, but treat a reuse presentation as a benign error.",
+      "reasonNotChosen": "Half the defence: the rotation prevents indefinite re-use of a single lifted token, but the reuse signal is ignored. The BCP recommendation is to treat reuse as evidence of theft and revoke."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-oauth2/contributions/adrs/adr-1106-security-auth-oauth2-multi-provider-routing.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1106-security-auth-oauth2-multi-provider-routing",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Multi-provider routing is expressed at the query-parameter layer, not through a hard-coded default",
+  "context": "A project configured with more than one provider needs a way to route a sign-in request to a specific provider. Three shapes exist: a hard-coded default provider (the first in the list), an explicit query parameter naming the provider, or a distinct sign-in URL per provider. The first is dangerous (an operator who reorders the list changes the sign-in behaviour without a code change); the third is verbose (N routes to declare and wire). The second is observable at the URL layer and refuses ambiguity.",
+  "decision": "On N>1 provider configurations, the flow controller requires an explicit `provider` query parameter on the sign-in route (`GET /auth/sign-in?provider=<id>`); a missing or unknown id is refused with a stable-coded response. On N==1 configurations, the sign-in route without a `provider` parameter short-circuits to the single configured provider; a `provider` parameter naming an id other than the single configured one is refused. The provider-selector TAC (TAC-1104) renders a list-of-providers page as an optional UX; a project may substitute a bespoke selector as long as it honours the query-parameter contract.",
+  "consequences": "The routing is legible from the URL alone: an operator inspecting a sign-in link knows which provider is being invoked. Adding a provider is a config-record write plus a link on whatever selector surface the project uses; the state machine does not change. The trade against a hard-coded default is a small piece of URL noise on multi-provider deployments; that noise is exactly the observability the URL was for.",
+  "alternativesConsidered": [
+    {
+      "name": "Hard-coded default (first provider in the list)",
+      "summary": "A sign-in request without a `provider` parameter defaults to the first configured provider.",
+      "reasonNotChosen": "Changes behaviour on a list reorder without a code change; a project that removes a provider silently changes the sign-in flow. The routing loses observability."
+    },
+    {
+      "name": "Distinct sign-in URL per provider (`/auth/sign-in/google`, `/auth/sign-in/github`)",
+      "summary": "One route per configured provider.",
+      "reasonNotChosen": "Verbose (N routes), and the URL vocabulary leaks the provider id into every place the sign-in URL is referenced. The query-parameter shape keeps the base URL stable across configurations."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Two failure modes justify fixing the flow. First, the implicit flow returns tokens on the front channel and cannot be hardened against interception or replay in a single-page application; browsers and IdPs have deprecated it. Second, a provider-shape choice that lets one project run authorisation-code and another run implicit forks the composition surface and forces every downstream TAC (session bridge, refresh discipline, sign-out) to reason about both. Fixing the flow at the blueprint layer keeps the flow-controller state machine linear and the provider adapter surface small.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:01-flow-shape"
+  ],
+  "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-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-002",
+  "prdId": "PRD-001",
+  "title": "One provider-abstraction contract fixes what a plug-in provider must declare",
+  "description": "Every provider a project drops in is a plain data record on a fixed shape: `id` (project-local stable slug), `label` (operator-visible name), `authorizeUrl`, `tokenUrl`, `userinfoUrl`, `issuer` (OIDC), `jwksUri` (OIDC), `clientId`, `clientSecret` (server-only; the record on the client tier carries a redacted placeholder), `scopes[]`, `redirectUri`, `flow` (fixed to `authorisation-code-pkce` at v1), `providerKind` (`oidc` or `oauth2-only`). A provider whose declaration is missing a required field, or declares `providerKind: oidc` but omits `issuer` or `jwksUri`, is refused at boot with a stable-coded error naming the provider `id` and the missing field. No project code path reasons against the provider's vendor name; every reasoning path reasons against the record's fields.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A provider abstraction that scales beyond two vendors names the shape the code depends on, not the vendors that satisfy it. If the code path branches on `provider.id === 'google'` the mechanism has already lost the promise this blueprint makes. A field-record contract lets the flow controller and the session bridge stay one implementation across every provider a project ever wires; adding a provider is a config-record write, not a code edit. Field-level fail-fast on boot is the mechanism that catches misconfigured records before they surface as a signed-in user whose profile turns out to be blank.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:02-provider-contract"
+  ],
+  "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-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-003",
+  "prdId": "PRD-001",
+  "title": "CSRF on the authorisation redirect is defended with an unguessable state parameter",
+  "description": "Every authorisation redirect the flow controller mints carries a `state` parameter. The value is a cryptographically random 128-bit-or-more opaque string generated per request; the controller binds `state` to the pending flow record (provider id, code_verifier, nonce, requested redirect target, minted-at timestamp) and stores that record in an integrity-checked one-time server-side pending-flow store keyed by `state`. On callback, the controller looks up the pending flow by the returned `state`, refuses the callback if the lookup misses or the record has already been consumed, and deletes the record after a single successful consumption. A stored pending flow older than a configured `pendingFlowTtlSeconds` (default 600) is treated as absent. The `state` value is never logged, never exposed in a client-tier document, and never rendered into an error page.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "Without a bound `state` the authorisation callback endpoint is an unauthenticated request the browser can be tricked into invoking with an attacker-controlled `code`, and the session-issue seam is a CSRF-shaped identity forgery. Binding the flow record on the server side (rather than storing state in a cookie the browser echoes back) also carries the PKCE verifier off the client tier for the duration of the flow, which removes a category of storage-side leaks the client tier can suffer. The one-time consumption plus TTL defends against replay of a captured state value.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:03-csrf"
+  ],
+  "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-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-004",
+  "prdId": "PRD-001",
+  "title": "PKCE with the S256 challenge method is mandatory on every authorisation-code exchange",
+  "description": "Every authorisation redirect includes `code_challenge` derived from a cryptographically random 43-to-128-character `code_verifier` by BASE64URL(SHA256(verifier)), and `code_challenge_method=S256`. The `plain` challenge method is not accepted. The `code_verifier` is stored server-side on the pending-flow record keyed by `state`; it is never sent on the front channel and is never rendered into the client tier. The token exchange POST carries the `code_verifier` verbatim; the flow controller refuses to construct a token-exchange request that does not carry a matching verifier for the pending flow, and refuses to consume a token-exchange response for a `state` whose stored verifier does not match. A provider that refuses the S256 challenge method or that does not appear to enforce PKCE binding at all is a project-level ADR conversation, not a config-flag flip.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "The authorisation-code flow without PKCE lets an attacker who intercepts an authorisation code (through a compromised redirect handler, a shared browser environment, or an intermediary proxy) redeem it at the token endpoint without further evidence of possession. PKCE binds the code to a verifier the requester holds; without the verifier the code is unspendable. Mandating S256 excludes the `plain` method that a mis-implemented provider might otherwise accept and that erodes the guarantee to nil.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:04-pkce"
+  ],
+  "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-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-oauth2-REQ-005",
+  "prdId": "PRD-001",
+  "title": "OIDC identity is verified through the id_token when the provider declares OIDC",
+  "description": "When a provider's declaration carries `providerKind: oidc`, the token-exchange response is expected to carry an `id_token` (a signed JWT). The flow controller verifies the id_token against the provider's `jwksUri` before any downstream consumption: signature validation with a key resolved from JWKS by the token's `kid`, `iss` equality against the provider's `issuer`, `aud` containment of the provider's `clientId`, `exp` in the future by at least one second, `iat` in the past by no more than `idTokenMaxAgeSeconds` (default 3600), and `nonce` equality against the value the flow controller minted onto the authorisation redirect and stored on the pending flow. A missing id_token when the provider declared OIDC is a refuse-fast: the flow terminates with `OAUTH2_MISSING_ID_TOKEN` and no session is issued. A provider declared as `providerKind: oauth2-only` bypasses id_token verification and relies on the userinfo endpoint's response for identity, per REQ-006.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "A provider that speaks OIDC lets the flow controller verify identity claims signed by the provider without a network hop after the token exchange; the id_token is the cheapest, strongest identity signal available. A refuse-fast when a declared-OIDC provider omits the id_token catches misconfiguration (a client that requested only OAuth2 scopes, a provider whose `scope=openid` was omitted) that would otherwise silently fall back to userinfo and lose the JWT audit trail. A separate posture for `oauth2-only` providers keeps the mechanism usable against providers (GitHub is the canonical example) whose surface does not include id_token.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:05-id-token"
+  ],
+  "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-006.json

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A single reduction point stops the provider's claim vocabulary from leaking through the codebase. If handlers reach for `req.auth.claims.email_verified` today the codebase depends on the provider's schema forever, and the provider-swap promise this blueprint makes collapses. Deriving `principalId` from `{provider.id, subject}` also makes multi-provider composition safe: a user who signs in through Google and later through the same email at GitHub is TWO distinct principals until the project authors an explicit identity-merge policy; the blueprint refuses to accidentally merge them.",
+  "tags": [
+    "blueprint:security-auth-oauth2",
+    "category:06-session-bridge"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}