@volter/twin-clerk 0.1.0

package/dist/src/clerk-twin.js

@@ -0,0 +1,1658 @@
+// 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.js";
+import { emitClerkEvent, eventTypeFor } from "./clerk-events.js";
+const SERVICE = 'clerk';
+/** 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';
+/** 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, fallbackHost) {
+    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 = {
+    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, status = 404, code = 'resource_not_found', longMessage) {
+    return {
+        status,
+        body: {
+            errors: [{ code, message, long_message: longMessage ?? message, meta: {} }],
+            clerk_trace_id: 'trace_twin',
+        },
+    };
+}
+function nowUnixMs(occurredAt) {
+    return occurredAt ? Date.parse(occurredAt) : Date.now();
+}
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+function hashPassword(password) {
+    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, digest) {
+    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) {
+    return nodeCrypto().randomBytes(bytes).toString('hex');
+}
+/** A base32 (RFC 4648) secret, the shape Clerk/authenticator apps use for TOTP. */
+function base32Secret(bytes = 20) {
+    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) {
+    if (!body)
+        return {};
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : {};
+    }
+    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, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type && !r.id.startsWith('_') && r.deleted !== true && !r.id.startsWith('_') && r._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, n) {
+    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, occurredAt, root, discriminator = '') {
+    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) {
+    if (Array.isArray(value))
+        return value.map(deepClean);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            if (!k.startsWith('_'))
+                out[k] = deepClean(v);
+        return out;
+    }
+    return value;
+}
+function view(type, r) {
+    const { type: _t, updatedAt: _u, _clerk_type, ...rest } = r;
+    // drop any twin-internal `_`-prefixed fields (top-level + nested) from the vendor body
+    const clean = {};
+    for (const [k, v] of Object.entries(rest))
+        if (!k.startsWith('_'))
+            clean[k] = deepClean(v);
+    const out = { ...clean, id: r.id };
+    if (_clerk_type !== undefined)
+        out.type = _clerk_type;
+    return out;
+}
+function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+function getOne(type, id, root) {
+    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(items, params) {
+    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(items, params) {
+    const { page, total } = paginate(items, params);
+    return { data: page, total_count: total };
+}
+async function writeResource(type, id, fields, op, req) {
+    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) {
+    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, data, op, req) {
+    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) {
+    if (!('type' in fields))
+        return fields;
+    const { type: vt, ...rest } = fields;
+    return { ...rest, _clerk_type: vt };
+}
+async function create(type, fields, op, req, providedId) {
+    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) => Array.isArray(u.email_addresses) ? u.email_addresses : [];
+function buildUser(params, req) {
+    const emails = Array.isArray(params.email_address) ? params.email_address : [];
+    const phones = Array.isArray(params.phone_number) ? params.phone_number : [];
+    // 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 ?? null,
+        first_name: params.first_name ?? null,
+        last_name: params.last_name ?? 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 : [],
+        saml_accounts: [],
+        public_metadata: params.public_metadata ?? {},
+        private_metadata: params.private_metadata ?? {},
+        unsafe_metadata: params.unsafe_metadata ?? {},
+        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 ?? null,
+        password_enabled: hasPassword,
+        // `_password_digest` is twin-internal (never serialized — dropped by view()).
+        _password_digest: passwordDigest,
+    };
+}
+// ── route handler ────────────────────────────────────────────────────────────────
+export async function handleClerkTwinRequest(req) {
+    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 = { ...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) => 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?.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;
+            if (!password)
+                return err('password is required', 422, 'form_param_missing');
+            const digest = cur._password_digest;
+            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 || `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 : [];
+            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 : [];
+            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;
+            const email = params.email_address;
+            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;
+            const phone = params.phone_number;
+            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;
+            const walletAddress = (params.web3_wallet ?? params.wallet_address);
+            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;
+            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 = { 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;
+            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;
+            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;
+            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) => rows('organization', req.root).some((o) => o.slug === s);
+            let slug = params.slug ?? 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 ?? 5,
+                admin_delete_enabled: true, created_by: params.created_by ?? null,
+                public_metadata: params.public_metadata ?? {}, private_metadata: params.private_metadata ?? {},
+            }, '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 = {};
+            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;
+            const role = params.role ?? '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;
+            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;
+            if (!email)
+                return err('email_address is required', 422, 'form_param_missing');
+            const inv = await create('organization_invitation', {
+                email_address: email, role: params.role ?? 'basic_member', organization_id: idAt(2),
+                status: 'pending', public_metadata: params.public_metadata ?? {}, private_metadata: params.private_metadata ?? {},
+            }, '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;
+            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;
+            if (!name)
+                return err('name is required', 422, 'form_param_missing');
+            const mode = params.enrollment_mode ?? '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 = {};
+            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 || `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 : Array.isArray(params.invitations) ? params.invitations : [];
+            if (list.length === 0)
+                return err('a non-empty array of invitations is required', 422, 'form_param_missing');
+            const created = [];
+            for (const raw of list) {
+                const item = (raw && typeof raw === 'object') ? raw : {};
+                const email = item.email_address;
+                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 ?? 'basic_member', organization_id: idAt(2),
+                    status: 'pending', public_metadata: item.public_metadata ?? {}, private_metadata: item.private_metadata ?? {},
+                }, '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;
+            const name = params.name;
+            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 : [];
+            const role = await create('organization_role', { key, name, description: params.description ?? '', 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;
+            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 ?? 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 ?? {},
+                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']]) {
+        if (collection === coll) {
+            if (seg.length === 2 && method === 'POST') {
+                const identifier = params.identifier;
+                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;
+            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 ?? {}, lifetime: params.lifetime ?? 60,
+                allowed_clock_skew: params.allowed_clock_skew ?? 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 = {};
+            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;
+            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 ?? 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;
+            const actor = params.actor;
+            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 ?? 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;
+            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;
+            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;
+            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 ?? 'profile email',
+                callback_url: params.callback_url ?? 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 = {};
+            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;
+            const domain = params.domain;
+            const provider = params.provider;
+            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 ?? null, idp_sso_url: params.idp_sso_url ?? null,
+                idp_certificate: params.idp_certificate ?? 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 ?? {},
+            }, '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 = {};
+            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;
+            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 ?? 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 = {};
+            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;
+                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 ?? 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 = {};
+                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;
+            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;
+        const proxyUrl = params.proxy_url;
+        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 = {};
+            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, listKey, idn, req) {
+    const list = Array.isArray(user[listKey]) ? user[listKey] : [];
+    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, idnId, root) {
+    for (const u of rows('user', root)) {
+        const list = Array.isArray(u[listKey]) ? u[listKey] : [];
+        const idn = list.find((e) => e.id === idnId);
+        if (idn)
+            return { user: u, idn };
+    }
+    return undefined;
+}
+async function emailPhoneSubRoutes(listKey, objectName, seg, method, params, query, req, idAt) {
+    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];
+        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];
+        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, req) {
+    const emails = Array.isArray(params.email_address) ? params.email_address : [];
+    const phones = Array.isArray(params.phone_number) ? params.phone_number : [];
+    const username = params.username;
+    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) {
+    const patch = {};
+    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, query) {
+    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, q) {
+    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, params) {
+    const out = {};
+    for (const bag of ['public_metadata', 'private_metadata', 'unsafe_metadata']) {
+        if (bag in params) {
+            const existing = (cur[bag] && typeof cur[bag] === 'object') ? cur[bag] : {};
+            out[bag] = { ...existing, ...params[bag] };
+        }
+    }
+    return out;
+}
+function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'org';
+}
+function getBySlug(type, slug, root) {
+    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, userId, root) {
+    return rows('organization_membership', root)
+        .find((m) => m.organization_id === orgId && m._user_id === userId);
+}
+function membershipsOf(orgId, root) {
+    return rows('organization_membership', root)
+        .filter((m) => m.organization_id === orgId)
+        .map((m) => expandMembership(m, root));
+}
+async function createMembership(orgId, userId, role, req) {
+    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, req) {
+    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' },
+];
+const SYSTEM_ROLES = [
+    { 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) {
+    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, root) {
+    const found = defaultRoles(root).find((r) => r.key === role);
+    if (found && Array.isArray(found.permissions))
+        return found.permissions;
+    return ['org:sys_profile:read', 'org:sys_memberships:read'];
+}
+// ── instance settings (singleton) ─────────────────────────────────────────────────
+const INSTANCE_ID = 'instance_twin';
+const DEFAULT_INSTANCE = {
+    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) {
+    const stored = projectResources(SERVICE, root).find((r) => r.type === 'instance' && r.id === INSTANCE_ID && r._deleted !== true);
+    return stored ? { ...DEFAULT_INSTANCE, ...view('instance', stored), object: 'instance', id: INSTANCE_ID } : { ...DEFAULT_INSTANCE };
+}
+async function patchInstance(params, req) {
+    const cur = instanceSettings(req.root);
+    const merged = { ...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], ...v };
+        }
+        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, root) {
+    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;
+    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, template, req) {
+    const base = {
+        // 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 : {};
+    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',
+];