rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-oauth2-US-10108",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-out invalidates the project session; the provider redirect is a configured option",
+  "asA": "operator who has signed in through the project's OAuth2 sign-in surface",
+  "iWant": "a sign-out request to clear my project session on the server and in the browser",
+  "soThat": "the next request from this browser is unauthenticated regardless of what the provider still holds",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10108-1",
+      "description": "A POST to the sign-out route invalidates the session handle server-side and clears the session cookie in the browser.",
+      "given": "a session issued from US-10101 and a project route at `POST /auth/sign-out` wired to the flow controller",
+      "when": "the browser dispatches the sign-out request",
+      "then": "the response clears the session cookie (`Set-Cookie` with the cookie name, empty value, `Max-Age=0`, `HttpOnly`, `Secure`, `SameSite=Lax`); the session-record store no longer holds a record for the pre-signout session handle; the next protected-route request from this browser is refused as unauthenticated even if the browser replays the pre-signout cookie value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10108-2",
+      "description": "When a provider record sets `providerLogout: 'redirect'` and declares `endSessionEndpoint`, sign-out returns a 302 to that endpoint after clearing the project session.",
+      "given": "a mock provider whose declaration sets `providerLogout: 'redirect'` and carries an `endSessionEndpoint`, and a session issued against that provider",
+      "when": "the sign-out route is invoked",
+      "then": "the response status is 302; the `Location` header equals the declared `endSessionEndpoint` (with the configured `post_logout_redirect_uri` and, for OIDC providers, the `id_token_hint` query parameter as the raw id_token stored on the session record); the session cookie is cleared on the same response",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10108-3",
+      "description": "A provider record that sets `providerLogout: 'redirect'` without declaring `endSessionEndpoint` refuses boot with a stable-coded error.",
+      "given": "a project config that sets `providerLogout: 'redirect'` on a provider record whose `endSessionEndpoint` field is absent",
+      "when": "the flow controller's provider validator runs at boot",
+      "then": "the boot terminates with error code `OAUTH2_LOGOUT_NOT_DECLARED` naming the provider id; no server process is left listening; the audit log records one `oauth2.provider_config_refused` event carrying the provider id and reason class `logout-endpoint-missing`",
+      "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"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "security-auth-oauth2-US-10109",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A second provider drops in through config only; the same flow serves both",
+  "asA": "operator wiring the project against a second identity provider",
+  "iWant": "adding the second provider to be a config-record write with no change to the flow-controller or session-bridge code",
+  "soThat": "the provider abstraction promise the blueprint makes is real, not aspirational",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10109-1",
+      "description": "A round-trip against a second mock OIDC provider added purely by extending the provider-config list issues a project session whose Principal carries the second provider's id.",
+      "given": "the mock provider from US-10101 plus a second mock OIDC provider added to the provider-config module with a distinct `id`, `issuer`, and JWKS; no code change to the flow controller or session-bridge modules",
+      "when": "a browser dispatches `GET /auth/sign-in?provider=<second-id>` and completes the round-trip",
+      "then": "the resulting session's `request.auth.provider` equals the second provider's `id`; `principalId` is derived under the second provider's slug and does not collide with any principalId issued against the first provider even when the underlying `sub` claim value is identical; the flow controller's request log records the redirect and the token exchange against the second provider's URLs, not the first",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10109-2",
+      "description": "A sign-in request whose `provider` query parameter names an id not in the provider-config list is refused before any redirect.",
+      "given": "the two-provider configuration from AC-10109-1",
+      "when": "a browser dispatches `GET /auth/sign-in?provider=nonexistent-id`",
+      "then": "the response is a 4xx with body error code `OAUTH2_PROVIDER_UNKNOWN`; no `Location` header pointing at an authorise endpoint is emitted; no pending-flow record is written",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1102-security-auth-oauth2-provider-adapter",
+    "TAC-1104-security-auth-oauth2-provider-selector"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "security-auth-oauth2-US-10110",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Live-provider runtime-verify ACs are accountBound and skip cleanly when the provider is unreachable",
+  "asA": "operator running the project's CI pipeline without live-provider credentials configured",
+  "iWant": "the runtime-verify layer to skip the live-provider smoke ACs with a stable-coded reason",
+  "soThat": "CI does not fail and the honest coverage state is on the record",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10110-1",
+      "description": "Every TC bound to a runtime-verify AC that targets a live public provider carries an `accountBound` flag; the runtime-verify runner honours the flag by skipping and emitting a stable-coded reason.",
+      "given": "a project scratch tree with this blueprint applied, one project-authored TC bound to AC-10110-2 flagged `accountBound`, and no live-provider credentials in the runtime environment",
+      "when": "`rcf audit coverage --strict` reports the coverage state and the runtime-verify runner is invoked",
+      "then": "the coverage report lists the AC as covered by a TC whose latest run outcome is `skipped` with reason `OAUTH2_LIVE_PROVIDER_UNREACHABLE`; the pipeline exit code is 0; the audit log records one `oauth2.accountbound_skip` event carrying the AC id and the missing-credential class",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-10110-2",
+      "description": "A live public-provider smoke against a real IdP (Google, GitHub, Microsoft, or a corporate SSO the project has credentials for) completes a full authorisation-code + PKCE round-trip and issues a project session whose Principal carries the live provider's id.",
+      "given": "live-provider credentials configured in the runtime environment and the project's redirect URI registered at the provider's console (operator-authored, out of the blueprint's mechanism reach)",
+      "when": "the operator drives a real browser through the sign-in surface at the live provider",
+      "then": "the flow completes; a project session cookie is set with the same shape as AC-10101-3; `request.auth.provider` equals the live provider's declared id; the project-authored TC for this AC records a `pass` outcome",
+      "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-10111.json

@@ -0,0 +1,28 @@
+{
+  "usId": "security-auth-oauth2-US-10111",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-oauth2-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Provider records are validated at boot; the state machine reasons against fields, not vendor names",
+  "asA": "operator configuring one or more provider records for the project",
+  "iWant": "the provider adapter to validate every record's shape at boot and expose a fields-only surface to the flow controller",
+  "soThat": "adding, removing, or swapping a provider is a config-record write with no code path change and no vendor-name branch",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-10111-1",
+      "description": "The provider adapter's boot-time validator enforces the provider-abstraction contract on every configured record and the flow controller reads only record fields on every step of the state machine. The two refusal ACs anchored under the sign-out and multi-provider stories (AC-10108-3, AC-10109-2) exercise this contract's refuse-fast behaviour at the concrete failure modes; this story's AC binds the shape-level property that every record must satisfy before either of those refuse-fast paths can even be reached.",
+      "given": "a project provider-config module carrying at least one record and the provider adapter loaded at boot per TAC-1102",
+      "when": "the flow controller initiates any step of the authorisation-code + PKCE flow against the configured provider (mint redirect, exchange code, verify id_token, invoke userinfo, mint sign-out redirect)",
+      "then": "every URL, credential, scope list, redirect target, and provider-kind determination the flow controller reads comes from the record's declared fields (`authorizeUrl`, `tokenUrl`, `userinfoUrl`, `issuer`, `jwksUri`, `clientId`, `clientSecret`, `scopes`, `redirectUri`, `providerKind`, `endSessionEndpoint`); a source-tree scan of the flow-controller module records zero string-literal branches keyed on a provider `id` value (no `provider.id === 'google'`, no vendor-name switch); a boot with a record missing any REQ-002-mandated field refuses with the stable-coded error class named on TAC-1102's responsibilities and no server process is left listening",
+      "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/docs/topics.md

@@ -0,0 +1,58 @@
+# security-auth-oauth2 blueprint coordination vocabulary
+
+This file is the security-auth-oauth2 half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | security-auth-oauth2 contribution | Composition intent |
+|---|---|---|
+| `authModel` | ADR-1101-security-auth-oauth2-auth-model | Deliberate conflict on the same string minted by `security-auth-magic-link` (ADR-501), `security-auth-clerk` (ADR-1001), the client half of `application-spa` (ADR-205), and the server half of `application-api-rest` (ADR-304). This blueprint's shape is delegated identity via OAuth2 authorisation-code + PKCE against a project-configured IdP; a composing blueprint that holds a different opinion on the authentication model contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the project's authentication model for both the client tier and the server tier, with a resolution recorded on `manifest.resolutions[]` or via `--resolve authModel=project:<ADR-id>` on the add |
+
+The security-auth-oauth2 blueprint claims one global topic. Every other contribution is scope-local (ADR-1102 through ADR-1106 name the provider-abstraction contract shape, the PKCE discipline, the session-bridge shape, the refresh-token posture, and the multi-provider routing without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, security-auth-clerk, persistence-data-sqlite, ci-pipeline, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camelCase, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`auth`, `authentication`, `identityProvider`, `oauthProvider` are all wrong when `authModel` already exists).
+
+## The deliberate authModel conflict, restated
+
+This blueprint is the vendor-neutral shape of the `authModel` decision. Three other shipped auth-family blueprints hold vendor-specific or model-specific shapes on the same topic:
+
+- `security-auth-magic-link` (ADR-501): passwordless magic-link with server-issued opaque cookie sessions. Local-first, no third-party identity dependency.
+- `security-auth-clerk` (ADR-1001): hosted identity via Clerk; the vendor owns the sign-in surface, credential storage, MFA, and account recovery; the project owns a middleware boundary against Clerk's session-verification.
+- `security-auth-oauth2` (ADR-1101, this blueprint): delegated identity via OAuth2 authorisation-code + PKCE against any project-configured IdP. Vendor-neutral; the project drops in the provider it wants.
+- `security-auth-keycloak` (planned, ADR-12xx suffix block reserved): self-hosted Keycloak realm as the identity source. Vendor-committed; larger ops footprint.
+
+Composing any two of these on one project raises a `globalAdrTopic` conflict on `authModel` at `rcf define blueprint add`. The four documented resolutions apply: adopt the incoming, keep the existing, author a project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add. The composition-precedent (SPA + REST on `errorEnvelope` and `authModel`) is the same pattern the client half and the server half of the wire contract have already established; the auth-family blueprints follow it.
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19, extended by round-2 outcomes 2026-08-30 for the four-digit ADR/TAC suffix widening); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 10101-10111 sit at the LOW end of the 10101-10899 band on purpose. A project-side story that mechanically derives from a security-auth-oauth2 REQ id into the number `10111` would collide against security-auth-oauth2-US-10111 in this package; the band leaves headroom at the HIGH end (US 10181-10899) so a project's own stories anchored to security-auth-oauth2 REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+The ADR/TAC suffix block 1101-1199 is the second block to cross into the four-digit suffix space; `security-auth-clerk` opened the four-digit door at 1001-1099. Every shipped blueprint continues to load, validate, and audit against this shape without a schema change: rcf-schemas 0.5.0 `adrId` and `tacId` patterns are `^ADR-\d{3,}(-[a-z0-9]+...)?$` (three-digit minimum, unbounded above); four-digit and higher suffixes validate verbatim. The registry table above records the growth for a downstream author reaching for the next block.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `authModel` exactly as spelled here when your blueprint holds an opinion on the project's authentication model; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- Provider-abstraction contract (ADR-1102), PKCE discipline (ADR-1103), session-bridge shape (ADR-1104), refresh-token posture (ADR-1105), and multi-provider routing (ADR-1106) are scope-local. A composing blueprint that holds an opinion on any of them authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate authentication-model variations.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint), `sessionStore` (unclaimed; a future session-persistence-committed blueprint's natural global, and the shape this blueprint's session-bridge is deliberately open on). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.

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

@@ -0,0 +1,65 @@
+# security-auth-oauth2 guide
+
+## What it is
+
+A vendor-neutral blueprint for delegated identity through OAuth2 authorisation-code with PKCE. It fixes the flow, the provider-abstraction contract, the CSRF discipline, the id_token verification path (for OIDC-declared providers), the session-bridge shape, the refresh-token posture, the sign-out semantics, and the multi-provider routing. It does not commit the project to one vendor; it commits the project to one flow that every conforming vendor plugs into.
+
+A project applies this blueprint, drops in one or more provider records (Google, GitHub, Microsoft, Okta, Auth0, a corporate ADFS-fronted OIDC, a self-hosted `node-oidc-provider`), and inherits the state machine that gets the sign-in ceremony right against any of them. Adding a second provider is a config-record write. The state machine does not change.
+
+## What it deliberately is not
+
+Not a vendor-committed blueprint. If a project wants a hosted-identity fast lane with the vendor doing most of the work, `security-auth-clerk` is the sibling; if a project wants a self-hosted Keycloak realm, `security-auth-keycloak` (when it ships) is the sibling. The vendor-neutral shape here trades some vendor-specific richness (Google's `hd` claim, Microsoft's tenant scoping, GitHub's per-org enforcement) for one code path across every conforming vendor. Vendor-specific companion blueprints layer on top when demand justifies them.
+
+Not a passwordless-magic-link blueprint. `security-auth-magic-link` is the sibling for projects that want no third-party identity dependency and are willing to own the principal registry, the email adapter, and the anti-enumeration posture.
+
+Not a session-persistence blueprint. The session-bridge (TAC-1103) injects a session-record store; the reference wiring is in-memory. A project that wants durable sessions composes `persistence-data-sqlite` (or `persistence-data-d1` when it ships) and points the store at a table. The blueprint does not commit the storage shape.
+
+Not an MFA blueprint. MFA is the IdP's concern; the blueprint delegates. A provider that requires MFA at the vendor surface is transparent to the flow controller.
+
+Not a provider-selector UX blueprint beyond a reference rendering. TAC-1104 is optional at wire time; a project that wants a rich multi-provider selector substitutes its own surface as long as the query-parameter contract on `/auth/sign-in?provider=<id>` stays intact.
+
+## When to reach for it
+
+- The project wants delegated identity but is not committed to a single hosted vendor.
+- The project may or may not add a second provider later; the seam should be ready.
+- The project's ops posture prefers the sign-in surface (and the credential storage) to live at an IdP the project does not run.
+- The project has, or will register, an application at one or more IdPs and hold the resulting `clientId`/`clientSecret` pair through the secrets-management blueprint.
+- The project wants runtime-verify to actually verify the state machine and the identity-lift in CI without paying for a per-CI-run set of live-vendor credentials.
+
+## When it does not fit
+
+- The project has no external IdP and no plan to obtain one. `security-auth-magic-link` is the shape.
+- The project is committed to Clerk and wants the vendor to do more of the work than an OAuth2 record allows. `security-auth-clerk` is the shape.
+- The project has an existing Keycloak realm and wants a vendor-committed integration. `security-auth-keycloak` (when it ships) is the shape.
+- The project's session-verification requirements need statelessness at scale (no server-side session record). This blueprint's session-bridge is opaque-handle by ADR-1104; a JWT-in-cookie posture is a project-level ADR supersede on the session-bridge shape.
+
+## What a good outcome looks like
+
+- One provider record per configured IdP, on the fixed shape, validated at boot.
+- One sign-in ceremony code path across every provider; adding a second provider is a config-record write.
+- Every callback either issues a project session or terminates with a stable-coded refusal naming the reason class.
+- The browser holds an opaque-handle cookie; provider tokens live server-side; nothing on `request.auth` is a provider token.
+- Refresh-token rotation is silent when the flow is healthy and revokes the chain when a refresh-token reuse is detected.
+- Sign-out clears the project session; the operator-declared `providerLogout` flag is what decides the provider-side redirect.
+- `rcf audit coverage --strict` on the project's post-blueprint-apply state reports every blueprint AC as uncovered by TC (the blueprint ships no test files); every AC is a runtime-observable fact the project authors a TC against; the ship gate refuses on any uncovered AC that is not `accountBound`.
+- The live-provider smoke AC is `accountBound` and skipped by the runtime-verify runner when credentials are absent; the project-authored TC records the outcome honestly.
+
+## Operator decisions that remain open after apply
+
+- Which IdP(s) to configure. The blueprint lists Google, GitHub, Microsoft, Okta, Auth0, corporate ADFS, and self-hosted `node-oidc-provider` as illustrative examples; the project picks and registers.
+- Where the `clientSecret` lives. The recommended pattern is a secret declared in the project's `secrets.yaml` (`security-secrets-management` composed) read at boot; a project that has not composed the secrets blueprint reads from its process environment or an equivalent.
+- The session-record store. In-memory is the reference wiring; a project running more than one process points the store at a table.
+- The session lifetime (`sessionExpirySeconds`) and the pending-flow TTL (`pendingFlowTtlSeconds`). Defaults in the reference wiring are 8 hours and 10 minutes respectively; the project may tighten or extend per its risk posture.
+- The `enrichPrincipal` hook. Empty roles and organisationIds arrays are the default; a project that maps IdP claims to project roles authors the hook and lists the mapping in a project-level ADR.
+- The provider selector surface. TAC-1104's reference rendering is deliberately plain; a project that wants a branded selector substitutes its own.
+- The live-provider smoke. AC-10110-2 is `accountBound`; a project that has live credentials wires them and the TC lights up, otherwise the skip is honest.
+
+## Cost honesty
+
+Shipping this doc set costs the project 10 REQs, 10 USs (27 ACs), 4 TACs, and 6 ADRs on the tree; the ACs are runtime-observable and the project's build cycle owns writing the TCs. The realisation cost is one flow controller, one provider adapter with per-record boot validation, one session-bridge with an injected store, and (optionally) a selector rendering; the reference wiring runs to a small number of files in one package. The mock OIDC provider is a one-off project-authored fake stood up per `assets/mock-provider/mock-oidc-shape.md` (or an existing library); the shape is what the ACs bind against. The live-provider smoke costs the operator credentials and a redirect URI registration at the provider's console per IdP; that cost is unavoidable and the `accountBound` posture keeps it out of CI.
+
+## Promotion signals to the vendor-committed siblings
+
+- The project wants the vendor to host the sign-in surface, credential storage, MFA, and account recovery; the trade of a vendor commitment is acceptable. Promote to `security-auth-clerk`: supersede ADR-1101 with a project-level ADR pointing at Clerk's authModel; apply `security-auth-clerk`; the flow controller and the session-bridge from this blueprint are retired and Clerk's middleware boundary takes over.
+- The project's ops team runs (or wants to run) a Keycloak realm; the project wants a vendor-committed integration. Promote to `security-auth-keycloak` when it ships; the OAuth2-generic path is a valid interim.
+- The project's audience needs a passwordless-magic-link posture (regulated environment, no third-party identity dependency); demote to `security-auth-magic-link`.

package/blueprints/security-secrets-management/README.md

@@ -0,0 +1,48 @@
+# Security secrets management blueprint (v1.0.0)
+
+The eighth content blueprint on the rcf-build-lite blueprint mechanism. Scope: a vendor-agnostic secrets management contract centred on a repo-root `secrets.yaml` manifest, a single Secrets Manager client every call site imports, least-privilege per-deployable slices, a durable metadata-only audit trail, an agent-safe piped-stdin CLI, `.env` as an ephemeral regenerable reflection, an environment-aware manifest shape elicited from the operator, and a three-way elicited operator UI choice. Targeted at small greenfield rcf-lite projects; larger deployments supersede the default vendor (ADR-902) with a project-level ADR and swap the vendor adapter.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/security-secrets-management
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `security` category; `rcf define blueprint remove security-secrets-management` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `security`, and the 30 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 10 REQs, 10 USs (30 ACs), 5 TACs, 5 ADRs, all schema-valid and namespaced (`security-secrets-management-REQ-001` prefix family; `ADR-901-security-secrets-management-secrets-source` suffix family) |
+| Manifest shape sample | `assets/manifest-samples/secrets-yaml-shape.md` | The exact shape of a `secrets.yaml` entry with `environments`, `deployables`, `secrets[]`, and `uiIntegration`, worked as one committable example |
+| Environment-aware example | `assets/manifest-samples/environment-aware-example.md` | Two shapes of the environments section (three-env `dev/ci/live` and a project-specific list) with a pick guide |
+| Agent access pattern | `assets/cli-usage/agent-access-pattern.md` | The piped-stdin pattern for `secrets read` and `secrets put`, including a Node.js spawn wrapper that keeps the value off argv and off any log line |
+| UI three-way choice | `assets/ui-integration/three-way-choice.md` | The elicitation script for the admin-UI choice with the shape of each outcome and the field contract for the `integrate` variant |
+| Guide | `guide/security-secrets-management.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signals for the hosted-vendor and admin-SPA companion blueprints |
+| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-pipeline, observability-essentials, security-secrets-management) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the manifest shape, the client contract, the least-privilege posture, the audit shape, the agent access discipline, the `.env` reflection posture, the rotation gate, the UI-choice contract); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: a vendor SDK (the default vendor is named in ADR-902 as SOPS+age, the shape of the vendor adapter is fixed by TAC-901, the actual adapter code is a project-authored implementation); a specific manifest schema library (any YAML parser plus the loader in TAC-902 satisfies the loader responsibilities); a project's authorisation model (secrets management authorises READ of secret material; who is allowed to act on which secret at which UI surface is a project-side authorisation concern layered above the audit sink); a rotation orchestrator (the blueprint gates on rotation age at CI, it does not itself run the rotation for you; running the rotation is a project-authored procedure the vendor's own tooling supports); the admin-UI Secrets page itself when `uiIntegration.mode` is `integrate` (the field contract is fixed by TAC-905, the page implementation lives in the host project); an admin-spa blueprint (a companion future blueprint, promotion signal noted in the guide); a project's audit-storage engine (the blueprint fixes the event shape, not where the events land).
+
+## The one global decision
+
+ADR-901-security-secrets-management-secrets-source ships `scope: global` on topic `secretsSource`. This is the project's single source of truth for secret material: a repo-root manifest plus a vendor-agnostic client. A composing blueprint that wants a vendor-committed shape (a Vault-specific blueprint, an AWS Secrets Manager blueprint) conflicts here by design and expects a project-level ADR resolution. Vendor DEFAULT (ADR-902) is deliberately scope-local: the contract is global; the default that ships behind it is not.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from vendor-choice (which is not global), and the AC id band allocation (security-secrets-management owns 8101-8899, ADR/TAC suffix block 9xx).
+
+## Quality bar
+
+Repo-root `secrets.yaml` as the sole declaration of every secret the project depends on; one Secrets Manager client as the sole importer of the vendor binding on the boundary; per-deployable declared slice enforced at both the client and the vendor-side credential scoping; loud-fail-at-boot on a required-absent secret with a stable-coded error naming the logical name and active environment; single-shot audit event per fetch attempt with metadata-only fields; agent access via piped-stdin CLI that refuses value-on-argv and refuses TTY-echo-without-`--show`; CLI structured surfaces (`--json`, `--report`) that never carry a value; CLI log stream wrapped in a redactor that replaces resolved values with a fixed placeholder before any bytes leave the process; `.env` as an atomically-written gitignored regenerable reflection with a source-tree scan refusing direct `.env` reads at boot; environment-aware manifest with the environment set elicited at first apply and enforced thereafter; CI rotation gate that fails on expired-age and unknown-age entries and audits every applied override; three-way elicited UI choice (`integrate`, `admin-spa`, `none`) with a field contract that renders metadata only, never a value. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed application (source-tree import-graph scans for the boundary properties, in-memory audit-sink accumulation for the audit shape, port-scan for the fail-safe boot posture, byte-equality checks against resolved values for the leakage properties, CI-gate exit code for the rotation and manifest-miss gates, page-render inspection for the UI-choice outcomes). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational surface a project must own on its own is the vendor adapter implementation (the SOPS-with-age default, or a superseding vendor's adapter); that responsibility is stated as a TAC interface, not as a smuggled runtime probe. The one AC whose runtime observability depends on operator choice is AC-8110-3 (`uiIntegration.mode: 'none'` outcome); the runtime observability there is the absence of a Secrets page anywhere in the deployed application, which a project's own smoke scan can confirm cheaply.

package/blueprints/security-secrets-management/assets/cli-usage/agent-access-pattern.md

@@ -0,0 +1,69 @@
+# Agent access pattern for the Secrets CLI
+
+The CLI shape a coding agent should reach for. Every verb keeps the secret bytes off argv, off logs, and off stdout unless a real human on a real terminal has explicitly asked to see them.
+
+## Reading a value into a downstream consumer
+
+```
+secrets read database-password | psql --dbname=app --username=api --password-from-stdin
+```
+
+`secrets read` writes the value to stdout as raw bytes. The pipe hands it to `psql`. The value crosses one pipe and no more.
+
+## Reading a value into a spawned process (Node.js wrapper)
+
+The pattern below shows the value being read from the CLI, handed to a child process as an environment variable set at spawn time, and never printed on the way through.
+
+```js
+import { spawn } from "node:child_process";
+
+async function runWithSecret(secretName, envVarName, command, args) {
+  const reader = spawn("secrets", ["read", secretName], {
+    stdio: ["ignore", "pipe", "inherit"]
+  });
+  const chunks = [];
+  for await (const chunk of reader.stdout) chunks.push(chunk);
+  const value = Buffer.concat(chunks).toString("utf8").trimEnd();
+  const readerExit = await new Promise(resolve => reader.on("exit", resolve));
+  if (readerExit !== 0) {
+    throw new Error(`secrets read ${secretName} exited ${readerExit}`);
+  }
+  const child = spawn(command, args, {
+    stdio: "inherit",
+    env: { ...process.env, [envVarName]: value }
+  });
+  return await new Promise(resolve => child.on("exit", resolve));
+}
+```
+
+The value is held in memory for the shortest time the pattern allows: read from the pipe, passed as a spawn env, and then out of scope. Nothing in this script writes it to a log, echoes it to stdout, or persists it to a file.
+
+## Writing a value (rotation)
+
+```
+generate-fresh-secret | secrets put stripe-api-key
+```
+
+`secrets put` reads the value from stdin. Passing the value as a positional argument (`secrets put stripe-api-key HUNTER2`) is refused with `SECRETS_VALUE_ON_ARGV_REFUSED`; even the refusal message does not carry the value.
+
+## Reading a metadata list
+
+```
+secrets list --json
+```
+
+Emits one JSON entry per manifest entry with fields `name`, `environment`, `owner`, `rotationDays`, `lastRotatedAt`, `required`. No entry carries a `value` or a hash of one; the admin UI's Secrets page renders against this same field set.
+
+## Debug read for a human (terminal only)
+
+```
+secrets read database-password --show
+```
+
+The `--show` flag is honoured only when stdout is an actual TTY (not a captured stream, not a pipe, not a redirected file). This is the one legitimate reason to look at a value with your own eyes; it is deliberately not scriptable through an agent transcript.
+
+## What NOT to do
+
+- Do not embed a secret value as a literal in agent-authored code, configuration, or a scratch file, even temporarily. Every reference is by logical name through the client.
+- Do not pass a value on argv to any command. If a downstream tool only accepts values on argv, wrap it in a small script that reads stdin and re-spawns the tool with the value as an environment variable set at spawn time.
+- Do not echo the value from a debug print. The CLI's own logger runs through a redactor, but agent-authored code does not; a stray `console.log(process.env.SECRET)` in a working script defeats the whole discipline.

package/blueprints/security-secrets-management/assets/manifest-samples/environment-aware-example.md

@@ -0,0 +1,33 @@
+# Environment-aware manifest shapes (samples)
+
+The `environments` array is elicited from the operator at first apply. Two common shapes and a pick guide.
+
+## Shape A: three-env `dev` / `ci` / `live`
+
+```yaml
+environments:
+  - dev
+  - ci
+  - live
+```
+
+Suits a project with a single production target, one CI runner pool, and one developer laptop pattern. `dev` and `ci` values may point at safely fake or shared-test credentials; `live` values point at real vendor-issued production credentials.
+
+## Shape B: project-specific list
+
+```yaml
+environments:
+  - dev
+  - preview
+  - staging
+  - prod
+```
+
+Suits a project with per-PR preview deployments, a shared staging environment, and a promoted-to-production target. Every entry's `paths` object must carry a key for each of the four; the loader refuses a partial entry.
+
+## Pick guide
+
+- Prefer the smallest environment list that captures every meaningfully-distinct resolution path. Adding an environment adds a slot to every entry's `paths` and is a re-encrypt for every value on the default SOPS+age vendor.
+- Do not use environment names as feature flags. `dev-with-fake-payments` is a separate concern; keep environments to distinct deployment contexts.
+- Name environments as lower-kebab strings; the loader refuses other shapes.
+- The environment set is a boot-time selector; a process selects exactly one environment at start-up and holds it for its lifetime. A deployable that needs to switch environments mid-life is misusing the concept; that is what per-request tenancy is for at the application layer, not what environments are for at the secrets layer.

package/blueprints/security-secrets-management/assets/manifest-samples/secrets-yaml-shape.md

@@ -0,0 +1,74 @@
+# `secrets.yaml` shape (sample)
+
+The manifest lives at the repo root and is the single declaration of every secret the project depends on. Values never appear here; names, per-environment paths, and metadata do.
+
+## Full shape
+
+```yaml
+version: 1
+environments:
+  - dev
+  - ci
+  - live
+uiIntegration:
+  mode: integrate    # one of: integrate, admin-spa, none
+deployables:
+  - id: api
+    slice:
+      - database-password
+      - stripe-api-key
+      - session-salt
+  - id: worker
+    slice:
+      - database-password
+      - queue-signing-key
+secrets:
+  - name: database-password
+    owner: platform-team
+    rotationDays: 90
+    required: true
+    paths:
+      dev: secrets/dev/database-password.enc
+      ci: secrets/ci/database-password.enc
+      live: secrets/live/database-password.enc
+  - name: stripe-api-key
+    owner: payments-team
+    rotationDays: 30
+    required: true
+    paths:
+      dev: secrets/dev/stripe-api-key.enc
+      ci: secrets/ci/stripe-api-key.enc
+      live: secrets/live/stripe-api-key.enc
+  - name: session-salt
+    owner: platform-team
+    rotationDays: 365
+    required: true
+    paths:
+      dev: secrets/dev/session-salt.enc
+      ci: secrets/ci/session-salt.enc
+      live: secrets/live/session-salt.enc
+  - name: queue-signing-key
+    owner: platform-team
+    rotationDays: 180
+    required: false
+    paths:
+      dev: secrets/dev/queue-signing-key.enc
+      ci: null
+      live: secrets/live/queue-signing-key.enc
+```
+
+## Field notes
+
+- `version`: an integer for future manifest evolution; loader refuses an unknown version.
+- `environments`: a non-empty array of lower-kebab strings; the project's environment names, elicited from the operator at first apply and enforced from then on.
+- `uiIntegration.mode`: one of `integrate`, `admin-spa`, `none`, recording the operator's three-way UI choice.
+- `deployables[]`: each entry declares an `id` (matching the boot input the process passes to the client) and a `slice` (the ordered array of secret names that deployable is allowed to read).
+- `secrets[]`: each entry carries `name`, `owner`, `rotationDays`, `required`, and a `paths` object whose key set equals `environments`. A path may be null on an optional entry to mark the secret as intentionally not present in that environment; a null on a required entry fails boot in that environment.
+
+## What the loader refuses
+
+- A missing `secrets.yaml` at the repo root.
+- An entry whose `paths` key set differs from `environments`.
+- An entry that carries a `value` field (secret values never live in the manifest).
+- An entry whose `name` is not lower-kebab.
+- A `uiIntegration.mode` value not in the enumerated set.

package/blueprints/security-secrets-management/assets/ui-integration/three-way-choice.md

@@ -0,0 +1,44 @@
+# The three-way UI choice (elicitation and outcomes)
+
+At first apply the working agent elicits one of three outcomes for the operator-facing Secrets Management surface and records the choice on the manifest header field `uiIntegration.mode`.
+
+## The elicitation
+
+Ask the operator:
+
+> Where should the operator-facing Secrets Management page live?
+>
+> A. Integrate a Secrets page into an existing project admin UI. Choose this when the project already ships an admin surface (a dashboard, an operations console) and one more page fits.
+>
+> B. Adopt a separate admin-spa blueprint that hosts the Secrets page as one of its screens. Choose this when the project does not yet have an admin surface and building a small one is the right move.
+>
+> C. Decline a UI entirely; rely on the CLI plus the audit stream. Choose this when the project is small, the operator is the only human on the loop, and a page adds surface without adding value.
+
+Record the answer as `uiIntegration.mode: 'integrate' | 'admin-spa' | 'none'` in the manifest.
+
+## Outcome A: `integrate`
+
+The blueprint contributes the field contract for the Secrets page (TAC-905); the host project implements the page inside its existing admin UI. Each row on the page carries:
+
+- `name` (the manifest logical name)
+- `environment` (the active environment for this page's view; the page may offer an environment switcher)
+- `owner` (from the manifest entry)
+- `lastRotatedAt` (from the vendor)
+- `rotationDays` (from the manifest entry)
+- `required` (from the manifest entry)
+
+No cell renders a secret value. A "request rotation" action per row hands off to the project's own rotation procedure (a link, a modal describing the vendor's rotation flow, an operator-authored runbook); the blueprint does not itself run the rotation.
+
+## Outcome B: `admin-spa`
+
+The blueprint records the choice; the project applies the companion admin-spa blueprint (unshipped at v1.0.0, promotion signal: the third project asks for this outcome) which hosts the Secrets page as one of its screens against the same field contract. Until the companion ships, this outcome is a placeholder: the operator's stated intent is that when the companion exists, that is where the page will live.
+
+## Outcome C: `none`
+
+The blueprint contributes nothing to the operator UI surface. The CLI and the audit stream are the only operator-facing surfaces this blueprint ships. A project that later wants a UI can supersede the choice by re-eliciting and picking `integrate` or `admin-spa` at that point; the change is a manifest header edit and the corresponding TAC realisation.
+
+## What the choice must NOT do
+
+- The choice must not force the presence of a UI on a project that does not want one.
+- The choice must not force the absence of a UI on a project that already has an admin surface where one more page belongs.
+- The choice must not, at any outcome, put a secret value on a rendered page. The field contract fixes the surface; no outcome relaxes it.

package/blueprints/security-secrets-management/blueprint.json

@@ -0,0 +1,43 @@
+{
+  "slug": "security-secrets-management",
+  "version": "1.0.0",
+  "category": "security",
+  "contributions": [
+    { "id": "security-secrets-management-REQ-001", "kind": "req", "path": "requirements/security-secrets-management-req-001.json" },
+    { "id": "security-secrets-management-REQ-002", "kind": "req", "path": "requirements/security-secrets-management-req-002.json" },
+    { "id": "security-secrets-management-REQ-003", "kind": "req", "path": "requirements/security-secrets-management-req-003.json" },
+    { "id": "security-secrets-management-REQ-004", "kind": "req", "path": "requirements/security-secrets-management-req-004.json" },
+    { "id": "security-secrets-management-REQ-005", "kind": "req", "path": "requirements/security-secrets-management-req-005.json" },
+    { "id": "security-secrets-management-REQ-006", "kind": "req", "path": "requirements/security-secrets-management-req-006.json" },
+    { "id": "security-secrets-management-REQ-007", "kind": "req", "path": "requirements/security-secrets-management-req-007.json" },
+    { "id": "security-secrets-management-REQ-008", "kind": "req", "path": "requirements/security-secrets-management-req-008.json" },
+    { "id": "security-secrets-management-REQ-009", "kind": "req", "path": "requirements/security-secrets-management-req-009.json" },
+    { "id": "security-secrets-management-REQ-010", "kind": "req", "path": "requirements/security-secrets-management-req-010.json" },
+    { "id": "security-secrets-management-US-8101", "kind": "us", "path": "user-stories/security-secrets-management-us-8101.json" },
+    { "id": "security-secrets-management-US-8102", "kind": "us", "path": "user-stories/security-secrets-management-us-8102.json" },
+    { "id": "security-secrets-management-US-8103", "kind": "us", "path": "user-stories/security-secrets-management-us-8103.json" },
+    { "id": "security-secrets-management-US-8104", "kind": "us", "path": "user-stories/security-secrets-management-us-8104.json" },
+    { "id": "security-secrets-management-US-8105", "kind": "us", "path": "user-stories/security-secrets-management-us-8105.json" },
+    { "id": "security-secrets-management-US-8106", "kind": "us", "path": "user-stories/security-secrets-management-us-8106.json" },
+    { "id": "security-secrets-management-US-8107", "kind": "us", "path": "user-stories/security-secrets-management-us-8107.json" },
+    { "id": "security-secrets-management-US-8108", "kind": "us", "path": "user-stories/security-secrets-management-us-8108.json" },
+    { "id": "security-secrets-management-US-8109", "kind": "us", "path": "user-stories/security-secrets-management-us-8109.json" },
+    { "id": "security-secrets-management-US-8110", "kind": "us", "path": "user-stories/security-secrets-management-us-8110.json" },
+    { "id": "TAC-901-security-secrets-management-manager-client", "kind": "tac", "path": "tacs/tac-901-security-secrets-management-manager-client.json" },
+    { "id": "TAC-902-security-secrets-management-manifest", "kind": "tac", "path": "tacs/tac-902-security-secrets-management-manifest.json" },
+    { "id": "TAC-903-security-secrets-management-env-reflector", "kind": "tac", "path": "tacs/tac-903-security-secrets-management-env-reflector.json" },
+    { "id": "TAC-904-security-secrets-management-rotation-gate", "kind": "tac", "path": "tacs/tac-904-security-secrets-management-rotation-gate.json" },
+    { "id": "TAC-905-security-secrets-management-agent-cli", "kind": "tac", "path": "tacs/tac-905-security-secrets-management-agent-cli.json" },
+    {
+      "id": "ADR-901-security-secrets-management-secrets-source",
+      "kind": "adr",
+      "path": "adrs/adr-901-security-secrets-management-secrets-source.json",
+      "scope": "global",
+      "topic": "secretsSource"
+    },
+    { "id": "ADR-902-security-secrets-management-default-vendor", "kind": "adr", "path": "adrs/adr-902-security-secrets-management-default-vendor.json" },
+    { "id": "ADR-903-security-secrets-management-agent-access-discipline", "kind": "adr", "path": "adrs/adr-903-security-secrets-management-agent-access-discipline.json" },
+    { "id": "ADR-904-security-secrets-management-dotenv-reflection", "kind": "adr", "path": "adrs/adr-904-security-secrets-management-dotenv-reflection.json" },
+    { "id": "ADR-905-security-secrets-management-rotation-and-audit", "kind": "adr", "path": "adrs/adr-905-security-secrets-management-rotation-and-audit.json" }
+  ]
+}