rcf-lite 0.12.0 → 0.14.0

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

@@ -0,0 +1,42 @@
+{
+  "slug": "security-auth-clerk",
+  "version": "1.1.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"
+}

package/blueprints/security-auth-clerk/contributions/tacs/tac-1002-security-auth-clerk-authorisation-adapter.json

@@ -0,0 +1,30 @@
+{
+  "tacId": "TAC-1002-security-auth-clerk-authorisation-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Authorisation adapter",
+  "purpose": "The one module in the project that reads a Principal's roles, organisation ids, and claim bag to answer authorisation questions. Owns the mapping table from project-defined verbs onto the role and organisation-membership predicates that grant them. Exposes `can(principal, verb, subject?) -> boolean` and `assert(principal, verb, subject?) -> void | throw`. Downstream handlers speak verbs; the adapter is the only code that reasons in role and organisation vocabulary.",
+  "responsibilities": [
+    "Load the project-authored verb-to-role mapping table once at construction; hold it as an in-memory map (AC-9104-1).",
+    "Evaluate `can(principal, verb)` as true when the intersection of the principal's roles and the mapping table's role set for the verb is non-empty (AC-9104-1).",
+    "Evaluate `can(principal, verb, subject)` with organisation scoping: when the subject carries `organisationId`, require that the principal's `organisationIds` array includes it (AC-9105-1, AC-9105-2).",
+    "Expose `assert(principal, verb, subject?)` that returns silently on grant and throws `AUTHZ_FORBIDDEN` naming the verb on refusal; the thrown error must not serialise principal claim material (AC-9104-2).",
+    "Confine the reading of `principal.roles`, `principal.organisationIds`, and `principal.claims` to this module and the claims mapper (TAC-1004); no handler reads those fields directly (AC-9104-3)."
+  ],
+  "internalStructure": "One stateless class over an injected mapping table. The mapping table is a project-authored module that exports `{ [verb: string]: { roles: string[] } }`. Extensions (custom predicates beyond role membership and organisation scoping) are project decisions that layer above the adapter's default reasoner; the blueprint does not name a predicate DSL.",
+  "interfaces": [
+    {
+      "name": "mappingTable",
+      "kind": "read-api",
+      "description": "Project-authored module exporting `{ [verb: string]: { roles: string[] } }`. A verb not present in the map evaluates to `false` on `can` and to throw on `assert`."
+    }
+  ],
+  "dependencies": [
+    { "name": "Clerk claims mapper", "kind": "tac", "tacId": "TAC-1004-security-auth-clerk-claims-mapper", "description": "The reduction from raw Clerk claims onto the Principal shape the adapter consumes." }
+  ],
+  "tradeoffs": "Fixing the adapter's decision shape (role-set intersection plus optional organisation scoping) leaves fine-grained resource-level authorisation (per-record ACLs, dynamic ownership predicates) as a project decision layered above it. The blueprint's floor is verb-plus-organisation because that is what Clerk's own claim vocabulary supports out of the box; a project that needs richer predicates authors them as a project-side extension that consumes this adapter's output rather than replaces it.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/tacs/tac-1003-security-auth-clerk-session-verifier.json

@@ -0,0 +1,38 @@
+{
+  "tacId": "TAC-1003-security-auth-clerk-session-verifier",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Clerk session verifier",
+  "purpose": "The one module in the project that speaks to Clerk's session-verification surface. Owns the verification of a `__session` cookie value into either a set of validated Clerk claims or a rejection with a stable failure class. Owns the revocation-observation posture: the verifier does not cache a valid session past its useful life, and it bounds how long a revoked session can continue to satisfy `verifySessionCookie` before the revocation is honoured.",
+  "responsibilities": [
+    "Expose `verifySessionCookie(cookieValue) -> { valid: boolean, claims?: object, reason?: string, revokedAt?: string }` (AC-9101-3, AC-9103-1, AC-9107-1).",
+    "Reject tampered cookies (signature mismatch, malformed shape, unknown session id) without a cached-hit shortcut; every rejection contributes an audit event carrying the failure class and no cookie value (AC-9101-3).",
+    "Honour Clerk-side revocation within the `revocationCheckIntervalMs` window declared by ADR-1005; a session revoked more than `revocationCheckIntervalMs` ago must not verify (AC-9107-2).",
+    "Emit an audit event on every verification attempt (success and failure) with fields `{ outcome, reasonClass?, sessionIdPrefix, at }`; no field carries the cookie value, no field carries a full session id, no field carries a raw claim (AC-9101-3).",
+    "Confine the import of Clerk's server SDK to this module and the middleware wiring (TAC-1001); do not export the SDK's internal types across the module boundary (AC-9102-2)."
+  ],
+  "internalStructure": "One stateless class over an injected Clerk SDK client and an injected audit sink. The verifier is instantiated once at process boot with the Clerk publishable and secret keys read from the project's secrets manifest under placeholder-named entries (`CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`). The revocation check is either the Clerk SDK's native revocation-aware verify (preferred when the SDK exposes it at the project's build time) or a bounded-freshness cache the verifier maintains itself; ADR-1005 documents which shape the default vendor default expects.",
+  "interfaces": [
+    {
+      "name": "clerkClient",
+      "kind": "read-api",
+      "description": "The Clerk server SDK's session-verification surface. The verifier's constructor takes a Clerk client instance; the module does not construct its own from environment variables."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with `{ outcome, reasonClass?, sessionIdPrefix, at }` on every verification attempt; never invoked with a cookie value or a full session id."
+    },
+    {
+      "name": "clock",
+      "kind": "clock",
+      "description": "Injectable clock returning the current instant; used for revocation-window bounding and for the audit event's `at` field."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The verifier holds credential material (the Clerk secret key) in memory for the lifetime of the process; a heap dump of a compromised process exposes it. That is the same trade the secrets-management blueprint's Secrets Manager client makes, and the mitigation is the same: process isolation and the secrets rotation gate. The revocation-check window is a latency versus freshness trade the operator tunes on ADR-1005; a shorter window costs a Clerk round trip per request under some SDK shapes, a longer window admits a bounded read of a revoked session.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/tacs/tac-1004-security-auth-clerk-claims-mapper.json

@@ -0,0 +1,22 @@
+{
+  "tacId": "TAC-1004-security-auth-clerk-claims-mapper",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Clerk claims mapper",
+  "purpose": "The one module that reduces a raw Clerk claim bag (as returned by the session verifier on success) into the project's Principal shape. Owns the mapping between Clerk's role and organisation vocabulary and the project's `Principal.roles` and `Principal.organisationIds` arrays. Preserves the raw claims under `Principal.claims` as an escape hatch for the small number of cases where a downstream module genuinely needs a claim not covered by the reduction; that escape hatch is explicit and rare, not the default path.",
+  "responsibilities": [
+    "Expose `reduceClaims(rawClaims) -> Principal` where `Principal` is the shape `{ principalId, roles, organisationIds, claims }` (AC-9102-1).",
+    "Compute `principalId` from the Clerk user id claim (canonical name at the SDK version the project builds against); refuse a missing or empty user id with a stable-coded `PRINCIPAL_REDUCTION_FAILED` error (AC-9102-1).",
+    "Compute `roles` as the union of the principal's global-role claim and any organisation-role claims flattened to bare role strings; the ordering is not stable across versions but the set membership is (AC-9104-1).",
+    "Compute `organisationIds` as the array of Clerk organisation ids the principal is a member of at the time the session was issued (AC-9105-1).",
+    "Preserve `claims` as the raw claim bag verbatim; downstream modules that read `claims` do so through the authorisation adapter (TAC-1002) or the claims mapper module itself, not through direct field access in a handler (AC-9104-3)."
+  ],
+  "internalStructure": "One stateless pure function per named reduction step; the top-level `reduceClaims` composes them. The claim-key vocabulary Clerk uses is captured in one named constant record (`CLERK_CLAIM_KEYS`) at the top of the module, so a Clerk-side rename is a one-file change here rather than a codebase sweep.",
+  "interfaces": [],
+  "dependencies": [],
+  "tradeoffs": "Preserving `claims` as an escape hatch admits a class of downstream code that reads a raw Clerk claim rather than adding a mapping. The blueprint accepts that trade because the alternative (refusing every unmapped claim) forces the project to author every mapping up front, which fights the incremental-adoption posture the rcf-lite tier depends on. The discipline is that any downstream `.claims` read is a code-review-visible smell: if the same claim is read twice, add it to the reduction and stop reading through the escape hatch.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-auth-clerk/contributions/user-stories/security-auth-clerk-us-9101.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-clerk-US-9101",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A Clerk sign-in round-trip issues a Secure HttpOnly session cookie the middleware verifies",
+  "asA": "operator signing in through the project's Clerk-hosted sign-in surface",
+  "iWant": "a completed sign-in to leave my browser holding a Clerk-issued session cookie that the project's middleware verifies on the next request",
+  "soThat": "the project reasons about my identity on every subsequent request without me presenting credentials again",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9101-1",
+      "description": "After a successful sign-in against the project's Clerk development instance, the response carrying the sign-in completion sets a session cookie named `__session` with Secure, HttpOnly, and SameSite=Lax attributes.",
+      "given": "an operator who has completed sign-in on the project's Clerk-configured sign-in surface backed by a real Clerk development instance",
+      "when": "the browser inspects the cookie jar for the project's top-level domain immediately after the sign-in redirect completes",
+      "then": "a cookie named `__session` is present with `HttpOnly`, `Secure`, and `SameSite=Lax` flags set; no other cookie carries the session credential",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9101-2",
+      "description": "A subsequent request carrying the `__session` cookie to a route wired through the project's middleware boundary is treated as authenticated and the request-object carries the resolved principal.",
+      "given": "the `__session` cookie from AC-9101-1 and a project route wired through the middleware from TAC-1001",
+      "when": "the request is dispatched to the route",
+      "then": "the middleware attaches a `request.auth` object carrying `principalId`, `roles`, and `organisationIds`; the route handler observes `request.auth.principalId` as a non-empty string that matches the Clerk-issued user id for the signed-in operator",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9101-3",
+      "description": "The middleware verifies the session cookie against Clerk's session-verification surface on every request; a tampered cookie is rejected without a cached hit.",
+      "given": "a request whose `__session` cookie value has been altered by a single byte from the value in AC-9101-1",
+      "when": "the request reaches the middleware",
+      "then": "the middleware treats the request as unauthenticated; no `request.auth` object is attached; the verifier's audit log records one verification-failure event carrying the failure class and no cookie value",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1001-security-auth-clerk-middleware",
+    "TAC-1003-security-auth-clerk-session-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}