rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3104.json

@@ -0,0 +1,55 @@
+{
+  "usId": "security-auth-magic-link-US-3104",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Session cookies are Secure, HttpOnly, and SameSite=Lax on every issue and refresh",
+  "asA": "operator whose browser holds the credential",
+  "iWant": "the session cookie kept away from client-side script and away from cross-site request paths",
+  "soThat": "an XSS injection cannot exfiltrate my session and a cross-site request cannot ride it",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3104-1",
+      "description": "Every Set-Cookie header that issues or refreshes the session cookie carries the Secure attribute.",
+      "given": "any response that issues or refreshes the session cookie",
+      "when": "the Set-Cookie header is parsed",
+      "then": "the Secure attribute is present",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3104-2",
+      "description": "Every Set-Cookie header that issues or refreshes the session cookie carries the HttpOnly attribute.",
+      "given": "any response that issues or refreshes the session cookie",
+      "when": "the Set-Cookie header is parsed",
+      "then": "the HttpOnly attribute is present",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3104-3",
+      "description": "Every Set-Cookie header that issues or refreshes the session cookie carries SameSite=Lax.",
+      "given": "any response that issues or refreshes the session cookie",
+      "when": "the Set-Cookie header is parsed",
+      "then": "the SameSite attribute is present with value Lax",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3104-4",
+      "description": "The session cookie value is not readable by client-side script under the runtime browser policy the app targets.",
+      "given": "a browser page authenticated to the deployed app",
+      "when": "document.cookie is queried by page script",
+      "then": "the returned string contains no substring matching the issued session handle",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-502-security-auth-magic-link-session-manager",
+    "TAC-503-security-auth-magic-link-login-routes"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3105.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-magic-link-US-3105",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-out and administrative revoke both invalidate on the server",
+  "asA": "operator who wants sign-out to actually mean the session is gone",
+  "iWant": "POST /logout to invalidate the session server-side and revocation-by-principal to end every session for that principal",
+  "soThat": "a leaked cookie stops working the moment I have signed out or the moment an administrator revokes me",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3105-1",
+      "description": "POST /logout invalidates the server-side session record for the presented handle and returns a response that clears the session cookie on the browser.",
+      "given": "an authenticated request with a valid session cookie",
+      "when": "POST /logout runs",
+      "then": "the session record for that handle is deleted from the store, and the response carries a Set-Cookie header clearing the session cookie (Max-Age=0 or an expiry in the past)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3105-2",
+      "description": "After POST /logout, a subsequent request presenting the same handle is treated as unauthenticated.",
+      "given": "POST /logout has completed for a session S",
+      "when": "a subsequent authenticated request is made using S's handle",
+      "then": "the server treats the request as unauthenticated (redirects to /login or returns 401 per the surface's convention) and does not resurrect the session",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3105-3",
+      "description": "The session manager exposes a revokeAllForPrincipal(principalId) operation that invalidates every unexpired session for that principal in one call.",
+      "given": "a principal with N unexpired sessions in the store",
+      "when": "revokeAllForPrincipal is invoked with that principal id",
+      "then": "the store's session count for that principal drops to zero and every previously issued handle for that principal fails validation on the next request",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-502-security-auth-magic-link-session-manager",
+    "TAC-503-security-auth-magic-link-login-routes"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3106.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-magic-link-US-3106",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-in submission gives away no information about registration",
+  "asA": "operator on a surface that must not become an enumeration oracle",
+  "iWant": "POST /login to return the same body, status, and timing regardless of whether the submitted address is registered",
+  "soThat": "an attacker with a wordlist cannot harvest the registered set by watching the endpoint",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3106-1",
+      "description": "The response body for POST /login is byte-identical across registered, unregistered, malformed, and empty submissions.",
+      "given": "POST /login is exercised with a registered address, an unregistered address, a malformed string, and an empty body in turn",
+      "when": "each response body is captured",
+      "then": "every captured body is byte-identical",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3106-2",
+      "description": "The response status for POST /login is identical (200) across registered, unregistered, malformed, and empty submissions that are not rate-limited.",
+      "given": "POST /login is exercised with a registered, unregistered, malformed, and empty submission under the rate-limit ceiling",
+      "when": "each response status is captured",
+      "then": "every status is 200",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3106-3",
+      "description": "The wall-clock latency floor for POST /login is enforced by an anti-enumeration budget; no response is returned earlier than the configured budget, and the budget dominates the slowest legitimate branch.",
+      "given": "an anti-enumeration budget of N milliseconds is configured, and N exceeds the slowest legitimate branch's measured wall-clock",
+      "when": "POST /login is exercised with a registered submission and an unregistered submission over 20 samples each",
+      "then": "no observed wall-clock is less than N, and the mean absolute difference between the two sample sets is under 25 milliseconds",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-503-security-auth-magic-link-login-routes",
+    "TAC-505-security-auth-magic-link-principal-registry"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3107.json

@@ -0,0 +1,54 @@
+{
+  "usId": "security-auth-magic-link-US-3107",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-in endpoints are rate-limited with honest Retry-After",
+  "asA": "operator on a service that will get hit with mint floods and token-guessing sweeps",
+  "iWant": "POST /login and GET /login/verify both to reject beyond a configured ceiling with a 429 and a Retry-After the client can trust",
+  "soThat": "the endpoints stop misfiring on abuse traffic without any WAF in the path",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3107-1",
+      "description": "POST /login rejects with 429 once its ceiling is crossed within the configured window; the response carries a Retry-After header whose value is a positive integer or an HTTP-date not earlier than the request time.",
+      "given": "POST /login is called from one client key beyond its ceiling within the window",
+      "when": "the ceiling-plus-one request lands",
+      "then": "the response status is 429 and Retry-After is present with a positive integer or a valid HTTP-date at or after request time",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3107-2",
+      "description": "GET /login/verify rejects with 429 once its ceiling is crossed within the configured window; the response carries a Retry-After header.",
+      "given": "GET /login/verify is called from one client key beyond its ceiling within the window",
+      "when": "the ceiling-plus-one request lands",
+      "then": "the response status is 429 and Retry-After is present",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3107-3",
+      "description": "A 429 response from either endpoint does not disclose registration state; the response body is generic and identical across principals.",
+      "given": "POST /login is rate-limited under registered and unregistered submissions in turn",
+      "when": "the 429 response bodies are captured",
+      "then": "every captured body is byte-identical",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3107-4",
+      "description": "The blueprint's default ceiling for POST /login is five requests per minute per client key; the ceiling is a project-configurable option.",
+      "given": "POST /login runs with no project override",
+      "when": "the effective ceiling is inspected",
+      "then": "the ceiling is five requests per minute per client key; when the project supplies rateLimit={ max, timeWindow } the effective ceiling matches the override",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-503-security-auth-magic-link-login-routes"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3108.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-magic-link-US-3108",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sessions and tokens survive a process restart",
+  "asA": "operator whose deploy should not sign every operator out",
+  "iWant": "outstanding sessions and unconsumed sign-in tokens to remain valid across a restart of the authenticating service",
+  "soThat": "a deploy is invisible to the signed-in operator and a magic link that was minted just before a restart still works",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3108-1",
+      "description": "A session issued before a process restart continues to authenticate requests after the process starts back up, without a fresh sign-in and without a change of handle value.",
+      "given": "a session S is issued and then the authenticating process is stopped and started",
+      "when": "a subsequent authenticated request is made using S's handle after the restart",
+      "then": "the server authenticates the request, exposes the same principal id on the request context, and does not require a fresh sign-in",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3108-2",
+      "description": "An unconsumed sign-in token minted before a process restart can be consumed after the restart, within its original expiry window.",
+      "given": "a token T is minted and then the authenticating process is stopped and started, all within T's expiry window",
+      "when": "GET /login/verify is called with T after the restart",
+      "then": "the response is a 302 to the configured post-sign-in route and carries a Set-Cookie header issuing a fresh session handle",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3108-3",
+      "description": "The idle-expiry clock for a session survives a process restart; the wall-clock elapsed during the restart counts against the idle window.",
+      "given": "a session S with idle window I is issued, then the process is stopped for a duration D and restarted",
+      "when": "a subsequent request is made using S's handle after the restart",
+      "then": "the server applies the same idle-expiry rule it would have applied with no restart, using the last-seen timestamp recorded before the stop",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-501-security-auth-magic-link-manager",
+    "TAC-502-security-auth-magic-link-session-manager"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3109.json

@@ -0,0 +1,48 @@
+{
+  "usId": "security-auth-magic-link-US-3109",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Auth events are logged as structured entries and never quote secrets",
+  "asA": "operator investigating an auth incident from the log store",
+  "iWant": "every material auth event to emit one structured entry with fields I can query",
+  "soThat": "the incident is reconstructable from the log without the log itself becoming the leak",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3109-1",
+      "description": "The blueprint's declared auth events (signInRequested, magicLinkMinted, magicLinkSent, magicLinkConsumed, sessionIssued, sessionRefreshed, sessionInvalidated, sessionRevoked, rateLimitTripped, adapterSendFailed) each emit exactly one structured entry per occurrence, carrying at minimum event name, UTC timestamp, outcome, principal id where applicable, and request id where applicable.",
+      "given": "each declared event class is exercised in turn",
+      "when": "the log stream is captured",
+      "then": "each event class emits exactly one entry per occurrence, with the named minimum fields present and typed as declared",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3109-2",
+      "description": "No emitted log entry contains a sign-in token secret, a session handle value, or an email-delivery-provider api key in any field.",
+      "given": "the full declared event set is exercised across successful and failing branches",
+      "when": "every emitted entry is scanned",
+      "then": "no field contains a substring matching any minted token, any issued session handle, or any configured adapter credential",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3109-3",
+      "description": "The magicLinkSent entry names the delivery adapter's returned providerMessageId when one is returned, and the string 'none' otherwise; the entry never carries the recipient's email in a field named otherwise, and the recipient email is always the principal id field's value.",
+      "given": "a magicLinkSent event is emitted after an adapter send",
+      "when": "the entry is inspected",
+      "then": "providerMessageId is present with a non-empty string or the literal 'none', and the recipient email appears only in the principalId field",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-501-security-auth-magic-link-manager",
+    "TAC-502-security-auth-magic-link-session-manager",
+    "TAC-503-security-auth-magic-link-login-routes",
+    "TAC-504-security-auth-magic-link-email-delivery-adapter"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3110.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-magic-link-US-3110",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Email delivery is a pluggable adapter behind a narrow contract",
+  "asA": "operator swapping a stub adapter for a real provider or vice versa without touching auth code",
+  "iWant": "the auth flow to depend on one small interface and know nothing about the provider",
+  "soThat": "provider migration, test doubles, and outage fallbacks are project decisions instead of blueprint rewrites",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3110-1",
+      "description": "The magic-link routes and managers call the email-delivery-adapter through a single send({ to, subject, textBody, htmlBody }) method returning { ok, providerStatus, providerMessageId, error }; no provider-specific fields, credentials, or endpoints appear in the routes or managers.",
+      "given": "the auth code path is walked from POST /login to send completion",
+      "when": "the outgoing calls to the adapter interface are enumerated",
+      "then": "only the declared send method is invoked, with only the declared arguments, and the returned outcome is consumed only via the declared fields",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3110-2",
+      "description": "An adapter that returns { ok: false, error } surfaces the failure to the auth event log via an adapterSendFailed entry, but does not change the POST /login response body or status.",
+      "given": "a registered principal submits POST /login and the adapter's send resolves with { ok: false, error: 'boom' }",
+      "when": "the response and log stream are captured",
+      "then": "the response body and status match a successful send exactly, and exactly one adapterSendFailed entry is emitted with the error string in the outcome field",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3110-3",
+      "description": "The blueprint ships a stub adapter for testing whose send resolves { ok: true, providerStatus: 200, providerMessageId: 'stub' } and records outgoing calls in memory; the project uses the stub in tests and swaps in the real adapter in production without touching the routes or managers.",
+      "given": "the stub adapter is wired into a scratch project's test harness",
+      "when": "POST /login runs against a registered principal",
+      "then": "the stub's send is invoked with the declared arguments and its in-memory record contains one call with those arguments",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-504-security-auth-magic-link-email-delivery-adapter"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/user-stories/security-auth-magic-link-us-3111.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-magic-link-US-3111",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-011",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Principal registry is pluggable and returns only a boolean",
+  "asA": "operator running anything from a solo-operator deployment to a multi-tenant tree",
+  "iWant": "the auth flow to ask exactly one question of my registry (is this address registered) and receive only a boolean",
+  "soThat": "principal shape (single email, allow-list, database query) is my decision and not the blueprint's",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3111-1",
+      "description": "The magic-link routes call the principal-registry through a single isRegistered(email) method returning a Promise resolving to a boolean; no other registry method is called on the auth path.",
+      "given": "the auth code path is walked from POST /login through registration lookup",
+      "when": "the outgoing calls to the registry interface are enumerated",
+      "then": "only isRegistered is invoked, with only the submitted email string, and only the resolved boolean is consumed",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3111-2",
+      "description": "A registry that returns false for a submission produces an identical POST /login response to a registry that returns true; the registry answer is invisible in the response body, status, and Content-Type.",
+      "given": "the same email string is submitted twice, once against a registry that returns false and once against a registry that returns true",
+      "when": "the two responses are compared",
+      "then": "the response bodies are byte-identical, the statuses are equal, and the Content-Type headers are equal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3111-3",
+      "description": "The blueprint ships a single-address registry implementation for solo-operator deployments; the implementation reads one email from configuration and returns true for that email and false for every other input.",
+      "given": "the single-address registry is instantiated with a configured email",
+      "when": "isRegistered is called with the configured email, a different email, an empty string, and a malformed value in turn",
+      "then": "the resolved boolean is true only for the configured email and false for every other case",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-505-security-auth-magic-link-principal-registry"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/docs/topics.md

@@ -0,0 +1,45 @@
+# security-auth-magic-link blueprint coordination vocabulary
+
+This file is the security-auth-magic-link 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-magic-link contribution | Origin | Composition note |
+|---|---|---|---|
+| `authModel` | ADR-501-security-auth-magic-link-model | Reused verbatim from the application-spa vocabulary and the application-api-rest vocabulary | DELIBERATE pairing: application-spa contributes ADR-205-application-spa-auth-model (client half: cookie-based session, 401-redirect posture), application-api-rest contributes ADR-302-application-api-rest-auth-model (server half: four declared auth classes). Applying any two of the three on one project surfaces the pairing for operator resolution. Expected resolution: one project-level ADR that fixes the credential shape (this blueprint's opaque cookie session), maps it onto the server's auth classes if REST is applied, and specifies the client half's session-expiry posture if SPA is applied |
+
+The security-auth-magic-link blueprint claims only one global topic. Every other contribution is scope-local (the four operational ADRs, ADR-502 through ADR-505, do not contribute global topics; a composing blueprint that holds an opinion on token secrecy, anti-enumeration budgets, session lifecycle, or rate limits authors its own project-level ADR if it wants to override).
+
+Rules for new topics (inherited from the application-spa and REST vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`sessionAuth`, `magicLink`, `sessionModel` are all wrong when `authModel` already exists; `operatorPanel` is claimed by the hello-panel walkthrough exemplar and is not free).
+
+## 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); 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 3101-3111 sit at the LOW end of the 3101-3899 band on purpose. A project-side story that mechanically derives from `security-auth-magic-link-REQ-011` into the number `3111` would collide against security-auth-magic-link-US-3111 in this package; the band leaves headroom at the HIGH end (US 3181-3899) so a project's own stories anchored to security-auth-magic-link REQs can allocate without conflict.
+
+## 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. An OIDC-flavoured security-auth-magic-link blueprint (see the security-auth-magic-link blueprint's guide, section 'when it does not fit') will conflict here by design.
+- This blueprint's decision states the passwordless-magic-link half plus the opaque cookie-session transport. Compose compatible client and server halves, or expect the operator to supersede with one project-level auth-model ADR.
+- 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 application-spa, application-api-rest, and security-auth-magic-link). 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-magic-link/guide/security-auth-magic-link.md

@@ -0,0 +1,65 @@
+# Auth blueprint guide
+
+## What it is
+
+A passwordless-sign-in floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a magic-link authentication model: how sign-in works on the wire, what shape the session takes in the browser, how tokens live and die, how the sign-in endpoints defend themselves against enumeration and brute force, what the auth event log looks like, and how the project plugs its own email transport and its own principal registry into a fixed contract.
+
+Concretely, the blueprint ships eleven requirements, eleven user stories (thirty-seven acceptance criteria), five architecture components, and five architecture decision records. One ADR is `scope: global` on the `authModel` topic; the other four are scope-local operational ADRs (token secrecy, anti-enumeration budget, session lifecycle, rate limiting) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not authorisation. Roles, permissions, quotas, and tenancy do not live inside this blueprint; they layer above the session record's principal id, in project-authored requirements and TACs.
+
+Not multi-factor authentication. MFA layers on top of a resolved session; a project that needs it wires a step-up flow after session issue.
+
+Not federated identity. OIDC through an external identity provider, SAML integration with corporate directories, and social-login through OAuth providers are all out of scope; a future `auth-oidc` blueprint (see 'when it does not fit') owns that space.
+
+Not an email transport. The blueprint contributes the adapter contract and one stub implementation; the project supplies the real transport (SMTP, Resend, SES, whatever fits).
+
+Not a principal registry. The blueprint contributes the lookup contract and one single-address implementation for solo-operator deployments; the project supplies the registry shape that matches its principal model.
+
+## When to reach for it
+
+Reach for the security-auth-magic-link blueprint when:
+
+- The project is a small greenfield rcf-lite deployment (single deployable, one small team of operators or one solo operator, no external identity provider requirement).
+- Sign-in is a rare event compared with authenticated work (an operator signs in once a session and then works; the delay of a magic link is a fine cost for the security posture).
+- The project can plug in an email transport with reasonable delivery latency (a magic link that takes minutes to arrive is a bad user experience; check the transport SLA before shipping).
+- The project needs a defensible security posture out of the box (opaque handles, HttpOnly cookies, anti-enumeration, rate limits, server-side revocation) without a full identity-provider deployment.
+
+## When it does not fit
+
+Do not reach for the security-auth-magic-link blueprint when:
+
+- Multi-user identity, role management, group memberships, or user provisioning are project requirements. A `auth-oidc` blueprint (unshipped at v1.0.0, promotion signal: the third project asks for it) will own this. Until then, a project with these needs authors its own auth model and does not apply this blueprint.
+- The project has a hard requirement for OAuth authorization-code flows against an external provider (Google, GitHub, corporate SSO). Same promotion path; supersede with a project-level ADR and skip this blueprint.
+- The project is a service-to-service API with no browser clients and no interactive sign-in. The application-api-rest blueprint's service class (ADR-302 four-classes model) is the right shape; the security-auth-magic-link blueprint's magic-link flow is not.
+- The operator population is large enough that magic-link email delivery volume is a first-order operational concern (thousands of sign-ins per hour). At that volume the mint endpoint's rate limits become an operator experience problem, and a session-lived credential (bearer, refresh token) is the more defensible shape.
+- Email delivery cannot be trusted (isolated network, no outbound SMTP, delivery SLA in tens of minutes). The magic-link flow's usability floor is 'the operator sees the link within one minute'; below that floor the flow is worse than a password.
+
+The design brief `w-2026-07-28-029` originally scoped a `keycloak-local` blueprint against WESPA's implementation. The security-auth-magic-link blueprint at v1.0.0 does not include keycloak-local because the container-plus-realm cost is disproportionate for the rcf-lite tier this blueprint targets. The keycloak-local pattern is the natural body of a future `auth-oidc` blueprint aimed at bigger projects; the two blueprints are meant to co-reside in the ecosystem, not to compete, and both would deliberately conflict on `authModel` so the operator picks one per project.
+
+## What a good outcome looks like
+
+A project applies the security-auth-magic-link blueprint on a fresh tree, wires the two pluggable interfaces to project-supplied implementations (a real email adapter and a project-shaped principal registry), realises the five TACs in project-authored FBSes, and lands on a deployed application where:
+
+- The operator visits /login, submits their email, and reads 'if this address is registered, a link is on its way' regardless of whether the address is theirs, their colleague's, or a typo.
+- One minute later the link arrives; the operator clicks it and lands on the post-sign-in route with a session cookie set. No password ever existed.
+- The session survives the operator closing and reopening the browser (up to the fifteen-minute idle window and thirty-day absolute ceiling), survives a deploy of the authenticating service, and ends when the operator clicks sign-out or when an administrator revokes.
+- The auth event log tells the operator, without secret leakage, every mint, send, consume, issue, refresh, invalidate, revoke, and rate-limit trip.
+- A repeat submission of a stale magic-link URL, an expired URL, or a URL for a different operator's session returns a generic 401 and issues no session.
+
+## Operator decisions that remain open after apply
+
+- Email transport (SMTP, Resend, SES, project-specific). Blueprint owns the adapter contract; project owns the implementation.
+- Principal registry shape (single address, allow-list file, database lookup, external directory). Blueprint owns the lookup contract; project owns the implementation.
+- Durable store engine (SQLite, Postgres, project-specific). Blueprint owns the store interface on both managers; project owns the engine.
+- Post-sign-in landing route. Blueprint's routes redirect to a configured path; project picks the path.
+- Idle window and absolute lifetime overrides. Blueprint defaults to fifteen minutes idle and thirty days absolute; a project with tighter needs overrides in a project-level ADR.
+- Rate-limit ceilings. Blueprint defaults to five per minute on mint and twenty per minute on consume; a project with heavier legitimate load overrides and states the trade.
+- Anti-enumeration budget. Blueprint defaults to 800 ms; a project with a faster adapter narrows the budget, a project with a slower adapter widens it.
+- Cookie name. Blueprint uses `auth_session` unless configured otherwise; a project with a name-collision picks a distinct name.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every sign-in incurs an email round-trip; operator experience floor depends on the transport SLA. Every authenticated request incurs a session-store lookup; store latency is on the hot path. Every session lives in a durable store and every unconsumed token lives in the same store; storage grows with active operators and expired tokens (a project-level cleanup job is the natural response). The anti-enumeration budget adds a fixed floor to every sign-in submission latency; legitimate operators pay it every time. The rate-limit ceilings are conservative defaults and will trip on unusual retry patterns; a project with a support burden of 'I clicked submit ten times and now I can't sign in for a minute' either raises the ceiling or educates the operator. The blueprint says nothing about authorisation, MFA, or federated identity; a project that needs those spends its own build cycles on them and this blueprint does not save it any work.

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

@@ -0,0 +1,50 @@
+# Security auth OAuth2 blueprint (v1.0.0)
+
+The eleventh content blueprint on the rcf-build-lite blueprint mechanism, category `security`. A vendor-neutral sibling to `security-auth-magic-link` and `security-auth-clerk` on the `authModel` global topic: identity is delegated to any OAuth2-compatible IdP the project selects (Google, GitHub, Microsoft, Okta, Auth0, a corporate ADFS-fronted OIDC, a self-hosted `node-oidc-provider`) through a fixed provider-abstraction contract. The project owns the flow controller (authorisation-code + PKCE state machine), the provider adapter (pluggable record validation and JWKS fetch), the session-bridge (opaque-handle project session, no provider tokens in the browser), and an optional provider selector. Targeted at small greenfield rcf-lite projects that want delegated identity without vendor commitment; larger deployments supersede vendor-neutral posture with a vendor-committed sibling (`security-auth-clerk`, `security-auth-keycloak` when it ships) or with a project-level ADR.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/security-auth-oauth2
+```
+
+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-auth-oauth2` cleanly removes an unreferenced application.
+
+Composing with `security-auth-magic-link`, `security-auth-clerk`, or any other blueprint contributing `scope: global` on `authModel` (which includes `application-spa` and `application-api-rest`) raises a `globalAdrTopic` conflict at add time. The four documented resolutions apply (adopt the incoming, keep the existing, project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add). See `docs/topics.md` for the deliberate-conflict statement.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `security`, and the 31 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 10 REQs, 11 USs (28 ACs), 4 TACs, 6 ADRs, all schema-valid and namespaced (`security-auth-oauth2-REQ-001` prefix family; `ADR-1101-security-auth-oauth2-auth-model` suffix family) |
+| Provider records | `assets/providers/*.md` | Sample provider records for Google (OIDC), GitHub (oauth2-only), and a generic OIDC-discovery-driven record; placeholders for `clientId` and `clientSecret` only |
+| Session-bridge sample | `assets/session-bridge/opaque-handle-shape.md` | The reference opaque-handle session-record shape and the reduced Principal contract; record-only, non-production |
+| Mock provider bootstrap | `assets/mock-provider/mock-oidc-shape.md` | The shape of a local mock OIDC provider stood up per REQ-010's acceptance-bar AC; the file names the endpoints, the JWKS shape, and the token minting shape without committing a specific library version |
+| Provider selector sample | `assets/provider-selector/list-shape.md` | The rendering shape the reference selector emits and the query-parameter contract a bespoke replacement honours |
+| Guide | `guide/security-auth-oauth2.md` | Operator-facing: when to use it, when not, the promotion signals for the Clerk and Keycloak siblings, the operator decisions that remain open, the cost-honesty paragraph |
+| 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, email-smtp-resend, persistence-data-sqlite, ci-pipeline, observability-essentials, security-secrets-management, security-auth-clerk, security-auth-oauth2) |
+
+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 OAuth2 authorisation-code + PKCE flow, the provider-abstraction contract, the CSRF-via-state discipline, the id_token verification path, the session-bridge shape, the refresh-token rotation posture, the sign-out semantics, the multi-provider routing, the accountBound runtime-verify posture); 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 specific OAuth2 or OIDC library dependency (Node has several; project chooses); the mock OIDC provider's binary or a full runtime dependency (the blueprint commits the shape a project stands one up against; the tool itself lives on the project); MFA specifics (the IdP owns MFA at the hosted surface; the blueprint delegates); vendor-specific quirks (Google's `hd` claim, GitHub's per-org enforcement, Microsoft's tenant scoping); a specific session store (the session-bridge injects it; in-memory in the reference wiring, table-backed on a persistence-composed project); real IdP client credentials, real tenant identifiers, real callback URLs (placeholders only); a Clerk-webhook consumer (out of scope for OAuth2-generic; the Clerk sibling owns that territory); a Keycloak realm configuration (out of scope; the Keycloak sibling when it ships owns that territory).
+
+## The one global decision
+
+ADR-1101-security-auth-oauth2-auth-model ships `scope: global` on topic `authModel`. This is the project's single decision on how identity is proven, where credentials live, and what the wire credential looks like. Composing with `security-auth-magic-link`, `security-auth-clerk`, `application-spa`, `application-api-rest`, or any future `security-auth-*` blueprint conflicts here by design and expects a project-level ADR resolution. The composition-precedent (SPA + REST on `errorEnvelope` and `authModel`) is the same pattern the auth-family blueprints follow.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, and the AC id band allocation (security-auth-oauth2 owns 10101-10899, ADR/TAC suffix block 11xx / 1101-1199; the second blueprint to sit in the four-digit ADR/TAC suffix space after security-auth-clerk).
+
+## Quality bar
+
+Authorisation-code + PKCE (S256) as the sole flow, with implicit / password-grant / client-credentials refused at the flow-controller boundary; every provider a plain data record satisfying the provider-abstraction contract with per-field validation at boot; CSRF defended by a server-bound `state` value on a one-time pending-flow record; PKCE verifier stored server-side for the pending-flow duration and presented on the token exchange; id_token verified against the provider's JWKS with signature, issuer, audience, expiry, and nonce checks on every OIDC callback; refuse-fast when an OIDC-declared provider omits the id_token; session cookie an opaque server-issued handle with `Secure`, `HttpOnly`, `SameSite=Lax`; provider tokens (access, id, refresh) stored server-side and never reachable from `request.auth`; refresh-token rotation on every exchange with reuse detection revoking the chain; sign-out invalidates the session record and clears the cookie, with optional redirect to the provider's `endSessionEndpoint` when the record declares one; multi-provider routing at the query-parameter layer with refusal on missing or unknown provider id; runtime-verify against a project-authored mock OIDC provider (real OIDC on the wire) with live-vendor smokes marked `accountBound` and skipped with a stable-coded reason when credentials are unavailable. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+Two named gaps at v1.0.0. First, AC-10110-2 (the live-provider smoke against Google, GitHub, Microsoft, or a corporate SSO) is `accountBound` and depends on operator-provided credentials plus a redirect URI registered at the provider's console; those steps sit outside the blueprint's mechanism reach. The project's ship gate reads the honest coverage: the AC is covered by a project-authored TC whose latest outcome is `skipped` with reason `OAUTH2_LIVE_PROVIDER_UNREACHABLE` when credentials are absent, and `pass` when the operator has driven the smoke. The `accountBound` skip does not fail CI and does not count as coverage passed for a project auditing its live-vendor readiness; the ship-gate operator reads the AC and drives the smoke themselves before promoting a build past staging. Second, 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 (redirect-inspection for the authorise URL shape, token-exchange-request inspection for the PKCE verifier presentation, response-cookie inspection for the session-cookie contract, `request.auth` shape inspection for the Principal reduction, mock-provider callback replay for state and PKCE refusal classes, mock-provider JWKS mutation for id_token refusal classes, session-record store inspection for refresh-token rotation, cookie-clear inspection for sign-out, `Location`-header inspection for provider-side sign-out redirect). 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 is the mock OIDC provider bootstrap (from `assets/mock-provider/`) or an equivalent existing library the project pulls in; that responsibility is stated as an operator step in the guide and referenced by REQ-010, not smuggled as a runtime probe here.