rcf-lite 0.12.0 → 0.14.0

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

@@ -0,0 +1,38 @@
+{
+  "usId": "security-auth-clerk-US-9102",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The middleware reduces a verified Clerk session into a stable in-process principal shape",
+  "asA": "downstream request handler in the project",
+  "iWant": "to read a single stable principal shape from every authenticated request rather than a raw Clerk claim bag",
+  "soThat": "my handler's authorisation checks and audit logging speak one project vocabulary instead of Clerk's claim-key vocabulary",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9102-1",
+      "description": "For every authenticated request, `request.auth` is an object whose keys are exactly `{ principalId: string, roles: string[], organisationIds: string[], claims: object }`.",
+      "given": "an authenticated request that has passed the middleware",
+      "when": "a handler reads `request.auth`",
+      "then": "the observed object's own-property keys are the set `{principalId, roles, organisationIds, claims}` with no additional own properties; `principalId` is a non-empty string; `roles` and `organisationIds` are arrays of strings; `claims` is an object carrying the raw Clerk claim bag for the escape-hatch case",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9102-2",
+      "description": "A source-tree scan finds no import of Clerk's SDK outside the middleware module (TAC-1001) and the session verifier module (TAC-1003).",
+      "given": "the project's source tree after the blueprint's TACs are realised",
+      "when": "a scan enumerates every import of `@clerk/*` or the Clerk server SDK equivalent",
+      "then": "every match resolves to a file inside the middleware module directory or the session verifier module directory; no other project file imports Clerk directly",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1001-security-auth-clerk-middleware",
+    "TAC-1003-security-auth-clerk-session-verifier",
+    "TAC-1004-security-auth-clerk-claims-mapper"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-clerk-US-9103",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A protected route admits authenticated requests and refuses unauthenticated ones",
+  "asA": "operator navigating the deployed application",
+  "iWant": "routes marked as protected to serve me when I hold a valid session and to refuse me when I do not",
+  "soThat": "the middleware boundary is what actually gates access rather than a comment on a handler",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9103-1",
+      "description": "A request to a protected route carrying a valid `__session` cookie for a signed-in operator receives the handler's response with status 200 (or the handler's success status for the specific route).",
+      "given": "a protected route wired through the middleware with a role gate of `authenticated`",
+      "when": "an authenticated request from a signed-in Clerk-development-instance user reaches the route",
+      "then": "the middleware runs the handler; the response status is the handler's declared success status (200 for a GET); the response body is what the handler returns",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9103-2",
+      "description": "A request to the same protected route carrying no `__session` cookie is refused at the middleware boundary before the handler runs.",
+      "given": "the same protected route from AC-9103-1",
+      "when": "a request without a `__session` cookie reaches the route",
+      "then": "the response status is 401 (for an API-shaped route) or a 302 redirect to the sign-in surface (for a page-shaped route); the handler is never invoked; the response body carries no principal or session information",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9103-3",
+      "description": "The middleware refuses on expired sessions the same way it refuses on missing sessions.",
+      "given": "a request carrying a `__session` cookie whose corresponding Clerk session has been ended (via administrative revoke on the Clerk dashboard, or by expiry)",
+      "when": "the request reaches a protected route",
+      "then": "the middleware refuses with the same status and shape as AC-9103-2; the handler is never invoked",
+      "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"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "security-auth-clerk-US-9104",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The authorisation adapter maps Clerk roles onto project verbs",
+  "asA": "handler that needs to know whether the caller is allowed to perform an operation",
+  "iWant": "to call `can(principal, verb)` and receive a boolean decision computed from a project-authored mapping table",
+  "soThat": "my handler's authorisation check is legible in project vocabulary and swap-safe if the identity vendor changes",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9104-1",
+      "description": "The authorisation adapter's `can(principal, verb)` returns `true` when the mapping table grants the verb to at least one role the principal holds, and `false` otherwise.",
+      "given": "a mapping table declaring that the verb `article.edit` is granted to roles `editor` and `admin`; a principal whose `roles` array is `['editor']`",
+      "when": "the handler calls `can(principal, 'article.edit')`",
+      "then": "the call returns `true`; a second call `can(principal, 'billing.invoice.void')` (a verb not granted to `editor`) returns `false`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9104-2",
+      "description": "The authorisation adapter's `assert(principal, verb)` returns silently on a granted verb and throws a stable-coded `AUTHZ_FORBIDDEN` error naming the verb on a refused one; the error carries no principal claim material.",
+      "given": "the same mapping table and principal as AC-9104-1",
+      "when": "the handler calls `assert(principal, 'article.edit')` and then `assert(principal, 'billing.invoice.void')`",
+      "then": "the first call returns without throwing; the second call throws an `AUTHZ_FORBIDDEN` error whose message contains the string `billing.invoice.void` and whose serialised form contains no role name, no organisation id, and no Clerk claim key or value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9104-3",
+      "description": "A source-tree scan finds no handler code that reads `principal.roles` or `principal.claims` directly; every authorisation check goes through `can` or `assert`.",
+      "given": "the project's source tree after the blueprint's TACs are realised",
+      "when": "a scan enumerates every reference to `.roles`, `.organisationIds`, or `.claims` on an object whose type resolves to the project's `Principal` shape",
+      "then": "every match sits inside the authorisation adapter module (TAC-1002) or the claims-mapper module (TAC-1004); no handler file reads a claim directly",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1002-security-auth-clerk-authorisation-adapter",
+    "TAC-1004-security-auth-clerk-claims-mapper"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-clerk-US-9105",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The authorisation adapter maps organisation membership onto scoped access",
+  "asA": "handler serving a resource that belongs to an organisation",
+  "iWant": "to call `can(principal, verb, subject)` where the subject carries an `organisationId` and receive a decision that considers organisation membership",
+  "soThat": "an operator who is admin in one organisation cannot read another organisation's resources by holding a global admin role in Clerk's dashboard",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9105-1",
+      "description": "The adapter's `can(principal, verb, subject)` returns `true` only when the mapping table grants the verb to a role the principal holds AND (when the subject carries an `organisationId`) the principal's `organisationIds` array includes that id.",
+      "given": "a principal whose `organisationIds` is `['org-A']` and whose `roles` is `['admin']`; a mapping table granting the verb `document.read` to `admin`",
+      "when": "the handler calls `can(principal, 'document.read', { organisationId: 'org-A' })` and then `can(principal, 'document.read', { organisationId: 'org-B' })`",
+      "then": "the first call returns `true`; the second call returns `false`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9105-2",
+      "description": "When the subject does not carry an `organisationId`, the adapter falls back to role-only evaluation; a role-granted verb succeeds regardless of the principal's organisation membership set.",
+      "given": "the same principal and mapping table as AC-9105-1",
+      "when": "the handler calls `can(principal, 'document.read', {})` and `can(principal, 'document.read')`",
+      "then": "both calls return `true`; no organisation membership check is performed",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1002-security-auth-clerk-authorisation-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-clerk-US-9106",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A role-gated UI slot renders per the authorisation adapter's decision",
+  "asA": "operator viewing a page that carries UI elements gated by verb",
+  "iWant": "elements I am allowed to see to render and elements I am not allowed to see to be absent from the DOM",
+  "soThat": "the UI does not mislead me about what I can do, and does not tempt exploit attempts by revealing forbidden verbs behind disabled buttons",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9106-1",
+      "description": "A UI slot wired to a project verb through the adapter's `can` decision is present in the rendered DOM when `can` returns `true` for the current principal and absent when `can` returns `false`.",
+      "given": "a page carrying a UI slot gated on the verb `article.delete`, and a principal for whom `can(principal, 'article.delete')` returns `true`",
+      "when": "a page-render probe fetches the page as the signed-in operator and inspects the rendered DOM",
+      "then": "the DOM contains the slot's rendered element; a subsequent render as a signed-in operator whose principal returns `false` for the same verb produces a DOM in which the slot is absent (no hidden node, no disabled control, no aria-hidden variant)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9106-2",
+      "description": "The UI slot's absence is not the only defence; the corresponding server-side handler also refuses via `assert` on the same verb when the caller lacks it.",
+      "given": "the same page and verb from AC-9106-1, and a principal whose `can` returns `false`",
+      "when": "a request bypassing the UI (direct API call) attempts the verb's underlying action",
+      "then": "the server-side handler's `assert(principal, 'article.delete')` throws `AUTHZ_FORBIDDEN`; the response status is 403 and no state mutation occurs",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1002-security-auth-clerk-authorisation-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "security-auth-clerk-US-9107",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sign-out invalidates the session on Clerk and the middleware refuses subsequent requests",
+  "asA": "operator who wants sign-out to actually mean the session is gone",
+  "iWant": "the Clerk-initiated sign-out to invalidate my session such that a subsequent request carrying the same cookie is refused",
+  "soThat": "a leaked cookie stops working the moment I have signed out",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9107-1",
+      "description": "After a Clerk-initiated sign-out (client-side call to Clerk's `signOut` or an equivalent server-invoked revocation), a request to a protected route carrying the pre-sign-out `__session` cookie is refused by the middleware.",
+      "given": "an operator who has signed in and holds a valid `__session` cookie, then invokes the project's sign-out surface which calls Clerk's `signOut`",
+      "when": "a subsequent request replays the same `__session` cookie against a protected route",
+      "then": "the middleware treats the request as unauthenticated; the response status is 401 (API) or a redirect (page); the handler is never invoked",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9107-2",
+      "description": "An administrative revoke performed on the Clerk dashboard has the same effect: a request replaying the revoked session's cookie is refused.",
+      "given": "a valid `__session` cookie for a signed-in operator whose session has just been revoked via the Clerk dashboard",
+      "when": "a request replays that cookie against a protected route",
+      "then": "the middleware refuses per AC-9107-1; no cache the middleware or session verifier holds keeps the revoked session alive beyond one revocation-propagation cycle (the verifier's `revocationCheckIntervalMs`, documented in ADR-1005; the value is bounded and stated)",
+      "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"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-clerk-US-9108",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The signInStrategy config surface fixes the shape not the choice",
+  "asA": "operator configuring which sign-in strategies the project's Clerk instance offers",
+  "iWant": "a single config record on the project side that names the primary and alternate strategies",
+  "soThat": "changing the enabled strategy set is a config edit and a Clerk-dashboard change rather than a codebase search-and-replace",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9108-1",
+      "description": "The project exposes a single `signInStrategy` config record whose shape is `{ primary: string, alternates: string[] }` and whose values are Clerk's currently-documented strategy identifiers.",
+      "given": "the project's configuration surface at boot",
+      "when": "the sign-in surface reads its strategy configuration",
+      "then": "the surface reads exactly one `signInStrategy` config record; the record's own-property keys are exactly `{primary, alternates}`; `primary` is a non-empty string; `alternates` is an array of strings",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9108-2",
+      "description": "A source-tree scan finds no hard-coded strategy string outside the config module.",
+      "given": "the project's source tree after the blueprint's TACs are realised",
+      "when": "a scan enumerates literal string matches for the strategy identifiers known to Clerk's strategy enumeration at build time",
+      "then": "every match resolves to the single config module or to test fixtures; no sign-in surface, no middleware, no handler carries a hard-coded strategy string",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1001-security-auth-clerk-middleware"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-clerk-US-9109",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Rate-limiting and anti-enumeration on the sign-in flow are delegated to Clerk",
+  "asA": "operator triggering repeated sign-in attempts",
+  "iWant": "the project to leave rate-limiting and anti-enumeration to Clerk rather than layering a second rate limiter on top",
+  "soThat": "the sign-in surface's rate-limit behaviour is one system's behaviour and does not confuse users with two competing back-off timers",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9109-1",
+      "description": "The project's sign-in surface applies no project-authored rate limiter, throttle, or enumeration defence to the sign-in POST or its equivalent Clerk-initiated flow.",
+      "given": "the project's request-handling surface for the sign-in route(s) that front Clerk's sign-in flow",
+      "when": "a source-tree scan enumerates rate-limit middleware, throttle wrappers, or enumeration-defence checks bound to the sign-in surface",
+      "then": "the scan returns zero matches on the sign-in surface; the same scan on other surfaces (a public API, a webhook receiver) is unaffected by this AC",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9109-2",
+      "description": "Repeated sign-in attempts against the project's Clerk development instance exhibit Clerk's documented rate-limit behaviour, not a project-authored variant.",
+      "given": "a burst of N sign-in attempts (N chosen to exceed Clerk's documented per-address threshold for the strategy) against the project's Clerk-development instance",
+      "when": "the burst is dispatched and the responses are collected",
+      "then": "the observed refusal shape (status code, response body error identifier, retry-after header if any) matches Clerk's documented rate-limit response for the strategy; no project-authored refusal shape appears in the burst",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1001-security-auth-clerk-middleware"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "security-auth-clerk-US-9110",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The project runtime does not create, update, or delete users or organisations on Clerk",
+  "asA": "operator running the deployed application",
+  "iWant": "the project's request lifecycle to leave user and organisation management to Clerk's own surfaces",
+  "soThat": "identity state has one authoritative home and the project does not accumulate a split-brain user table that drifts from Clerk",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9110-1",
+      "description": "A source-tree scan finds no request-lifecycle call to Clerk's user-create, user-update, user-delete, organisation-create, organisation-update, or organisation-delete Backend API endpoints outside a project-authored provisioning script directory.",
+      "given": "the project's source tree after the blueprint's TACs are realised",
+      "when": "a scan enumerates every call to Clerk's Backend API mutation endpoints",
+      "then": "every match resolves to a file under a directory conventionally named `scripts/provisioning/` (or the project's declared equivalent); no match resolves to a request handler, a middleware, or a runtime module served by the project's HTTP surface",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9110-2",
+      "description": "The middleware's session verifier and claims mapper do not mutate Clerk state as a side effect of verification; a scan of the session verifier module finds no calls to Clerk Backend API mutation endpoints.",
+      "given": "the session verifier module (TAC-1003) and the claims mapper module (TAC-1004) after the blueprint's TACs are realised",
+      "when": "a scan enumerates every Clerk SDK call the two modules make",
+      "then": "every match resolves to a read-shaped operation (session verification, organisation membership lookup); no match resolves to a Clerk mutation endpoint",
+      "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"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "security-auth-clerk-US-9111",
+  "prdId": "PRD-001",
+  "reqId": "security-auth-clerk-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Clerk-reachable acceptance criteria are marked accountBound and skip with a stable-coded reason when Clerk is unreachable",
+  "asA": "operator running the project's runtime-verify suite in a CI environment without Clerk reachability",
+  "iWant": "the acceptance criteria that depend on a live Clerk development instance to skip with a documented reason rather than pass on a fake",
+  "soThat": "the ship gate does not falsely record identity behaviour as verified when the verification path never actually ran",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-9111-1",
+      "description": "Every test case bound to an AC whose runtime observability requires a live Clerk session (AC-9101-1, AC-9101-2, AC-9101-3, AC-9103-1, AC-9103-2, AC-9103-3, AC-9107-1, AC-9107-2, AC-9109-2) carries an `accountBound` marker on the test harness.",
+      "given": "the project's runtime-verify test harness at manifest-generation time",
+      "when": "the harness enumerates test cases and their bound ACs",
+      "then": "every TC bound to one of the enumerated ACs above has the `accountBound` marker set; TCs bound to other ACs (source-tree scans, in-process principal-shape assertions, adapter unit-shaped checks) do not carry the marker",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-9111-2",
+      "description": "A runtime-verify run against a target without Clerk reachability records the accountBound TCs as skipped with the stable-coded reason `AUTH_CLERK_UNREACHABLE`, not as passed.",
+      "given": "a runtime-verify run configured with no reachable Clerk publishable/secret keys or with Clerk's session-verification surface unreachable",
+      "when": "the run enumerates accountBound TCs",
+      "then": "every accountBound TC records outcome `skipped` with reason field equal to `AUTH_CLERK_UNREACHABLE`; the ship gate report flags the skipped set; the run's overall status reflects the skip rather than a pass",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1003-security-auth-clerk-session-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,56 @@
+# security-auth-clerk blueprint coordination vocabulary
+
+This file is the security-auth-clerk half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | security-auth-clerk contribution | Origin | Composition note |
+|---|---|---|---|
+| `authModel` | ADR-1001-security-auth-clerk-auth-model | Reused from the SPA vocabulary (`application-spa` contributes the client half; `application-api-rest` contributes the server half; `security-auth-magic-link` contributes the passwordless magic-link identity model). This blueprint contributes a Clerk-hosted identity model on the same topic string on purpose. | The one project-wide decision on how identity is proven, where credentials live, and what the wire credential looks like. Composing this blueprint with any of `application-spa`, `application-api-rest`, `security-auth-magic-link`, or a future `security-auth-oauth2` / `security-auth-keycloak` conflicts here by design; the expected resolution is one project-level ADR that fixes the identity surface (Clerk-hosted per this blueprint, or magic-link, or another) and maps it onto the client and server halves' cookie shape and 401-redirect posture |
+
+The security-auth-clerk blueprint claims one global topic. Every other contribution is scope-local (ADR-1002 through ADR-1005 name the middleware-boundary shape, the authorisation-adapter contract, the claims-mapping discipline, and the session-lifecycle posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`identity`, `identityProvider`, `authVendor`, `signIn` are all wrong when `authModel` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 9101-9110 sit at the LOW end of the 9101-9899 band on purpose. A project-side story that mechanically derives from a security-auth-clerk REQ id into the number `9110` would collide against security-auth-clerk-US-9110 in this package; the band leaves headroom at the HIGH end (US 9181-9899) so a project's own stories anchored to security-auth-clerk REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+ADR and TAC suffixes for this blueprint widen to four digits (1001-1099) because the three-digit space fills at 9xx (security-secrets-management). Sibling round-2 auth blueprints (security-auth-oauth2, security-auth-keycloak) will continue the widening at 1101-1199 and 1201-1299 respectively; the shipped shelf has not carried four-digit suffixes before this blueprint, so the fallback rule on this PR's cover note applies if the rcf-schemas grammar refuses that shape.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `authModel` exactly as spelled here (matching the existing SPA, REST, and security-auth-magic-link contributions) when your blueprint holds an opinion on the project's identity surface, credential shape, or sign-in flow; contribute your own scope:global ADR on that string and let composition surface the pairing. A vendor-committed auth blueprint (security-auth-oauth2 against a named provider, security-auth-keycloak against a named IdP shape) conflicts here by design; the operator resolves at apply.
+- Middleware boundary shape (ADR-1002), authorisation-adapter contract (ADR-1003), claims-mapping discipline (ADR-1004), and session-lifecycle posture (ADR-1005) are scope-local. A composing blueprint that holds an opinion on any of them authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate `authModel` variations.
+- The `signInStrategy` config surface (REQ-005) is not a global topic string. A project composes this blueprint with an OAuth2 or Keycloak sibling and reconciles the enabled strategy set at the project's config module; the mechanism does not enforce a single strategy vocabulary across auth-family blueprints because each vendor names its strategies differently.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint), `emailWebhookContract` (a project intending to fan email-delivery events into a shared bus would benefit from a global here; email-smtp-resend explicitly does not mint it). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-1001 on `authModel` is a Clerk-committed sibling to `security-auth-magic-link`'s ADR-501-security-auth-magic-link-model on the same topic string. Applying both on one project raises a `globalAdrTopic` conflict the operator resolves via one of the four documented resolutions (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add). The pairing precedent is `application-spa` + `application-api-rest` on `errorEnvelope` and `authModel`; this blueprint reuses the same composition-precedent pattern rather than minting a new one.
+
+## Rename awareness
+
+Cross-references in this blueprint's prose use the target-state slugs from the ratified renames pass: `security-auth-magic-link` (for the shipped `auth` blueprint), `persistence-data-sqlite`, `observability-essentials`, `application-spa`, `application-api-rest`. If the rename PR has not yet merged when this blueprint ships, a rebase against the rename PR is required before merge; the cross-references above stay valid at the target state.

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

@@ -0,0 +1,80 @@
+# Security auth Clerk blueprint guide
+
+## What it is
+
+A Clerk-committed authentication floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a hosted-identity pattern: how the project delegates identity to Clerk, how it verifies the resulting session cookie on the server, how it reduces the verified claims into a stable Principal shape, how the authorisation adapter maps Clerk roles and organisation memberships onto project-defined verbs, how sign-in strategy sits as a config surface rather than a hard-coded choice, how sign-out honours Clerk-side revocation within a bounded window, how rate-limiting and anti-enumeration are delegated to Clerk, how user and organisation provisioning stays read-only from the runtime's perspective, and how runtime-verify acceptance criteria acknowledge that Clerk-reachable behaviour cannot be faked.
+
+Concretely, the blueprint ships nine requirements, eleven user stories (twenty-five acceptance criteria), four architecture components, and five architecture decision records. One ADR is `scope: global` on the `authModel` topic; the other four are scope-local operational ADRs (middleware-boundary shape, authorisation-adapter contract, claims-mapping discipline, session-lifecycle posture) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a Clerk SDK version pin. The SDK's package version is a project-package-manifest concern; the blueprint fixes the shape of the boundary (the `verify(request)` contract, the `__session` cookie name, the reduced Principal shape) and lets the project pick which Clerk SDK major it builds against.
+
+Not an MFA policy. Clerk owns MFA at the hosted identity surface; the blueprint delegates MFA to Clerk's configuration and does not encode an MFA strategy or enforcement rule at the project's runtime. A project with a hard MFA-for-all-admins requirement configures that on the Clerk dashboard.
+
+Not a user or organisation mirror. Clerk is authoritative for identity state. A project that needs to mirror Clerk state into a local table for query purposes (a per-user preferences row, a per-organisation audit log) does so through a project-authored Clerk-webhook consumer; that consumer is out of scope for the blueprint's default. A project that includes one adds one project-authored TAC and one scope-local ADR alongside this blueprint's contributions.
+
+Not a project-side rate limiter or anti-enumeration defence. Clerk applies its own throttling and enumeration defences at the identity surface; the blueprint requires that the project does not layer a second, competing rate limiter on top of the sign-in flow.
+
+Not an OAuth2-provider-list blueprint. A project that wants direct OAuth2 against a specific set of social providers, without a hosted identity vendor, reaches for the future `security-auth-oauth2` sibling blueprint when it ships. A project that wants a self-hosted OIDC surface reaches for the future `security-auth-keycloak` sibling. Both conflict with this blueprint on `authModel` by design.
+
+Not the sign-in UI. Clerk hosts the sign-in surface (either fully hosted at Clerk's domain or embedded through Clerk's components). The blueprint's job is to wire the surface into a project route and to verify the resulting session on the server; the pixels of the sign-in form are Clerk's.
+
+## When to reach for it
+
+Reach for the security-auth-clerk blueprint when:
+
+- The project needs user accounts, sessions, sign-in UX, and account recovery, and the operator's preference is to buy that surface from a hosted vendor rather than build it.
+- The project's operator wants a straightforward path to enterprise-shaped features (SAML, SCIM, organisation memberships, roles) without owning the identity infrastructure that supports them.
+- The team is small enough that owning the identity surface (email deliverability, MFA rollout, breach-check integration, session persistence) is a distraction from the product.
+- The project's compliance posture accepts a hosted identity vendor; a project subject to data-residency constraints that Clerk's regions do not satisfy is on the wrong blueprint.
+- The project already uses (or plans to use) Clerk's dashboard for user administration and does not want a second admin surface.
+
+## When it does not fit
+
+Do not reach for the security-auth-clerk blueprint when:
+
+- The project cannot depend on a hosted third-party identity surface (data-residency constraints, an air-gapped deployment, a compliance regime that requires self-hosted identity). Reach for `security-auth-keycloak` when it ships, or supersede ADR-1001 with a project-level ADR and pick a self-hosted vendor whose adapter the project authors.
+- The project's identity surface is genuinely trivial (one operator, no organisations, no roles). A passwordless magic-link floor (`security-auth-magic-link`) is honestly a smaller machine at that scale; this blueprint's provider dependency and pricing tier are overkill.
+- The project wants direct OAuth2 against a specific set of social providers and nothing else, with no hosted identity vendor. `security-auth-oauth2` will cover that shape when it ships; picking this blueprint plus Clerk's OAuth strategies is valid but is a bigger machine than a project that only wants "sign in with GitHub" needs.
+- The project cannot accept the `accountBound` runtime-verify posture (runtime tests that skip when Clerk is unreachable, rather than pass on a fake). Every hosted-identity blueprint carries this posture; a project that needs offline test independence is on the wrong blueprint family.
+
+An earlier round-1 pass shipped `security-auth-magic-link` as the generic-auth blueprint; the round-2 pass introduces the vendor-committed siblings (this blueprint for Clerk, plus the reserved `security-auth-oauth2` and `security-auth-keycloak`). The composition-precedent is `application-spa` + `application-api-rest` on the `errorEnvelope` and `authModel` topics: siblings on the same topic conflict on purpose and expect a project-level ADR resolution.
+
+## What a good outcome looks like
+
+A project applies the blueprint on a fresh tree, provisions a Clerk development instance, stores the publishable and secret keys in the secrets manifest under placeholder-named entries (`CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`), chooses its `signInStrategy` primary and alternates, realises the four TACs in project-authored FBSes (one framework-specific middleware shim, one authorisation-adapter with a project verb-to-role mapping, one session verifier over the Clerk SDK, one claims mapper), and lands on a deployed application where:
+
+- The sign-in surface renders Clerk's hosted (or embedded) sign-in UI; the operator signs in and lands on the app with a `__session` cookie in their browser.
+- Every request to a protected route arrives at the middleware, which verifies the cookie against Clerk and attaches `request.auth = { principalId, roles, organisationIds, claims }` before the handler runs.
+- Every handler that gates on identity calls `can(request.auth, verb, subject?)` or `assert(request.auth, verb, subject?)` on the authorisation adapter; no handler reads `request.auth.roles` or `request.auth.claims` directly.
+- Role-based UI slots on rendered pages appear or disappear per the adapter's decision; the corresponding server-side handler enforces the same verb through `assert`.
+- The Clerk SDK is imported by two modules in the project (the middleware wiring and the session verifier). A source-tree scan confirms the boundary.
+- The operator signs out; a subsequent request replaying the pre-sign-out cookie is refused by the middleware within the `revocationCheckIntervalMs` window declared on ADR-1005.
+- The sign-in flow has no project-authored rate limiter; Clerk's own throttling is the observed behaviour under a burst of attempts.
+- User and organisation management happens on the Clerk dashboard (or on a project-authored provisioning script directory that runs outside the request lifecycle); the runtime never mutates Clerk identity state.
+- The runtime-verify test surface marks Clerk-reachable ACs as `accountBound` and, when the CI runner has Clerk reachable, they pass against the development instance; when the CI runner does not, they skip with `AUTH_CLERK_UNREACHABLE`, not pass silently.
+
+## Operator decisions that remain open after apply
+
+- Vendor choice (Clerk default per ADR-1001, or a superseding project-level ADR selecting Auth0, WorkOS, Cognito, or a project-authored hosted-identity adapter). Blueprint owns the boundary on both sides; project owns the vendor when it supersedes.
+- `signInStrategy` primary and alternates (email link, email code, password, phone code, OAuth against named providers, SAML). Blueprint owns the shape; project owns the choice; Clerk dashboard owns the enablement.
+- Verb-to-role mapping table (project vocabulary; every downstream `can` and `assert` call speaks in these verbs). Blueprint owns the adapter shape; project owns the mapping.
+- Organisation scoping policy (whether to scope every resource by `organisationId` or leave organisation membership as a flat role decoration). Blueprint owns the adapter's optional-subject shape; project owns the choice.
+- `revocationCheckIntervalMs` (30 seconds default per ADR-1005, or a shorter window at the cost of a per-request Clerk round trip, or a longer window up to the session's declared expiry). Blueprint owns the shape and the ceiling; project owns the number.
+- Clerk plan tier (development, production, per-user pricing). Blueprint owns none of this; the operator picks per project needs.
+- Provisioning-script directory location (`scripts/provisioning/` by convention on AC-9110-1, or a project-declared equivalent). Blueprint owns that provisioning is not a request handler; project owns where the scripts live.
+- Whether to layer a project-authored Clerk-webhook consumer (for user-created, session-ended, or organisation-membership-changed events). Blueprint's default omits it; a project that adds one authors one TAC and one ADR alongside this blueprint's contributions.
+
+## Runtime coverage
+
+The middleware boundary contract (TAC-1001's `verify(request) -> { authenticated, principal?, reason? }`) is framework-agnostic and runs unchanged on Node HTTP servers (Express, Fastify) and on the Cloudflare Workers fetch handler. Two sample sets ship in `assets/`:
+
+- `assets/middleware/node-middleware-shape.md` for Express and Fastify: adapter wrappers around `verify(request)` that attach the reduced `Principal` to `request.auth`.
+- `assets/middleware/workers-fetch-shape.md` and `assets/wiring/workers-wrangler-toml-shape.md` for Cloudflare Workers: a fetch-handler adapter that carries the same `verify(request)` contract onto the Fetch API `Request` shape, plus the wrangler.toml overlay (`nodejs_compat`, the two Clerk secret names, the `CLERK_SIGN_IN_URL` var, and the `run_worker_first` posture on auth-gated routes that the assets binding would otherwise silently bypass).
+
+A project on a single framework picks up one adapter and pays nothing for the others; a project that hosts multiple runtimes (a Node main app plus a Workers edge function against the same Clerk instance) picks up both sample sets and shares one session verifier and one claims mapper across them.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Clerk is a paid vendor beyond the development tier; the operator budgets for it. The `accountBound` runtime-verify posture means the CI runner needs Clerk reachability to actually verify the runtime-verify ACs; a CI runner without outbound network for that vendor either skips those ACs (which the ship gate flags) or the operator wires a preview Clerk instance for CI to reach. The middleware boundary discipline (`request.auth` and `can`/`assert` everywhere) is a code-review load on every new handler; a project that lets the discipline slip loses the vendor-swap-safety the blueprint is buying. The `revocationCheckIntervalMs` window is a stated trade between per-request cost and sign-out prompt-ness; the operator picks a number that reflects the project's actual policy, not the blueprint's default forever. The read-only provisioning posture forces the operator to run Clerk mutations outside the request lifecycle; a project that wants a per-request user-create call is on a different pattern and should think again. The blueprint says nothing about MFA policy, about pricing, about SLA, or about vendor-lock exit; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.