rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Passwordless sign-in via emailed single-use magic link",
+  "description": "The application authenticates operators through a passwordless sign-in flow: the operator submits their email address to a POST /login endpoint; the server, when the address is a registered principal, mints a single-use token, composes a sign-in URL carrying that token, and sends the URL to the address via the configured email delivery adapter; the operator clicks the URL and lands on GET /login/verify, which consumes the token and issues a server-side session. No password field exists anywhere on the surface.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Passwords are a persistent liability: they leak, they get reused, they force the project into hashing, rotation, and reset flows that add surface without adding safety. A magic-link flow removes the credential the operator must remember, keeps the secret material server-owned and short-lived, and fits a single-deployable rcf-lite project without an external identity provider.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:01-sign-in-flow"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/requirements/security-auth-magic-link-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Sign-in tokens are single-use, time-limited, and superseded by the next mint",
+  "description": "Every sign-in token minted by the magic-link flow is consumable exactly once. A consumed token cannot be exchanged for a session a second time; an unconsumed token past its expiry cannot be exchanged either. When a fresh token is minted for a principal that has an outstanding unconsumed token, the outstanding token is invalidated at mint time so only the newest token can consume. Token expiry is bounded by a project-configurable window whose default the blueprint fixes at fifteen minutes.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A reusable token is a stolen-link problem waiting to happen; a token with no ceiling on lifetime is a permanent bearer credential mailed in plaintext. Bounding both dimensions and invalidating predecessors on remint means an intercepted or archived link stops working the moment the operator asks for another one.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:02-token-lifecycle"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/requirements/security-auth-magic-link-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Sessions are server-issued opaque handles, never signed client-readable claims",
+  "description": "A successful token consumption issues a session by writing a server-side record and returning an opaque handle to the client. The handle is base64url of at least 24 bytes of cryptographically random entropy; it carries no identity claim, no scope claim, no signed payload, and no data the client can decode. Identity, scope, and expiry are looked up server-side from the record on every request. No JWT-shaped token, no self-describing bearer, and no client-decodable envelope is issued on any authenticated code path.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A signed client-readable token turns every session into a JWT-shaped design problem: key rotation, revocation lists, clock skew, algorithm-confusion attacks. An opaque handle plus a server-side record makes revocation a delete, makes scope changes atomic, and keeps the secret material where the operator can actually see it.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:03-session-shape"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/requirements/security-auth-magic-link-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Session handles are carried in a Secure, HttpOnly, SameSite cookie",
+  "description": "The session handle is transported to the browser as a cookie with Secure, HttpOnly, and SameSite=Lax set on every issue and every refresh. The cookie is never readable by client-side script. The cookie's Path defaults to '/', its Domain is unset so the browser scopes it to the origin, and its Max-Age reflects the session's absolute expiry. Non-browser clients that authenticate via bearer header are out of scope for this requirement; projects wanting a bearer transport in addition compose a project-level ADR that supersedes the transport half.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A script-readable session handle is an XSS-to-account-takeover pipeline; a permissive SameSite is a CSRF pipeline. Setting all three flags at the transport layer is the cheapest way to keep the credential out of the DOM and out of the cross-site request path.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:04-session-transport"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/requirements/security-auth-magic-link-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Server-side session revocation on sign-out and administratively for a principal",
+  "description": "POST /logout invalidates the server-side session record for the presented handle and clears the cookie on the response. After sign-out, the handle cannot resurrect an authenticated request. An administrative revoke operation is exposed on the session manager surface that invalidates every unexpired session for a given principal in one call; sign-in flows that follow the revoke issue new records with fresh handles. Client-side cookie clearing alone is not the revocation mechanism.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A session that only ends when the browser forgets its cookie is a session an attacker with the cookie can still ride. Making revocation a server-side delete on a stored record is what makes 'sign me out everywhere' honest.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:05-session-revocation"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/requirements/security-auth-magic-link-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Sign-in submission is anti-enumeration: identical body, status, and timing for every input",
+  "description": "The POST /login handler returns the same response body, the same HTTP status, and the same wall-clock latency floor regardless of whether the submitted email is a registered principal, an unregistered address, a malformed string, or an empty value. The response never confirms or denies registration. The timing floor is set by a per-handler anti-enumeration budget that dominates the slowest legitimate branch (mint plus adapter send). Registered-branch work runs behind the same delay ceiling as unregistered-branch work.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "A login endpoint that differentiates its responses on the basis of principal registration is a free enumeration oracle; an attacker with a wordlist harvests the registered set without ever guessing a password. Uniform body, uniform status, and uniform timing collapse the oracle.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:06-anti-enumeration"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Rate limits on the sign-in mint and consume endpoints",
+  "description": "POST /login and GET /login/verify are rate limited independently. The mint endpoint's ceiling is tight enough to make magic-link flooding unattractive and loose enough that a legitimate operator retry does not trip it; the blueprint defaults to five mints per minute per client key. The consume endpoint's ceiling defends against token-guessing sweeps; the blueprint defaults to twenty attempts per minute per client key. Both endpoints emit Retry-After with an honest wait window on 429 responses. Rate-limit rejections do not reveal registration state.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "An unbounded mint endpoint is an email-bombing pipeline aimed at the operator's own inbox; an unbounded consume endpoint is a brute-force pipeline aimed at the token space. Class-appropriate limits with honest Retry-After close both without asking the operator to configure a WAF.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:07-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-008",
+  "prdId": "PRD-001",
+  "title": "Sessions and tokens survive process restart",
+  "description": "The session store and the sign-in token store are backed by durable storage that survives a process restart. A process restart of the authenticating service does not invalidate outstanding sessions, does not reset idle-expiry clocks, and does not consume-then-lose in-flight sign-in tokens. The blueprint does not fix the storage engine; the project supplies the durable store through the session-manager and magic-link-manager interfaces.",
+  "category": "nonFunctional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "In-memory sessions turn every deploy into a forced logout for every operator, which teaches the operator to distrust the sign-out button when it does happen. Persistent storage is the difference between authentication that outlives the process and authentication that pretends to.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:08-persistence"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-009",
+  "prdId": "PRD-001",
+  "title": "Structured auth event log with zero secret leakage",
+  "description": "Every material auth event emits one structured log entry: sign-in requested, magic link minted, magic link sent, magic link consumed, session issued, session refreshed, session invalidated, session revoked, rate-limit tripped, adapter-send failed. Each entry carries at minimum an event name, a UTC timestamp, an outcome, and where applicable a principal id and a request id. Token secrets, session handles, and email-delivery-provider api keys never appear in any field of any log entry.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "An unlogged auth surface is a black box the first time it misfires; a logged auth surface that quotes tokens is the same black box plus a smoking gun in the log store. Naming the event set and forbidding secret quoting means the log is useful in an incident without becoming an incident itself.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:09-observability"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-010",
+  "prdId": "PRD-001",
+  "title": "Email delivery is a pluggable adapter behind a fixed contract",
+  "description": "The blueprint owns a narrow email-delivery-adapter interface with a single send({ to, subject, textBody, htmlBody }) method returning a Promise resolving to a normalised outcome ({ ok, providerStatus, providerMessageId, error }). The project supplies the transport (SMTP, Resend, SES, a stub for tests). The magic-link routes call only the adapter interface; provider-specific fields, credentials, and rate-limit semantics never appear in the routes or the managers. Adapter-send failures are recorded on the event log and swallowed for the response body under the anti-enumeration budget.",
+  "category": "technical",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Hard-coding a delivery provider ties the blueprint to a business decision the project owns; hard-coding provider errors into the response body reintroduces the enumeration oracle the anti-enumeration requirement closes. A narrow contract lets the project swap providers without touching auth code.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:10-email-adapter"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/requirements/security-auth-magic-link-req-011.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-magic-link-REQ-011",
+  "prdId": "PRD-001",
+  "title": "Principal registry is pluggable behind a fixed lookup contract",
+  "description": "The blueprint owns a narrow principal-registry interface with a single isRegistered(email) method returning a Promise resolving to a boolean. The project supplies the registry implementation: a single-address constant for solo-operator deployments, a static allow-list file for small teams, or a database lookup for multi-tenant projects. The magic-link routes call only the registry interface and receive nothing from it except the boolean; principal roles, quotas, and identity metadata are project concerns that layer above this contract, not inside it.",
+  "category": "technical",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "The security-auth-magic-link blueprint's opinion is on the flow, not on who counts as a principal. Fixing the registry answer in the blueprint would fight every project that scales past its assumed shape; narrowing the contract to a boolean keeps the flow generic while letting the project own the truth.",
+  "tags": [
+    "blueprint:security-auth-magic-link",
+    "category:11-principal-registry"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/tacs/tac-501-security-auth-magic-link-manager.json

@@ -0,0 +1,45 @@
+{
+  "tacId": "TAC-501-security-auth-magic-link-manager",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Magic-link manager",
+  "purpose": "Owns the mint and consume semantics of the sign-in token: entropy source, expiry ceiling, single-use enforcement, invalidation of predecessors on remint, and event emission for the mint and consume moments. The token secret exists as plaintext only as the return value of mint and the argument to consume; nowhere else on the surface holds it.",
+  "responsibilities": [
+    "Mint a fresh token for a submitted principal with at least 24 bytes of cryptographic entropy, returning { token, expiresAt } (AC-3101-3, AC-3102-3).",
+    "Invalidate every prior unconsumed token for the principal at mint time so the newest token is the only one that can consume (AC-3102-4).",
+    "Consume a presented token exactly once, resolving to a principal id on success and to a failure without side effects on repeat, expiry, or unknown (AC-3102-1, AC-3102-2).",
+    "Never emit the token secret in any event field; emit magicLinkMinted with the principal id and expiresAt only (AC-3109-2, AC-3109-3).",
+    "Persist unconsumed tokens through the store interface so a process restart does not invalidate them (AC-3108-2)."
+  ],
+  "internalStructure": "One stateless manager class with an injected store; the store owns durability and the manager owns semantics. The token value is base64url of 32 random bytes generated via node:crypto.randomBytes; expiryMs defaults to 900000 (fifteen minutes) and is a constructor option.",
+  "interfaces": [
+    {
+      "name": "store",
+      "kind": "read-write-api",
+      "description": "Project-supplied durable store implementing invalidatePriorMagicLinkTokens(email), insertMagicLinkToken({ token, email, expiresAt }), and consumeMagicLinkToken(token) returning the record or null."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, principalId, outcome, at, ... } for magicLinkMinted and magicLinkConsumed; never invoked with the token secret."
+    },
+    {
+      "name": "now",
+      "kind": "clock",
+      "description": "Injectable millisecond clock for expiry arithmetic (test surface)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Session manager",
+      "kind": "tac",
+      "tacId": "TAC-502-security-auth-magic-link-session-manager",
+      "description": "Downstream consumer of a successful consume: converts the resolved principal id into an issued session record."
+    }
+  ],
+  "tradeoffs": "The manager holds no state of its own; every read and write goes through the store. That trade means every operation is a database round trip, which is honest for a persistence-first design and keeps restart continuity free. Projects that want in-memory token issuance for tests supply an in-memory store implementation of the same interface.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/tacs/tac-502-security-auth-magic-link-session-manager.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-502-security-auth-magic-link-session-manager",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Session manager",
+  "purpose": "Owns the shape and lifecycle of the server-side session record: opaque high-entropy handle generation, idle-sliding expiry, absolute expiry ceiling, per-request refresh, per-handle invalidation, and administrative revoke-by-principal. The handle is the credential; the record is the truth.",
+  "responsibilities": [
+    "Issue a session by inserting a record and returning { handle, expiresAt } where handle is base64url of at least 24 bytes of entropy (AC-3103-1, AC-3103-2).",
+    "Validate a presented handle by lookup, applying the sliding idle window and the fixed absolute expiry (AC-3105-2).",
+    "Refresh the idle-expiry clock on every validated request without changing the handle value.",
+    "Invalidate a session by handle in one call (invalidateSession) and every session for a principal in one call (revokeAllForPrincipal) (AC-3105-1, AC-3105-3).",
+    "Guarantee handles carry no encoded payload: no dot-separated segments, no principal id, no expiry, no scope in the string (AC-3103-2, AC-3103-3).",
+    "Emit sessionIssued, sessionRefreshed, sessionInvalidated, and sessionRevoked events without quoting the handle value (AC-3109-1, AC-3109-2)."
+  ],
+  "internalStructure": "One stateless manager class with an injected store; the store owns durability and the manager owns lifecycle rules. The default idle window is 900000 ms (fifteen minutes); the default absolute lifetime is 2592000000 ms (thirty days). Both are constructor options.",
+  "interfaces": [
+    {
+      "name": "store",
+      "kind": "read-write-api",
+      "description": "Project-supplied durable store implementing insertSession(record), findSession(handle), refreshSession(handle, lastSeenAt), deleteSession(handle), and deleteSessionsForPrincipal(principalId)."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, principalId, outcome, at, ... } for the four session events; never invoked with the handle value."
+    },
+    {
+      "name": "now",
+      "kind": "clock",
+      "description": "Injectable millisecond clock for expiry arithmetic."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Login routes",
+      "kind": "tac",
+      "tacId": "TAC-503-security-auth-magic-link-login-routes",
+      "description": "The routes issue sessions on token consume and clear them on sign-out; the manager's methods are what the routes call."
+    }
+  ],
+  "tradeoffs": "The 900000 / 2592000000 default pair prioritises operator convenience over aggressive session rotation; projects with tighter idle needs or shorter absolute lifetimes override the constructor options and update the ADR's consequences to reflect the change. Sessions survive process restart because the store is durable; a project that supplies an in-memory store implementation trades restart continuity for test speed and states the trade in its own ADR.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/tacs/tac-503-security-auth-magic-link-login-routes.json

@@ -0,0 +1,76 @@
+{
+  "tacId": "TAC-503-security-auth-magic-link-login-routes",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Login routes",
+  "purpose": "Owns the HTTP surface of the sign-in flow: the GET /login form page, the POST /login submission handler, the GET /login/verify consume handler, and the POST /logout handler. The routes compose the magic-link manager, the session manager, the email delivery adapter, and the principal registry into one HTTP-shaped orchestration; anti-enumeration timing and per-route rate-limit configuration live here.",
+  "responsibilities": [
+    "Serve GET /login as a page with exactly one email input and no password input (AC-3101-1).",
+    "Accept POST /login with an application/x-www-form-urlencoded email field and return a 200 with a generic body (AC-3101-2, AC-3106-1, AC-3106-2).",
+    "Enforce an anti-enumeration budget on POST /login so no response returns earlier than the configured wall-clock floor and no branch's outcome affects the observable timing (AC-3106-3).",
+    "Configure per-route rate limits on POST /login (default five per minute per client key) and on GET /login/verify (default twenty per minute per client key), emitting 429 with Retry-After on breach (AC-3107-1, AC-3107-2, AC-3107-4).",
+    "On registered submissions, call the magic-link manager to mint a token, compose the sign-in URL from the deployment base URL, and hand the URL to the email delivery adapter (AC-3101-3).",
+    "On GET /login/verify with a valid unconsumed unexpired token, call the session manager to issue a session, set the session cookie with Secure, HttpOnly, and SameSite=Lax, and redirect to the configured post-sign-in route (AC-3101-4, AC-3104-1, AC-3104-2, AC-3104-3).",
+    "On GET /login/verify with any other token value, return a 401 with a generic sign-in-failed body and no Set-Cookie (AC-3101-5).",
+    "On POST /logout, call the session manager to invalidate the presented handle and return a Set-Cookie that clears the session cookie (AC-3105-1, AC-3105-2)."
+  ],
+  "internalStructure": "One routes module registered onto the project's HTTP framework instance; the module receives its collaborators (magic-link manager, session manager, adapter, registry) as constructor arguments. The anti-enumeration budget is an injected constant with a default of 800 ms; per-route rate limits are configured on the framework's rate-limit plugin, not implemented in the module.",
+  "interfaces": [
+    {
+      "name": "app",
+      "kind": "framework-instance",
+      "description": "The project's HTTP framework instance the routes are registered onto; the framework must expose a per-route rate-limit configuration surface."
+    },
+    {
+      "name": "magicLinks",
+      "kind": "collaborator",
+      "description": "TAC-501 instance; the routes call mint and consume through it."
+    },
+    {
+      "name": "sessions",
+      "kind": "collaborator",
+      "description": "TAC-502 instance; the routes call issueSession, invalidateSession, and cookie helpers through it."
+    },
+    {
+      "name": "adapter",
+      "kind": "collaborator",
+      "description": "TAC-504 instance; the routes call adapter.send through it."
+    },
+    {
+      "name": "registry",
+      "kind": "collaborator",
+      "description": "TAC-505 instance; the routes call registry.isRegistered through it and consume only the boolean result."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Magic-link manager",
+      "kind": "tac",
+      "tacId": "TAC-501-security-auth-magic-link-manager",
+      "description": "Provides mint and consume semantics."
+    },
+    {
+      "name": "Session manager",
+      "kind": "tac",
+      "tacId": "TAC-502-security-auth-magic-link-session-manager",
+      "description": "Provides session issue, invalidate, and cookie shape."
+    },
+    {
+      "name": "Email delivery adapter",
+      "kind": "tac",
+      "tacId": "TAC-504-security-auth-magic-link-email-delivery-adapter",
+      "description": "Provides the send method the routes call."
+    },
+    {
+      "name": "Principal registry",
+      "kind": "tac",
+      "tacId": "TAC-505-security-auth-magic-link-principal-registry",
+      "description": "Provides isRegistered."
+    }
+  ],
+  "tradeoffs": "Rate-limit ceilings and the anti-enumeration budget are conservative defaults that make operator retry cheap and abuse expensive; a project with a heavier legitimate load overrides the ceilings and states the trade in its own ADR. The routes are the only auth-shaped HTTP surface the blueprint ships; projects wanting a bearer-token flow instead layer a project-authored ADR superseding auth-model and provide their own routes.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/tacs/tac-504-security-auth-magic-link-email-delivery-adapter.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-504-security-auth-magic-link-email-delivery-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Email delivery adapter",
+  "purpose": "Names the narrow interface the auth flow uses to hand a composed sign-in URL to an external email transport, and specifies the outcome shape returned. Provider selection, credential handling, and provider-specific error semantics live inside project-authored implementations of this interface; nothing on the auth routes or the managers reaches around the interface.",
+  "responsibilities": [
+    "Declare the send({ to, subject, textBody, htmlBody }) method as the sole auth-facing surface and { ok, providerStatus, providerMessageId, error } as the sole returned shape (AC-3110-1).",
+    "Ship one stub adapter implementation that resolves { ok: true, providerStatus: 200, providerMessageId: 'stub' } and records outgoing calls in memory, for tests and dry runs (AC-3110-3).",
+    "Route send failures to the auth event log via an adapterSendFailed entry without changing the POST /login response body or status (AC-3110-2, AC-3109-1)."
+  ],
+  "internalStructure": "One JSDoc-typed interface declaration in the contract file and one stub-implementation module; provider adapters (SMTP, Resend, SES) are project-authored modules that satisfy the interface. The routes hold an adapter reference passed at composition time and call adapter.send directly.",
+  "interfaces": [
+    {
+      "name": "send",
+      "kind": "async-method",
+      "description": "send({ to, subject, textBody, htmlBody }) -> Promise<{ ok, providerStatus, providerMessageId, error }>; the sole method the auth code calls on the adapter."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "Fixing the return shape means every provider adapter has to normalise its own vocabulary (provider status codes, provider message ids) into the four declared fields; that is the cost of keeping the auth code provider-neutral. Projects that need richer provider observability wire it on the provider side of the interface and mirror the salient fields onto the adapterSendFailed event outcome.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/security-auth-magic-link/contributions/tacs/tac-505-security-auth-magic-link-principal-registry.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-505-security-auth-magic-link-principal-registry",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Principal registry",
+  "purpose": "Names the narrow interface the auth flow uses to ask 'is this address registered?' and specifies that the answer is a boolean and nothing else. Principal roles, quotas, tenancy, and identity metadata are project concerns layered above this interface, not inside it.",
+  "responsibilities": [
+    "Declare the isRegistered(email) method as the sole auth-facing surface and boolean as the sole returned type (AC-3111-1).",
+    "Ship one single-address registry implementation that reads one email from configuration and returns true only for that email (AC-3111-3).",
+    "Guarantee, at the interface level, that the response to a submission is uniform across true and false answers because the boolean never surfaces in the response body, status, or Content-Type (AC-3111-2)."
+  ],
+  "internalStructure": "One JSDoc-typed interface declaration in the contract file and one single-address-implementation module. Multi-principal registries (allow-list file, database lookup, external identity provider) are project-authored modules that satisfy the interface.",
+  "interfaces": [
+    {
+      "name": "isRegistered",
+      "kind": "async-method",
+      "description": "isRegistered(email) -> Promise<boolean>; the sole method the auth code calls on the registry."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "Narrowing the answer to a boolean forbids the registry from returning richer information about the principal on the sign-in path; that is deliberate, because richer information on the sign-in path is exactly what makes an enumeration oracle. Projects that need identity metadata for authorisation load it after session issue, keyed by the principal id from the session record.",
+  "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-3101.json

@@ -0,0 +1,64 @@
+{
+  "usId": "security-auth-magic-link-US-3101",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Operator signs in by receiving a one-shot magic link in their inbox",
+  "asA": "operator with a registered email address and no memorised password",
+  "iWant": "to submit my address to a sign-in form and receive a single URL that signs me in when I click it",
+  "soThat": "no password exists anywhere for me to lose, reuse, or leak",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3101-1",
+      "description": "GET /login renders a form with a single email field and a submit control. No password field is present anywhere on the page.",
+      "given": "the operator navigates to /login",
+      "when": "the page renders",
+      "then": "the response body contains an input with type='email' and name='email', and no input with type='password' or autocomplete='current-password'",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3101-2",
+      "description": "POST /login accepts application/x-www-form-urlencoded with an email field and returns a 200 response confirming that if the address is registered a link has been sent.",
+      "given": "the operator submits the form with a valid email string",
+      "when": "the POST /login handler runs",
+      "then": "the response status is 200 and the body confirms that a link will arrive if the address is registered, without confirming or denying that this address is registered",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3101-3",
+      "description": "A submission for a registered address causes exactly one email to be dispatched via the configured adapter, carrying a URL that resolves to GET /login/verify on this deployment with the minted token as the sole query parameter.",
+      "given": "a registered principal submits the form",
+      "when": "the handler completes",
+      "then": "the email-delivery-adapter.send call fires exactly once with a body containing a URL whose path is /login/verify and whose only query parameter carries the token",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3101-4",
+      "description": "Following the emailed URL to GET /login/verify with a valid unconsumed unexpired token issues a session and redirects the operator to the configured post-sign-in landing route.",
+      "given": "the operator follows the emailed URL within the token's validity window",
+      "when": "GET /login/verify runs",
+      "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-3101-5",
+      "description": "GET /login/verify with a missing, malformed, unknown, expired, or already-consumed token returns a 401 with a generic sign-in-failed response and no session issue.",
+      "given": "GET /login/verify is called with any token value that does not resolve to a valid unconsumed unexpired record",
+      "when": "the handler runs",
+      "then": "the response status is 401, no Set-Cookie is emitted, and the response body reveals nothing about which failure class the token fell into",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-501-security-auth-magic-link-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-3102.json

@@ -0,0 +1,54 @@
+{
+  "usId": "security-auth-magic-link-US-3102",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-in tokens consume exactly once, expire on a bounded clock, and are superseded on remint",
+  "asA": "operator whose emailed link might be intercepted, archived, or replayed",
+  "iWant": "each link to work exactly one time within a short window and to become useless the moment I ask for a fresh link",
+  "soThat": "a stolen or forwarded URL stops mattering as soon as I have moved past it",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3102-1",
+      "description": "A token consumed by GET /login/verify cannot be consumed a second time; a repeat call with the same token returns 401 without issuing a session.",
+      "given": "a token has been consumed once, issuing a session",
+      "when": "GET /login/verify is called again with the same token value",
+      "then": "the response status is 401 and no Set-Cookie header is emitted",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3102-2",
+      "description": "A token past its expiry cannot be consumed; GET /login/verify after the expiry window returns 401 without issuing a session.",
+      "given": "a valid unconsumed token whose expiresAt is now in the past",
+      "when": "GET /login/verify is called with that token",
+      "then": "the response status is 401 and no Set-Cookie header is emitted",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3102-3",
+      "description": "The default token expiry window is fifteen minutes; the window is a project-configurable option on the magic-link manager and its effective value is enumerable at runtime.",
+      "given": "a token is minted without a project override",
+      "when": "the manager records the expiry",
+      "then": "the recorded expiresAt is fifteen minutes after the mint clock; when a project supplies expiryMs the recorded expiry matches the override",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3102-4",
+      "description": "Minting a fresh token for a principal invalidates every prior unconsumed token for that principal; the previous URL cannot be exchanged after remint.",
+      "given": "a principal has an unconsumed token T1 and requests a fresh sign-in link, minting T2",
+      "when": "GET /login/verify is called with T1",
+      "then": "the response status is 401 and no Set-Cookie header is emitted",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-501-security-auth-magic-link-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-3103.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-auth-magic-link-US-3103",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-magic-link-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Session handles are opaque, high-entropy, and carry no client-readable claims",
+  "asA": "operator who does not want their session credential to double as a signed self-describing token",
+  "iWant": "the handle in my browser to be nothing more than a random opaque string that only the server can interpret",
+  "soThat": "revocation is a server delete and there is no signed payload for anyone to forge, decode, or replay past its expiry",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-3103-1",
+      "description": "Issued session handles are base64url of at least 24 bytes of entropy; every issue produces a distinct handle across a batch of one thousand.",
+      "given": "one thousand sessions are issued in a batch",
+      "when": "the handles are inspected",
+      "then": "every handle is a base64url string decoding to at least 24 bytes, and no two handles in the batch are equal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3103-2",
+      "description": "Handles carry no encoded payload; a handle contains no principal id, no expiry, no scope, and no signed segment separable by dots or other JWT-shaped delimiters.",
+      "given": "any issued session handle",
+      "when": "the string is inspected",
+      "then": "it contains no dot-separated JWT segments, decodes to random bytes, and reveals no substring matching the principal id, expiry timestamp, or scope value stored in the session record",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-3103-3",
+      "description": "No authenticated response body or header on any code path emits a JWT-shaped token, a signed bearer, or any credential envelope beyond the opaque session cookie.",
+      "given": "any authenticated request-response pair on the surface",
+      "when": "response headers and body are scanned for JWT-shaped tokens (three dot-separated base64url segments) or Authorization headers with Bearer prefixes",
+      "then": "no such artefact is present outside of a Set-Cookie header carrying the opaque session handle",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-502-security-auth-magic-link-session-manager"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}