rcf-lite 0.12.0 → 0.14.0

package/blueprints/persistence-data-sqlite/guide/persistence-data-sqlite.md

@@ -0,0 +1,69 @@
+# Persistence blueprint guide
+
+## What it is
+
+A default durable-store floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a persistence pattern: how the store gets opened, how the schema evolves, how migrations apply, how a mid-migration crash is handled, how the store event log looks, how the boundary between the domain and the engine is drawn, and how backups are taken. The default engine is a single SQLite file in WAL mode; Postgres is a documented future variant behind the same facade.
+
+Concretely, the blueprint ships eleven requirements, eleven user stories (twenty-five acceptance criteria), four architecture components, and five architecture decision records. Two ADRs are `scope: global` on the topics `persistenceStore` (the engine choice) and `migrationDiscipline` (the forward-only refuse-newer-at-open posture); the other three are scope-local operational ADRs (event secrecy, store-boundary discipline, backup model) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a domain schema. The tables the project's own entities live in are project-authored, on top of the migration catalog the project maintains. The blueprint governs the store facade and the migration discipline; the domain shape is the project's own responsibility.
+
+Not an ORM. There is no query builder, no active-record layer, no framework-shaped abstraction between the facade's named verbs and the engine binding. Projects that want an ORM wire it inside the facade's implementation and preserve the outward verb surface.
+
+Not a Postgres blueprint. A future `persistence-postgres` blueprint (see 'when it does not fit') will contribute a Postgres-flavoured store TAC and an ADR on `persistenceStore` that deliberately conflicts with this one; until then, projects that need Postgres supersede ADR-601 with a project-level ADR.
+
+Not a logical dump story. Backups are file-level engine-native snapshots. Cross-engine migration and portable dumps are out of scope; projects that need them layer a dump runner beside the file-level backup runner.
+
+Not a connection pool. The facade holds one handle for the process lifetime. Projects that select an engine that benefits from a pool (Postgres) wire it inside the facade and preserve the outward interface.
+
+Not a replication story. Cross-region replication and hot standbys are engine-native decisions a project makes on top of the file-level backup story; the blueprint's backup runner does not orchestrate them.
+
+## When to reach for it
+
+Reach for the persistence-data-sqlite blueprint when:
+
+- The project is a small greenfield rcf-lite deployment (single deployable, one small team, one host or a small container fleet, no ops team standing by).
+- The domain has a natural relational shape (bounded set of entities with well-defined relationships) that SQL expresses cleanly.
+- Zero-infrastructure persistence is a feature (no database server to run, no connection pool to size, no network round trip between the process and the store).
+- The scale envelope is single-writer (concurrent writers negotiate through the same process, not across processes on different hosts) and the working set fits on the same host the process runs on.
+- The recovery story that fits is 'copy the file to safe storage, point a compatible build at the copy'; downtime-free file-level backup is the primary recovery path.
+
+## When it does not fit
+
+Do not reach for the persistence-data-sqlite blueprint when:
+
+- Multi-writer scale across hosts, hot standby replication, or cross-region durability are project requirements. A `persistence-postgres` blueprint (unshipped at v1.0.0, promotion signal: the third project asks for it) will own this. Until then, a project with these needs supersedes ADR-601 with a project-level ADR selecting the alternate engine and rewrites the migration catalog into the alternate dialect. The store facade contract, the migration runner contract, and the backup runner contract are preserved.
+- The working set is genuinely too large for a single host to hold with reasonable performance (tens of gigabytes of hot data, hundreds of writes per second sustained). At that scale the single-writer envelope becomes an operator experience problem, and Postgres (or the engine ADR-601 promotes) is the more defensible shape.
+- The domain shape is genuinely non-relational (opaque blob storage, event streams, time-series with a fixed retention model). A different blueprint (a KV-store blueprint, an event-sourced blueprint, a time-series blueprint) owns those shapes; supersede with a project-level ADR and skip this blueprint.
+- The project has a hard requirement for a portable schema-agnostic dump as the primary backup (compliance mandate, cross-engine restore drill). File-level backup is the primary recovery path in ADR-605; projects that need the logical dump layer it on top, or supersede ADR-605 with a project-level ADR.
+- The deploy target does not have a persistent filesystem the SQLite file can live on (ephemeral containers with no volume mount, serverless functions). The blueprint assumes a stable path the file survives at across deploys; a project without that assumption picks a different engine.
+
+The design brief `w-2026-07-28-029` originally scoped store-selection separately from the persistence-data-sqlite blueprint. The persistence-data-sqlite blueprint at v1.0.0 does not include a Postgres engine variant because the rcf-lite blueprint mechanism (Phase 1) has no variant/profile selector: two engine TACs contributed together are both applied, and both leave dangling tacIds references if only one is realised. Shipping SQLite-first with Postgres as a documented promotion path mirrors the security-auth-magic-link blueprint's keycloak-local deferral (see the auth guide) and keeps v1.0.0 shippable. A future `persistence-postgres` blueprint plus a mechanism-side variant concept (v1.1 candidate) is the natural evolution.
+
+## What a good outcome looks like
+
+A project applies the persistence-data-sqlite blueprint on a fresh tree, wires its own domain migration entries into the catalog (starting at version 1), realises the four TACs in project-authored FBSes, and lands on a deployed application where:
+
+- The boot sequence opens the store once through the facade; the opened event fires with the configured store path; the schemaVersion read returns the catalog's max version.
+- A schema change ships as a new numbered entry in the catalog; the next deploy's boot fires a migrated event whose applied array contains exactly the new version; consumer code reads through the facade at the new schema.
+- A SIGKILL of the process while a write is in flight leaves the store openable on the next boot, with committed writes intact and the in-flight transaction rolled back; the opened event fires cleanly, no corruption error surfaces.
+- A rollback to an older build against a store the newer build wrote fails at boot with a stable-coded refuse-newer error naming both versions; the operator diagnoses in one step (the older build cannot run against the newer store) and redeploys the newer build.
+- A backup runs on a cron against the live store; the backupCheckpoint event fires on the sink with the artifact path and the completion timestamp; a fresh process opens the artifact and reads the rows committed at or before the completion timestamp.
+- The auth event log, the wire-request log, and every other domain log surface holds no store-lifecycle records; the store's event log holds no domain-row values.
+
+## Operator decisions that remain open after apply
+
+- Engine choice (SQLite default, Postgres or KV-store or event-sourced by superseding ADR-601). Blueprint owns the facade contract on both sides of the boundary; project owns the engine.
+- Migration catalog layout (one file or one file per migration, under the schema-samples reference). Blueprint owns the shape; project owns the layout choice at whatever history size feels comfortable.
+- Store path or connection string (the configuration input to the open entry point). Blueprint owns the entry point signature; project owns the deployed value and how it is supplied (env var, config file, container volume).
+- Domain schema (every table beyond the schemaVersion bookkeeping table). Blueprint owns the migration discipline; project owns the tables.
+- Backup schedule and destination (cron cadence, artifact path template, retention). Blueprint owns the backup runner and its event; project owns when and where.
+- Restore drill cadence (a backup you have not restored is a hope, not a backup). Blueprint owns the artifact shape; project owns proving it works.
+- Log sink implementation (where opened / migrated / backupCheckpoint / closed events go). Blueprint owns the event shape and the metadata-only discipline; project owns the shipper.
+- Facade verb catalogue (the named CRUD verbs the domain needs). Blueprint owns the boundary discipline (named verbs, no raw-query passthrough); project owns the verbs.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every boot pays the migration runner's cost (a single SELECT against the bookkeeping table on a routine boot; the full migration cost on a schema evolution boot). Every facade verb is a project-authored function; the boundary discipline means new query shapes are a two-file edit (facade plus consumer) instead of a scattered raw SQL fragment. Every schema change is a numbered entry the project must not edit after shipping (a shipped migration is a fact of production; a correction is a new migration). The refuse-newer property makes rollback deploys fail at boot rather than silently; that safety comes at the cost of ops running the older build against the older data (or accepting that a data-shape change is one-way). File-level backup is fast and cheap but engine-native; a project that needs a portable dump layers it on top and keeps both in sync. The store's event log is deliberately minimal; a project that needs richer per-operation events (row-level audit trail, hot-path timing) authors those on top of the facade's verbs, not inside the store event sink.

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

@@ -0,0 +1,52 @@
+# Security auth Clerk blueprint (v1.1.0)
+
+The tenth content blueprint on the rcf-build-lite blueprint mechanism, category `security`. A Clerk-committed sibling to `security-auth-magic-link` on the `authModel` global topic: Clerk hosts the identity surface (users, sessions, sign-in UX, credential storage, MFA, account recovery); the project owns a framework-agnostic middleware boundary, a session verifier confined to one module, a Clerk-claim-to-project-verb authorisation adapter, and a reduced principal shape the rest of the codebase reasons against. Targeted at small greenfield rcf-lite projects that want hosted identity without building the user-and-session surface themselves; larger deployments supersede the vendor by superseding ADR-1001 with a project-level ADR and swapping the middleware and verifier adapters.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/security-auth-clerk
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `security` category; `rcf define blueprint remove security-auth-clerk` cleanly removes an unreferenced application.
+
+Composing with `security-auth-magic-link` (or any other blueprint contributing `scope: global` on `authModel`, which includes `application-spa` and `application-api-rest`) raises a `globalAdrTopic` conflict at add time. The four documented resolutions apply (adopt the incoming, keep the existing, project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add). See `docs/topics.md` for the deliberate-conflict statement.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `security`, and the 29 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 9 REQs, 11 USs (25 ACs), 4 TACs, 5 ADRs, all schema-valid and namespaced (`security-auth-clerk-REQ-001` prefix family; `ADR-1001-security-auth-clerk-auth-model` suffix family) |
+| React-family sample | `assets/wiring/clerk-provider-react.md` | The shape of a `ClerkProvider` wiring in a React-family client tier: where the provider mounts, what the SPA blueprint's session-and-redirect posture composes with |
+| Vue-family sample | `assets/wiring/clerk-provider-vue.md` | The same shape rendered for a Vue-family client tier so the operator can pattern-match without a framework translation step |
+| Middleware sample (Node) | `assets/middleware/node-middleware-shape.md` | The framework-agnostic middleware boundary contract (`verify(request)`), with adapter samples for Express and Fastify |
+| Middleware sample (Workers) | `assets/middleware/workers-fetch-shape.md` | The Cloudflare Workers fetch-handler adapter around the same `verify(request)` contract; a project on Workers picks up this file, a project on Node picks up the Node sample |
+| Workers wrangler integration | `assets/wiring/workers-wrangler-toml-shape.md` | The wrangler.toml overlay a Workers deployer applies: `nodejs_compat`, `CLERK_SIGN_IN_URL`, the Clerk secret names, and the `run_worker_first` posture the auth-gate bypass finding required |
+| Role-claim mapping | `assets/authorisation/role-claim-mapping-sample.md` | A worked verb-to-role mapping-table example, with the reduction from Clerk's `org:role` claim shape into the project's `roles` array |
+| Guide | `guide/security-auth-clerk.md` | Operator-facing: when to use it, when not, the promotion signals for the OAuth2 and Keycloak siblings, the operator decisions that remain open, the cost-honesty paragraph |
+| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (Clerk-hosted identity, the `__session` cookie transport, the middleware boundary shape, the authorisation-adapter contract, the claims-mapping discipline, the session-lifecycle posture, the `signInStrategy` config surface, the read-only provisioning posture, the delegated rate-limit posture, the accountBound runtime-verify posture); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: a Clerk SDK version pin (the blueprint fixes the shape, not the version; the project's package manifest pins the SDK); MFA configuration (Clerk owns MFA at the hosted surface; the blueprint delegates); a Clerk-webhook consumer contract (out of scope for the default; a project that needs one adds one project-authored TAC and one scope-local ADR); a project-side user table or organisation table (Clerk is authoritative; a project that mirrors state into a local table does so through a project-authored consumer, not through this blueprint); a project-side rate limiter or anti-enumeration defence on the sign-in flow (Clerk-delegated per REQ-007); a fixed sign-in strategy choice (fixed shape per REQ-005, choice is project-owned); an OAuth2 provider list (that is the sibling `security-auth-oauth2` blueprint's territory when it ships); a Keycloak realm configuration (that is `security-auth-keycloak`'s territory when it ships).
+
+## The one global decision
+
+ADR-1001-security-auth-clerk-auth-model ships `scope: global` on topic `authModel`. This is the project's single decision on how identity is proven, where credentials live, and what the wire credential looks like. Composing with `security-auth-magic-link`, `application-spa`, `application-api-rest`, or any future `security-auth-*` blueprint conflicts here by design and expects a project-level ADR resolution. The composition-precedent (SPA + REST on `errorEnvelope` and `authModel`) is the same pattern.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, and the AC id band allocation (security-auth-clerk owns 9101-9899, ADR/TAC suffix block 10xx / 1001-1099; this is the first blueprint whose ADR/TAC suffix crosses into four digits).
+
+## Quality bar
+
+A framework-agnostic middleware boundary as the single point of authentication decision on the server; every runtime path that needs the caller's identity reads the reduced Principal shape attached at `request.auth`; the Clerk SDK is imported by exactly two modules (middleware wiring and session verifier); the wire credential is Clerk's `__session` cookie with Secure, HttpOnly, and SameSite=Lax; a tampered cookie is rejected with an audit event carrying no cookie value; every authorisation check goes through the adapter's `can` or `assert` and speaks in project verbs, never in Clerk role or claim vocabulary; role-based UI slots render only when the adapter grants the verb and the corresponding server-side handler enforces the same verb through `assert`; a Clerk-initiated sign-out invalidates subsequent requests within the documented `revocationCheckIntervalMs`; the sign-in surface applies no project-authored rate limiter (Clerk-delegated); user and organisation mutations against Clerk are confined to a provisioning script directory (not a request handler); the `signInStrategy` config surface fixes the shape not the choice; runtime-verify ACs are `accountBound` and skip with a stable-coded reason when Clerk is unreachable rather than passing on a fake. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0, given the same posture the security-secrets-management blueprint takes: every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable (cookie-jar inspection for the transport contract, `request.auth` shape inspection for the principal reduction, source-tree import scans for the Clerk-SDK boundary, `can` and `assert` return values for the authorisation adapter, page-render inspection for the UI-slot gating, live sign-out plus replay for the revocation behaviour, live rate-limit burst against Clerk for the delegation posture, and source-tree call-site scans for the read-only provisioning posture). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational surface a project must own is the middleware boundary implementation for its specific HTTP framework (an Express shim, a Fastify plugin, a Workers fetch wrapper) plus the vendor adapter inside the session verifier; those responsibilities are stated as TAC interfaces, not as smuggled runtime probes. Two ACs whose runtime observability depends on the operator's Clerk deployment reachability are AC-9107-2 (revocation propagation window) and AC-9109-2 (Clerk-documented rate-limit response shape): both are accountBound and the runtime-verify skip mechanism named on AC-9110-2 covers them when Clerk is unreachable.

package/blueprints/security-auth-clerk/assets/authorisation/role-claim-mapping-sample.md

@@ -0,0 +1,99 @@
+# Verb-to-role mapping sample
+
+A worked example of the project-authored mapping table the authorisation adapter (TAC-1002) consumes, plus a worked example of the claims-mapper reduction (TAC-1004) that turns Clerk's raw claim shape into the `Principal.roles` and `Principal.organisationIds` the adapter reasons against.
+
+## The mapping table
+
+The mapping table is a project-authored module the adapter loads once at construction. Verbs are project vocabulary; roles are the strings Clerk propagates. A verb absent from the table evaluates to `false` on `can` and throws on `assert`.
+
+```
+// src/authz/mapping-table.ts
+export const mappingTable = {
+  // Editorial workflow
+  'article.read':   { roles: ['reader', 'editor', 'admin'] },
+  'article.edit':   { roles: ['editor', 'admin'] },
+  'article.delete': { roles: ['admin'] },
+
+  // Billing surface
+  'billing.invoice.view': { roles: ['billing', 'admin'] },
+  'billing.invoice.void': { roles: ['admin'] },
+
+  // Admin dashboard
+  'admin.dashboard.view':  { roles: ['admin'] },
+  'admin.users.view':      { roles: ['admin'] },
+  'admin.users.impersonate': { roles: ['admin'] },
+};
+```
+
+## The claims-mapper reduction
+
+The claims mapper reads a raw Clerk claim bag (as returned by the session verifier on success) and produces the `Principal` the adapter reasons against. The `CLERK_CLAIM_KEYS` constant is the one place in the module that hard-codes Clerk-side claim key strings; a Clerk-side rename is a one-file change here.
+
+```
+// src/auth/claims-mapper.ts
+const CLERK_CLAIM_KEYS = {
+  userId: 'sub',                     // Clerk emits the user id on the JWT-standard sub claim
+  organisationMemberships: 'org_memberships',
+  organisationId: 'org_id',
+  organisationRole: 'org_role',
+  publicMetadata: 'public_metadata',
+  // Adjust these values against Clerk's currently-canonical claim vocabulary at
+  // the SDK version the project builds against.
+};
+
+export function reduceClaims(rawClaims) {
+  const principalId = rawClaims?.[CLERK_CLAIM_KEYS.userId];
+  if (!principalId || typeof principalId !== 'string') {
+    const err = new Error('PRINCIPAL_REDUCTION_FAILED: missing or invalid user id claim');
+    err.code = 'PRINCIPAL_REDUCTION_FAILED';
+    throw err;
+  }
+
+  const orgMemberships = rawClaims[CLERK_CLAIM_KEYS.organisationMemberships] ?? [];
+  const organisationIds = orgMemberships.map((m) => m[CLERK_CLAIM_KEYS.organisationId]);
+  const orgRoles = orgMemberships.map((m) => m[CLERK_CLAIM_KEYS.organisationRole]);
+
+  // Global roles (from publicMetadata.roles by convention) plus per-org roles
+  // flatten into one bare-string roles array; the set membership is what the
+  // adapter reasons against.
+  const globalRoles = rawClaims?.[CLERK_CLAIM_KEYS.publicMetadata]?.roles ?? [];
+  const roles = Array.from(new Set([...globalRoles, ...orgRoles]));
+
+  return {
+    principalId,
+    roles,
+    organisationIds,
+    claims: rawClaims,
+  };
+}
+```
+
+## Downstream code speaks in verbs
+
+```
+// src/handlers/article-edit.ts
+import { assert } from '../authz/adapter';
+
+export async function handleArticleEdit(request, response) {
+  assert(request.auth, 'article.edit', { organisationId: request.body.organisationId });
+  // If assert did not throw, the caller is allowed.
+  // Proceed with the edit.
+}
+```
+
+Never:
+
+```
+// ANTI-PATTERN: bypasses the adapter, reads Clerk vocabulary in a handler.
+if (request.auth.roles.includes('editor') || request.auth.roles.includes('admin')) {
+  // ...
+}
+```
+
+The scan on AC-9104-3 catches the anti-pattern; the discipline is that every check goes through `can` or `assert`.
+
+## Notes
+
+- The mapping table is small enough at project boot that adding a verb is a one-line edit; a project whose table grows past a hundred verbs is signal to consolidate at a coarser verb grain, not to bypass the adapter.
+- The organisation-scoping subject shape (`{ organisationId }` on the second argument of `assert`) is the blueprint's default. Projects that need finer subject shapes (record-owner predicates, hierarchical org trees) layer them above the adapter's return value rather than replacing the adapter.
+- The `publicMetadata.roles` convention above is one of several ways to propagate global roles from Clerk into the session; the specific convention is a Clerk-configuration choice the operator makes on the Clerk dashboard, and the claims mapper adjusts accordingly.

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/middleware/workers-fetch-shape.md

@@ -0,0 +1,123 @@
+# Workers fetch-handler shape
+
+The Cloudflare Workers adapter for the middleware boundary (TAC-1001). Chooser: a project on Node picks up `node-middleware-shape.md` (Express or Fastify adapter around `verify(request)`); a project on Workers picks up this file. Both adapters wrap the same `verify` contract; the reduced `Principal` shape the project reasons against downstream is identical.
+
+## Why Workers gets its own sample
+
+The framework-agnostic `verify(request)` contract (TAC-1001 responsibility 1) already carries onto Workers. What differs is mechanical:
+
+- **Request object.** The handler receives a Fetch API `Request`; header reads go through `request.headers.get('cookie')`, not `request.headers.cookie`. There is no `req.accepts()`; content-negotiation is a header inspection on `accept`.
+- **Response shape.** Handlers return a Fetch API `Response` synchronously; there is no `res.status().json()` chain. The refusal paths return `new Response(...)` bodies.
+- **Secret transport.** The Clerk secret arrives on `env.CLERK_SECRET_KEY` (and `env.CLERK_PUBLISHABLE_KEY`) at request time, not from `process.env` at module load. The `createVerify` factory therefore runs inside the fetch handler, not at module top-level; a per-request construction is cheap because Clerk's `authenticateRequest` is the network cost, not the client construction.
+- **Session-cookie parse.** Clerk's `@clerk/backend` `authenticateRequest(request, ...)` reads the `__session` cookie off the Fetch `Request` itself; no manual cookie header parsing is needed at the middleware seam. The pre-check below (a substring test for `__session=`) is a fast-path refusal so unauthenticated hits do not incur an SDK round trip.
+
+## The Workers fetch adapter
+
+```
+// src/auth/adapters/workers.mjs
+import { createSessionVerifier } from '../session-verifier.mjs';
+import { reduceClaims } from '../claims-mapper.mjs';
+
+function jsonResponse(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' }
+  });
+}
+
+export function createVerify({ clerkSecretKey, clerkPublishableKey, auditSink, clock }) {
+  const verifier = createSessionVerifier({
+    clerkSecretKey,
+    clerkPublishableKey,
+    auditSink,
+    clock
+  });
+
+  return async function verify(request) {
+    // Fast-path refusal without an SDK round trip.
+    const cookieHeader = request.headers.get('cookie') ?? '';
+    if (!/(?:^|;\s*)__session=/.test(cookieHeader)) {
+      return { authenticated: false, reason: 'no-session-cookie' };
+    }
+    // Clerk's authenticateRequest reads the __session cookie off the Request
+    // and does the vendor-verified session verification server-side.
+    const result = await verifier.verifySessionCookie(null, request);
+    if (!result.valid) {
+      return { authenticated: false, reason: result.reason ?? 'invalid-session' };
+    }
+    let principal;
+    try {
+      principal = reduceClaims(result.claims);
+    } catch (err) {
+      return { authenticated: false, reason: 'claims-map-failed' };
+    }
+    return { authenticated: true, principal };
+  };
+}
+
+// One-file adapter that a route dispatcher inside `fetch()` can call.
+// The blueprint does not mandate any particular router; the shape below is
+// the seam a project's router calls into. Route dispatch stays a project
+// concern.
+export function workersRequireAuth({ verify }) {
+  return async function requireAuth(request) {
+    const result = await verify(request);
+    if (result.authenticated) {
+      return { ok: true, principal: result.principal };
+    }
+    const wantsHtml = (request.headers.get('accept') ?? '').includes('text/html');
+    const refusal = wantsHtml
+      ? Response.redirect(new URL('/sign-in', request.url).toString(), 302)
+      : jsonResponse({ error: 'unauthenticated', reason: result.reason }, 401);
+    return { ok: false, refusal };
+  };
+}
+```
+
+## Wiring it inside a fetch handler
+
+```
+// src/worker.mjs
+import { createVerify, workersRequireAuth } from './auth/adapters/workers.mjs';
+
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+
+    // Public probes and the sign-in redirect run before the auth gate.
+    if (url.pathname === '/health' && request.method === 'GET') {
+      return new Response(null, { status: 200 });
+    }
+    if (url.pathname === '/sign-in') {
+      return Response.redirect(env.CLERK_SIGN_IN_URL, 302);
+    }
+
+    // Auth-gated routes go through the middleware boundary.
+    const verify = createVerify({
+      clerkSecretKey: env.CLERK_SECRET_KEY,
+      clerkPublishableKey: env.CLERK_PUBLISHABLE_KEY,
+      auditSink: (evt) => console.log(JSON.stringify({ ...evt, kind: 'audit' })),
+      clock: () => new Date()
+    });
+    const requireAuth = workersRequireAuth({ verify });
+
+    if (url.pathname.startsWith('/api/')) {
+      const authResult = await requireAuth(request);
+      if (!authResult.ok) return authResult.refusal;
+      // request.auth is a Fetch API surface convention the project owns:
+      // attach the principal onto a locals object the route handler reads.
+      return dispatchApi(url, request, env, ctx, authResult.principal);
+    }
+
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+## Notes
+
+- **Attachment convention.** The Fetch `Request` is immutable, so the middleware cannot literally set `request.auth`. The Workers adapter's shape returns `{ ok, principal, refusal }` and the route handler carries the `principal` forward as a function argument. AC-9101-2's runtime observation binds against the reduced `Principal` shape on the successful path either way; the mechanism of attachment is framework-shaped, not contract-shaped.
+- **SDK boundary discipline.** Only `session-verifier.mjs` and this adapter's `createVerify` factory import from `@clerk/backend`. AC-9102-2's source-tree scan still holds on Workers; the two-module allowance covers the Workers case unchanged.
+- **Refusal shape.** The 401 JSON body for API-shaped routes and the 302 redirect for HTML-shaped routes match the Node adapters. AC-9103-2 and AC-9103-3 read the same shapes.
+- **Static-asset ordering.** The wrangler `[assets]` binding serves files before the fetch handler runs by default, which silently bypasses this middleware on any URL that also resolves to a static file. The `run_worker_first` posture on any auth-gated route is a wrangler-configuration concern; the workers wrangler.toml sample carries the fix.
+- **Runtime.** The verifier calls into `@clerk/backend` which needs Node built-ins; wrangler's `compatibility_flags = ["nodejs_compat"]` is the enabling flag on the wrangler side. This is a runtime-config concern, not a middleware-shape concern.

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/assets/wiring/workers-wrangler-toml-shape.md

@@ -0,0 +1,51 @@
+# Workers wrangler.toml integration note
+
+The wrangler-side configuration a project needs when the Clerk middleware runs inside a Cloudflare Worker. This is a composition boundary between this blueprint (owns the middleware and session-verifier contracts) and `deploy-cloudflare-workers` (owns the wrangler shape); the notes below are the Clerk-specific overlay a Workers deployer applies on top of that blueprint's wrangler-toml sample.
+
+## The Clerk-specific overlay
+
+```
+# wrangler.toml - Clerk-specific overlay
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+# Public URL of the Clerk-hosted sign-in surface. Not a secret; safe to
+# commit. The middleware's HTML refusal path redirects here.
+CLERK_SIGN_IN_URL = "https://<clerk-subdomain>.accounts.dev/sign-in"
+
+[assets]
+directory = "./public"
+binding = "ASSETS"
+# Every auth-gated route that could collide with a static file must appear
+# here, or the assets binding serves the static file BEFORE the fetch
+# handler runs and the middleware is silently bypassed. See the composition
+# note below.
+run_worker_first = ["/api/*", "/sign-in"]
+```
+
+Secrets are declared by name only, in the deploy blueprint's discipline: no `[secrets]` block in wrangler.toml (that block is decorative and not honoured by wrangler at 4.x, per the deploy blueprint's F-009 fix), and no value in any committed file. The two names the Clerk middleware reads are:
+
+- `CLERK_SECRET_KEY` - server-side Clerk API key, read as `env.CLERK_SECRET_KEY` by `session-verifier.mjs`.
+- `CLERK_PUBLISHABLE_KEY` - Clerk publishable key, read as `env.CLERK_PUBLISHABLE_KEY` by `session-verifier.mjs`.
+
+Bootstrap-and-steady-state guidance for setting the values lives on the deploy blueprint's `bootstrap-vs-steady-state.md` asset; the shape is the same for both Clerk secrets.
+
+## The auth-gate bypass finding
+
+The default `[assets]` binding on a Cloudflare Worker serves any file in the assets directory at its path before the Worker's `fetch` handler runs. If an auth-gated route (`/notes` for a UI page, `/api/notes` for an API surface) collides with a static file at the same path, the static file is served without ever hitting the middleware. This is a silent auth bypass at ship time; a project ships assuming the middleware protects `/notes` and only finds out on the first live probe that `/notes` returned the HTML shell to an unauthenticated request.
+
+The `run_worker_first` array is the wrangler-side fix: every path listed there is routed through the fetch handler before the assets binding gets a chance. A project on the middleware boundary shape should list every auth-gated route class on the list.
+
+The composition responsibility is shared: `deploy-cloudflare-workers` teaches the mechanism (`run_worker_first` in wrangler-toml-shape.md, its US-12101 AC-12101-4 is the runtime-observable acceptance), and this blueprint teaches which routes need it (every auth-gated one on the project's HTTP surface). Neither blueprint carries the project's route list; that emerges from the project's own routing surface.
+
+## What is NOT taught here
+
+- **Which routes are gated.** The blueprint fixes the middleware boundary shape and the auth model. The concrete route list is a project decision the wrangler.toml integrates against.
+- **How the assets binding composes with static-first vs worker-first per-path routing.** The rules and mechanism belong to the deploy blueprint.
+- **Custom-domain vs workers.dev-only production URL.** Same: deploy blueprint concern. The Clerk overlay above is identical either way.
+
+## Notes
+
+- The `CLERK_SIGN_IN_URL` var is not a secret. Committing it in `wrangler.toml [vars]` is the default; a project that wants the value to differ across environments moves it to an environment-specific `[env.<name>.vars]` block per wrangler's standard shape.
+- The `nodejs_compat` flag is required because `@clerk/backend` relies on Node built-ins. Without it, the Worker fails to start with a runtime error naming the missing built-in.
+- Reading the secret at request time from `env` (not at module top-level from `process.env`) is what the workers-fetch-shape sample's `createVerify` factory does; the two files together are the enabling shape.