rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-auth-clerk/assets/middleware/node-middleware-shape.md

@@ -0,0 +1,86 @@
+# Node middleware boundary shape
+
+The framework-agnostic middleware boundary contract, worked as a shape reference plus two framework-specific adapter samples. The blueprint's TAC-1001 fixes the shape (`verify(request) -> { authenticated, principal?, reason? }`) and the attachment convention (`request.auth`). The framework adapters below are one-file wrappers around the same `verify`; a project on Fastify does not import the Express sample, and vice versa.
+
+## The core `verify` shape
+
+```
+// src/auth/middleware.ts (or the project's equivalent module path)
+import { createSessionVerifier } from './session-verifier';
+import { reduceClaims } from './claims-mapper';
+
+export function createVerify({ clerkClient, auditSink, clock }) {
+  const verifier = createSessionVerifier({ clerkClient, auditSink, clock });
+
+  return async function verify(request) {
+    const cookieHeader = request.headers.cookie ?? '';
+    const sessionCookie = parseCookie(cookieHeader, '__session');
+    if (!sessionCookie) {
+      return { authenticated: false, reason: 'no-session-cookie' };
+    }
+
+    const result = await verifier.verifySessionCookie(sessionCookie);
+    if (!result.valid) {
+      return { authenticated: false, reason: result.reason ?? 'invalid-session' };
+    }
+
+    const principal = reduceClaims(result.claims);
+    return { authenticated: true, principal };
+  };
+}
+```
+
+`parseCookie` is a one-liner cookie-header parser the project already has (or writes as a two-line helper); Clerk's SDK exposes its own cookie helpers on some Node adapters, and using those is fine.
+
+## Express adapter
+
+```
+// src/auth/adapters/express.ts
+import { createVerify } from '../middleware';
+
+export function expressMiddleware(deps) {
+  const verify = createVerify(deps);
+
+  return async function (req, res, next) {
+    const result = await verify(req);
+    if (!result.authenticated) {
+      if (req.accepts('html')) {
+        return res.redirect(302, '/sign-in');
+      }
+      return res.status(401).json({ error: 'unauthenticated', reason: result.reason });
+    }
+    req.auth = result.principal;
+    next();
+  };
+}
+```
+
+## Fastify adapter
+
+```
+// src/auth/adapters/fastify.ts
+import fp from 'fastify-plugin';
+import { createVerify } from '../middleware';
+
+export const fastifyPlugin = fp(async (fastify, deps) => {
+  const verify = createVerify(deps);
+
+  fastify.addHook('preHandler', async (request, reply) => {
+    const result = await verify(request);
+    if (!result.authenticated) {
+      if (request.headers.accept?.includes('text/html')) {
+        return reply.redirect(302, '/sign-in');
+      }
+      return reply.code(401).send({ error: 'unauthenticated', reason: result.reason });
+    }
+    request.auth = result.principal;
+  });
+});
+```
+
+## Notes
+
+- Both adapters attach to `request.auth`; downstream handlers read the same field name regardless of framework. This is what the `AC-9101-2` runtime observation binds against.
+- Both adapters refuse with 401 for API-shaped requests and a 302 redirect for HTML-shaped ones; the shape choice is a route-class convention the operator adjusts if the project's error envelope differs.
+- Neither adapter caches the verification result across requests inside the adapter; the caching (if any) lives inside the session verifier and is bounded by the `revocationCheckIntervalMs` window on ADR-1005.
+- Neither adapter reads the raw claim bag; the reduction happens once inside `createVerify` and the adapter attaches the reduced `Principal`.

package/blueprints/security-auth-clerk/assets/wiring/clerk-provider-react.md

@@ -0,0 +1,48 @@
+# ClerkProvider wiring: React-family sample
+
+This is a shape-level sample for wiring Clerk's client SDK into a React-family client tier. It is a reference for the operator or the working agent realising the blueprint's TACs; it is not a copy-paste production module. The Clerk SDK identifiers below (`@clerk/clerk-react`, `ClerkProvider`, `useAuth`, `useUser`) reflect the SDK's shape at the blueprint's authoring window; consult Clerk's currently-canonical documentation at the project's build time and adjust if the package or export name has changed.
+
+## Where the provider mounts
+
+The provider wraps the client tier's route surface once, at the top of the tree, above the router. Every route inside the provider has access to the Clerk client through the hook surface; nothing outside the provider does.
+
+```
+// src/main.tsx (or the framework's equivalent boot module)
+import { ClerkProvider } from '@clerk/clerk-react';
+import { Router } from './router';
+
+const publishableKey = window.__CLERK_PUBLISHABLE_KEY__;
+// Read from the project's config surface, not from process.env directly.
+// The secrets-management blueprint's Secrets Manager client is the source
+// on the server side; the client tier consumes the publishable key
+// as a build-time replacement or a boot-time injected global.
+
+export function App() {
+  return (
+    <ClerkProvider publishableKey={publishableKey}>
+      <Router />
+    </ClerkProvider>
+  );
+}
+```
+
+## What the client tier reads
+
+Two hooks cover most cases:
+
+- `useAuth()` returns `{ isSignedIn, signOut, ... }`. The client tier calls `signOut()` on the operator's sign-out action; this is what invalidates the session on Clerk's side per AC-9107-1.
+- `useUser()` returns the resolved user object; the client tier reads it for display purposes (an avatar, a display name). Downstream authorisation checks do not run on the client-tier user object; they run on the server against `request.auth` through the authorisation adapter.
+
+## The `__session` cookie is invisible to the client tier
+
+The Clerk SDK on the client tier does not read the `__session` cookie value (it is HttpOnly). The SDK's client-side state (whether the user is signed in, who the user is at the display level) is synchronised through Clerk's own client-side session store; the cookie is the credential the browser sends to the project's server on every same-origin request.
+
+## Composition with the SPA blueprint
+
+If the project has applied `application-spa`, the SPA blueprint's 401-redirect posture composes with this blueprint's middleware: a route the SPA blueprint marks as requiring authentication redirects to the sign-in surface when the middleware refuses; the SPA blueprint's error envelope shape is unchanged by this blueprint.
+
+## What this sample deliberately does not cover
+
+- A specific router library binding (React Router, TanStack Router). The provider mounts above the router; the router choice is the project's.
+- Server-side rendering configuration. The Clerk SDK has SSR support that varies by framework (Next.js, Remix); consult the currently-canonical Clerk documentation for the project's framework.
+- The sign-in and sign-up components themselves (`<SignIn />`, `<SignUp />`, or the hosted alternative). Those are Clerk-provided; the operator mounts them at a route (`/sign-in`, `/sign-up`) and the blueprint's job is to verify the resulting session on the server.

package/blueprints/security-auth-clerk/assets/wiring/clerk-provider-vue.md

@@ -0,0 +1,41 @@
+# Clerk plugin wiring: Vue-family sample
+
+The Vue-family counterpart to the React sample. Same shape (a provider mounted once, above the router); different SDK. The Clerk Vue-family package identifier below (`@clerk/vue`) reflects Clerk's Vue support at the blueprint's authoring window; consult Clerk's currently-canonical documentation at the project's build time and adjust if the package or plugin surface has changed.
+
+## Where the plugin registers
+
+The plugin registers on the Vue app instance once, at boot, before the router is used.
+
+```
+// src/main.ts (or the framework's equivalent boot module)
+import { createApp } from 'vue';
+import { clerkPlugin } from '@clerk/vue';
+import App from './App.vue';
+import { router } from './router';
+
+const publishableKey = window.__CLERK_PUBLISHABLE_KEY__;
+// Read from the project's config surface, not from import.meta.env directly.
+// Same convention as the React sample.
+
+const app = createApp(App);
+app.use(clerkPlugin, { publishableKey });
+app.use(router);
+app.mount('#app');
+```
+
+## What the client tier reads
+
+The Clerk Vue plugin exposes composables (`useAuth`, `useUser`, `useSignOut`) whose surface mirrors the React hooks. The client tier calls `useSignOut()` (or the equivalent) on the operator's sign-out action; that is what invalidates the session on Clerk's side per AC-9107-1.
+
+## The `__session` cookie is invisible to the client tier
+
+Same rule as the React sample: the cookie is HttpOnly; the SDK synchronises client-side sign-in state through its own store; the cookie rides on every same-origin request to the project's server.
+
+## Composition with the SPA blueprint
+
+If the project has applied `application-spa`, the SPA blueprint's 401-redirect posture composes with this blueprint's middleware exactly as it does in the React case; the SPA blueprint's session-and-redirect posture is framework-agnostic on the client tier.
+
+## What this sample deliberately does not cover
+
+- Nuxt-specific module wiring. Clerk has Nuxt-specific modules; the operator on a Nuxt project consults Clerk's Nuxt documentation for the module-mode wiring rather than following this shape.
+- The sign-in and sign-up components. Same as the React sample: those are Clerk-provided.

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

@@ -0,0 +1,42 @@
+{
+  "slug": "security-auth-clerk",
+  "version": "1.0.0",
+  "category": "security",
+  "contributions": [
+    { "id": "security-auth-clerk-REQ-001", "kind": "req", "path": "requirements/security-auth-clerk-req-001.json" },
+    { "id": "security-auth-clerk-REQ-002", "kind": "req", "path": "requirements/security-auth-clerk-req-002.json" },
+    { "id": "security-auth-clerk-REQ-003", "kind": "req", "path": "requirements/security-auth-clerk-req-003.json" },
+    { "id": "security-auth-clerk-REQ-004", "kind": "req", "path": "requirements/security-auth-clerk-req-004.json" },
+    { "id": "security-auth-clerk-REQ-005", "kind": "req", "path": "requirements/security-auth-clerk-req-005.json" },
+    { "id": "security-auth-clerk-REQ-006", "kind": "req", "path": "requirements/security-auth-clerk-req-006.json" },
+    { "id": "security-auth-clerk-REQ-007", "kind": "req", "path": "requirements/security-auth-clerk-req-007.json" },
+    { "id": "security-auth-clerk-REQ-008", "kind": "req", "path": "requirements/security-auth-clerk-req-008.json" },
+    { "id": "security-auth-clerk-REQ-009", "kind": "req", "path": "requirements/security-auth-clerk-req-009.json" },
+    { "id": "security-auth-clerk-US-9101", "kind": "us", "path": "user-stories/security-auth-clerk-us-9101.json" },
+    { "id": "security-auth-clerk-US-9102", "kind": "us", "path": "user-stories/security-auth-clerk-us-9102.json" },
+    { "id": "security-auth-clerk-US-9103", "kind": "us", "path": "user-stories/security-auth-clerk-us-9103.json" },
+    { "id": "security-auth-clerk-US-9104", "kind": "us", "path": "user-stories/security-auth-clerk-us-9104.json" },
+    { "id": "security-auth-clerk-US-9105", "kind": "us", "path": "user-stories/security-auth-clerk-us-9105.json" },
+    { "id": "security-auth-clerk-US-9106", "kind": "us", "path": "user-stories/security-auth-clerk-us-9106.json" },
+    { "id": "security-auth-clerk-US-9107", "kind": "us", "path": "user-stories/security-auth-clerk-us-9107.json" },
+    { "id": "security-auth-clerk-US-9108", "kind": "us", "path": "user-stories/security-auth-clerk-us-9108.json" },
+    { "id": "security-auth-clerk-US-9109", "kind": "us", "path": "user-stories/security-auth-clerk-us-9109.json" },
+    { "id": "security-auth-clerk-US-9110", "kind": "us", "path": "user-stories/security-auth-clerk-us-9110.json" },
+    { "id": "security-auth-clerk-US-9111", "kind": "us", "path": "user-stories/security-auth-clerk-us-9111.json" },
+    { "id": "TAC-1001-security-auth-clerk-middleware", "kind": "tac", "path": "tacs/tac-1001-security-auth-clerk-middleware.json" },
+    { "id": "TAC-1002-security-auth-clerk-authorisation-adapter", "kind": "tac", "path": "tacs/tac-1002-security-auth-clerk-authorisation-adapter.json" },
+    { "id": "TAC-1003-security-auth-clerk-session-verifier", "kind": "tac", "path": "tacs/tac-1003-security-auth-clerk-session-verifier.json" },
+    { "id": "TAC-1004-security-auth-clerk-claims-mapper", "kind": "tac", "path": "tacs/tac-1004-security-auth-clerk-claims-mapper.json" },
+    {
+      "id": "ADR-1001-security-auth-clerk-auth-model",
+      "kind": "adr",
+      "path": "adrs/adr-1001-security-auth-clerk-auth-model.json",
+      "scope": "global",
+      "topic": "authModel"
+    },
+    { "id": "ADR-1002-security-auth-clerk-middleware-boundary", "kind": "adr", "path": "adrs/adr-1002-security-auth-clerk-middleware-boundary.json" },
+    { "id": "ADR-1003-security-auth-clerk-authorisation-adapter-contract", "kind": "adr", "path": "adrs/adr-1003-security-auth-clerk-authorisation-adapter-contract.json" },
+    { "id": "ADR-1004-security-auth-clerk-claims-mapping-discipline", "kind": "adr", "path": "adrs/adr-1004-security-auth-clerk-claims-mapping-discipline.json" },
+    { "id": "ADR-1005-security-auth-clerk-session-lifecycle", "kind": "adr", "path": "adrs/adr-1005-security-auth-clerk-session-lifecycle.json" }
+  ]
+}

package/blueprints/security-auth-clerk/contributions/adrs/adr-1001-security-auth-clerk-auth-model.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1001-security-auth-clerk-auth-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Clerk-hosted identity with server-verified session cookies is the project's authentication model",
+  "context": "A project has one authentication model; the client tier, the server tier, and every operator surface must reason against it. The security-auth-clerk blueprint contributes a Clerk-committed shape of that model: identity, sign-in UX, credential storage, MFA, and account recovery all live at Clerk; the project owns the reduction of a verified session into a principal and the authorisation adapter that speaks in project verbs. A client-tier blueprint (application-spa), a server-tier blueprint (application-api-rest), and every other auth-family blueprint (security-auth-magic-link, security-auth-oauth2 when it ships, security-auth-keycloak when it ships) contribute their own decisions on this topic; blueprint composition surfaces the pairing at add time for the operator to reconcile into one project-level model. That surfacing is intended.",
+  "decision": "The project's authentication model is Clerk-hosted identity. Sign-in is delegated to Clerk's sign-in surfaces (hosted UI or embedded components); credential storage, MFA, account recovery, and sign-in strategy choice are Clerk's concerns. The wire credential is a Clerk-issued session cookie named `__session` (per Clerk's currently-supported cookie contract), Secure, HttpOnly, SameSite=Lax. Server-side middleware verifies the cookie against Clerk's session-verification surface and lifts the resolved claims into a reduced Principal shape the rest of the project reasons against. The project does not own a user table, does not mint credentials, and does not implement sign-in UX beyond wiring the Clerk surface into a route. User and organisation provisioning are Clerk-owned and are read-only from the runtime's perspective (REQ-009). Rate-limiting and anti-enumeration on the sign-in flow are Clerk's (REQ-007).",
+  "consequences": "The project owns the middleware boundary, the session verifier, the claims mapper, and the authorisation adapter; Clerk owns everything else on the identity surface. Vendor swap (from Clerk to a different hosted identity vendor) is a project-level ADR supersede on this topic plus an adapter swap on the middleware and verifier modules; the boundary shape does not change. Composing with another auth-family blueprint (magic-link, OAuth2, Keycloak) conflicts on this topic by design; the expected resolution is one project-level ADR that fixes the identity surface and the credential shape for the whole project. The `accountBound` posture on runtime-verify ACs is explicit: runs without Clerk reachability skip those ACs with a stable-coded reason; passing without a live Clerk session is not an option.",
+  "alternativesConsidered": [
+    {
+      "name": "Passwordless magic-link with server-issued opaque cookie sessions",
+      "summary": "The security-auth-magic-link blueprint's model: mint a single-use token on POST /login, deliver by email, verify on GET /login/verify, issue an opaque-handle session cookie.",
+      "reasonNotChosen": "Valid for projects that want no third-party identity dependency; the trade is that the project owns the principal registry, the email adapter, the rate-limiter, and the anti-enumeration posture. Clerk removes that surface at the cost of a vendor dependency; the blueprint at hand names that trade explicitly."
+    },
+    {
+      "name": "Self-hosted OIDC via Keycloak",
+      "summary": "Run a Keycloak instance the project federates against through the OIDC authorization-code flow.",
+      "reasonNotChosen": "Valid for projects with existing ops capacity and a hard multi-tenant IdP requirement; the container plus realm configuration cost is disproportionate at the rcf-lite tier this blueprint targets. A future security-auth-keycloak blueprint covers that shape and conflicts here on the same topic; the operator resolves at apply."
+    },
+    {
+      "name": "Direct OAuth2 authorization-code flow with a specific external provider (Google, GitHub)",
+      "summary": "Skip a hosted identity vendor; wire OAuth2 directly against one or more social providers.",
+      "reasonNotChosen": "Valid where a project wants exactly one social sign-in and nothing more; the trade is that the project owns token handling, refresh flows, provider quirks, and the principal registry. A future security-auth-oauth2 blueprint covers that shape and conflicts here on the same topic; the operator resolves at apply."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/adrs/adr-1002-security-auth-clerk-middleware-boundary.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1002-security-auth-clerk-middleware-boundary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The middleware boundary contract is framework-agnostic and single-shaped",
+  "context": "Every project that consumes this blueprint runs on some Node HTTP framework, and the field of realistic frameworks is not one: rcf-lite projects ship on Express, Fastify, plain Node HTTP, and Cloudflare Workers with roughly equal frequency. Fixing the framework at the blueprint layer would force the majority of consumers into a shim they did not want; leaving both the shape and the framework open would leave the blueprint unable to make any concrete claim about what an authenticated request looks like.",
+  "decision": "The middleware boundary contract is a single function shape, `verify(request) -> { authenticated, principal?, reason? }`, and one attachment convention, `request.auth`. Framework-specific adapters are project-authored thin shims that call the same `verify`. The blueprint ships adapter samples for two of the four common shapes (Express and Fastify are the two the guide's samples cover); the other two are one-file adaptations the project authors when it needs them.",
+  "consequences": "The middleware module has one testable surface (`verify`) that the shim wrappers do not distort. Framework variance is absorbed at the shim layer, where it should be; the blueprint's ACs bind to the shape the middleware produces, not to the shim's plumbing. A project that hosts multiple runtimes (an Express main app and a Workers edge function, say) reuses the same verifier and mapper through two shims and pays the shim cost twice.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship as an Express middleware",
+      "summary": "Fix the framework at Express; every consumer imports the middleware as Express-shaped and adapts on the way in.",
+      "reasonNotChosen": "Locks out Fastify, Workers, and plain Node HTTP consumers; Express is not the majority framework at the rcf-lite tier, and forcing a shim is the wrong default."
+    },
+    {
+      "name": "Ship as a Clerk-SDK-directly-consumed pattern with no boundary module",
+      "summary": "Every route imports Clerk's SDK directly and reads whichever claim shape it needs.",
+      "reasonNotChosen": "Breaks REQ-001's principal reduction and REQ-004's authorisation adapter; the vendor lock is total and the swap cost is a rewrite."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/adrs/adr-1003-security-auth-clerk-authorisation-adapter-contract.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1003-security-auth-clerk-authorisation-adapter-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Authorisation checks speak in project verbs through the adapter, never in Clerk claim vocabulary",
+  "context": "Downstream code that reads `principal.roles.includes('admin')` or `principal.claims['org:role'] === 'X'` ties the project to Clerk's claim vocabulary version and drifts silently when Clerk changes it. It also makes the vendor swap a codebase sweep rather than an adapter change. The blueprint ships an authorisation adapter (TAC-1002) that maps Clerk claims onto project-defined verbs; the discipline that keeps the adapter useful is that every downstream check goes through it.",
+  "decision": "Every authorisation check in the project goes through `can(principal, verb, subject?)` or `assert(principal, verb, subject?)` on the authorisation adapter. Verbs are project-defined strings owned by the project's mapping-table module. No handler, no middleware wrapper, no template, and no view helper reads `principal.roles`, `principal.organisationIds`, or `principal.claims` directly. The source-tree scan on AC-9104-3 is the enforcement mechanism.",
+  "consequences": "The vocabulary the project's code speaks in is project-owned; changing the Clerk vendor is a mapping-table rewrite plus an adapter swap on the middleware and verifier, not a codebase sweep. The trade is that adding a new authorisation check requires adding a verb to the mapping table before the handler can call `can` on it; the adapter refuses unknown verbs, which forces the discipline. A project that finds itself adding a new verb per change is signal that the mapping is too fine-grained; consolidate at the mapping level, not by bypassing the adapter.",
+  "alternativesConsidered": [
+    {
+      "name": "Handlers read `principal.roles` directly for simple cases",
+      "summary": "Allow direct role reads on the principal for the common case; use the adapter only for the complex cases.",
+      "reasonNotChosen": "The common case is the majority of the code; the discipline collapses if the adapter is optional. The scan-catches-everything discipline requires 'no direct reads anywhere'."
+    },
+    {
+      "name": "Skip verbs and speak in roles",
+      "summary": "The adapter exposes `hasRole(principal, roleName)` and downstream code checks for role membership rather than verb grants.",
+      "reasonNotChosen": "Same failure mode as reading `principal.roles` directly, one indirection deeper. Roles are Clerk's vocabulary; verbs are the project's, and the project's vocabulary is what the code should speak in."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/adrs/adr-1004-security-auth-clerk-claims-mapping-discipline.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1004-security-auth-clerk-claims-mapping-discipline",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Clerk claim keys live in one named constant record; the raw `claims` bag is an escape hatch",
+  "context": "Clerk's claim vocabulary is not stable across major SDK versions; a rename on the Clerk side (a claim key shifting from one string to another) is a real thing that happens between versions. The blueprint's ambition to keep the vendor swap cheap depends on the project not scattering literal Clerk claim keys through its handler code. At the same time, refusing to expose the raw claims at all forces the project to author every mapping up front, which fights the incremental-adoption posture the rcf-lite tier depends on.",
+  "decision": "The claims mapper (TAC-1004) exports one named constant record `CLERK_CLAIM_KEYS` that maps each project-facing name (`userId`, `roles`, `organisations`, ...) to the Clerk-side claim key string at the SDK version the project builds against. Every reduction step in the mapper reads through that record; no other module in the mapper hard-codes a Clerk claim key. The mapper's `reduceClaims` return value carries a `claims` field with the raw claim bag verbatim as an escape hatch; downstream reads on `.claims` are treated as a code-review-visible smell but not a mechanism refusal.",
+  "consequences": "A Clerk-side claim rename is a one-file change: update `CLERK_CLAIM_KEYS`. The escape hatch admits a small class of downstream code that reads a raw Clerk claim directly rather than through a reduction; the discipline states that if the same claim is read more than once it must move into the reduction. The scan on AC-9104-3 catches `.roles`, `.organisationIds`, and `.claims` reads outside the adapter and the mapper; a scan that catches `.claims[<key>]` in a handler is a code-review flag, not a mechanism refusal.",
+  "alternativesConsidered": [
+    {
+      "name": "Refuse to expose the raw claims bag at all",
+      "summary": "The mapper reduces to the fixed shape and drops everything else on the floor.",
+      "reasonNotChosen": "Forces the project to author every mapping up front. The escape hatch is what makes incremental adoption cheap; disciplining its use is a code-review concern, not a mechanism one."
+    },
+    {
+      "name": "Read the raw claim bag freely everywhere",
+      "summary": "Skip the reduction; downstream code reads `principal.claims[key]` directly.",
+      "reasonNotChosen": "Same failure mode as the discipline this whole blueprint exists to prevent; claim keys sprawl and the vendor swap becomes a rewrite."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/adrs/adr-1005-security-auth-clerk-session-lifecycle.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1005-security-auth-clerk-session-lifecycle",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Session verification honours Clerk revocation within a bounded freshness window",
+  "context": "Clerk owns session issuance and revocation; the project's verifier owns the read side. Verifying every request against Clerk's revocation-aware endpoint on every request is a per-request round trip whose latency the project pays for; caching the verification result for the session's declared expiry admits a window during which a revoked session continues to verify against a stale cache. The blueprint's decision on this trade must be explicit because REQ-006 makes revocation a hard requirement and the shape of 'hard' is bounded by whichever number the operator picks here.",
+  "decision": "The session verifier honours Clerk-side revocation within `revocationCheckIntervalMs` of the revocation event. The default value is 30000 (30 seconds) when the Clerk SDK version in use exposes a revocation-aware verify (in which case the verifier consults the SDK's revocation surface at or shorter than that interval); when the SDK version does not, the verifier falls back to a per-request revocation check on the same call path and the interval becomes de facto zero at the cost of one Clerk round trip per verification. Either way the number is documented at the project's config surface and every verification event's audit record carries a `revocationCheckMode` field naming which shape was used.",
+  "consequences": "Under the default, a revoked session may continue to verify for up to 30 seconds after revocation before the verifier's cache expires and the next verification observes the revocation. The trade is stated: 30 seconds is short enough that operator-visible sign-out is prompt and long enough that per-request Clerk round trips are avoided on the hot path. Projects with a stricter freshness requirement drop the interval or use the SDK's revocation-aware verify directly at the cost of that round trip; projects with a laxer requirement raise the interval but the ceiling is the session's own expiry (a longer cache than the session's lifetime is a bug the verifier refuses to boot with).",
+  "alternativesConsidered": [
+    {
+      "name": "Revocation-check on every request always",
+      "summary": "The verifier always consults Clerk's revocation surface on every verification; no local cache.",
+      "reasonNotChosen": "One Clerk round trip per request is a cost the rcf-lite tier's hot path does not want to eat by default; projects that need it enable it explicitly."
+    },
+    {
+      "name": "No revocation check until the session expires",
+      "summary": "The verifier caches until the session's declared expiry and never re-checks against Clerk before then.",
+      "reasonNotChosen": "Sign-out becomes eventual to a degree operator-visible sign-out cannot tolerate; the whole point of REQ-006 is that the cookie stops working when the operator signs out."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Clerk owns the identity surface; the project reads a resolved principal",
+  "description": "The project's authentication model delegates the identity surface (users, sessions, sign-in UX, credential storage, MFA, account recovery) to Clerk. The project does not own a user table, does not mint or store credentials, and does not implement the sign-in UI beyond mounting a Clerk-hosted component or route. What the project owns is the reduction of a verified Clerk session into a stable in-process principal shape (a `principalId` string, a `roles` string array, an `organisationIds` string array) that the rest of the project reasons against. Any code path that needs to know who the current caller is reads that resolved principal; no code path calls Clerk directly outside the middleware and session-verifier boundary.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Two failure modes justify the strict boundary. First, calls to Clerk scattered across the codebase make the vendor swap a rewrite rather than an adapter change; the blueprint's promise (Clerk is the default, another hosted identity vendor is a project-level ADR supersede) collapses. Second, code that reasons against raw Clerk claim shapes ties the project to Clerk's claim vocabulary version and drifts silently when Clerk changes it; a stable in-process principal shape is the seam that absorbs that drift.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:01-identity-boundary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Session-cookie transport under Clerk's session model",
+  "description": "The wire credential is a Clerk-issued session cookie named `__session` (Clerk's documented cookie name at Clerk's currently-supported major). The cookie is Secure, HttpOnly, and SameSite=Lax under a top-level domain; the project does not read the cookie value from JavaScript on the client. Every request that requires an authenticated caller carries the cookie; the server-side middleware verifies the cookie against Clerk's session-verification surface and lifts the resolved principal onto the request. Bearer-in-header transport is out of scope for the blueprint's default; a project that requires it authors a project-level ADR and layers the required transport alongside the cookie one without removing the cookie floor.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "The session-cookie model is what Clerk ships as the default browser flow and it composes with the SPA blueprint's XSS floor (HttpOnly means script exfiltration is not the failure mode) and with the REST blueprint's CSRF-shape choice (SameSite=Lax is the floor and a project can layer a double-submit token on top). Pinning the cookie name to Clerk's documented value is what lets the verifier and the middleware speak the same wire without a translation layer.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:02-session-transport"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Framework-agnostic middleware boundary contract",
+  "description": "The project integrates Clerk on the server through a middleware boundary whose shape is fixed by the blueprint and whose framework is not. The boundary is a function of the form `verify(request) -> { authenticated: boolean, principal?: Principal, reason?: string }` where `Principal` is the reduced shape from REQ-001. Framework-specific adapters (an Express request handler, a Fastify hook, a Node HTTP wrapper, a Cloudflare Workers fetch handler) are project-authored thin wrappers that delegate to the same underlying verifier; the blueprint does not mandate Express and does not mandate any single HTTP framework, only the shape of the boundary. A request that fails verification is denied at the boundary; a request that passes carries the principal onto the request object under a fixed field name (`request.auth`) for downstream handlers to read.",
+  "category": "technical",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Fixing the shape and leaving the framework open is what lets the blueprint apply cleanly against every Node HTTP framework the rcf-lite tier realistically ships against. A project on Fastify does not have to import Express to consume this blueprint; a project on Workers does not have to shim a Node middleware chain. The stable field name (`request.auth`) is what lets downstream handlers and higher-level authorisation checks read the principal without adapter-specific glue.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:03-middleware-boundary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Authorisation adapter maps Clerk claims onto project verbs",
+  "description": "The project's authorisation layer does not consume Clerk claim shapes directly. A single Authorisation Adapter module owns the mapping from a verified principal (roles array, organisation ids array, arbitrary claim bag from the Clerk session) onto the set of project-defined verbs the caller is allowed to perform. The adapter's surface is `can(principal, verb, subject?) -> boolean` and `assert(principal, verb, subject?) -> void | throw`. Verbs are project-defined strings (`article.edit`, `admin.dashboard.view`, `billing.invoice.void`); the adapter's mapping table is project-authored and read from a single module the rest of the project imports. No downstream code path checks `principal.roles.includes('admin')` or `principal.organisationIds.includes('X')` directly; every check goes through `can` or `assert`.",
+  "category": "technical",
+  "domain": "authorisation",
+  "priority": "must",
+  "rationale": "Clerk's role and organisation vocabulary is Clerk's, not the project's; the same failure mode that motivates REQ-001's principal reduction motivates a further reduction from principal claims onto project verbs. Downstream code that speaks in verbs is legible (the site's `article.edit` is unambiguous), swap-safe (moving from Clerk to a different identity vendor is an adapter-mapping change, not a codebase rewrite), and testable (project verbs give the test surface a stable vocabulary).",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:04-authorisation-adapter"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Sign-in strategy is a fixed-shape config surface",
+  "description": "Clerk supports multiple sign-in strategies (email link, email code, password, phone code, OAuth via named providers, SAML). The project's Clerk instance is configured to enable one or more of them; the blueprint fixes the SHAPE of that configuration on the project side as a single `signInStrategy` config record (`{ primary: string, alternates: string[] }`) rather than fixing the CHOICE. The values in the record are Clerk's currently-documented strategy identifiers (as printed by the Clerk dashboard or the Clerk SDK's strategy enumeration at the project's build time). The project's sign-in surface reads the config record and does not hard-code any strategy string; changing the enabled strategy set is a config edit and a Clerk-dashboard change, not a codebase change.",
+  "category": "functional",
+  "domain": "authentication",
+  "priority": "should",
+  "rationale": "Fixing the shape leaves the choice open to the operator without leaving the codebase full of hard-coded strategy strings that drift as Clerk's vocabulary drifts. A project that starts on email link and later adds SAML for enterprise is a config bump, not a fork of the sign-in surface. Fixing the choice at the blueprint layer would be premature at the rcf-lite tier where the operator's requirements around sign-in shape are project-specific.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:05-sign-in-strategy"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Sign-out invalidates on Clerk's server; subsequent requests fail verification",
+  "description": "Sign-out is initiated by a client-side call to the Clerk sign-out surface (the `signOut` method on Clerk's client SDK or the equivalent server-invoked revocation). The blueprint requires that after sign-out the same session cookie no longer verifies: a subsequent request carrying the pre-sign-out `__session` cookie MUST be treated as unauthenticated by the middleware. Client-side cookie clearing alone is not the revocation mechanism; the revocation is a Clerk-side state change and the middleware's session verifier must observe it. An administrative revoke of a user or session on the Clerk dashboard has the same runtime effect as user-initiated sign-out.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "The same rule the magic-link blueprint restates about server-side revocation applies here for the same reason: a session that only ends when the browser forgets its cookie is a session an attacker with the cookie can still ride. Clerk owns the revocation surface; the blueprint's job is to require that the middleware's verifier honours it and does not cache past its useful life.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:06-sign-out-revocation"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Rate-limiting and anti-enumeration are delegated to Clerk",
+  "description": "The project does not implement rate-limiting or anti-enumeration on the sign-in flow. Clerk applies its own throttling and account-enumeration defences at the identity surface; the project's job is to name the delegation and not to layer a second-rate rate limiter on top. If the project's request-shape floor requires a rate limiter for other routes (a public API, a webhook receiver), it authors that separately; the sign-in and sign-up surfaces are Clerk's.",
+  "category": "security",
+  "domain": "authentication",
+  "priority": "should",
+  "rationale": "A project-side rate limiter over the sign-in flow either duplicates what Clerk already does (dead code that drifts) or interferes with it (retries and back-off that Clerk's own surface handles differently, resulting in confusing user-facing errors). Naming the delegation explicitly is the acceptance bar; the runtime observability is that the sign-in surface's rate-limit behaviour matches Clerk's documented behaviour rather than a project-authored variant.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:07-rate-limiting-delegation"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-008",
+  "prdId": "PRD-001",
+  "title": "Runtime acceptance rides a real Clerk development instance",
+  "description": "Clerk hosts the identity surface; there is no in-project emulator for the sign-in flow at the fidelity the acceptance criteria depend on. Runtime acceptance for the blueprint's ACs uses a real Clerk development instance (Clerk's documented development-tier deployment shape) with placeholder-configured publishable and secret keys held in the project's secrets manifest. The blueprint's `accountBound` posture is explicit: an environment without Clerk reachability cannot satisfy the runtime-verify class of ACs and the project's ship gate must acknowledge that.",
+  "category": "nonFunctional",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Faking Clerk's session issuance in-process elides the parts of the flow the blueprint most needs verified (real signature check on real Clerk-issued cookies, real revocation-on-sign-out, real claim propagation). The rcf-lite ship gate accommodates `accountBound` tests already; the blueprint states the posture and the ACs bind to it rather than pretending an emulator will do.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:08-account-bound"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-auth-clerk-REQ-009",
+  "prdId": "PRD-001",
+  "title": "User and organisation provisioning are read-only from the project's perspective",
+  "description": "Users and organisations are created, updated, and deleted through Clerk's surfaces (the Clerk dashboard, the Clerk sign-up flow, or the Clerk Backend API called from a project-authored provisioning script). The project's runtime does not create, update, or delete users or organisations on Clerk's behalf as part of the request lifecycle; roles and organisation memberships are read from the verified session by the middleware and propagated as read-only fields on the principal. A project that needs to mirror Clerk state into a local table for query purposes does so through a project-authored Clerk-webhook consumer whose contract is out of scope for the blueprint's default (a project that includes one authors one additional TAC and a scope-local ADR).",
+  "category": "technical",
+  "domain": "authentication",
+  "priority": "must",
+  "rationale": "Split-brain identity state (Clerk holds one shape, the project's tables hold a divergent shape) is the failure mode this requirement forecloses. Clerk is authoritative for identity; the project reads. Mirroring is a project decision layered on the read-only floor, not a substitute for it.",
+  "tags": [
+    "blueprint:security-auth-clerk",
+    "category:09-provisioning-boundary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/tacs/tac-1001-security-auth-clerk-middleware.json

@@ -0,0 +1,42 @@
+{
+  "tacId": "TAC-1001-security-auth-clerk-middleware",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Clerk middleware boundary",
+  "purpose": "The framework-agnostic boundary the project's HTTP surface delegates to for every request that reaches an authenticated route. Owns the `verify(request) -> { authenticated, principal?, reason? }` contract and the attachment of `request.auth` for downstream handlers. Delegates the actual session-cookie verification to the session verifier (TAC-1003) and the claim-to-principal reduction to the claims mapper (TAC-1004). Framework-specific adapters (Express middleware, Fastify hook, Node HTTP wrapper, Workers fetch wrapper) are project-authored thin shims that delegate to this one module.",
+  "responsibilities": [
+    "Expose `verify(request)` returning `{ authenticated: boolean, principal?: Principal, reason?: string }` (AC-9101-2, AC-9101-3).",
+    "Attach `request.auth` on the request object when verification succeeds; do not attach it on failure (AC-9101-2, AC-9102-1).",
+    "Refuse requests on failed verification with a status appropriate to the route class (401 for API-shaped, redirect for page-shaped) as declared by the wiring shim; the handler must not be invoked (AC-9103-2, AC-9103-3, AC-9107-1).",
+    "Read the `__session` cookie by name from the request; do not accept credentials from any other transport under the blueprint's default (AC-9101-1, AC-9101-3).",
+    "Read the `signInStrategy` config record from the project's config module for any sign-in surface that requires it; hold no hard-coded strategy string (AC-9108-1, AC-9108-2).",
+    "Confine the import of Clerk's server SDK to this module and to the session verifier (TAC-1003); other project code imports the middleware, not the SDK (AC-9102-2)."
+  ],
+  "internalStructure": "One stateless factory function producing the `verify` closure over an injected session verifier and an injected claims mapper. Framework shims (an `expressMiddleware()` wrapper, a `fastifyPlugin()` wrapper, a `workersHandler()` wrapper) are one-file adapters colocated with this TAC's module directory; each delegates to the same `verify`. The wrapper for a given framework is enabled by the project's boot code choosing one; the blueprint does not mandate the choice.",
+  "interfaces": [
+    {
+      "name": "sessionVerifier",
+      "kind": "read-api",
+      "description": "The session verifier (TAC-1003) exposing `verifySessionCookie(cookieValue) -> { valid, claims?, revokedAt? }`. The middleware calls this on the `__session` cookie value and treats a non-valid return as unauthenticated."
+    },
+    {
+      "name": "claimsMapper",
+      "kind": "read-api",
+      "description": "The claims mapper (TAC-1004) exposing `reduceClaims(rawClaims) -> Principal`. The middleware calls this on a valid session's claims to produce the `Principal` it attaches to `request.auth`."
+    },
+    {
+      "name": "config",
+      "kind": "read-api",
+      "description": "The project's config module exposing `signInStrategy: { primary, alternates }`. The middleware reads it once at construction; a re-read is a boot-time concern."
+    }
+  ],
+  "dependencies": [
+    { "name": "Clerk session verifier", "kind": "tac", "tacId": "TAC-1003-security-auth-clerk-session-verifier", "description": "The session-verification surface the middleware delegates cookie verification to." },
+    { "name": "Clerk claims mapper", "kind": "tac", "tacId": "TAC-1004-security-auth-clerk-claims-mapper", "description": "The reduction from raw Clerk claims onto the project's Principal shape." }
+  ],
+  "tradeoffs": "Fixing the shape and the boundary while leaving the framework open costs the project one thin shim per HTTP framework it uses. Projects on a single framework carry one shim and pay nothing; projects that host multiple runtimes (an Express main app plus a Workers edge function) carry two shims but share the verifier and the mapper. That is intentional: the seam that absorbs framework variation is the shim, not the middleware.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}