rcf-lite 0.12.0 → 0.13.0

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

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

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

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

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

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

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

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

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, ci-pipeline, 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` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| 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.