rcf-lite 0.11.0 → 0.13.0

package/blueprints/security-auth-keycloak/docs/topics.md

@@ -0,0 +1,74 @@
+# security-auth-keycloak blueprint coordination vocabulary
+
+This file is the security-auth-keycloak 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-keycloak contribution | Composition intent |
+|---|---|---|
+| `authModel` | ADR-1201-security-auth-keycloak-auth-model | Deliberate conflict on the same string minted by `security-auth-magic-link` (ADR-501), `security-auth-clerk` (ADR-1001), `security-auth-oauth2` (ADR-1101), the client half of `application-spa` (ADR-205), and the server half of `application-api-rest` (ADR-302). This blueprint's shape is delegated identity to a Keycloak realm the operator runs, federated through OIDC authorisation-code + PKCE, with per-realm verification mode (JWKS or introspection). 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-keycloak blueprint claims one global topic. Every other contribution is scope-local (ADR-1202 through ADR-1206 name the verification-mode choice, the provider-routing seam, the session-vs-token contract, the JWKS rotation-cache lifetime, and the refresh-and-sign-out posture 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, security-auth-oauth2, 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`, `keycloakProvider` are all wrong when `authModel` already exists).
+
+## The deliberate authModel conflict, restated
+
+This blueprint is the vendor-committed Keycloak shape of the `authModel` decision. Three other shipped auth-family blueprints hold different 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): 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` (ADR-1201, this blueprint): delegated identity to a Keycloak realm the operator runs, federated through OIDC. Vendor-committed; larger ops footprint; full self-hosted control.
+
+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 11101-11113 sit at the LOW end of the 11101-11899 band on purpose. A project-side story that mechanically derives from a security-auth-keycloak REQ id into the number `11113` would collide against security-auth-keycloak-US-11113 in this package; the band leaves headroom at the HIGH end (US 11181-11899) so a project's own stories anchored to security-auth-keycloak REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+The ADR/TAC suffix block 1201-1299 is the third block in the four-digit suffix space; `security-auth-clerk` opened the door at 1001-1099 and `security-auth-oauth2` took 1101-1199. 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.
+
+## Provider-aware install-design shape (plain language, no named second issuer)
+
+The blueprint is Keycloak-committed. What the install design is AWARE of is that a project may deploy this mechanism in an environment where a receiving system's request stream also carries tokens issued by another OAuth2 or OIDC server. This shape is NOT a claim about the blueprint's mechanism reach - the blueprint verifies against Keycloak realms only, and refuses to name any specific second issuer. The shape lives at the seam where a project's OWN middleware decides which issuer is authoritative for a request:
+
+- TAC-1204 (the provider router) contributes the pure-function contract `route(request) -> { realmSlug, verificationMode } | 'notThisIssuer'`. A project with only Keycloak wires it to a constant; a project with two Keycloak realms wires it to inspect a project-chosen request feature; a project with Keycloak alongside a non-Keycloak issuer returns the sentinel and the project's own middleware chain above owns what happens next.
+- REQ-004 (the introspection path) speaks the RFC 7662 shape whether the issuer is Keycloak or another conforming server. The blueprint reaches only for the endpoint declared on the realm's discovery; a project that has chosen to consult a non-Keycloak issuer at introspection is a project-level ADR conversation, not a mechanism change here.
+
+The blueprint refuses to encode:
+
+- A specific second issuer's name, product, or integration.
+- A specific request marker (a header name, a path prefix, a claim, a subdomain shape) the routing function would inspect.
+- A specific dual-issuer deployment shape (a docker-compose recipe, a Kubernetes topology, a load-balancer rule).
+- A specific standards-suite reference the ratified reshape ruling excluded from this blueprint.
+
+A project that has one Keycloak realm inherits the seam at zero cost (constant routeFn). A project that has two Keycloak realms pays one function call per request. A project with an issuer above this blueprint's reach pays one function call per request and owns the routing policy on its own ADR.
+
+## 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.
+- Verification-mode choice (ADR-1202), provider-routing seam (ADR-1203), session-vs-token contract (ADR-1204), JWKS rotation-cache lifetime (ADR-1205), and refresh-and-sign-out posture (ADR-1206) 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). 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-keycloak/guide/security-auth-keycloak.md

@@ -0,0 +1,81 @@
+# security-auth-keycloak guide
+
+## What it is
+
+A Keycloak-committed blueprint for delegated identity through OAuth2 authorisation-code with PKCE against a Keycloak realm the operator runs. It fixes the Keycloak-shaped decisions the vendor-neutral OAuth2 sibling deliberately leaves open: a Keycloak realm as the concrete issuer, JWKS-with-rotation-cache OR RFC 7662 introspection as the per-realm verification mode, the client-roles / realm-roles claim shape for role extraction, the local-first stand-up shape through the vendor's official container image, the fail-safe boot posture per realm, and the runtime-verify posture that binds against a real local Keycloak container without demanding a cloud tenant.
+
+A project applies this blueprint, declares one or more realm-config records (each pointing at a Keycloak realm the operator runs), and inherits the discovery-driven endpoint record, the JWT verifier (or the introspection client), the role adapter, and the provider-routing seam. Adding a second realm is a config-record write plus a routeFn edit. The mechanism does not change.
+
+## What it deliberately is not
+
+Not a vendor-neutral blueprint. `security-auth-oauth2` is the sibling for projects that are not committed to a single vendor. This blueprint occupies the vendor-committed lane: the concrete Keycloak-shaped decisions (JWKS vs introspection, client-roles vs realm-roles, local container, RP-initiated logout through the realm's end_session_endpoint) are fixed here so the project code path names a Keycloak realm rather than an abstract provider record.
+
+Not a hosted-identity blueprint. `security-auth-clerk` is the sibling for projects that want the vendor to host the sign-in surface, credential storage, MFA, and account recovery. This blueprint targets the operator who wants self-hosted control over the realm and the admin surface.
+
+Not a passwordless-magic-link blueprint. `security-auth-magic-link` is the sibling for projects with no third-party identity dependency and the willingness to own the whole authentication surface in-house.
+
+Not a flow-controller-contributing blueprint. The state machine that mints the pending-flow record, builds the authorisation redirect, and drives the callback is either the sibling `security-auth-oauth2` blueprint's TAC-1101 (compose the two blueprints, resolve the `authModel` global conflict to Keycloak, and point the oauth2 provider adapter at a Keycloak realm through this blueprint's discovery client and verifier) or a project-authored controller above this blueprint's five TACs. Either path is valid; the blueprint is honest that it contributes the Keycloak-shaped pieces, not the state machine.
+
+Not a session-persistence blueprint. The session-bridge (in opaque-handle mode) injects the session-record store; the reference wiring is in-memory. A project that wants durable sessions composes `persistence-data-sqlite` (or `persistence-data-d1`) and points the store at a table. The blueprint does not commit the storage shape.
+
+Not an MFA blueprint. MFA is the realm's concern; the blueprint delegates. A realm that requires MFA at the sign-in surface is transparent to the mechanism.
+
+## When to reach for it
+
+- The project has, or will run, a Keycloak realm; the ops posture prefers self-hosted identity over hosted-vendor identity.
+- The project needs the Keycloak-specific decisions (JWKS-vs-introspection, client-roles-vs-realm-roles, RP-initiated logout) fixed at the mechanism layer so the project code path is Keycloak-shaped rather than provider-abstract.
+- The project may have another OAuth2 or OIDC issuer alongside Keycloak (a second realm, a corporate issuer the middleware layer above this blueprint routes to) and wants the routing seam visible at one named point.
+- The project wants runtime-verify to actually verify against a real Keycloak container in CI without demanding a cloud tenant.
+- The project's ops team accepts running the Keycloak container as part of the deployment (either as a per-suite container in CI, a shared team-level container, or a production Kubernetes deployment).
+
+## When it does not fit
+
+- The project wants delegated identity but is not committed to one vendor. `security-auth-oauth2` 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 no external IdP and no plan to obtain one, or the ops posture cannot run a Keycloak container. `security-auth-magic-link` is the shape.
+- The project's session-verification requirements need statelessness at scale (no server-side session record). This blueprint supports that (ADR-1204's stateless mode) but the operator has to accept the per-request verification cost on every request; a project that prefers opaque-handle everywhere and can afford the store is on a smoother default.
+
+## What a good outcome looks like
+
+- One realm-config record per configured realm, on the fixed shape, validated at boot.
+- The sign-in ceremony is the same code path across every configured realm; adding a realm is a record write plus a routeFn edit.
+- Every access token either verifies (JWKS mode against a cached JWKS with kid-miss refresh; introspection mode against the RFC 7662 endpoint with optional short-lived cache) or refuses with a stable-coded reason.
+- The browser holds an opaque-handle cookie (opaque-handle mode) or no session cookie at all (stateless mode); provider tokens live server-side (opaque-handle) or are re-verified per request (stateless); nothing on `request.auth` is a Keycloak-minted token.
+- The provider-router seam is one named function; a reviewer inspecting the deployment can see the routing decision in one place.
+- Refresh honours the realm's rotation model; a realm-signalled invalidation revokes the session cleanly.
+- Sign-out clears the project session; the realm record's `providerLogout` flag decides realm-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 cloud-realm smoke AC is `accountBound` and skipped by the runtime-verify runner when credentials are absent; the project-authored TC records the outcome honestly. The local-container smokes run every CI pass without any cloud dependency.
+
+## Operator decisions that remain open after apply
+
+- Which Keycloak realm(s) to configure. The blueprint runs against one realm, two realms, or N realms; the operator picks and declares each on a realm-config record.
+- Where the `clientSecret` per record 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 verification mode per realm (`jwks` or `introspection`). Match the mode to the Keycloak client's configuration; a realm with a mix of client kinds gets one record per kind.
+- The role claim shape per realm (`client-roles` or `realm-roles`). Match to the realm's client configuration; the choice is legible on the record.
+- The session mode per realm (`opaque-handle` or `stateless`). Default is opaque-handle; stateless is opt-in for deployments where a session store is undesirable.
+- The boot posture per realm (`strict`, `deferred`, or `standby`). Default is strict; the operator picks based on deployment shape.
+- The JWKS cache TTL per realm. Default 900 seconds; the operator raises or lowers per the realm's rotation cadence and the project's staleness tolerance.
+- The provider-router routeFn. A single-realm deployment uses the reference constant; a multi-realm or issuer-hand-off deployment writes its own.
+- The Keycloak container tag. The operator pins the currently-supported stable at harness-setup time and upgrades on the vendor's cadence.
+- The `enrichPrincipal` hook. Empty roles and organisationIds arrays are the default (with the raw Keycloak role strings on `roles[]`); a project that maps Keycloak roles onto project-role vocabulary authors the hook and lists the mapping in a project-level ADR.
+- The live cloud-realm smoke. AC-11112-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 12 REQs, 13 USs (34 ACs), 5 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 discovery client, one JWT verifier (JWKS mode), one introspection client (opaque mode), one provider router, one role adapter, and (per the composition choice) either the sibling `security-auth-oauth2` blueprint's flow controller wired to a Keycloak realm or a project-authored flow controller above the five TACs. The reference wiring runs to a small number of files in one package. The Keycloak container is a one-off harness dependency the operator stands up per the local-container asset; runtime-verify against it is free of cloud cost. The live cloud-realm smoke costs the operator credentials on a project-owned Keycloak deployment; that cost is unavoidable and the `accountBound` posture keeps it out of CI.
+
+## Promotion signals to the other siblings
+
+- The project outgrows self-hosting and wants a hosted vendor to run the sign-in surface, credential storage, MFA, and account recovery. Promote to `security-auth-clerk`: supersede ADR-1201 with a project-level ADR pointing at Clerk's authModel; apply `security-auth-clerk`; retire the Keycloak container.
+- The project needs delegated identity that is not vendor-committed (a small project that wants to plug in Google or GitHub without running a realm). Demote to `security-auth-oauth2`: supersede ADR-1201 with a project-level ADR pointing at oauth2's authModel; apply `security-auth-oauth2`.
+- The project's audience needs a passwordless-magic-link posture (regulated environment, no third-party identity dependency). Demote to `security-auth-magic-link`.
+
+## Provider-aware install-design shape (Baz-reshape, restated)
+
+The blueprint stays Keycloak-committed. What the blueprint does NOT do is assume Keycloak is the only issuer the receiving system will ever consult. Two shapes make this explicit:
+
+- The provider-router seam (TAC-1204, ADR-1203) exposes one named point in the request-processing chain where a project's own middleware makes the routing decision. A project with only Keycloak wires the seam to a constant; a project with two Keycloak realms wires the seam to pick between them per request marker; a project with Keycloak alongside another OAuth2 or OIDC issuer above this blueprint's mechanism reach returns the sentinel `notThisIssuer` and the middleware layer above owns the request.
+- The introspection path (REQ-004, TAC-1203) speaks the RFC 7662 shape whether the issuer is Keycloak or another conforming server; a project that has chosen to consult a non-Keycloak issuer at the introspection seam does not need a new vocabulary.
+
+The blueprint refuses to name any specific second issuer, any specific request marker, or any specific dual-provider deployment shape. Those are project-level decisions the operator authors on a project-side ADR whose `related-reqs` cites REQ-005 and ADR-1203.

package/blueprints/security-auth-magic-link/README.md

@@ -0,0 +1,46 @@
+# Auth blueprint (v1.0.0)
+
+The third content blueprint on the rcf-build-lite blueprint mechanism (design brief v2, ratified; Phase 4 of the blueprint programme). Scope: passwordless magic-link sign-in with server-issued opaque cookie sessions, single deployable, pluggable email delivery and pluggable principal registry, targeted at small greenfield rcf-lite projects. Composes with the application-spa blueprint (client half) and the application-api-rest blueprint (server half) by design, contributing one deliberate scope:global conflict on `authModel`.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/security-auth-magic-link
+```
+
+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; `rcf define blueprint remove security-auth-magic-link` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, and the 32 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 11 REQs, 11 USs (37 ACs), 5 TACs, 5 ADRs, all schema-valid against rcf-schemas 0.4.5 and namespaced (`security-auth-magic-link-REQ-001` prefix family; `ADR-501-security-auth-magic-link-model` suffix family) |
+| Email templates | `assets/email-templates/magic-link-email.md` | The text and HTML bodies the routes hand to the adapter for magic-link delivery, with placeholders for base URL, token URL, and expiry window |
+| Stub adapter reference | `assets/email-templates/stub-adapter.md` | The record-only stub the blueprint ships for tests, with the exact call log shape and outcome shape |
+| Principal registry samples | `assets/principal-registry-samples/single-address.md` | The single-address registry implementation for solo-operator deployments |
+| Principal registry samples | `assets/principal-registry-samples/allow-list-file.md` | An allow-list file registry pattern for small teams |
+| Guide | `guide/security-auth-magic-link.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signal for the future auth-oidc blueprint |
+| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-pipeline, observability-essentials) |
+
+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 sign-in flow, the token lifecycle, the session lifecycle, the two pluggable interfaces); 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: authorisation (roles, permissions, tenancy) is a project concern that layers above the session record's principal id, not inside this blueprint; multi-factor authentication is a project concern that layers on top of a resolved session; federated identity (OIDC, SAML) is a future auth-oidc blueprint (see guide 'when it does not fit'); email transport is a project concern behind the pluggable adapter contract; principal registry shape is a project concern behind the pluggable lookup contract.
+
+## The one global decision
+
+ADR-501-security-auth-magic-link-model ships `scope: global` on topic `authModel`. This is the third half of the project-level authentication model; application-spa contributes ADR-205-application-spa-auth-model on the same topic (the client half: cookie-based sessions, 401-redirect posture), application-api-rest contributes ADR-302-application-api-rest-auth-model on the same topic (the server half: four declared auth classes enforced in middleware). Applying any two of the three on one project surfaces the pairing for operator resolution, which is the composition mechanism doing its job. See `docs/topics.md` for the exact strings, the expected resolutions, and the AC id band allocation (security-auth-magic-link owns 3101-3899).
+
+## Quality bar
+
+Passwordless sign-in via emailed one-shot URL; single-use time-limited tokens with a fifteen-minute default expiry and remint-invalidates-predecessors; server-issued opaque handles of at least 24 bytes of entropy with no JWT-shaped payload; Secure HttpOnly SameSite=Lax cookie transport; server-side revocation on sign-out and administrative revoke-all-for-principal; anti-enumeration on the sign-in submission (byte-identical body, identical status, wall-clock timing floor); rate-limited mint and consume endpoints with honest Retry-After; session and token persistence across process restart; structured auth event log with zero secret leakage; pluggable email delivery adapter behind a narrow contract; pluggable principal registry behind a narrow contract. 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 (Set-Cookie inspection, response body byte-comparison, adapter-call enumeration, event-log field scanning). 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 durable store implementation the two managers depend on (security-auth-magic-link-REQ-008); that responsibility is stated as a TAC dependency, not as a smuggled runtime probe.

package/blueprints/security-auth-magic-link/assets/email-templates/magic-link-email.md

@@ -0,0 +1,44 @@
+# Magic-link email template
+
+Two bodies, one subject. The routes compose `{{ signInUrl }}` from the deployment base URL, `/login/verify`, and the minted token; the routes pass `{{ expiryWindow }}` as the token's expiry in a human phrase (default: 'fifteen minutes'). The adapter receives all four fields on every call.
+
+## Subject
+
+```
+Sign in to {{ appName }}
+```
+
+## Text body
+
+```
+Someone (hopefully you) asked to sign in to {{ appName }}.
+
+Follow this link within the next {{ expiryWindow }} to complete the sign-in:
+
+  {{ signInUrl }}
+
+The link is single-use and expires. If you did not request a sign-in, ignore
+this email; the link will do nothing on its own.
+```
+
+## HTML body
+
+```html
+<!doctype html>
+<html>
+  <body>
+    <p>Someone (hopefully you) asked to sign in to {{ appName }}.</p>
+    <p>
+      Follow this link within the next {{ expiryWindow }} to complete the sign-in:
+      <br>
+      <a href="{{ signInUrl }}">{{ signInUrl }}</a>
+    </p>
+    <p>
+      The link is single-use and expires. If you did not request a sign-in,
+      ignore this email; the link will do nothing on its own.
+    </p>
+  </body>
+</html>
+```
+
+Both bodies name the same URL. The plaintext copy is what the email adapter's provider is most likely to render for spam-scoring and preview purposes; keep them in sync.

package/blueprints/security-auth-magic-link/assets/email-templates/stub-adapter.md

@@ -0,0 +1,55 @@
+# Stub email adapter
+
+The blueprint's TAC-504 names a stub-adapter implementation that projects wire into their test harness in place of the real transport. The stub records every outgoing call in memory and resolves the fixed outcome below; nothing leaves the process.
+
+## Interface satisfied
+
+```
+send({ to, subject, textBody, htmlBody })
+  -> Promise<{ ok, providerStatus, providerMessageId, error }>
+```
+
+## Fixed outcome (successful case)
+
+```json
+{
+  "ok": true,
+  "providerStatus": 200,
+  "providerMessageId": "stub",
+  "error": null
+}
+```
+
+## Fixed outcome (failing case)
+
+Constructed by the test with an override:
+
+```json
+{
+  "ok": false,
+  "providerStatus": 502,
+  "providerMessageId": null,
+  "error": "stub configured to fail: <reason>"
+}
+```
+
+## In-memory call log shape
+
+The stub exposes `sends`, an array of every call in the order received:
+
+```json
+[
+  {
+    "to": "operator@example.com",
+    "subject": "Sign in to demo-app",
+    "textBody": "Someone (hopefully you) asked ...",
+    "htmlBody": "<!doctype html>..."
+  }
+]
+```
+
+Tests assert on `sends[0].to`, `sends[0].textBody.includes(signInUrl)`, and `sends.length === 1` per AC-3110-3 and AC-3101-3.
+
+## Do not use in production
+
+The stub is a test surface. Loading the stub in a production build defeats the sign-in flow silently: mint succeeds, the recipient never receives a link, the anti-enumeration budget hides the failure from the response, and only the `adapterSendFailed` event log entry names the problem (and even then, only if a real send would have failed; a stub records success). A project's deployment config forbids the stub adapter's module name in production; see the project's own configuration ADR for the mechanism.

package/blueprints/security-auth-magic-link/assets/principal-registry-samples/allow-list-file.md

@@ -0,0 +1,46 @@
+# Allow-list-file principal registry (project-authored pattern)
+
+A common step past the single-address registry: a static file on disk holding the registered set, one address per line. The blueprint does not ship this implementation, but the pattern below is what most small teams end up with before they need a database.
+
+## Interface satisfied
+
+```
+isRegistered(email) -> Promise<boolean>
+```
+
+## Configuration
+
+The project supplies one field:
+
+```json
+{
+  "registeredEmailsFile": "/etc/app/registered-emails.txt"
+}
+```
+
+## File format
+
+Plain text, one address per line, ignored:
+
+- lines that start with `#` (comments)
+- empty lines
+- surrounding whitespace on each address
+
+Example:
+
+```
+# Registered operators; edit and restart the app to apply.
+operator@example.com
+teammate@example.com
+
+# On-call cover
+oncall@example.com
+```
+
+## Behaviour
+
+The registry reads the file once at start (or reloads on a project-owned signal) and holds the trimmed lowercase set in memory. `isRegistered(email)` returns true when the trimmed lowercase form of `email` is in the set, false otherwise.
+
+## Why the blueprint does not ship it
+
+Two reasons. First, the reload story is project-specific: some projects want a SIGHUP reload, some want a filesystem watcher, some want a restart-required posture. Second, the file location and permissions are project deployment concerns; hardcoding `/etc/app/...` in the blueprint is a WESPA leak of exactly the shape the authoring standard's provenance rule forbids. The blueprint documents the pattern here so a project writing it does not reinvent the shape.

package/blueprints/security-auth-magic-link/assets/principal-registry-samples/single-address.md

@@ -0,0 +1,35 @@
+# Single-address principal registry
+
+The blueprint's TAC-505 ships one registry implementation: a single-address lookup for solo-operator deployments. The project supplies one email string at configuration time; the registry returns true only for that email (compared case-insensitively after trimming whitespace) and false for every other input.
+
+## Interface satisfied
+
+```
+isRegistered(email) -> Promise<boolean>
+```
+
+## Configuration
+
+The project supplies one field:
+
+```json
+{
+  "registeredEmail": "operator@example.com"
+}
+```
+
+## Behaviour table
+
+| Input | Resolved |
+|---|---|
+| `operator@example.com` | `true` |
+| `Operator@Example.COM` | `true` (case-insensitive) |
+| `  operator@example.com ` | `true` (whitespace trimmed) |
+| `other@example.com` | `false` |
+| `""` | `false` |
+| `null` or `undefined` | `false` |
+| `"not-an-email"` | `false` (registry does not validate shape, but no match means false) |
+
+## Why it exists
+
+The rcf-lite tier this blueprint targets includes solo-operator projects (watchpost, personal dashboards, single-tenant admin surfaces). The single-address registry is the smallest useful implementation and demonstrates the boolean-only shape of the contract; projects that scale past one operator write their own allow-list-file or database-lookup implementation, keeping the same interface.

package/blueprints/security-auth-magic-link/blueprint.json

@@ -0,0 +1,45 @@
+{
+  "slug": "security-auth-magic-link",
+  "version": "1.0.0",
+  "category": "security",
+  "contributions": [
+    { "id": "security-auth-magic-link-REQ-001", "kind": "req", "path": "requirements/security-auth-magic-link-req-001.json" },
+    { "id": "security-auth-magic-link-REQ-002", "kind": "req", "path": "requirements/security-auth-magic-link-req-002.json" },
+    { "id": "security-auth-magic-link-REQ-003", "kind": "req", "path": "requirements/security-auth-magic-link-req-003.json" },
+    { "id": "security-auth-magic-link-REQ-004", "kind": "req", "path": "requirements/security-auth-magic-link-req-004.json" },
+    { "id": "security-auth-magic-link-REQ-005", "kind": "req", "path": "requirements/security-auth-magic-link-req-005.json" },
+    { "id": "security-auth-magic-link-REQ-006", "kind": "req", "path": "requirements/security-auth-magic-link-req-006.json" },
+    { "id": "security-auth-magic-link-REQ-007", "kind": "req", "path": "requirements/security-auth-magic-link-req-007.json" },
+    { "id": "security-auth-magic-link-REQ-008", "kind": "req", "path": "requirements/security-auth-magic-link-req-008.json" },
+    { "id": "security-auth-magic-link-REQ-009", "kind": "req", "path": "requirements/security-auth-magic-link-req-009.json" },
+    { "id": "security-auth-magic-link-REQ-010", "kind": "req", "path": "requirements/security-auth-magic-link-req-010.json" },
+    { "id": "security-auth-magic-link-REQ-011", "kind": "req", "path": "requirements/security-auth-magic-link-req-011.json" },
+    { "id": "security-auth-magic-link-US-3101", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3101.json" },
+    { "id": "security-auth-magic-link-US-3102", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3102.json" },
+    { "id": "security-auth-magic-link-US-3103", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3103.json" },
+    { "id": "security-auth-magic-link-US-3104", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3104.json" },
+    { "id": "security-auth-magic-link-US-3105", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3105.json" },
+    { "id": "security-auth-magic-link-US-3106", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3106.json" },
+    { "id": "security-auth-magic-link-US-3107", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3107.json" },
+    { "id": "security-auth-magic-link-US-3108", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3108.json" },
+    { "id": "security-auth-magic-link-US-3109", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3109.json" },
+    { "id": "security-auth-magic-link-US-3110", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3110.json" },
+    { "id": "security-auth-magic-link-US-3111", "kind": "us", "path": "user-stories/security-auth-magic-link-us-3111.json" },
+    { "id": "TAC-501-security-auth-magic-link-manager", "kind": "tac", "path": "tacs/tac-501-security-auth-magic-link-manager.json" },
+    { "id": "TAC-502-security-auth-magic-link-session-manager", "kind": "tac", "path": "tacs/tac-502-security-auth-magic-link-session-manager.json" },
+    { "id": "TAC-503-security-auth-magic-link-login-routes", "kind": "tac", "path": "tacs/tac-503-security-auth-magic-link-login-routes.json" },
+    { "id": "TAC-504-security-auth-magic-link-email-delivery-adapter", "kind": "tac", "path": "tacs/tac-504-security-auth-magic-link-email-delivery-adapter.json" },
+    { "id": "TAC-505-security-auth-magic-link-principal-registry", "kind": "tac", "path": "tacs/tac-505-security-auth-magic-link-principal-registry.json" },
+    {
+      "id": "ADR-501-security-auth-magic-link-model",
+      "kind": "adr",
+      "path": "adrs/adr-501-security-auth-magic-link-model.json",
+      "scope": "global",
+      "topic": "authModel"
+    },
+    { "id": "ADR-502-security-auth-magic-link-token-secrecy", "kind": "adr", "path": "adrs/adr-502-security-auth-magic-link-token-secrecy.json" },
+    { "id": "ADR-503-security-auth-magic-link-anti-enumeration-budget", "kind": "adr", "path": "adrs/adr-503-security-auth-magic-link-anti-enumeration-budget.json" },
+    { "id": "ADR-504-security-auth-magic-link-session-lifecycle", "kind": "adr", "path": "adrs/adr-504-security-auth-magic-link-session-lifecycle.json" },
+    { "id": "ADR-505-security-auth-magic-link-rate-limiting", "kind": "adr", "path": "adrs/adr-505-security-auth-magic-link-rate-limiting.json" }
+  ]
+}

package/blueprints/security-auth-magic-link/contributions/adrs/adr-501-security-auth-magic-link-model.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-501-security-auth-magic-link-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Passwordless magic-link sign-in with server-issued opaque cookie sessions as the project's authentication model",
+  "context": "A project has one authentication model; the client tier, the server tier, and every operator surface must reason against it. The security-auth-magic-link blueprint contributes the third half of the model: how an operator actually gets through the door, and what shape the session takes on the wire once they have. A client-tier blueprint (SPA) and a server-tier blueprint (REST) applied to the same project contribute their own decisions on this topic, and blueprint composition surfaces the pairing at add time for the operator to reconcile into one project-level model. That surfacing is intended.",
+  "decision": "Sign-in is passwordless: the operator submits their email to POST /login, the server mints a single-use time-limited token when the address is a registered principal, and the sign-in URL carrying the token is delivered by a pluggable email adapter. GET /login/verify consumes the token and issues a session. The session is a server-side record; the credential the operator's browser holds is an opaque base64url handle of at least 24 bytes of entropy, transported in a Secure HttpOnly SameSite=Lax cookie. No password field exists on any surface; no JWT-shaped self-describing token is issued on any code path.",
+  "consequences": "The project owns email delivery through the adapter interface and owns the principal registry through the isRegistered contract. Revocation is a server-side delete on the session record; 'sign me out everywhere' is one call. XSS cannot exfiltrate the credential because the handle is HttpOnly. CSRF has a SameSite=Lax floor and the project layers whatever extra token defence the application-spa and application-api-rest halves agree on. Composing with a client-tier or server-tier blueprint deliberately conflicts on this topic; the expected resolution is one project-level ADR that fixes the credential shape (this ADR's opaque cookie session), maps it onto the server's auth classes (the application-api-rest blueprint's four classes if applied), and specifies how the client half handles session expiry (the application-spa blueprint's cookie session and 401-redirect posture if applied).",
+  "alternativesConsidered": [
+    {
+      "name": "Password + hashed store",
+      "summary": "Operators register a password, the server stores a hash, the sign-in form takes email plus password.",
+      "reasonNotChosen": "The blueprint owns the sign-in flow; password handling brings hashing choice, rotation policy, breach-check integration, and reset flows every project has to build correctly to be safe. For the rcf-lite tier a passwordless flow removes the credential the operator must remember and keeps the secret material server-owned and short-lived."
+    },
+    {
+      "name": "Federated OIDC through an external identity provider",
+      "summary": "Delegate authentication to a Keycloak-local or hosted identity provider through the OIDC authorization-code flow.",
+      "reasonNotChosen": "Valid where an external IdP is a project requirement (multi-tenant identity, role management, group memberships). For a small greenfield rcf-lite project the container plus realm configuration cost outweighs the benefit; that model belongs in a future 'auth-oidc' blueprint aimed at bigger projects. See guide 'when it does not fit' for the promotion signal."
+    },
+    {
+      "name": "Signed JWT bearer tokens in a client-readable header or storage",
+      "summary": "Issue a self-describing bearer on sign-in that the client attaches to every request.",
+      "reasonNotChosen": "Script-readable credentials fail security-auth-magic-link-REQ-004's transport floor; opaque handle plus server record is cheaper to revoke and safer under XSS. Projects that need bearer transport (native clients, service-to-service) layer a project-level ADR superseding the transport half."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/adrs/adr-502-security-auth-magic-link-token-secrecy.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-502-security-auth-magic-link-token-secrecy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Sign-in tokens and session handles are opaque secrets that never appear in logs or on client-readable surfaces",
+  "context": "Two credential-shaped values exist inside the auth flow: the sign-in token (short-lived, single-use) and the session handle (long-lived, revocable). Both are secrets. Either one leaking into a log line, a metric label, an error message, or a client-visible response body reintroduces the class of failures the flow's design forbids. The project's observability stack cannot be trusted to redact after the fact; the discipline has to be enforced at emit time.",
+  "decision": "Sign-in tokens and session handles are opaque strings the auth layer holds only long enough to complete their operation. The token secret exists as plaintext only as the return of magicLinkManager.mint and the argument to magicLinkManager.consume; the session handle exists as plaintext only inside the cookie value the response sets and the cookie header the next request presents. Neither value appears in any structured-log field, any metric label, any span attribute, any error message body, or any response body other than the Set-Cookie header for the session handle. The magic-link event log fields carry the principal id, the expiresAt timestamp, and the outcome; the session event log fields carry the principal id, the outcome, and where relevant the reason for invalidation. Nothing else.",
+  "consequences": "The events log is safe to ship to third-party observability providers because it holds no credential material; a log store breach is not a session-takeover breach. Providers that need per-session correlation for debugging must derive their correlation id from something other than the handle (a request id is the intended surface). Error messages surfaced to the operator confirm success or failure but never quote credential material back at them.",
+  "alternativesConsidered": [
+    {
+      "name": "Log token and handle values under a redaction rule at the log shipper",
+      "summary": "Emit secrets structured and rely on a downstream redactor.",
+      "reasonNotChosen": "Redactors miss cases (new field, misspelled field, escaped value), and the log is already on disk by the time the redactor runs. Not-emitting-in-the-first-place is the only reliable posture."
+    },
+    {
+      "name": "Emit hashed token and handle values",
+      "summary": "Log a stable hash so investigations can correlate without exposing the plaintext.",
+      "reasonNotChosen": "A hashed handle still lets an attacker with log access confirm 'this handle is the handle for that principal', which is enough for correlation attacks. The request id already provides the correlation surface without leaking anything."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/adrs/adr-503-security-auth-magic-link-anti-enumeration-budget.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-503-security-auth-magic-link-anti-enumeration-budget",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "POST /login enforces a uniform response body, status, and wall-clock timing floor against enumeration",
+  "context": "A sign-in submission handler that differentiates its behaviour on the basis of principal registration hands attackers a free enumeration oracle: an attacker with a wordlist harvests the registered set by watching for any observable difference between 'this address is registered' and 'this address is not'. The three surfaces that leak this signal are the response body, the response status, and the wall-clock latency; a defence has to close all three.",
+  "decision": "POST /login returns byte-identical response bodies and identical HTTP statuses (200) across registered, unregistered, malformed, and empty submissions that are not rate-limited. Rate-limited responses (429) are also identical across principals. A per-handler anti-enumeration budget enforces a wall-clock floor on the response: the handler never returns earlier than the budget, regardless of code path. The budget is a configurable millisecond value with a default of 800; the default is set to comfortably dominate the slowest legitimate branch (mint plus adapter send on a typical email provider). Adapter-send failures are caught inside the budget and surfaced only via the event log, never via the response.",
+  "consequences": "The endpoint is not an enumeration oracle: a submission for a random address looks exactly like a submission for the operator's actual address. Legitimate operator retries pay the budget as latency every time; the budget is deliberately noticeable to raise the cost of high-volume mint sprays. The event log is the only surface where the registered-versus-unregistered distinction is observable, and the log is a server-owned surface.",
+  "alternativesConsidered": [
+    {
+      "name": "Different bodies with the same status and timing",
+      "summary": "Return a body that names the failure reason for unregistered submissions but keeps the timing floor uniform.",
+      "reasonNotChosen": "The body is exactly the enumeration signal the design closes; keeping timing uniform while leaking the answer in the body defeats the point."
+    },
+    {
+      "name": "Rate-limit only, no timing floor",
+      "summary": "Rely on a tight rate limit to keep enumeration expensive without introducing latency for legitimate operators.",
+      "reasonNotChosen": "Rate limits per client key are worked around by attackers rotating client keys (residential proxies, botnets). The timing floor is uniform per request and does not depend on the attacker's shape."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/adrs/adr-504-security-auth-magic-link-session-lifecycle.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-504-security-auth-magic-link-session-lifecycle",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Sessions carry a sliding idle window, a fixed absolute lifetime, and server-side revocation as the only invalidation truth",
+  "context": "A session has three lifetime axes: how long it can be idle before it invalidates, how long it can live in absolute wall-clock terms regardless of activity, and how quickly a revoke can end it on demand. Every axis has to be a server-side decision because the client cannot be trusted to end its own session honestly; a session that only ends when the browser forgets its cookie is a session an attacker with the cookie can still ride.",
+  "decision": "Every session record carries a lastSeenAt timestamp and an absoluteExpiresAt timestamp. The sliding idle window is fifteen minutes by default (900000 ms); validateSession invalidates any record whose lastSeenAt is older than the idle window and refreshes lastSeenAt on every valid request. The absolute lifetime is thirty days by default (2592000000 ms); validateSession invalidates any record whose absoluteExpiresAt is in the past, regardless of activity. invalidateSession(handle) deletes the record; revokeAllForPrincipal(principalId) deletes every record for the principal in one call. Both defaults are constructor options; project overrides update the ADR's consequences in a project-level ADR.",
+  "consequences": "A stolen cookie has at most fifteen minutes of inactivity before it stops working; if the operator uses the session actively, the sliding window can extend to the absolute ceiling of thirty days. 'Sign me out everywhere' is one revokeAllForPrincipal call. Sessions survive process restart because the store is durable; the idle clock counts wall-clock elapsed during a restart against the window, so a long-stopped process does not falsely refresh sessions. Projects with tighter operator-lifetime needs (regulated environments, shared devices) supersede the defaults in a project-level ADR.",
+  "alternativesConsidered": [
+    {
+      "name": "Absolute expiry only, no sliding window",
+      "summary": "One expiry ceiling per session, no per-request refresh.",
+      "reasonNotChosen": "Every long-lived operator hits the ceiling mid-work and pays a forced sign-in. The sliding window keeps active operators signed in without extending the absolute ceiling."
+    },
+    {
+      "name": "Sliding window only, no absolute ceiling",
+      "summary": "Sessions live forever as long as the operator uses them.",
+      "reasonNotChosen": "Fails 'sessions rotate on a bounded schedule' expectations; an absolute ceiling caps blast-radius for a session record whose creation the operator no longer remembers."
+    },
+    {
+      "name": "Client-side expiry (the cookie's Max-Age carries the truth)",
+      "summary": "Rely on the browser to stop presenting an expired cookie.",
+      "reasonNotChosen": "The server has to enforce every session decision because the client cannot be trusted; a cookie's Max-Age helps browser hygiene but is never the invalidation surface."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/adrs/adr-505-security-auth-magic-link-rate-limiting.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-505-security-auth-magic-link-rate-limiting",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Per-endpoint rate limits with honest Retry-After on the sign-in mint and consume paths",
+  "context": "Two auth endpoints attract abuse. POST /login is a mint endpoint that an unbounded caller turns into an email-flooding pipeline aimed at the operator's own inbox. GET /login/verify is a consume endpoint that an unbounded caller turns into a brute-force pipeline against the token space. Both need ceilings low enough to make the abuse economically uninteresting without tripping on legitimate operator retry patterns.",
+  "decision": "POST /login is rate-limited to five requests per minute per client key by default. GET /login/verify is rate-limited to twenty requests per minute per client key by default. Both endpoints emit HTTP 429 on breach with a Retry-After header carrying a positive integer or a valid HTTP-date at or after the request time. 429 responses do not disclose registration state; the body is generic and identical across principals. Ceilings and windows are project-configurable options on the routes composition; overrides update the numbers stated in the project-level ADR that supersedes rate posture. The client key derivation defaults to the request's client IP (via the framework's rate-limit plugin); projects behind a trusted proxy configure the plugin to derive from a forwarded-for header instead.",
+  "consequences": "Legitimate operator sign-in retries stay well under the ceiling. A mint spray is stopped inside the first minute per client key; a token-guessing sweep is stopped inside the same window. Retry-After is honest, so well-behaved clients back off predictably; badly behaved clients are shed by the plugin without cost to the auth code. Projects with heavier legitimate load (shared IP behind NAT, corporate proxy) raise the ceilings and state the trade in a project-level ADR.",
+  "alternativesConsidered": [
+    {
+      "name": "Global rate limit only",
+      "summary": "One ceiling across the whole service.",
+      "reasonNotChosen": "A global limit trades a legitimate operator's sign-in against every other endpoint; the sign-in endpoints have their own abuse pattern and deserve their own ceiling."
+    },
+    {
+      "name": "No rate limit; rely on external WAF",
+      "summary": "Assume the deploy target puts a WAF in front of the service.",
+      "reasonNotChosen": "The blueprint targets small greenfield deployments where a WAF is not a given; making rate-limits the service's own responsibility means the floor holds without external infrastructure."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}