@volter/twin-clerk 0.1.0

package/src/clerk-twin.ts

@@ -0,0 +1,1580 @@
+// Clerk Backend API twin REQUEST HANDLER — the canonical api.clerk.com surface for the
+// twin, backed by the event/action-log kernel. Contract:
+// handleClerkTwinRequest({method, path, body}) -> {status, body}. Response SHAPES mirror
+// real Clerk (snake_case ids with vendor prefixes — user_/sess_/org_/orgmem_/orginv_,
+// object discriminators, paginated list shapes) so the real `@clerk/backend` SDK works
+// unmodified. HTTP wrapper: clerk-server.ts → createClerkTwinServer.
+//
+// State lives in the action log (R18): writes are local actions, reads are the
+// projection. No real Clerk is ever called. A twin fakes auth, so ANY Backend API key is
+// accepted (the real vendor's 401 on a bad key is not modeled — see README ## Coverage).
+//
+// THE meaty part: session tokens and JWT-template tokens are REAL RS256 JWTs signed from
+// a persisted local keypair, and /.well-known/jwks.json serves the matching JWKS, so an
+// app verifying a twin-issued token against the twin's JWKS succeeds unmodified.
+import { applyTwinWrite, projectResources, nodeBuiltin, resolveSubjectId } from '@volter/world-core';
+import { buildJwks, signJwt, signJwtHs256, verifyJwtWithJwks } from './clerk-jwt.ts';
+import { emitClerkEvent, eventTypeFor, type ClerkWebhookTarget } from './clerk-events.ts';
+
+const SERVICE = 'clerk';
+
+export type ClerkRequest = {
+  method: string; path: string; body?: string; occurredAt?: string; root?: string; readOnly?: boolean;
+  /** The Host this request arrived on (`host` / `x-forwarded-host`), so self-referential URLs the
+   *  API emits point back at wherever this twin is actually bound. Runtime contract R7: a twin
+   *  learns its own origin from the request and never assumes a port. */
+  host?: string;
+  /** The Origin of the browser request that asked for this work, set only by the Frontend API
+   *  door (clerk-js runs in a page). Real Clerk puts it in a session token's `azp`; a Backend
+   *  API call has no browser behind it and carries none. */
+  origin?: string;
+};
+
+/** The instance's issuer: the `iss` of every token the twin signs, and the `issuer` its OIDC
+ *  discovery document names. One value, so a verifier's `iss === discovery.issuer` holds. */
+export const CLERK_TWIN_ISSUER = 'https://twin.clerk.accounts.dev';
+
+export type ClerkResponse = { status: number; body: unknown };
+
+/** The absolute origin this request arrived on. Falls back to the domain's own name (a real,
+ *  port-free origin) only when the caller supplied no Host at all — e.g. an in-process call. */
+function originOf(req: ClerkRequest, fallbackHost: string): string {
+  const raw = (req.host ?? '').trim();
+  if (!raw) return `https://${fallbackHost}`;
+  if (/^https?:\/\//i.test(raw)) return raw.replace(/\/+$/, '');
+  // A local twin is plain HTTP; a real hostname is HTTPS.
+  const scheme = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(raw) ? 'http' : 'https';
+  return `${scheme}://${raw}`;
+}
+
+// resource type → id prefix (Clerk's conventions).
+const PREFIX: Record<string, string> = {
+  user: 'user', session: 'sess', organization: 'org', organization_membership: 'orgmem',
+  organization_invitation: 'orginv', invitation: 'inv', allowlist_identifier: 'alid',
+  blocklist_identifier: 'blid', jwt_template: 'jtmpl', email_address: 'idn', phone_number: 'idn',
+  client: 'client', sign_in_token: 'sit', oauth_application: 'oauth_app', redirect_url: 'ru',
+  saml_connection: 'samlc', domain: 'dmn', actor_token: 'actor',
+  organization_domain: 'orgdmn', testing_token: 'test',
+  web3_wallet: 'idn', webhook_endpoint: 'ep', webhook_attempt: 'wha',
+  waitlist_entry: 'wle', proxy_check: 'proxy_check',
+};
+
+// Clerk's error envelope: { errors: [{ code, message, long_message }], clerk_trace_id }.
+function err(message: string, status = 404, code = 'resource_not_found', longMessage?: string): ClerkResponse {
+  return {
+    status,
+    body: {
+      errors: [{ code, message, long_message: longMessage ?? message, meta: {} }],
+      clerk_trace_id: 'trace_twin',
+    },
+  };
+}
+
+function nowUnixMs(occurredAt?: string): number {
+  return occurredAt ? Date.parse(occurredAt) : Date.now();
+}
+
+// ── password hashing (REAL crypto) ──────────────────────────────────────────────
+// Clerk stores password digests with a chosen hasher (bcrypt/scrypt/argon2/…). The twin
+// uses node:crypto scrypt for a genuine salted one-way hash (`scrypt$<saltB64>$<hashB64>`)
+// so verify_password is a real constant-time comparison — never a plaintext compare.
+// EDGE-CPU CAVEAT (Cloudflare Worker host): scryptSync at node's default cost (N=16384, r=8,
+// ~16 MiB, memory-hard) can exceed the free-plan 10ms CPU budget → intermittent 503/1102 —
+// the SAME limit the baked RSA key exists to dodge. The managed-accounts identity path never
+// calls this (no password), so it's latent; if a password path is used on the edge, move this
+// off the serve path or lower the cost params. On a Node host it is fine as-is.
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+function hashPassword(password: string): string {
+  const { randomBytes, scryptSync } = nodeCrypto();
+  const salt = randomBytes(16);
+  const hash = scryptSync(password, salt, 32);
+  return `scrypt$${salt.toString('base64')}$${hash.toString('base64')}`;
+}
+function verifyPassword(password: string, digest: string): boolean {
+  const { scryptSync, timingSafeEqual } = nodeCrypto();
+  const parts = String(digest).split('$');
+  if (parts.length !== 3 || parts[0] !== 'scrypt') return false;
+  const salt = Buffer.from(parts[1]!, 'base64');
+  const expected = Buffer.from(parts[2]!, 'base64');
+  const actual = scryptSync(password, salt, expected.length);
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+// ── SECRET material (real randomness, no network): a TOTP seed, backup codes, an OAuth client
+// secret, a webhook signing secret. Secrecy is their purpose, so they are never derived from
+// world state; ids and bearer tokens are, through stableHex (R9). ──
+function secretHex(bytes: number): string {
+  return nodeCrypto().randomBytes(bytes).toString('hex');
+}
+/** A base32 (RFC 4648) secret, the shape Clerk/authenticator apps use for TOTP. */
+function base32Secret(bytes = 20): string {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+  const buf = nodeCrypto().randomBytes(bytes);
+  let bits = 0, value = 0, out = '';
+  for (const byte of buf) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) { out += alphabet[(value >>> (bits - 5)) & 31]; bits -= 5; }
+  }
+  if (bits > 0) out += alphabet[(value << (5 - bits)) & 31];
+  return out;
+}
+
+function parseBody(body?: string): Record<string, unknown> {
+  if (!body) return {};
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+// Live resources of a type. A delete is the kernel's tombstone (`deleted: true`, cleared by the next write — protocol 2).
+function rows(type: string, root?: string) {
+  return projectResources(SERVICE, root).filter((r) => r.type === type && !r.id.startsWith('_') && (r as Record<string, unknown>).deleted !== true && !r.id.startsWith('_') && (r as Record<string, unknown>)._fapi !== true);
+}
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist.
+ *  The resend exemplar's helper — the only entropy source an id is allowed on the serve path. */
+export function stableHex(seed: string, n: number): string {
+  let out = '';
+  for (let round = 0; out.length < n; round += 1) {
+    let h = 0x811c9dc5;
+    const s = `${round}:${seed}`;
+    for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+    out += h.toString(16).padStart(8, '0');
+  }
+  return out.slice(0, n);
+}
+// DETERMINISTIC (R9, resource level): the suffix is a stable hash of
+// `${type}:${occurredAt}:${ordinal}` — the world instant the write happened at plus the count
+// of rows the type already holds — never `Math.random`, so two identical worlds mint identical
+// ids and a replay is byte-identical. `discriminator` separates ids minted inside ONE request
+// at ONE instant off ONE ordinal (a user's nested identifiers), which the row count cannot.
+// The SHAPE is unchanged: `<prefix>_twin_<n>_<8 hex>`.
+function nextId(type: string, occurredAt: string | undefined, root?: string, discriminator = ''): string {
+  const prefix = PREFIX[type] ?? type;
+  let n = 0;
+  for (const r of rows(type, root)) {
+    const m = new RegExp(`^${prefix}_twin_(\\d+)_`).exec(r.id);
+    if (m) n = Math.max(n, Number(m[1]));
+  }
+  return `${prefix}_twin_${n + 1}_${stableHex(`${type}:${occurredAt ?? ''}:${n}:${discriminator}`, 8)}`;
+}
+
+// Clerk reserves several vendor field names that collide with kernel meta or are
+// dropped on projection (the kernel reserves `type`). Stash a vendor `type` under
+// `_clerk_type` and restore on view.
+// Recursively drop twin-internal `_`-prefixed keys (e.g. a nested `_access_token` inside
+// external_accounts) so they never leak into a vendor-facing body.
+function deepClean(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(deepClean);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) if (!k.startsWith('_')) out[k] = deepClean(v);
+    return out;
+  }
+  return value;
+}
+function view(type: string, r: Record<string, unknown>): Record<string, unknown> {
+  const { type: _t, updatedAt: _u, _clerk_type, ...rest } = r as Record<string, unknown> & { _clerk_type?: unknown };
+  // drop any twin-internal `_`-prefixed fields (top-level + nested) from the vendor body
+  const clean: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rest)) if (!k.startsWith('_')) clean[k] = deepClean(v);
+  const out: Record<string, unknown> = { ...clean, id: r.id };
+  if (_clerk_type !== undefined) out.type = _clerk_type;
+  return out;
+}
+
+function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+function getOne(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  const r = getRow(type, id, root);
+  return r ? view(type, r) : undefined;
+}
+
+// Clerk list shape. The Backend API returns either a bare array (older endpoints) or a
+// paginated envelope `{ data: [...], total_count }`. The SDK's Backend resources use the
+// paginated envelope for list endpoints (users/organizations/...). Honors limit/offset.
+function paginate<T>(items: T[], params: Record<string, unknown>): { page: T[]; total: number } {
+  const total = items.length;
+  let limit = 10;
+  if (params.limit !== undefined) {
+    const n = Number(params.limit);
+    if (Number.isFinite(n)) limit = Math.min(500, Math.max(1, Math.trunc(n)));
+  }
+  let offset = 0;
+  if (params.offset !== undefined) {
+    const n = Number(params.offset);
+    if (Number.isFinite(n) && n >= 0) offset = Math.trunc(n);
+  }
+  return { page: items.slice(offset, offset + limit), total };
+}
+function listEnvelope<T>(items: T[], params: Record<string, unknown>) {
+  const { page, total } = paginate(items, params);
+  return { data: page, total_count: total };
+}
+
+async function writeResource(
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+  op: string,
+  req: ClerkRequest,
+): Promise<Record<string, unknown>> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    { operation: op, subjectType: type, subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } },
+    req.root,
+  );
+  const out = view(type, resource);
+  const evType = eventTypeFor(op);
+  if (evType) {
+    await emitClerkEvent(op, out, { ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), endpoints: webhookTargets(req.root) });
+    await recordWebhookAttempts(evType, out, op, req);
+  }
+  return out;
+}
+
+/** The World's live webhook endpoints, from its tree: delivery survives a restart and belongs to
+ *  this World alone. A disabled or deleted endpoint receives nothing, like the vendor. */
+function webhookTargets(root: string | undefined): ClerkWebhookTarget[] {
+  return rows('webhook_endpoint', root)
+    .filter((ep) => ep.disabled !== true && typeof ep.url === 'string' && typeof ep.signing_secret === 'string')
+    .map((ep) => ({ url: String(ep.url), secret: String(ep.signing_secret), ...(Array.isArray(ep.filter_types) ? { filterTypes: ep.filter_types.map(String) } : {}) }));
+}
+
+// For every persisted webhook endpoint (created via the Backend API), record a delivery
+// attempt for this event — the attempts log a consumer inspects (svix-style). Delivery itself
+// is emitClerkEvent's (fire-and-forget); this records a `succeeded` attempt (disabled endpoints record
+// nothing). Endpoints whose `filter_types` exclude this event type are skipped.
+async function recordWebhookAttempts(evType: string, data: Record<string, unknown>, op: string, req: ClerkRequest): Promise<void> {
+  if (op.startsWith('webhook_')) return; // never recurse on our own bookkeeping writes
+  const endpoints = rows('webhook_endpoint', req.root);
+  for (const ep of endpoints) {
+    if (ep.disabled === true) continue;
+    const filters = ep.filter_types;
+    if (Array.isArray(filters) && filters.length > 0 && !filters.includes(evType)) continue;
+    const at = nowUnixMs(req.occurredAt);
+    await create('webhook_attempt', {
+      endpoint_id: ep.id, event_type: evType, status: 'succeeded', response_status_code: 200,
+      payload: { type: evType, object: 'event', data: { id: data.id } }, attempted_at: at,
+    }, 'webhook_attempt.create', req);
+  }
+}
+
+// Move a colliding vendor `type` field to `_clerk_type` so it survives projection.
+function stashType(fields: Record<string, unknown>): Record<string, unknown> {
+  if (!('type' in fields)) return fields;
+  const { type: vt, ...rest } = fields;
+  return { ...rest, _clerk_type: vt };
+}
+
+async function create(type: string, fields: Record<string, unknown>, op: string, req: ClerkRequest, providedId?: string): Promise<Record<string, unknown>> {
+  const id = providedId ?? nextId(type, req.occurredAt, req.root);
+  const at = nowUnixMs(req.occurredAt);
+  const stamped = stashType({ object: type, created_at: at, updated_at: at, ...fields });
+  return writeResource(type, id, stamped, op, req);
+}
+
+// ── USERS ───────────────────────────────────────────────────────────────────────
+const emailIdsFor = (u: Record<string, unknown>): Array<Record<string, unknown>> =>
+  Array.isArray(u.email_addresses) ? (u.email_addresses as Array<Record<string, unknown>>) : [];
+
+function buildUser(params: Record<string, unknown>, req: ClerkRequest): Record<string, unknown> {
+  const emails = Array.isArray(params.email_address) ? params.email_address as string[] : [];
+  const phones = Array.isArray(params.phone_number) ? params.phone_number as string[] : [];
+  // DETERMINISTIC (R9): the identifier id is minted from the world instant the create happened
+  // at plus the identifier's own ordinal — `Date.now()` here made every fresh-root replay serve
+  // different bytes for the same user.
+  const at = req.occurredAt ?? '';
+  const email_addresses = emails.map((email, i) => ({
+    id: `idn_twin_${stableHex(`email_address:${at}:${i}:${email}`, 12)}_${i}`, object: 'email_address', email_address: email,
+    verification: { status: 'verified', strategy: 'admin' }, linked_to: [], reserved: false,
+  }));
+  const phone_numbers = phones.map((phone, i) => ({
+    id: `idn_twin_${stableHex(`phone_number:${at}:${i}:${phone}`, 12)}_p${i}`, object: 'phone_number', phone_number: phone,
+    verification: { status: 'verified', strategy: 'admin' }, linked_to: [], reserved: false,
+  }));
+  const primary = email_addresses[0]?.id ?? null;
+  // Password: accept a plaintext `password` (hash it) or a pre-computed `password_digest`.
+  const hasPassword = typeof params.password === 'string' || typeof params.password_digest === 'string';
+  const passwordDigest =
+    typeof params.password === 'string' ? hashPassword(params.password)
+    : typeof params.password_digest === 'string' ? String(params.password_digest)
+    : null;
+  return {
+    username: (params.username as string) ?? null,
+    first_name: (params.first_name as string) ?? null,
+    last_name: (params.last_name as string) ?? null,
+    image_url: '',
+    has_image: false,
+    primary_email_address_id: primary,
+    primary_phone_number_id: phone_numbers[0]?.id ?? null,
+    email_addresses,
+    phone_numbers,
+    web3_wallets: [],
+    external_accounts: Array.isArray(params.external_accounts) ? params.external_accounts as unknown[] : [],
+    saml_accounts: [],
+    public_metadata: (params.public_metadata as object) ?? {},
+    private_metadata: (params.private_metadata as object) ?? {},
+    unsafe_metadata: (params.unsafe_metadata as object) ?? {},
+    banned: false,
+    locked: false,
+    last_sign_in_at: null,
+    two_factor_enabled: false,
+    totp_enabled: false,
+    backup_code_enabled: false,
+    last_active_at: null,
+    external_id: (params.external_id as string) ?? null,
+    password_enabled: hasPassword,
+    // `_password_digest` is twin-internal (never serialized — dropped by view()).
+    _password_digest: passwordDigest,
+  };
+}
+
+// ── route handler ────────────────────────────────────────────────────────────────
+export async function handleClerkTwinRequest(req: ClerkRequest): Promise<ClerkResponse> {
+  const method = req.method.toUpperCase();
+  const rawPath = req.path.split('?');
+  const path = rawPath[0]!.replace(/\/+$/, '') || '/';
+  const query = Object.fromEntries(new URLSearchParams(rawPath[1] ?? ''));
+  const body = parseBody(req.body);
+  const params: Record<string, unknown> = { ...query, ...body };
+  const seg = path.replace(/^\/+/, '').split('/'); // ["v1","users",...]
+  // protocol 2: after a landing adopted the vendor's id, a caller on a branch may still address a user or an organization
+  // by the local id — resolved through the alias map once, here at the boundary
+  if ((seg[1] === 'users' || seg[1] === 'organizations') && seg[2] && /^(user|org)_/.test(seg[2])) seg[2] = resolveSubjectId(SERVICE, seg[1] === 'users' ? 'user' : 'organization', decodeURIComponent(seg[2]), req.root);
+  const idAt = (i: number) => decodeURIComponent(seg[i] ?? '');
+
+  if (req.readOnly && method !== 'GET') {
+    return err('twin is read-only; omit readOnly to accept writes', 405, 'read_only');
+  }
+
+  // ── JWKS (the verifier endpoint; served at the well-known path Clerk uses) ──
+  if (method === 'GET' && (path === '/.well-known/jwks.json' || path === '/v1/jwks')) {
+    return { status: 200, body: await buildJwks(req.root) };
+  }
+
+  // ── OIDC discovery (what a verifier reads first: the issuer and where its keys live) ──
+  // Real Clerk serves this at the instance's issuer; the twin names only what it serves —
+  // the JWKS at this request's own origin, RS256, public subjects.
+  if (method === 'GET' && path === '/.well-known/openid-configuration') {
+    return {
+      status: 200,
+      body: {
+        issuer: CLERK_TWIN_ISSUER,
+        jwks_uri: `${originOf(req, new URL(CLERK_TWIN_ISSUER).host)}/.well-known/jwks.json`,
+        subject_types_supported: ['public'],
+        id_token_signing_alg_values_supported: ['RS256'],
+      },
+    };
+  }
+
+  // ── root ──
+  if (path === '/' || path === '/v1') {
+    return { status: 200, body: { service: 'clerk', object: 'twin', version: 'twin' } };
+  }
+
+  if (seg[0] !== 'v1') return err(`Unknown route: ${path}`, 404, 'resource_not_found');
+  const collection = seg[1];
+
+  // ── USERS ──
+  if (collection === 'users') {
+    if (seg.length === 2 && method === 'POST') {
+      const errResp = validateUserCreate(params, req);
+      if (errResp) return errResp;
+      const user = await create('user', buildUser(params, req), 'user.create', req);
+      return { status: 200, body: user };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('user', req.root).map((r) => view('user', r));
+      // filters: email_address[], username[], user_id[], query, organization_id[]
+      if (query.query) items = items.filter((u) => userMatchesQuery(u, String(query.query)));
+      const list = applyUserFilters(items, query);
+      // GET /v1/users returns a BARE ARRAY in the Backend API (the SDK wraps total separately)
+      return { status: 200, body: list };
+    }
+    if (seg[1] === 'users' && seg[2] === 'count' && method === 'GET') {
+      return { status: 200, body: { object: 'total_count', total_count: rows('user', req.root).length } };
+    }
+    if (seg.length === 3 && method === 'GET') {
+      const u = getOne('user', idAt(2), req.root);
+      return u ? { status: 200, body: u } : err(`User not found`, 404, 'resource_not_found');
+    }
+    if (seg.length === 3 && (method === 'PATCH' || method === 'PUT')) {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const patch = userPatch(params);
+      // Setting/changing a password hashes it and flips password_enabled (real crypto).
+      if (typeof params.password === 'string') {
+        patch._password_digest = hashPassword(params.password);
+        patch.password_enabled = true;
+      }
+      return { status: 200, body: await writeResource('user', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req) };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      await writeResource('user', idAt(2), { deleted: true }, 'user.delete', req);
+      return { status: 200, body: { object: 'user', id: idAt(2), deleted: true } };
+    }
+    // POST /v1/users/:id/ban | /unban | /lock | /unlock
+    if (seg.length === 4 && method === 'POST' && ['ban', 'unban', 'lock', 'unlock'].includes(seg[3]!)) {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const verb = seg[3]!;
+      const fields = verb === 'ban' ? { banned: true } : verb === 'unban' ? { banned: false } : verb === 'lock' ? { locked: true } : { locked: false };
+      return { status: 200, body: await writeResource('user', idAt(2), { ...fields, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req) };
+    }
+    // PATCH /v1/users/:id/metadata — merge metadata bags
+    if (seg.length === 4 && seg[3] === 'metadata' && method === 'PATCH') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const merged = mergeMetadata(cur, params);
+      return { status: 200, body: await writeResource('user', idAt(2), { ...merged, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req) };
+    }
+    // GET /v1/users/:id/organization_memberships
+    if (seg.length === 4 && seg[3] === 'organization_memberships' && method === 'GET') {
+      const memberships = rows('organization_membership', req.root)
+        .map((r) => expandMembership(view('organization_membership', r), req.root))
+        .filter((m) => (m.public_user_data as Record<string, unknown>)?.user_id === idAt(2));
+      return { status: 200, body: listEnvelope(memberships, query) };
+    }
+    // POST /v1/users/:id/verify_password — REAL scrypt verify (constant-time)
+    if (seg.length === 4 && seg[3] === 'verify_password' && method === 'POST') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const password = params.password as string | undefined;
+      if (!password) return err('password is required', 422, 'form_param_missing');
+      const digest = cur._password_digest as string | undefined;
+      if (!digest) return err('User does not have a password set', 422, 'form_password_not_set');
+      if (!verifyPassword(password, digest)) return err('Incorrect password', 422, 'form_password_incorrect');
+      return { status: 200, body: { verified: true } };
+    }
+    // ── TOTP / 2FA: POST creates a secret (+ otpauth uri), DELETE disables it ──
+    if (seg.length === 4 && seg[3] === 'totp' && method === 'POST') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const secret = base32Secret();
+      const userName = emailIdsFor(view('user', cur))[0]?.email_address ?? String(cur.id);
+      const otp = await create('totp', {
+        secret, uri: `otpauth://totp/Clerk:${encodeURIComponent(String(userName))}?secret=${secret}&issuer=Clerk&algorithm=SHA1&digits=6&period=30`,
+        verified: true, backup_codes: [],
+      }, 'totp.create', req, `totp_twin_${idAt(2)}`);
+      await writeResource('user', idAt(2), { totp_enabled: true, two_factor_enabled: true, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+      return { status: 200, body: { object: 'totp', id: otp.id, secret: otp.secret, uri: otp.uri, verified: true, backup_codes: null } };
+    }
+    if (seg.length === 4 && seg[3] === 'totp' && method === 'DELETE') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const otp = getRow('totp', `totp_twin_${idAt(2)}`, req.root);
+      if (otp) await writeResource('totp', String(otp.id), { deleted: true }, 'totp.delete', req);
+      await writeResource('user', idAt(2), { totp_enabled: false, two_factor_enabled: false, backup_code_enabled: false, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+      return { status: 200, body: { object: 'totp', user_id: idAt(2), deleted: true } };
+    }
+    // POST /v1/users/:id/backup_codes — (re)generate the user's 2FA recovery codes
+    if (seg.length === 4 && seg[3] === 'backup_codes' && method === 'POST') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const codes = Array.from({ length: 10 }, () => `${secretHex(4)}-${secretHex(4)}`);
+      await writeResource('user', idAt(2), { backup_code_enabled: true, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+      return { status: 200, body: { object: 'backup_code', codes } };
+    }
+    // ── PROFILE IMAGE: POST sets image_url (+ has_image), DELETE clears it ──
+    if (seg.length === 4 && seg[3] === 'profile_image' && method === 'POST') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      // Accept a data-url/url (file uploads arrive as multipart in real Clerk; the twin
+      // takes a `file` url string). A twin does not host bytes — it records the reference.
+      const url = (params.file as string) || `https://img.clerk.twin/${idAt(2)}.png`;
+      return { status: 200, body: await writeResource('user', idAt(2), { image_url: url, has_image: true, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req) };
+    }
+    if (seg.length === 4 && seg[3] === 'profile_image' && method === 'DELETE') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      return { status: 200, body: await writeResource('user', idAt(2), { image_url: '', has_image: false, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req) };
+    }
+    // POST /v1/users/:id/oauth_access_tokens/:provider — a user's OAuth provider token(s)
+    if (seg.length === 5 && seg[3] === 'oauth_access_tokens' && method === 'GET') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const provider = idAt(4);
+      const accounts = Array.isArray(cur.external_accounts) ? cur.external_accounts as Array<Record<string, unknown>> : [];
+      const acct = accounts.find((a) => a.provider === provider || a.provider === `oauth_${provider}`);
+      const tokens = acct && acct._access_token
+        ? [{ object: 'oauth_access_token', token: acct._access_token, provider: acct.provider, scopes: acct.approved_scopes ?? [], label: null }]
+        : [];
+      return { status: 200, body: listEnvelope(tokens, query) };
+    }
+    // DELETE /v1/users/:id/external_accounts/:eaid — unlink an OAuth (external) account
+    if (seg.length === 5 && seg[3] === 'external_accounts' && method === 'DELETE') {
+      const cur = getRow('user', idAt(2), req.root);
+      if (!cur) return err('User not found', 404, 'resource_not_found');
+      const accounts = Array.isArray(cur.external_accounts) ? cur.external_accounts as Array<Record<string, unknown>> : [];
+      if (!accounts.some((a) => a.id === idAt(4))) return err('External account not found', 404, 'resource_not_found');
+      const remaining = accounts.filter((a) => a.id !== idAt(4));
+      await writeResource('user', idAt(2), { external_accounts: remaining, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+      return { status: 200, body: { object: 'external_account', id: idAt(4), deleted: true } };
+    }
+  }
+
+  // ── EMAIL ADDRESSES (add an identifier to a user + verify it) ──
+  if (collection === 'email_addresses') {
+    if (seg.length === 2 && method === 'POST') {
+      const userId = params.user_id as string;
+      const email = params.email_address as string;
+      if (!userId || !email) return err('user_id and email_address are required', 422, 'form_param_missing');
+      const user = getRow('user', userId, req.root);
+      if (!user) return err('User not found', 404, 'resource_not_found');
+      const verified = params.verified === true;
+      const idn = await addUserIdentifier(user, 'email_addresses', {
+        object: 'email_address', email_address: email,
+        verification: verified ? { status: 'verified', strategy: 'admin' } : null,
+        linked_to: [], reserved: false,
+      }, req);
+      return { status: 200, body: idn };
+    }
+    return emailPhoneSubRoutes('email_addresses', 'email_address', seg, method, params, query, req, idAt);
+  }
+  // ── PHONE NUMBERS ──
+  if (collection === 'phone_numbers') {
+    if (seg.length === 2 && method === 'POST') {
+      const userId = params.user_id as string;
+      const phone = params.phone_number as string;
+      if (!userId || !phone) return err('user_id and phone_number are required', 422, 'form_param_missing');
+      const user = getRow('user', userId, req.root);
+      if (!user) return err('User not found', 404, 'resource_not_found');
+      const verified = params.verified === true;
+      const idn = await addUserIdentifier(user, 'phone_numbers', {
+        object: 'phone_number', phone_number: phone,
+        verification: verified ? { status: 'verified', strategy: 'admin' } : null,
+        linked_to: [], reserved: false,
+      }, req);
+      return { status: 200, body: idn };
+    }
+    return emailPhoneSubRoutes('phone_numbers', 'phone_number', seg, method, params, query, req, idAt);
+  }
+  // ── WEB3 WALLETS (a user identifier: a crypto wallet address) ──
+  if (collection === 'web3_wallets') {
+    if (seg.length === 2 && method === 'POST') {
+      const userId = params.user_id as string;
+      const walletAddress = (params.web3_wallet ?? params.wallet_address) as string;
+      if (!userId || !walletAddress) return err('user_id and web3_wallet are required', 422, 'form_param_missing');
+      const user = getRow('user', userId, req.root);
+      if (!user) return err('User not found', 404, 'resource_not_found');
+      const verified = params.verified === true;
+      const idn = await addUserIdentifier(user, 'web3_wallets', {
+        object: 'web3_wallet', web3_wallet: walletAddress,
+        verification: verified ? { status: 'verified', strategy: 'web3_metamask_signature' } : null,
+      }, req);
+      return { status: 200, body: idn };
+    }
+    return emailPhoneSubRoutes('web3_wallets', 'web3_wallet', seg, method, params, query, req, idAt);
+  }
+
+  // ── SESSIONS ──
+  if (collection === 'sessions') {
+    if (seg.length === 2 && method === 'POST') {
+      const userId = params.user_id as string;
+      if (!userId) return err('user_id is required', 422, 'form_param_missing');
+      if (!getRow('user', userId, req.root)) return err('User not found', 404, 'resource_not_found');
+      const at = nowUnixMs(req.occurredAt);
+      // client_id is a twin extension: the Frontend API surface owns real browser client
+      // identities and stamps them here so both surfaces project the same session rows.
+      const session = await create('session', {
+        client_id: typeof params.client_id === 'string' && params.client_id !== '' ? params.client_id : 'client_twin',
+        user_id: userId, status: 'active',
+        last_active_at: at, expire_at: at + 7 * 24 * 3600 * 1000, abandon_at: at + 30 * 24 * 3600 * 1000,
+        last_active_organization_id: null, actor: null,
+      }, 'session.create', req);
+      return { status: 200, body: session };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('session', req.root).map((r) => view('session', r));
+      if (query.user_id) items = items.filter((s) => s.user_id === query.user_id);
+      if (query.status) items = items.filter((s) => s.status === query.status);
+      return { status: 200, body: items };
+    }
+    if (seg.length === 3 && method === 'GET') {
+      const s = getOne('session', idAt(2), req.root);
+      return s ? { status: 200, body: s } : err('Session not found', 404, 'resource_not_found');
+    }
+    // POST /v1/sessions/:id/revoke
+    if (seg.length === 4 && seg[3] === 'revoke' && method === 'POST') {
+      const cur = getRow('session', idAt(2), req.root);
+      if (!cur) return err('Session not found', 404, 'resource_not_found');
+      return { status: 200, body: await writeResource('session', idAt(2), { status: 'revoked', updated_at: nowUnixMs(req.occurredAt) }, 'session.revoke', req) };
+    }
+    // POST /v1/sessions/:id/touch — bump last_active_at (+ optionally last active org)
+    if (seg.length === 4 && seg[3] === 'touch' && method === 'POST') {
+      const cur = getRow('session', idAt(2), req.root);
+      if (!cur) return err('Session not found', 404, 'resource_not_found');
+      if (cur.status !== 'active') return err('Session is not active', 400, 'invalid_session');
+      const patch: Record<string, unknown> = { last_active_at: nowUnixMs(req.occurredAt) };
+      if (typeof params.active_organization_id === 'string') patch.last_active_organization_id = params.active_organization_id;
+      return { status: 200, body: await writeResource('session', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'session.update', req) };
+    }
+    // POST /v1/sessions/:id/verify — verify a session token round-trip
+    if (seg.length === 4 && seg[3] === 'verify' && method === 'POST') {
+      const cur = getRow('session', idAt(2), req.root);
+      if (!cur) return err('Session not found', 404, 'resource_not_found');
+      const token = params.token as string | undefined;
+      if (token) {
+        const result = verifyJwtWithJwks(token, await buildJwks(req.root));
+        if (!result.valid) return err(`Invalid session token: ${result.reason}`, 400, 'invalid_token');
+      }
+      if (cur.status !== 'active') return err('Session is not active', 400, 'invalid_session');
+      return { status: 200, body: view('session', cur) };
+    }
+    // POST /v1/sessions/:id/tokens  and  /tokens/:template — issue a REAL signed JWT
+    if (seg.length >= 4 && seg[3] === 'tokens' && method === 'POST') {
+      const cur = getRow('session', idAt(2), req.root);
+      if (!cur) return err('Session not found', 404, 'resource_not_found');
+      const template = seg[4] ? decodeURIComponent(seg[4]) : undefined;
+      const claims = await sessionTokenClaims(cur, template, req);
+      const now = req.occurredAt ? Math.floor(nowUnixMs(req.occurredAt) / 1000) : undefined;
+      // A template with a custom HS256 signing key is signed with the shared secret (no JWKS);
+      // everything else is the twin's persisted RS256 keypair (served via JWKS).
+      const tmplRow = template ? rows('jwt_template', req.root).find((t) => t.name === template) : undefined;
+      const lifetime = (typeof tmplRow?.lifetime === 'number' ? tmplRow.lifetime : 60);
+      let jwt: string;
+      if (tmplRow?.custom_signing_key === true && typeof tmplRow._signing_key === 'string') {
+        jwt = signJwtHs256(claims, tmplRow._signing_key, { expiresInSeconds: lifetime, ...(now !== undefined ? { now } : {}) });
+      } else {
+        jwt = await signJwt(claims, { root: req.root, expiresInSeconds: lifetime, ...(now !== undefined ? { now } : {}) });
+      }
+      return { status: 200, body: { object: 'token', jwt } };
+    }
+  }
+
+  // ── ORGANIZATIONS ──
+  if (collection === 'organizations') {
+    if (seg.length === 2 && method === 'POST') {
+      const name = params.name as string;
+      if (!name) return err('name is required', 422, 'form_param_missing');
+      // Clerk: a slug the caller gives must be free; a slug Clerk derives from the name is made unique with a numeric suffix
+      const taken = (s: string) => rows('organization', req.root).some((o) => o.slug === s);
+      let slug = (params.slug as string) ?? slugify(name);
+      if (params.slug === undefined) for (let n = 2; taken(slug); n += 1) slug = `${slugify(name)}-${n}`;
+      if (taken(slug)) return err('That slug is taken', 422, 'form_identifier_exists');
+      const org = await create('organization', {
+        name, slug, image_url: '', has_image: false, members_count: params.created_by ? 1 : 0,
+        pending_invitations_count: 0, max_allowed_memberships: (params.max_allowed_memberships as number) ?? 5,
+        admin_delete_enabled: true, created_by: (params.created_by as string) ?? null,
+        public_metadata: (params.public_metadata as object) ?? {}, private_metadata: (params.private_metadata as object) ?? {},
+      }, 'organization.create', req);
+      // creator becomes an admin member
+      if (params.created_by) {
+        await createMembership(String(org.id), String(params.created_by), 'admin', req);
+      }
+      return { status: 200, body: org };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('organization', req.root).map((r) => view('organization', r));
+      if (query.query) items = items.filter((o) => String(o.name ?? '').toLowerCase().includes(String(query.query).toLowerCase()) || String(o.slug ?? '').includes(String(query.query)));
+      return { status: 200, body: listEnvelope(items, query) };
+    }
+    if (seg.length === 3 && method === 'GET') {
+      const o = getOne('organization', idAt(2), req.root) ?? getBySlug('organization', idAt(2), req.root);
+      return o ? { status: 200, body: o } : err('Organization not found', 404, 'resource_not_found');
+    }
+    if (seg.length === 3 && (method === 'PATCH' || method === 'PUT')) {
+      const cur = getRow('organization', idAt(2), req.root);
+      if (!cur) return err('Organization not found', 404, 'resource_not_found');
+      const patch: Record<string, unknown> = {};
+      for (const k of ['name', 'slug', 'max_allowed_memberships', 'admin_delete_enabled', 'public_metadata', 'private_metadata']) if (k in params) patch[k] = params[k];
+      return { status: 200, body: await writeResource('organization', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'organization.update', req) };
+    }
+    if (seg.length === 4 && seg[3] === 'metadata' && method === 'PATCH') {
+      const cur = getRow('organization', idAt(2), req.root);
+      if (!cur) return err('Organization not found', 404, 'resource_not_found');
+      const merged = mergeMetadata(cur, params);
+      return { status: 200, body: await writeResource('organization', idAt(2), { ...merged, updated_at: nowUnixMs(req.occurredAt) }, 'organization.update', req) };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('organization', idAt(2), req.root);
+      if (!cur) return err('Organization not found', 404, 'resource_not_found');
+      // Clerk cascades: the org's memberships go with it (a user's membership list never shows an organization that no longer exists)
+      for (const m of membershipsOf(idAt(2), req.root)) await writeResource('organization_membership', String(m.id), { deleted: true }, 'organization_membership.delete', req);
+      await writeResource('organization', idAt(2), { deleted: true }, 'organization.delete', req);
+      return { status: 200, body: { object: 'organization', id: idAt(2), deleted: true, slug: cur.slug } };
+    }
+
+    // ── ORGANIZATION MEMBERSHIPS: /v1/organizations/:org/memberships ──
+    if (seg.length === 4 && seg[3] === 'memberships' && method === 'POST') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const userId = params.user_id as string;
+      const role = (params.role as string) ?? 'basic_member';
+      if (!userId) return err('user_id is required', 422, 'form_param_missing');
+      if (!getRow('user', userId, req.root)) return err('User not found', 404, 'resource_not_found');
+      if (membershipFor(idAt(2), userId, req.root)) return err('User is already a member', 422, 'duplicate_record');
+      const m = await createMembership(idAt(2), userId, role, req);
+      return { status: 200, body: m };
+    }
+    if (seg.length === 4 && seg[3] === 'memberships' && method === 'GET') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const items = membershipsOf(idAt(2), req.root);
+      return { status: 200, body: listEnvelope(items, query) };
+    }
+    if (seg.length === 5 && seg[3] === 'memberships' && method === 'PATCH') {
+      const m = membershipFor(idAt(2), idAt(4), req.root);
+      if (!m) return err('Membership not found', 404, 'resource_not_found');
+      const role = params.role as string;
+      if (!role) return err('role is required', 422, 'form_param_missing');
+      const updated = await writeResource('organization_membership', String(m.id), { role, permissions: rolePermissions(role, req.root), updated_at: nowUnixMs(req.occurredAt) }, 'organization_membership.update', req);
+      return { status: 200, body: expandMembership(updated, req.root) };
+    }
+    if (seg.length === 5 && seg[3] === 'memberships' && method === 'DELETE') {
+      const m = membershipFor(idAt(2), idAt(4), req.root);
+      if (!m) return err('Membership not found', 404, 'resource_not_found');
+      await writeResource('organization_membership', String(m.id), { deleted: true }, 'organization_membership.delete', req);
+      await decrementMembers(idAt(2), req);
+      return { status: 200, body: { object: 'organization_membership', id: m.id, deleted: true } };
+    }
+
+    // ── ORGANIZATION INVITATIONS ──
+    if (seg.length === 4 && seg[3] === 'invitations' && method === 'POST') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const email = params.email_address as string;
+      if (!email) return err('email_address is required', 422, 'form_param_missing');
+      const inv = await create('organization_invitation', {
+        email_address: email, role: (params.role as string) ?? 'basic_member', organization_id: idAt(2),
+        status: 'pending', public_metadata: (params.public_metadata as object) ?? {}, private_metadata: (params.private_metadata as object) ?? {},
+      }, 'organization_invitation.create', req);
+      await writeResource('organization', idAt(2), { pending_invitations_count: Number(org.pending_invitations_count ?? 0) + 1 }, 'organization.update', req);
+      return { status: 200, body: inv };
+    }
+    if (seg.length === 4 && seg[3] === 'invitations' && method === 'GET') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      let items = rows('organization_invitation', req.root).map((r) => view('organization_invitation', r)).filter((i) => i.organization_id === idAt(2));
+      if (query.status) items = items.filter((i) => i.status === query.status);
+      return { status: 200, body: listEnvelope(items, query) };
+    }
+    if (seg.length === 6 && seg[3] === 'invitations' && seg[5] === 'revoke' && method === 'POST') {
+      const inv = getRow('organization_invitation', idAt(4), req.root);
+      if (!inv || inv.organization_id !== idAt(2)) return err('Invitation not found', 404, 'resource_not_found');
+      return { status: 200, body: await writeResource('organization_invitation', idAt(4), { status: 'revoked', updated_at: nowUnixMs(req.occurredAt) }, 'organization_invitation.update', req) };
+    }
+    // POST /v1/organizations/:org/invitations/:inv/accept — accept → creates a membership
+    if (seg.length === 6 && seg[3] === 'invitations' && seg[5] === 'accept' && method === 'POST') {
+      const inv = getRow('organization_invitation', idAt(4), req.root);
+      if (!inv || inv.organization_id !== idAt(2)) return err('Invitation not found', 404, 'resource_not_found');
+      if (inv.status !== 'pending') return err('Invitation is no longer pending', 422, 'organization_invitation_not_pending');
+      const userId = params.user_id as string;
+      if (!userId) return err('user_id is required', 422, 'form_param_missing');
+      if (!getRow('user', userId, req.root)) return err('User not found', 404, 'resource_not_found');
+      if (membershipFor(idAt(2), userId, req.root)) return err('User is already a member', 422, 'duplicate_record');
+      const m = await createMembership(idAt(2), userId, String(inv.role ?? 'basic_member'), req);
+      await writeResource('organization_invitation', idAt(4), { status: 'accepted', updated_at: nowUnixMs(req.occurredAt) }, 'organization_invitation.update', req);
+      const org = getRow('organization', idAt(2), req.root);
+      if (org) await writeResource('organization', idAt(2), { pending_invitations_count: Math.max(0, Number(org.pending_invitations_count ?? 0) - 1) }, 'organization.update', req);
+      return { status: 200, body: m };
+    }
+
+    // ── ORGANIZATION DOMAINS ──
+    if (seg.length === 4 && seg[3] === 'domains' && method === 'POST') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const name = params.name as string;
+      if (!name) return err('name is required', 422, 'form_param_missing');
+      const mode = (params.enrollment_mode as string) ?? 'manual_invitation';
+      if (!['manual_invitation', 'automatic_invitation', 'automatic_suggestion'].includes(mode)) {
+        return err('Unknown enrollment_mode', 422, 'form_param_value_invalid');
+      }
+      if (rows('organization_domain', req.root).some((d) => d.organization_id === idAt(2) && d.name === name)) {
+        return err('That domain is already added', 422, 'duplicate_record');
+      }
+      const d = await create('organization_domain', {
+        organization_id: idAt(2), name, enrollment_mode: mode,
+        verification: { status: 'verified', strategy: 'admin', attempts: 0, expire_at: null },
+        affiliation_email_address: null, total_pending_invitations: 0, total_pending_suggestions: 0,
+      }, 'organization_domain.create', req);
+      return { status: 200, body: d };
+    }
+    if (seg.length === 4 && seg[3] === 'domains' && method === 'GET') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const items = rows('organization_domain', req.root).map((r) => view('organization_domain', r)).filter((d) => d.organization_id === idAt(2));
+      return { status: 200, body: listEnvelope(items, query) };
+    }
+    if (seg.length === 5 && seg[3] === 'domains' && method === 'PATCH') {
+      const d = getRow('organization_domain', idAt(4), req.root);
+      if (!d || d.organization_id !== idAt(2)) return err('Domain not found', 404, 'resource_not_found');
+      const patch: Record<string, unknown> = {};
+      if ('enrollment_mode' in params) {
+        const mode = String(params.enrollment_mode);
+        if (!['manual_invitation', 'automatic_invitation', 'automatic_suggestion'].includes(mode)) return err('Unknown enrollment_mode', 422, 'form_param_value_invalid');
+        patch.enrollment_mode = mode;
+      }
+      return { status: 200, body: await writeResource('organization_domain', idAt(4), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'organization_domain.update', req) };
+    }
+    if (seg.length === 5 && seg[3] === 'domains' && method === 'DELETE') {
+      const d = getRow('organization_domain', idAt(4), req.root);
+      if (!d || d.organization_id !== idAt(2)) return err('Domain not found', 404, 'resource_not_found');
+      await writeResource('organization_domain', idAt(4), { deleted: true }, 'organization_domain.delete', req);
+      return { status: 200, body: { object: 'organization_domain', id: idAt(4), deleted: true } };
+    }
+
+    // ── ORGANIZATION LOGO upload / delete ──
+    if (seg.length === 4 && seg[3] === 'logo' && method === 'PUT') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const url = (params.file as string) || `https://img.clerk.twin/org/${idAt(2)}.png`;
+      return { status: 200, body: await writeResource('organization', idAt(2), { image_url: url, has_image: true, updated_at: nowUnixMs(req.occurredAt) }, 'organization.update', req) };
+    }
+    if (seg.length === 4 && seg[3] === 'logo' && method === 'DELETE') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      return { status: 200, body: await writeResource('organization', idAt(2), { image_url: '', has_image: false, updated_at: nowUnixMs(req.occurredAt) }, 'organization.update', req) };
+    }
+
+    // ── ORGANIZATION INVITATIONS: bulk create ──
+    if (seg.length === 5 && seg[3] === 'invitations' && seg[4] === 'bulk' && method === 'POST') {
+      const org = getRow('organization', idAt(2), req.root);
+      if (!org) return err('Organization not found', 404, 'resource_not_found');
+      const list = Array.isArray(params) ? params as unknown[] : Array.isArray(params.invitations) ? params.invitations as unknown[] : [];
+      if (list.length === 0) return err('a non-empty array of invitations is required', 422, 'form_param_missing');
+      const created: Array<Record<string, unknown>> = [];
+      for (const raw of list) {
+        const item = (raw && typeof raw === 'object') ? raw as Record<string, unknown> : {};
+        const email = item.email_address as string;
+        if (!email) return err('each invitation requires an email_address', 422, 'form_param_missing');
+        const inv = await create('organization_invitation', {
+          email_address: email, role: (item.role as string) ?? 'basic_member', organization_id: idAt(2),
+          status: 'pending', public_metadata: (item.public_metadata as object) ?? {}, private_metadata: (item.private_metadata as object) ?? {},
+        }, 'organization_invitation.create', req);
+        created.push(inv);
+      }
+      const org2 = getRow('organization', idAt(2), req.root);
+      if (org2) await writeResource('organization', idAt(2), { pending_invitations_count: Number(org2.pending_invitations_count ?? 0) + created.length }, 'organization.update', req);
+      return { status: 200, body: created };
+    }
+  }
+
+  // ── INSTANCE ORGANIZATION ROLES + PERMISSIONS ──
+  // Clerk exposes the instance's role set (each role carries a permission key list) and
+  // membership roles resolve their permissions from this registry. Defaults are the system
+  // admin/member roles; custom roles can be created and assigned to memberships.
+  if (collection === 'organizations_roles' || collection === 'organization_roles') {
+    if (seg.length === 2 && method === 'POST') {
+      const key = params.key as string;
+      const name = params.name as string;
+      if (!key || !name) return err('key and name are required', 422, 'form_param_missing');
+      if (defaultRoles(req.root).some((r) => r.key === key)) return err('That role key already exists', 422, 'duplicate_record');
+      const permissions = Array.isArray(params.permissions) ? params.permissions as string[] : [];
+      const role = await create('organization_role', { key, name, description: (params.description as string) ?? '', permissions, is_creator_eligible: !!params.is_creator_eligible }, 'organization_role.create', req);
+      return { status: 200, body: role };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      return { status: 200, body: listEnvelope(defaultRoles(req.root), query) };
+    }
+  }
+  if (collection === 'organizations_permissions' || collection === 'organization_permissions') {
+    if (seg.length === 2 && method === 'GET') {
+      return { status: 200, body: listEnvelope([...SYSTEM_PERMISSIONS], query) };
+    }
+  }
+
+  // ── INVITATIONS (application-level) ──
+  if (collection === 'invitations') {
+    if (seg.length === 2 && method === 'POST') {
+      const email = params.email_address as string;
+      if (!email) return err('email_address is required', 422, 'form_param_missing');
+      // `notify` defaults true (real Clerk emails an invite link); a twin never delivers, so
+      // when notify !== false it RECORDS the invite url + a queued notification instead of
+      // sending. `redirect_url` is the post-accept landing url carried on the invite link.
+      const notify = params.notify !== false;
+      const redirectUrl = (params.redirect_url as string) ?? null;
+      const url = notify ? `https://twin.clerk.accounts.dev/invitation?redirect_url=${encodeURIComponent(redirectUrl ?? '')}` : null;
+      const inv = await create('invitation', {
+        email_address: email, status: 'pending', public_metadata: (params.public_metadata as object) ?? {},
+        revoked: false, url, notified: notify, redirect_url: redirectUrl,
+      }, 'invitation.create', req);
+      return { status: 200, body: inv };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('invitation', req.root).map((r) => view('invitation', r));
+      if (query.status) items = items.filter((i) => i.status === query.status);
+      return { status: 200, body: items };
+    }
+    if (seg.length === 4 && seg[3] === 'revoke' && method === 'POST') {
+      const cur = getRow('invitation', idAt(2), req.root);
+      if (!cur) return err('Invitation not found', 404, 'resource_not_found');
+      return { status: 200, body: await writeResource('invitation', idAt(2), { status: 'revoked', revoked: true, updated_at: nowUnixMs(req.occurredAt) }, 'invitation.update', req) };
+    }
+  }
+
+  // ── ALLOWLIST / BLOCKLIST ──
+  for (const [coll, type] of [['allowlist_identifiers', 'allowlist_identifier'], ['blocklist_identifiers', 'blocklist_identifier']] as const) {
+    if (collection === coll) {
+      if (seg.length === 2 && method === 'POST') {
+        const identifier = params.identifier as string;
+        if (!identifier) return err('identifier is required', 422, 'form_param_missing');
+        const idType = identifier.includes('@') ? 'email_address' : 'phone_number';
+        const row = await create(type, { identifier, identifier_type: idType }, `${type}.create`, req);
+        return { status: 200, body: row };
+      }
+      if (seg.length === 2 && method === 'GET') {
+        return { status: 200, body: rows(type, req.root).map((r) => view(type, r)) };
+      }
+      if (seg.length === 3 && method === 'DELETE') {
+        const cur = getRow(type, idAt(2), req.root);
+        if (!cur) return err('Identifier not found', 404, 'resource_not_found');
+        await writeResource(type, idAt(2), { deleted: true }, `${type}.delete`, req);
+        return { status: 200, body: { object: type, id: idAt(2), deleted: true } };
+      }
+    }
+  }
+
+  // ── JWT TEMPLATES ──
+  if (collection === 'jwt_templates') {
+    if (seg.length === 2 && method === 'POST') {
+      const name = params.name as string;
+      if (!name) return err('name is required', 422, 'form_param_missing');
+      // custom_signing_key: bring-your-own HS256 secret (e.g. Supabase's shared secret). When
+      // custom_signing_key=true the template MUST carry signing_algorithm=HS256 + a `key`.
+      const custom = params.custom_signing_key === true;
+      const algo = custom ? String(params.signing_algorithm ?? 'HS256') : 'RS256';
+      if (custom) {
+        if (algo !== 'HS256') return err('custom_signing_key only supports HS256', 422, 'form_param_value_invalid');
+        if (typeof params.key !== 'string' || !params.key) return err('key is required when custom_signing_key is set', 422, 'form_param_missing');
+      }
+      const t = await create('jwt_template', {
+        name, claims: (params.claims as object) ?? {}, lifetime: (params.lifetime as number) ?? 60,
+        allowed_clock_skew: (params.allowed_clock_skew as number) ?? 5, custom_signing_key: custom, signing_algorithm: algo,
+        // `_signing_key` is twin-internal (never serialized — view() drops `_`-keys).
+        ...(custom ? { _signing_key: String(params.key) } : {}),
+      }, 'jwt_template.create', req);
+      return { status: 200, body: t };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      return { status: 200, body: rows('jwt_template', req.root).map((r) => view('jwt_template', r)) };
+    }
+    if (seg.length === 3 && method === 'GET') {
+      const t = getOne('jwt_template', idAt(2), req.root);
+      return t ? { status: 200, body: t } : err('Template not found', 404, 'resource_not_found');
+    }
+    if (seg.length === 3 && method === 'PATCH') {
+      const cur = getRow('jwt_template', idAt(2), req.root);
+      if (!cur) return err('Template not found', 404, 'resource_not_found');
+      const patch: Record<string, unknown> = {};
+      for (const k of ['name', 'claims', 'lifetime', 'allowed_clock_skew']) if (k in params) patch[k] = params[k];
+      return { status: 200, body: await writeResource('jwt_template', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'jwt_template.update', req) };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('jwt_template', idAt(2), req.root);
+      if (!cur) return err('Template not found', 404, 'resource_not_found');
+      await writeResource('jwt_template', idAt(2), { deleted: true }, 'jwt_template.delete', req);
+      return { status: 200, body: { object: 'jwt_template', id: idAt(2), deleted: true } };
+    }
+  }
+
+  // ── SIGN-IN TOKENS (issue a real signed JWT for a user, magic-link style) ──
+  if (collection === 'sign_in_tokens') {
+    if (seg.length === 2 && method === 'POST') {
+      const userId = params.user_id as string;
+      if (!userId) return err('user_id is required', 422, 'form_param_missing');
+      if (!getRow('user', userId, req.root)) return err('User not found', 404, 'resource_not_found');
+      const jwt = await signJwt({ sub: userId, sit: true }, { root: req.root, expiresInSeconds: (params.expires_in_seconds as number) ?? 2592000, ...(req.occurredAt ? { now: Math.floor(nowUnixMs(req.occurredAt) / 1000) } : {}) });
+      const t = await create('sign_in_token', { user_id: userId, status: 'pending', token: jwt, url: null }, 'sign_in_token.create', req);
+      return { status: 200, body: t };
+    }
+    // POST /v1/sign_in_tokens/:id/revoke — revoke a still-pending sign-in token
+    if (seg.length === 4 && seg[3] === 'revoke' && method === 'POST') {
+      const cur = getRow('sign_in_token', idAt(2), req.root);
+      if (!cur) return err('Sign-in token not found', 404, 'resource_not_found');
+      if (cur.status !== 'pending') return err('Sign-in token is no longer pending', 422, 'sign_in_token_cannot_be_revoked');
+      return { status: 200, body: await writeResource('sign_in_token', idAt(2), { status: 'revoked', updated_at: nowUnixMs(req.occurredAt) }, 'sign_in_token.update', req) };
+    }
+  }
+
+  // ── ACTOR TOKENS (impersonation: a token that signs in as a user, optionally AS an actor) ──
+  if (collection === 'actor_tokens') {
+    if (seg.length === 2 && method === 'POST') {
+      const userId = params.user_id as string;
+      const actor = params.actor as Record<string, unknown> | undefined;
+      if (!userId) return err('user_id is required', 422, 'form_param_missing');
+      if (!actor || typeof actor !== 'object' || typeof actor.sub !== 'string') return err('actor.sub is required', 422, 'form_param_missing');
+      if (!getRow('user', userId, req.root)) return err('User not found', 404, 'resource_not_found');
+      const jwt = await signJwt({ sub: userId, act: actor }, { root: req.root, expiresInSeconds: (params.expires_in_seconds as number) ?? 3600, ...(req.occurredAt ? { now: Math.floor(nowUnixMs(req.occurredAt) / 1000) } : {}) });
+      const t = await create('actor_token', { user_id: userId, actor, status: 'pending', token: jwt, url: null }, 'actor_token.create', req);
+      return { status: 200, body: t };
+    }
+    if (seg.length === 4 && seg[3] === 'revoke' && method === 'POST') {
+      const cur = getRow('actor_token', idAt(2), req.root);
+      if (!cur) return err('Actor token not found', 404, 'resource_not_found');
+      if (cur.status !== 'pending') return err('Actor token is no longer pending', 422, 'actor_token_cannot_be_revoked');
+      return { status: 200, body: await writeResource('actor_token', idAt(2), { status: 'revoked', updated_at: nowUnixMs(req.occurredAt) }, 'actor_token.update', req) };
+    }
+  }
+
+  // ── TESTING TOKENS (bypass bot protection in E2E; a short-lived opaque token) ──
+  if (collection === 'testing_tokens' && seg.length === 2 && method === 'POST') {
+    const at = nowUnixMs(req.occurredAt);
+    const tok = `testing_token_${stableHex(`testing_token:${req.occurredAt ?? ''}:${projectResources(SERVICE, req.root).filter((x) => x.type === 'testing_token').length}`, 32)}`;
+    const t = await create('testing_token', { token: tok, expires_at: at + 3600 * 1000 }, 'testing_token.create', req);
+    return { status: 200, body: { object: 'testing_token', id: t.id, token: tok, expires_at: at + 3600 * 1000 } };
+  }
+
+  // ── CLIENTS (verify a client/session token + handshake) ──
+  if (collection === 'clients') {
+    // POST /v1/clients/verify {token} — verify a session JWT and return the bound client+session
+    if (seg.length === 3 && seg[2] === 'verify' && method === 'POST') {
+      const token = params.token as string | undefined;
+      if (!token) return err('token is required', 422, 'form_param_missing');
+      const result = verifyJwtWithJwks(token, await buildJwks(req.root));
+      if (!result.valid) return err(`Invalid token: ${result.reason}`, 401, 'invalid_token');
+      const sid = String(result.payload?.sid ?? '');
+      const session = sid ? getRow('session', sid, req.root) : undefined;
+      const sub = String(result.payload?.sub ?? '');
+      return {
+        status: 200,
+        body: {
+          object: 'client', id: `client_twin`, session_ids: session ? [sid] : [],
+          sessions: session ? [view('session', session)] : [],
+          sign_in_id: null, sign_up_id: null, last_active_session_id: sid || null,
+          ...(sub ? { _user_id: undefined } : {}),
+        },
+      };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      // GET /v1/clients — active clients are derived from active sessions (the twin has one client)
+      const active = rows('session', req.root).filter((s) => s.status === 'active');
+      const clients = active.length === 0 ? [] : [{ object: 'client', id: 'client_twin', session_ids: active.map((s) => s.id), last_active_session_id: active[0]!.id }];
+      return { status: 200, body: listEnvelope(clients, query) };
+    }
+  }
+
+  // ── INSTANCE SETTINGS (restrictions, MFA, attack protection) ──
+  if (collection === 'instance') {
+    if (seg.length === 2 && method === 'GET') {
+      return { status: 200, body: instanceSettings(req.root) };
+    }
+    // PATCH /v1/instance and the focused sub-resources Clerk exposes
+    if (seg.length === 2 && (method === 'PATCH' || method === 'PUT')) {
+      return { status: 200, body: await patchInstance(params, req) };
+    }
+    if (seg.length === 3 && (method === 'PATCH' || method === 'PUT') && ['restrictions', 'organization_settings'].includes(seg[2]!)) {
+      return { status: 200, body: await patchInstance({ [seg[2]!]: params }, req) };
+    }
+  }
+
+  // ── REDIRECT URLS (the instance allowlist of post-auth redirect URLs) ──
+  if (collection === 'redirect_urls') {
+    if (seg.length === 2 && method === 'POST') {
+      const url = params.url as string;
+      if (!url) return err('url is required', 422, 'form_param_missing');
+      const r = await create('redirect_url', { url }, 'redirect_url.create', req);
+      return { status: 200, body: r };
+    }
+    if (seg.length === 2 && method === 'GET') return { status: 200, body: rows('redirect_url', req.root).map((r) => view('redirect_url', r)) };
+    if (seg.length === 3 && method === 'GET') {
+      const r = getOne('redirect_url', idAt(2), req.root);
+      return r ? { status: 200, body: r } : err('Redirect URL not found', 404, 'resource_not_found');
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('redirect_url', idAt(2), req.root);
+      if (!cur) return err('Redirect URL not found', 404, 'resource_not_found');
+      await writeResource('redirect_url', idAt(2), { deleted: true }, 'redirect_url.delete', req);
+      return { status: 200, body: { object: 'redirect_url', id: idAt(2), deleted: true } };
+    }
+  }
+
+  // ── OAUTH APPLICATIONS (the instance's own OAuth/OIDC apps; carries a client secret) ──
+  if (collection === 'oauth_applications') {
+    if (seg.length === 2 && method === 'POST') {
+      const name = params.name as string;
+      if (!name) return err('name is required', 422, 'form_param_missing');
+      const clientId = `client_${stableHex(`oauth_application:${req.occurredAt ?? ''}:${projectResources(SERVICE, req.root).filter((x) => x.type === 'oauth_application').length}`, 24)}`;
+      const clientSecret = `secret_${secretHex(24)}`;
+      const app = await create('oauth_application', {
+        name, instance_id: INSTANCE_ID, client_id: clientId, client_secret: clientSecret,
+        public: !!params.public, scopes: (params.scopes as string) ?? 'profile email',
+        callback_url: (params.callback_url as string) ?? null,
+        redirect_uris: Array.isArray(params.redirect_uris) ? params.redirect_uris : [],
+        authorize_url: 'https://twin.clerk.accounts.dev/oauth/authorize',
+        token_fetch_url: 'https://twin.clerk.accounts.dev/oauth/token',
+        user_info_url: 'https://twin.clerk.accounts.dev/oauth/userinfo',
+      }, 'oauth_application.create', req);
+      return { status: 200, body: app };
+    }
+    if (seg.length === 2 && method === 'GET') return { status: 200, body: listEnvelope(rows('oauth_application', req.root).map((r) => view('oauth_application', r)), query) };
+    if (seg.length === 3 && method === 'GET') {
+      const a = getOne('oauth_application', idAt(2), req.root);
+      return a ? { status: 200, body: a } : err('OAuth application not found', 404, 'resource_not_found');
+    }
+    if (seg.length === 3 && method === 'PATCH') {
+      const cur = getRow('oauth_application', idAt(2), req.root);
+      if (!cur) return err('OAuth application not found', 404, 'resource_not_found');
+      const patch: Record<string, unknown> = {};
+      for (const k of ['name', 'callback_url', 'scopes', 'public', 'redirect_uris']) if (k in params) patch[k] = params[k];
+      return { status: 200, body: await writeResource('oauth_application', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'oauth_application.update', req) };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('oauth_application', idAt(2), req.root);
+      if (!cur) return err('OAuth application not found', 404, 'resource_not_found');
+      await writeResource('oauth_application', idAt(2), { deleted: true }, 'oauth_application.delete', req);
+      return { status: 200, body: { object: 'oauth_application', id: idAt(2), deleted: true } };
+    }
+    // POST /v1/oauth_applications/:id/rotate_secret — issue a fresh client secret
+    if (seg.length === 4 && seg[3] === 'rotate_secret' && method === 'POST') {
+      const cur = getRow('oauth_application', idAt(2), req.root);
+      if (!cur) return err('OAuth application not found', 404, 'resource_not_found');
+      return { status: 200, body: await writeResource('oauth_application', idAt(2), { client_secret: `secret_${secretHex(24)}`, updated_at: nowUnixMs(req.occurredAt) }, 'oauth_application.update', req) };
+    }
+  }
+
+  // ── SAML CONNECTIONS (enterprise SSO connections) ──
+  if (collection === 'saml_connections') {
+    if (seg.length === 2 && method === 'POST') {
+      const name = params.name as string;
+      const domain = params.domain as string;
+      const provider = params.provider as string;
+      if (!name || !domain || !provider) return err('name, domain and provider are required', 422, 'form_param_missing');
+      const conn = await create('saml_connection', {
+        name, domain, provider, active: params.active === true, sync_user_attributes: params.sync_user_attributes !== false,
+        idp_entity_id: (params.idp_entity_id as string) ?? null, idp_sso_url: (params.idp_sso_url as string) ?? null,
+        idp_certificate: (params.idp_certificate as string) ?? null, acs_url: 'https://twin.clerk.accounts.dev/v1/saml/acs',
+        sp_entity_id: `https://twin.clerk.accounts.dev/saml/${domain}`, attribute_mapping: (params.attribute_mapping as object) ?? {},
+      }, 'saml_connection.create', req);
+      return { status: 200, body: conn };
+    }
+    if (seg.length === 2 && method === 'GET') return { status: 200, body: listEnvelope(rows('saml_connection', req.root).map((r) => view('saml_connection', r)), query) };
+    if (seg.length === 3 && method === 'GET') {
+      const c = getOne('saml_connection', idAt(2), req.root);
+      return c ? { status: 200, body: c } : err('SAML connection not found', 404, 'resource_not_found');
+    }
+    if (seg.length === 3 && method === 'PATCH') {
+      const cur = getRow('saml_connection', idAt(2), req.root);
+      if (!cur) return err('SAML connection not found', 404, 'resource_not_found');
+      const patch: Record<string, unknown> = {};
+      for (const k of ['name', 'domain', 'active', 'sync_user_attributes', 'idp_entity_id', 'idp_sso_url', 'idp_certificate', 'attribute_mapping']) if (k in params) patch[k] = params[k];
+      return { status: 200, body: await writeResource('saml_connection', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'saml_connection.update', req) };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('saml_connection', idAt(2), req.root);
+      if (!cur) return err('SAML connection not found', 404, 'resource_not_found');
+      await writeResource('saml_connection', idAt(2), { deleted: true }, 'saml_connection.delete', req);
+      return { status: 200, body: { object: 'saml_connection', id: idAt(2), deleted: true } };
+    }
+  }
+
+  // ── INSTANCE DOMAINS (the primary + satellite domains of the instance) ──
+  if (collection === 'domains') {
+    if (seg.length === 2 && method === 'POST') {
+      const name = params.name as string;
+      if (!name) return err('name is required', 422, 'form_param_missing');
+      const isSatellite = params.is_satellite === true;
+      if (!isSatellite && rows('domain', req.root).some((d) => !d.is_satellite)) {
+        return err('A primary domain already exists; satellite domains must set is_satellite', 422, 'duplicate_record');
+      }
+      if (rows('domain', req.root).some((d) => d.name === name)) return err('That domain is already added', 422, 'duplicate_record');
+      const d = await create('domain', {
+        name, is_satellite: isSatellite, frontend_api_url: `https://clerk.${name}`,
+        accounts_portal_url: isSatellite ? null : `https://accounts.${name}`,
+        proxy_url: (params.proxy_url as string) ?? null,
+        // Clerk's Domain object carries the ORIGIN the development instance is served from.
+        // Derived from this request (R7), or taken verbatim when the caller declares its own.
+        development_origin: typeof params.development_origin === 'string' ? params.development_origin : originOf(req, name),
+        cname_targets: [],
+      }, 'domain.create', req);
+      return { status: 200, body: d };
+    }
+    if (seg.length === 2 && method === 'GET') return { status: 200, body: listEnvelope(rows('domain', req.root).map((r) => view('domain', r)), query) };
+    if (seg.length === 3 && method === 'PATCH') {
+      const cur = getRow('domain', idAt(2), req.root);
+      if (!cur) return err('Domain not found', 404, 'resource_not_found');
+      const patch: Record<string, unknown> = {};
+      for (const k of ['name', 'proxy_url']) if (k in params) patch[k] = params[k];
+      return { status: 200, body: await writeResource('domain', idAt(2), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'domain.update', req) };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const cur = getRow('domain', idAt(2), req.root);
+      if (!cur) return err('Domain not found', 404, 'resource_not_found');
+      if (!cur.is_satellite) return err('The primary domain cannot be deleted', 422, 'primary_domain_not_deletable');
+      await writeResource('domain', idAt(2), { deleted: true }, 'domain.delete', req);
+      return { status: 200, body: { object: 'domain', id: idAt(2), deleted: true } };
+    }
+  }
+
+  // ── WEBHOOK ENDPOINTS (manage svix endpoints via the Backend API) + delivery attempts ──
+  if (collection === 'webhooks') {
+    // POST/GET/PATCH/DELETE /v1/webhooks/endpoints[/:id]
+    if (seg[2] === 'endpoints') {
+      if (seg.length === 3 && method === 'POST') {
+        const url = params.url as string;
+        if (!url) return err('url is required', 422, 'form_param_missing');
+        const secret = `whsec_${Buffer.from(secretHex(24)).toString('base64').slice(0, 32)}`;
+        const ep = await create('webhook_endpoint', {
+          url, signing_secret: secret, description: (params.description as string) ?? null,
+          disabled: false, filter_types: Array.isArray(params.filter_types) ? params.filter_types : null,
+        }, 'webhook_endpoint.create', req);
+        // Delivery reads the endpoint from the tree (webhookTargets), signed with this signing_secret.
+        return { status: 200, body: ep };
+      }
+      if (seg.length === 3 && method === 'GET') return { status: 200, body: listEnvelope(rows('webhook_endpoint', req.root).map((r) => view('webhook_endpoint', r)), query) };
+      if (seg.length === 4 && method === 'GET') {
+        const ep = getOne('webhook_endpoint', idAt(3), req.root);
+        return ep ? { status: 200, body: ep } : err('Webhook endpoint not found', 404, 'resource_not_found');
+      }
+      if (seg.length === 4 && method === 'PATCH') {
+        const cur = getRow('webhook_endpoint', idAt(3), req.root);
+        if (!cur) return err('Webhook endpoint not found', 404, 'resource_not_found');
+        const patch: Record<string, unknown> = {};
+        for (const k of ['url', 'description', 'disabled', 'filter_types']) if (k in params) patch[k] = params[k];
+        return { status: 200, body: await writeResource('webhook_endpoint', idAt(3), { ...patch, updated_at: nowUnixMs(req.occurredAt) }, 'webhook_endpoint.update', req) };
+      }
+      if (seg.length === 4 && method === 'DELETE') {
+        const cur = getRow('webhook_endpoint', idAt(3), req.root);
+        if (!cur) return err('Webhook endpoint not found', 404, 'resource_not_found');
+        await writeResource('webhook_endpoint', idAt(3), { deleted: true }, 'webhook_endpoint.delete', req);
+        return { status: 200, body: { object: 'webhook_endpoint', id: idAt(3), deleted: true } };
+      }
+      // GET /v1/webhooks/endpoints/:id/attempts — the delivery attempts log for this endpoint
+      if (seg.length === 5 && seg[4] === 'attempts' && method === 'GET') {
+        const cur = getRow('webhook_endpoint', idAt(3), req.root);
+        if (!cur) return err('Webhook endpoint not found', 404, 'resource_not_found');
+        const attempts = rows('webhook_attempt', req.root).map((r) => view('webhook_attempt', r)).filter((a) => a.endpoint_id === idAt(3));
+        return { status: 200, body: listEnvelope(attempts, query) };
+      }
+    }
+    // POST /v1/webhooks/svix — provision the svix app (returns the svix app id; idempotent)
+    if (seg.length === 3 && seg[2] === 'svix' && method === 'POST') {
+      return { status: 200, body: { object: 'svix_app', id: 'svix_app_twin', url: 'https://twin.clerk.accounts.dev/svix' } };
+    }
+  }
+
+  // ── WAITLIST ENTRIES (POST creates / returns the existing entry for an email; GET lists) ──
+  if (collection === 'waitlist_entries') {
+    if (seg.length === 2 && method === 'POST') {
+      const email = params.email_address as string;
+      if (!email || typeof email !== 'string' || !email.includes('@')) {
+        return err('email_address is required', 422, 'form_param_missing');
+      }
+      // Real Clerk: if the email is already on the waitlist, no new entry is created — the
+      // existing one is returned (idempotent on email_address).
+      const existing = rows('waitlist_entry', req.root).find((r) => r.email_address === email);
+      if (existing) return { status: 200, body: view('waitlist_entry', existing) };
+      // `notify` defaults true (real Clerk emails on approval); a twin never delivers.
+      const entry = await create('waitlist_entry', {
+        email_address: email, status: 'pending', is_locked: false,
+        invitation: null,
+      }, 'waitlist_entry.create', req);
+      return { status: 200, body: entry };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('waitlist_entry', req.root)
+        // default ordering: creation date descending (newest first), as the real API does
+        .sort((a, b) => Number(b.created_at ?? 0) - Number(a.created_at ?? 0))
+        .map((r) => view('waitlist_entry', r));
+      if (query.status) items = items.filter((i) => i.status === query.status);
+      if (query.email_address) items = items.filter((i) => i.email_address === query.email_address);
+      return { status: 200, body: listEnvelope(items, query) };
+    }
+  }
+
+  // ── PROXY CHECKS (validate that a proxy_url maps to a working proxy for a domain) ──
+  // The REAL endpoint runs a live DNS/HTTP reachability probe against the proxy — that is
+  // a genuine network op the twin can't perform offline. What IS modellable (and faithful)
+  // is the request validation + the recorded proxy_check record: the domain must exist, the
+  // proxy_url must be a well-formed https URL, and the deterministic result is "successful"
+  // when those hold (the twin's network is its own state — the proxy it would reach is the
+  // twin itself, so a well-formed config is reachable). See README ## Coverage.
+  if (collection === 'proxy_checks' && seg.length === 2 && method === 'POST') {
+    const domainId = params.domain_id as string;
+    const proxyUrl = params.proxy_url as string;
+    if (!domainId) return err('domain_id is required', 422, 'form_param_missing');
+    if (!proxyUrl) return err('proxy_url is required', 422, 'form_param_missing');
+    const domain = getRow('domain', domainId, req.root);
+    if (!domain) return err('Domain not found', 404, 'resource_not_found');
+    let wellFormed = false;
+    try {
+      const u = new URL(proxyUrl);
+      wellFormed = u.protocol === 'https:' && !!u.hostname;
+    } catch {
+      wellFormed = false;
+    }
+    if (!wellFormed) return err('proxy_url must be a valid https URL', 422, 'form_param_value_invalid');
+    const check = await create('proxy_check', {
+      domain_id: domainId, proxy_url: proxyUrl,
+      successful: true, last_run_at: nowUnixMs(req.occurredAt),
+    }, 'proxy_check.create', req);
+    return { status: 200, body: check };
+  }
+
+  // ── BETA FEATURES (instance-settings fields still in beta; folded into instance settings) ──
+  // PATCH /v1/beta_features/instance_settings — real Clerk mutates the beta instance settings
+  // (from_email_address / progressive_sign_up / test_mode) and returns the InstanceSettings.
+  if (collection === 'beta_features') {
+    if (seg.length === 3 && seg[2] === 'instance_settings' && (method === 'PATCH' || method === 'PUT')) {
+      const patch: Record<string, unknown> = {};
+      for (const k of ['from_email_address', 'progressive_sign_up', 'test_mode']) if (k in params) patch[k] = params[k];
+      return { status: 200, body: await patchInstance(patch, req) };
+    }
+  }
+
+  // ── EMAIL / SMS (the twin RETURNS the OTP/message; it does NOT deliver — see README) ──
+  if (collection === 'emails' && seg.length === 2 && method === 'POST') {
+    const email = await create('email_address', {
+      to_email_address: params.email_address ?? null, subject: params.subject ?? null,
+      body: params.body ?? null, status: 'queued', delivered_by_clerk: false,
+    }, 'email.create', req);
+    return { status: 200, body: email };
+  }
+
+  return err(`Unknown route: ${method} ${path}`, 404, 'resource_not_found');
+}
+
+// ── email/phone identifier sub-resources ─────────────────────────────────────────
+// Clerk identifiers (email_address / phone_number) are first-class objects WITH their
+// own ids, but they live inside the owning user. The twin keeps them in the user's
+// nested array and resolves an identifier id back to its user for retrieve/verify/delete.
+async function addUserIdentifier(user: Record<string, unknown>, listKey: string, idn: Record<string, unknown>, req: ClerkRequest): Promise<Record<string, unknown>> {
+  const list = Array.isArray(user[listKey]) ? user[listKey] as Array<Record<string, unknown>> : [];
+  const idType = idn.object === 'phone_number' ? 'phone_number' : idn.object === 'web3_wallet' ? 'web3_wallet' : 'email_address';
+  // The identifier ordinal is the owning user's list length: two identifiers added to one user
+  // at the same instant are distinct (the `rows()` count cannot see them — they are nested).
+  const withId = { id: nextId(idType, req.occurredAt, req.root, `${String(user.id)}:${listKey}:${list.length}`), ...idn };
+  const next = [...list, withId];
+  await writeResource('user', String(user.id), { [listKey]: next, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+  return withId;
+}
+function findIdentifier(listKey: string, idnId: string, root?: string): { user: Record<string, unknown>; idn: Record<string, unknown> } | undefined {
+  for (const u of rows('user', root)) {
+    const list = Array.isArray(u[listKey]) ? u[listKey] as Array<Record<string, unknown>> : [];
+    const idn = list.find((e) => e.id === idnId);
+    if (idn) return { user: u, idn };
+  }
+  return undefined;
+}
+async function emailPhoneSubRoutes(
+  listKey: string, objectName: string, seg: string[], method: string,
+  params: Record<string, unknown>, query: Record<string, string>, req: ClerkRequest, idAt: (i: number) => string,
+): Promise<ClerkResponse> {
+  if (seg.length === 3 && method === 'GET') {
+    const found = findIdentifier(listKey, idAt(2), req.root);
+    return found ? { status: 200, body: found.idn } : err('Identifier not found', 404, 'resource_not_found');
+  }
+  // PATCH /v1/email_addresses/:id {verified: true} — admin-mark the identifier verified
+  if (seg.length === 3 && (method === 'PATCH' || method === 'POST')) {
+    const found = findIdentifier(listKey, idAt(2), req.root);
+    if (!found) return err('Identifier not found', 404, 'resource_not_found');
+    const list = found.user[listKey] as Array<Record<string, unknown>>;
+    const verified = params.verified === true;
+    const updated = list.map((e) => e.id === idAt(2)
+      ? { ...e, verification: verified ? { status: 'verified', strategy: 'admin' } : { status: 'unverified', strategy: null } }
+      : e);
+    await writeResource('user', String(found.user.id), { [listKey]: updated, updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+    return { status: 200, body: updated.find((e) => e.id === idAt(2))! };
+  }
+  if (seg.length === 3 && method === 'DELETE') {
+    const found = findIdentifier(listKey, idAt(2), req.root);
+    if (!found) return err('Identifier not found', 404, 'resource_not_found');
+    const list = found.user[listKey] as Array<Record<string, unknown>>;
+    await writeResource('user', String(found.user.id), { [listKey]: list.filter((e) => e.id !== idAt(2)), updated_at: nowUnixMs(req.occurredAt) }, 'user.update', req);
+    return { status: 200, body: { object: objectName, id: idAt(2), deleted: true } };
+  }
+  return err(`Unknown route for ${listKey}`, 404, 'resource_not_found');
+}
+
+// ── validation + helpers ───────────────────────────────────────────────────────
+function validateUserCreate(params: Record<string, unknown>, req: ClerkRequest): ClerkResponse | null {
+  const emails = Array.isArray(params.email_address) ? params.email_address as string[] : [];
+  const phones = Array.isArray(params.phone_number) ? params.phone_number as string[] : [];
+  const username = params.username as string | undefined;
+  if (emails.length === 0 && phones.length === 0 && !username && !params.external_id) {
+    return err('You must provide at least one of the following: email_address, phone_number, username, external_id.', 422, 'form_param_missing');
+  }
+  // unique email across users
+  for (const email of emails) {
+    const taken = rows('user', req.root).some((u) => emailIdsFor(view('user', u)).some((e) => e.email_address === email));
+    if (taken) return err('That email address is taken.', 422, 'form_identifier_exists');
+  }
+  return null;
+}
+
+function userPatch(params: Record<string, unknown>): Record<string, unknown> {
+  const patch: Record<string, unknown> = {};
+  for (const k of ['first_name', 'last_name', 'username', 'public_metadata', 'private_metadata', 'unsafe_metadata', 'external_id', 'primary_email_address_id']) {
+    if (k in params) patch[k] = params[k];
+  }
+  return patch;
+}
+
+function applyUserFilters(items: Array<Record<string, unknown>>, query: Record<string, string>): Array<Record<string, unknown>> {
+  let out = items;
+  if (query.username) out = out.filter((u) => u.username === query.username);
+  if (query.email_address) out = out.filter((u) => emailIdsFor(u).some((e) => e.email_address === query.email_address));
+  if (query.external_id) out = out.filter((u) => u.external_id === query.external_id);
+  if (query.user_id) out = out.filter((u) => u.id === query.user_id);
+  return out;
+}
+
+function userMatchesQuery(u: Record<string, unknown>, q: string): boolean {
+  const hay = [u.first_name, u.last_name, u.username, u.external_id, ...emailIdsFor(u).map((e) => e.email_address)].filter(Boolean).map(String).join(' ').toLowerCase();
+  return hay.includes(q.toLowerCase());
+}
+
+function mergeMetadata(cur: Record<string, unknown>, params: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const bag of ['public_metadata', 'private_metadata', 'unsafe_metadata']) {
+    if (bag in params) {
+      const existing = (cur[bag] && typeof cur[bag] === 'object') ? cur[bag] as object : {};
+      out[bag] = { ...existing, ...(params[bag] as object) };
+    }
+  }
+  return out;
+}
+
+function slugify(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'org';
+}
+function getBySlug(type: string, slug: string, root?: string): Record<string, unknown> | undefined {
+  const r = rows(type, root).find((x) => x.slug === slug);
+  return r ? view(type, r) : undefined;
+}
+
+// ── memberships ──
+// Membership lookups operate on the RAW projected row (not view()) so the twin-internal
+// `_user_id` link is visible; expandMembership() then renders the vendor-facing shape.
+function membershipFor(orgId: string, userId: string, root?: string): Record<string, unknown> | undefined {
+  return rows('organization_membership', root)
+    .find((m) => m.organization_id === orgId && (m as Record<string, unknown>)._user_id === userId);
+}
+function membershipsOf(orgId: string, root?: string): Array<Record<string, unknown>> {
+  return rows('organization_membership', root)
+    .filter((m) => m.organization_id === orgId)
+    .map((m) => expandMembership(m, root));
+}
+async function createMembership(orgId: string, userId: string, role: string, req: ClerkRequest): Promise<Record<string, unknown>> {
+  const m = await create('organization_membership', {
+    organization_id: orgId, _user_id: userId, role, permissions: rolePermissions(role, req.root),
+    public_metadata: {}, private_metadata: {},
+  }, 'organization_membership.create', req);
+  const org = getRow('organization', orgId, req.root);
+  if (org) await writeResource('organization', orgId, { members_count: Number(org.members_count ?? 0) + 1 }, 'organization.update', req);
+  return expandMembership(m, req.root);
+}
+async function decrementMembers(orgId: string, req: ClerkRequest): Promise<void> {
+  const org = getRow('organization', orgId, req.root);
+  if (org) await writeResource('organization', orgId, { members_count: Math.max(0, Number(org.members_count ?? 0) - 1) }, 'organization.update', req);
+}
+
+// ── organization roles + permissions registry ─────────────────────────────────────
+// The full set of system permission keys an org membership can hold (Clerk's `org:sys_*`).
+const SYSTEM_PERMISSIONS = [
+  { object: 'permission', key: 'org:sys_profile:manage', name: 'Manage organization', type: 'system' },
+  { object: 'permission', key: 'org:sys_profile:delete', name: 'Delete organization', type: 'system' },
+  { object: 'permission', key: 'org:sys_memberships:manage', name: 'Manage members', type: 'system' },
+  { object: 'permission', key: 'org:sys_memberships:read', name: 'Read members', type: 'system' },
+  { object: 'permission', key: 'org:sys_domains:manage', name: 'Manage domains', type: 'system' },
+  { object: 'permission', key: 'org:sys_domains:read', name: 'Read domains', type: 'system' },
+] as const;
+const SYSTEM_ROLES: Array<{ object: string; key: string; name: string; description: string; permissions: string[]; is_creator_eligible: boolean }> = [
+  { object: 'role', key: 'admin', name: 'Admin', description: 'Full organization control', permissions: ['org:sys_profile:manage', 'org:sys_profile:delete', 'org:sys_memberships:manage', 'org:sys_memberships:read', 'org:sys_domains:manage', 'org:sys_domains:read'], is_creator_eligible: true },
+  { object: 'role', key: 'basic_member', name: 'Member', description: 'Standard organization member', permissions: ['org:sys_profile:read', 'org:sys_memberships:read'], is_creator_eligible: false },
+];
+/** All roles for the instance: the two system roles plus any custom-created roles. */
+function defaultRoles(root?: string): Array<Record<string, unknown>> {
+  const custom = rows('organization_role', root).map((r) => view('organization_role', r));
+  return [...SYSTEM_ROLES.map((r) => ({ ...r })), ...custom];
+}
+/** Resolve a role key → its permission key list (system role, custom role, or empty). */
+function rolePermissions(role: string, root?: string): string[] {
+  const found = defaultRoles(root).find((r) => r.key === role);
+  if (found && Array.isArray(found.permissions)) return found.permissions as string[];
+  return ['org:sys_profile:read', 'org:sys_memberships:read'];
+}
+
+// ── instance settings (singleton) ─────────────────────────────────────────────────
+const INSTANCE_ID = 'instance_twin';
+const DEFAULT_INSTANCE: Record<string, unknown> = {
+  object: 'instance', id: INSTANCE_ID, environment_type: 'development',
+  restrictions: { allowlist: false, blocklist: false, block_email_subaddresses: false, block_disposable_email_domains: false, ignore_dots_for_gmail_addresses: false },
+  organization_settings: { enabled: true, max_allowed_memberships: 5, creator_role: 'admin', domains: { enabled: false, enrollment_modes: [] } },
+  attack_protection: { user_lockout: { enabled: true, max_attempts: 100, duration_in_minutes: 60 }, pii: { enabled: false } },
+  mfa: { totp: false, sms: false, backup_codes: false },
+  // Beta-features instance settings (PATCH /v1/beta_features/instance_settings).
+  from_email_address: 'support', progressive_sign_up: false, test_mode: false,
+};
+function instanceSettings(root?: string): Record<string, unknown> {
+  const stored = projectResources(SERVICE, root).find((r) => r.type === 'instance' && r.id === INSTANCE_ID && (r as Record<string, unknown>)._deleted !== true);
+  return stored ? { ...DEFAULT_INSTANCE, ...view('instance', stored), object: 'instance', id: INSTANCE_ID } : { ...DEFAULT_INSTANCE };
+}
+async function patchInstance(params: Record<string, unknown>, req: ClerkRequest): Promise<Record<string, unknown>> {
+  const cur = instanceSettings(req.root);
+  const merged: Record<string, unknown> = { ...cur };
+  // Deep-merge the nested setting bags (restrictions / organization_settings / attack_protection / mfa).
+  for (const [k, v] of Object.entries(params)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && cur[k] && typeof cur[k] === 'object') {
+      merged[k] = { ...(cur[k] as object), ...(v as object) };
+    } else {
+      merged[k] = v;
+    }
+  }
+  merged.object = 'instance';
+  await applyTwinWrite(
+    SERVICE,
+    { operation: 'instance.update', subjectType: 'instance', subjectId: INSTANCE_ID, fields: { ...merged, updated_at: nowUnixMs(req.occurredAt) }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } },
+    req.root,
+  );
+  return instanceSettings(req.root);
+}
+// Render a membership in Clerk's shape: nested organization + public_user_data, with the
+// internal `_user_id` removed and exposed inside public_user_data.user_id. Resolves the raw
+// projected row by id so the `_user_id` link is reliable regardless of whether the caller
+// passes a raw row or a view()'d body.
+function expandMembership(input: Record<string, unknown>, root?: string): Record<string, unknown> {
+  const raw = (input._user_id !== undefined ? input : projectResources(SERVICE, root).find((r) => r.id === input.id)) ?? input;
+  const m = { ...input, ...raw };
+  const userId = String(m._user_id ?? '');
+  const user = getRow('user', userId, root);
+  const userView = user ? view('user', user) : undefined;
+  const org = getRow('organization', String(m.organization_id), root);
+  const { _user_id, _deleted, ...rest } = m as Record<string, unknown> & { _user_id?: unknown; _deleted?: unknown };
+  return {
+    ...rest,
+    public_user_data: {
+      user_id: userId,
+      first_name: userView?.first_name ?? null,
+      last_name: userView?.last_name ?? null,
+      image_url: userView?.image_url ?? '',
+      has_image: false,
+      identifier: emailIdsFor(userView ?? {})[0]?.email_address ?? null,
+    },
+    organization: org ? view('organization', org) : null,
+  };
+}
+
+// ── session token claims (the JWT payload Clerk puts in a session token) ──
+async function sessionTokenClaims(session: Record<string, unknown>, template: string | undefined, req: ClerkRequest): Promise<Record<string, unknown>> {
+  const base: Record<string, unknown> = {
+    // The authorized party is the Origin of the browser request that produced the token;
+    // a Backend API mint has no browser behind it.
+    azp: req.origin ?? 'http://localhost',
+    sid: String(session.id),
+    sub: String(session.user_id),
+    iss: CLERK_TWIN_ISSUER,
+  };
+  if (!template) return base;
+  const tmpl = rows('jwt_template', req.root).map((r) => view('jwt_template', r)).find((t) => t.name === template);
+  const claims = tmpl && tmpl.claims && typeof tmpl.claims === 'object' ? tmpl.claims as Record<string, unknown> : {};
+  return { ...base, ...claims };
+}
+
+// Resource types the twin serves (for the conformance + mirror surfaces).
+export const CLERK_RESOURCE_TYPES = [
+  'user', 'session', 'organization', 'organization_membership', 'organization_invitation',
+  'invitation', 'allowlist_identifier', 'blocklist_identifier', 'jwt_template', 'sign_in_token', 'email_address',
+  'actor_token', 'redirect_url', 'oauth_application', 'saml_connection', 'domain', 'webhook_endpoint',
+] as const;