@volter/twin-clerk 0.1.0

package/dist/src/clerk-fapi.js

@@ -0,0 +1,665 @@
+// Clerk FRONTEND API twin — the clerk.<domain> surface the real `@clerk/clerk-js`
+// browser bundle talks to. A sibling branch on the SAME seams as the Backend API twin:
+// every read is a projection of the same row store and every mutation delegates to
+// `handleClerkTwinRequest` (user lookup, scrypt password verify, session create/revoke,
+// token mint), so the two surfaces can never disagree about the world.
+//
+// Scope (first slice): environment, client, password sign-in, session tokens, sign-out.
+// Social/OAuth strategies, sign-ups, and MFA are absent from the environment document —
+// the client never offers what the twin does not model.
+//
+// Personas are WORLD STATE: users exist in the store (seeded from a personas file via
+// `--personas`, or created through the Backend API) and sign-in is a protocol against
+// them — nothing is pre-signed-in.
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
+import { handleClerkTwinRequest, stableHex } from "./clerk-twin.js";
+import { buildJwks, verifyJwtWithJwks } from "./clerk-jwt.js";
+const CLIENT_COOKIE = '__client';
+// FAPI error envelope (same shape family as the Backend API).
+function ferr(message, status = 400, code = 'request_invalid', meta) {
+    return { status, body: { errors: [{ code, message, long_message: message, meta: meta ?? {} }], clerk_trace_id: 'trace_twin_fapi' } };
+}
+// clerk-js sends application/x-www-form-urlencoded; tooling may send JSON. Accept both.
+function parseBody(body) {
+    if (!body)
+        return {};
+    const trimmed = body.trim();
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            return Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+        }
+        catch {
+            return {};
+        }
+    }
+    return Object.fromEntries(new URLSearchParams(trimmed));
+}
+async function backend(method, path, body, req) {
+    return handleClerkTwinRequest({
+        method,
+        path,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        ...(req.occurredAt !== undefined ? { occurredAt: req.occurredAt } : {}),
+        ...(req.root !== undefined ? { root: req.root } : {}),
+        ...(req.origin !== undefined ? { origin: req.origin } : {}),
+    });
+}
+const record = (v) => v;
+// ── the environment document ────────────────────────────────────────────────────
+// The client's boot call. Password is the only first factor; no social providers, no
+// sign-up flow beyond what the store models, no captcha, no MFA.
+function environmentDoc(now) {
+    return {
+        object: 'environment',
+        id: 'env_twin',
+        auth_config: {
+            object: 'auth_config',
+            id: 'aac_twin',
+            single_session_mode: true,
+            enhanced_email_deliverability: false,
+            test_mode: true,
+            demo: false,
+            cookieless_dev: false,
+            url_based_session_syncing: false,
+            claimed_at: now,
+            reverification: false,
+        },
+        display_config: {
+            object: 'display_config',
+            id: 'display_config_twin',
+            instance_environment_type: 'development',
+            application_name: 'twin',
+            branded: false,
+            preferred_sign_in_strategy: 'password',
+            logo_image_url: '',
+            favicon_image_url: '',
+            home_url: 'http://localhost',
+            sign_in_url: 'http://localhost/sign-in',
+            sign_up_url: 'http://localhost/sign-up',
+            after_sign_in_url: 'http://localhost',
+            after_sign_up_url: 'http://localhost',
+            after_sign_out_one_url: 'http://localhost',
+            after_sign_out_all_url: 'http://localhost',
+            after_switch_session_url: 'http://localhost',
+            captcha_public_key: null,
+            captcha_widget_type: null,
+            captcha_provider: 'turnstile',
+            captcha_public_key_invisible: null,
+            support_email: null,
+            clerk_js_version: '5',
+        },
+        user_settings: {
+            attributes: {
+                email_address: { enabled: true, required: true, used_for_first_factor: true, first_factors: ['email_code'], used_for_second_factor: false, second_factors: [], verifications: ['email_code'], verify_at_sign_up: false },
+                phone_number: { enabled: false, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                username: { enabled: false, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                first_name: { enabled: true, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                last_name: { enabled: true, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                password: { enabled: true, required: true, used_for_first_factor: true, first_factors: ['password'], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                web3_wallet: { enabled: false, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                authenticator_app: { enabled: false, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                backup_code: { enabled: false, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+                passkey: { enabled: false, required: false, used_for_first_factor: false, first_factors: [], used_for_second_factor: false, second_factors: [], verifications: [], verify_at_sign_up: false },
+            },
+            sign_in: { second_factor: { required: false } },
+            sign_up: { captcha_enabled: false, captcha_widget_type: null, custom_action_required: false, progressive: true, mode: 'public', legal_consent_enabled: false },
+            social: {
+                oauth_apple: { enabled: true, required: false, authenticatable: true, block_email_subaddresses: false, strategy: 'oauth_apple', not_selectable: false, deprecated: false, name: 'Apple', logo_url: '' },
+                oauth_google: { enabled: true, required: false, authenticatable: true, block_email_subaddresses: false, strategy: 'oauth_google', not_selectable: false, deprecated: false, name: 'Google', logo_url: '' },
+            },
+            actions: { delete_self: false, create_organization: false },
+            attack_protection: { user_lockout: { enabled: false }, pii: { enabled: false }, email_link: { require_same_client: false } },
+            passkey_settings: { allow_autofill: false, show_sign_in_button: false },
+            password_settings: {
+                allowed_special_characters: '', disable_hibp: true, min_length: 1, max_length: 0,
+                require_special_char: false, require_numbers: false, require_uppercase: false,
+                require_lowercase: false, show_zxcvbn: false, min_zxcvbn_strength: 0, enforce_hibp_on_sign_in: false,
+            },
+            saml: { enabled: false },
+            enterprise_sso: { enabled: false },
+        },
+        organization_settings: {
+            enabled: false, max_allowed_memberships: 0, force_organization_selection: false,
+            actions: { admin_delete: false }, domains: { enabled: false, enrollment_modes: [], default_role: null },
+            creator_role: 'org:admin',
+        },
+        fraud_settings: { native: { device_attestation_mode: 'disabled' } },
+        commerce_settings: { billing: { enabled: false, stripe_publishable_key: null, has_paid_user_plans: false, has_paid_org_plans: false, organization: { enabled: false }, user: { enabled: false } } },
+        api_keys_settings: { enabled: false },
+        maintenance_mode: false,
+    };
+}
+// ── FAPI views (the client-facing shapes of the same rows) ──────────────────────
+function fapiSession(session, user, lastTokenJwt) {
+    return {
+        object: 'session',
+        id: session.id,
+        status: session.status,
+        expire_at: session.expire_at,
+        abandon_at: session.abandon_at,
+        last_active_at: session.last_active_at,
+        last_active_organization_id: session.last_active_organization_id ?? null,
+        actor: session.actor ?? null,
+        tasks: [],
+        user,
+        public_user_data: user === null ? null : {
+            first_name: user.first_name ?? null,
+            last_name: user.last_name ?? null,
+            image_url: user.image_url ?? '',
+            has_image: false,
+            identifier: primaryIdentifier(user),
+            profile_image_url: user.profile_image_url ?? '',
+        },
+        created_at: session.created_at,
+        updated_at: session.updated_at,
+        // The envelope carries a REAL token per session — clerk-js derives sessionClaims from
+        // it on first render; a null here is an "Invalid state" throw in clerk-react.
+        last_active_token: lastTokenJwt === undefined || lastTokenJwt === null ? null : { object: 'token', jwt: lastTokenJwt },
+        factor_verification_age: null,
+    };
+}
+function primaryIdentifier(user) {
+    const emails = Array.isArray(user.email_addresses) ? user.email_addresses : [];
+    return String(emails[0]?.email_address ?? user.id);
+}
+// The Backend user view is already snake_case Clerk shape; FAPI adds organization_memberships.
+function fapiUser(user) {
+    return { ...user, organization_memberships: [] };
+}
+// ── client state (a real row: the browser's client with its sessions) ───────────
+async function getClientRow(clientId, req) {
+    const all = await backend('GET', '/v1/sessions', undefined, req);
+    if (all.status !== 200 || !Array.isArray(all.body))
+        return undefined;
+    const sessions = all.body.filter((s) => s.client_id === clientId && s.status === 'active');
+    return { id: clientId, sessions };
+}
+// PROTOCOL 2: a sign-in or sign-up attempt is a protocol scratchpad, and the browser's client remembers the one it is
+// mid-way through — both live in the TREE (subjects `sign_in_attempt`, `sign_up_attempt`, `fapi_client`), never in a
+// module-level map: a served twin holds no truth outside its root, and a branch sees its own attempts.
+const SERVICE = 'clerk';
+/** The instant this request happens at: the world's, never the process's. A served body that reads the wall
+ *  clock is not a pure function of (request, stored state) — two replays of one world would differ. */
+const atMs = (req) => {
+    const parsed = req.occurredAt ? Date.parse(req.occurredAt) : NaN;
+    return Number.isNaN(parsed) ? Date.parse(worldNow()) : parsed;
+};
+function readSubject(type, id, root) {
+    const r = projectResources(SERVICE, root).find((x) => x.type === type && x.id === id);
+    if (r === undefined)
+        return undefined;
+    const { type: _t, updatedAt: _u, id: _i, ...fields } = r;
+    return fields;
+}
+async function writeSubject(type, id, fields, req) {
+    await applyTwinWrite(SERVICE, { operation: `${type}.upsert`, subjectType: type, subjectId: id, fields: { _fapi: true, ...fields }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
+}
+const readSignIn = (id, root) => (id ? readSubject('sign_in_attempt', id, root) : undefined);
+const readSignUp = (id, root) => (id ? readSubject('sign_up_attempt', id, root) : undefined);
+const saveSignIn = (a, req) => writeSubject('sign_in_attempt', a.id, { ...a }, req);
+const saveSignUp = (a, req) => writeSubject('sign_up_attempt', a.id, { ...a, fields: { ...a.fields } }, req);
+const clientMemory = (clientId, root) => readSubject('fapi_client', clientId, root) ?? {};
+const rememberClient = (clientId, patch, req) => writeSubject('fapi_client', clientId, { ...clientMemory(clientId, req.root), ...patch }, req);
+async function clientEnvelope(clientId, req, signInAttempt) {
+    const at = atMs(req);
+    const row = await getClientRow(clientId, req);
+    const sessions = row === undefined ? [] : row.sessions;
+    const withUsers = [];
+    for (const s of sessions) {
+        const u = await backend('GET', `/v1/users/${encodeURIComponent(String(s.user_id))}`, undefined, req);
+        const minted = await backend('POST', `/v1/sessions/${encodeURIComponent(String(s.id))}/tokens`, {}, req);
+        withUsers.push(fapiSession(s, u.status === 200 ? fapiUser(record(u.body)) : null, minted.status === 200 ? String(record(minted.body).jwt) : null));
+    }
+    const last = withUsers.at(-1);
+    const memory = clientMemory(clientId, req.root);
+    const rememberedSignIn = readSignIn(memory.sign_in_attempt ?? '', req.root);
+    const rememberedSignUp = readSignUp(memory.sign_up_attempt ?? '', req.root);
+    return {
+        object: 'client',
+        id: clientId,
+        sessions: withUsers,
+        sign_in: signInAttempt ?? (rememberedSignIn === undefined ? null : signInView(rememberedSignIn, atMs(req))),
+        sign_up: rememberedSignUp === undefined ? null : signUpView(rememberedSignUp, atMs(req)),
+        last_active_session_id: last === undefined ? null : last.id,
+        cookie_expires_at: null,
+        captcha_bypass: true,
+        created_at: at,
+        updated_at: at,
+    };
+}
+// DETERMINISTIC (R9): a Frontend API id is a stable hash of (type, the world instant, the rows
+// the type already holds) in Clerk's `<prefix>_<24 hex>` shape — never a random UUID, so two
+// identical worlds mint identical clients and attempts.
+function fapiId(prefix, type, req) {
+    const held = projectResources(SERVICE, req.root).filter((x) => x.type === type).length;
+    return `${prefix}_${stableHex(`${type}:${new Date(atMs(req)).toISOString()}:${held}`, 24)}`;
+}
+/** Mint the browser's client and record it, so the next browser at the same instant counts it
+ *  and is minted a different id. */
+async function newClientId(req) {
+    const id = fapiId('client', 'fapi_client', req);
+    await writeSubject('fapi_client', id, {}, req);
+    return id;
+}
+function clientCookie(clientId) {
+    // SameSite=None + Secure + Partitioned: the app runs EMBEDDED (a Room Surface iframe on
+    // another origin), where a Lax cookie is silently dropped as third-party — which kills
+    // exactly the flows that cross a navigation (oauth consent → callback) and spares the
+    // in-response ones (ticket). Partitioned keeps it working under third-party phaseout.
+    return `${CLIENT_COOKIE}=${clientId}; Path=/; SameSite=None; Secure; Partitioned`;
+}
+// A social strategy's provider identity, as the fake provider would report it. Stable
+// per attempt so the consent page and the completed user agree.
+const OAUTH_PROVIDERS = {
+    oauth_apple: { name: 'Apple', domain: 'twin-apple.test' },
+    oauth_google: { name: 'Google', domain: 'twin-google.test' },
+};
+// One browser, one social identity: the same client always resolves to the same provider
+// account — exactly real-provider semantics, so a sign-up creates the member and a later
+// sign-in from the same browser returns them instead of minting a stranger the app has
+// never seen (which dead-ends any post-auth member lookup).
+async function mintExternalIdentity(strategy, clientId, req) {
+    const provider = OAUTH_PROVIDERS[strategy] ?? { domain: 'twin-oauth.test', name: 'Provider' };
+    const retained = clientId === undefined ? undefined : clientMemory(clientId, req.root).identities?.[strategy];
+    if (retained !== undefined)
+        return retained;
+    const tag = stableHex(`external_identity:${strategy}:${clientId ?? ''}:${new Date(atMs(req)).toISOString()}`, 8);
+    const identity = { email: `qa-${tag}@${provider.domain}`, firstName: 'Casey', lastName: `${provider.name}QA` };
+    if (clientId !== undefined)
+        await rememberClient(clientId, { identities: { ...(clientMemory(clientId, req.root).identities ?? {}), [strategy]: identity } }, req);
+    return identity;
+}
+function consentUrlFor(attemptId, redirectUrl) {
+    // The public origin the BROWSER must navigate to is exactly the origin the app gave in
+    // its own absolute redirect_url — no header plumbing through the mounts required.
+    const origin = new URL(redirectUrl).origin;
+    return `${origin}/v1/oauth-consent?attempt=${encodeURIComponent(attemptId)}`;
+}
+function signUpView(a, at) {
+    const missing = [];
+    if (a.strategy === undefined) {
+        if (a.fields.email_address === undefined)
+            missing.push('email_address');
+        if (a.fields.password === undefined)
+            missing.push('password');
+    }
+    const externalAccount = a.strategy === undefined ? null : a.status === 'complete'
+        ? { status: 'verified', strategy: a.strategy, attempts: null, expire_at: null, error: null }
+        : { status: 'unverified', strategy: a.strategy, attempts: null, expire_at: at + 600_000, error: null, external_verification_redirect_url: a.redirectUrl === undefined ? null : consentUrlFor(a.id, a.redirectUrl) };
+    return {
+        object: 'sign_up',
+        id: a.id,
+        status: a.status,
+        required_fields: a.strategy === undefined ? ['email_address', 'password'] : [],
+        optional_fields: ['first_name', 'last_name', 'phone_number', 'unsafe_metadata'],
+        missing_fields: a.status === 'complete' ? [] : missing,
+        unverified_fields: [],
+        verifications: { email_address: null, phone_number: null, external_account: externalAccount, web3_wallet: null },
+        username: null,
+        email_address: a.fields.email_address ?? null,
+        phone_number: a.fields.phone_number ?? null,
+        web3_wallet: null,
+        password_enabled: a.fields.password !== undefined,
+        first_name: a.fields.first_name ?? null,
+        last_name: a.fields.last_name ?? null,
+        unsafe_metadata: {},
+        public_metadata: {},
+        custom_action: false,
+        external_id: null,
+        created_session_id: a.createdSessionId,
+        created_user_id: a.createdUserId,
+        abandon_at: at + 3600_000,
+        legal_accepted_at: a.fields.legal_accepted === undefined ? null : at,
+    };
+}
+function signInView(a, at) {
+    return {
+        object: 'sign_in',
+        id: a.id,
+        status: a.status,
+        supported_identifiers: ['email_address'],
+        supported_first_factors: [{ strategy: 'password' }],
+        supported_second_factors: null,
+        first_factor_verification: a.status === 'complete'
+            ? { status: 'verified', strategy: a.strategy ?? 'password', attempts: 1, expire_at: null, error: null }
+            : a.strategy !== undefined
+                ? { status: 'unverified', strategy: a.strategy, attempts: null, expire_at: at + 600_000, error: null, external_verification_redirect_url: a.redirectUrl === undefined ? null : consentUrlFor(a.id, a.redirectUrl) }
+                : { status: null, strategy: null, attempts: null, expire_at: null, error: null },
+        second_factor_verification: null,
+        identifier: a.identifier,
+        user_data: {},
+        created_session_id: a.createdSessionId,
+        abandon_at: at + 3600_000,
+    };
+}
+// ── the handler ─────────────────────────────────────────────────────────────────
+export async function handleClerkFapiRequest(req) {
+    const seg = req.path.split('/').filter((s) => s.length > 0);
+    const method = req.method.toUpperCase();
+    const params = parseBody(req.body);
+    const cookieClient = req.cookies?.[CLIENT_COOKIE];
+    if (seg[0] !== 'v1')
+        return ferr(`Unknown route: ${req.path}`, 404, 'resource_not_found');
+    // GET /v1/environment — the boot document.
+    if (seg[1] === 'environment' && seg.length === 2 && method === 'GET') {
+        return { status: 200, body: environmentDoc(atMs(req)) };
+    }
+    // PATCH /v1/environment — clerk-js pings this in development; echo the document.
+    if (seg[1] === 'environment' && seg.length === 2 && method === 'PATCH') {
+        return { status: 200, body: environmentDoc(atMs(req)) };
+    }
+    // POST /v1/dev_browser — development-instance browser identification.
+    if (seg[1] === 'dev_browser' && method === 'POST') {
+        return { status: 200, body: { object: 'dev_browser', id: 'devb_twin', token: 'devb_twin_token' } };
+    }
+    // ── the twin provider's consent page: where an oauth strategy's external verification
+    // actually happens. GET renders the consent; POST completes the attempt (a REAL user row
+    // and session through the Backend doors) and redirects back to the app's callback.
+    if (seg[1] === 'oauth-consent') {
+        const attemptId = req.query?.attempt ?? params.attempt ?? '';
+        const su = readSignUp(attemptId, req.root);
+        const si = su === undefined ? readSignIn(attemptId, req.root) : undefined;
+        const holder = su ?? si;
+        if (holder === undefined || holder.strategy === undefined || holder.redirectUrl === undefined || holder.externalIdentity === undefined)
+            return ferr('Unknown or non-oauth attempt', 404, 'resource_not_found');
+        const provider = OAUTH_PROVIDERS[holder.strategy] ?? { domain: 'twin-oauth.test', name: 'Provider' };
+        const identity = holder.externalIdentity;
+        if (method === 'GET') {
+            // The form posts back to this page's own path RELATIVELY: the page is reached at the app's
+            // origin (consentUrlFor) or under a served World's mount path, and a root-absolute action
+            // would escape the mount; a twinPublicBase action would leave the app's origin (and its cookies).
+            const html = `<!doctype html><html><head><meta charset="utf-8"><title>${provider.name} — Continue</title>
+<style>body{font-family:system-ui;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#f5f5f5}main{background:#fff;border:1px solid #ddd;border-radius:12px;padding:32px;max-width:380px;text-align:center}button{margin-top:16px;padding:10px 24px;border-radius:8px;border:none;background:#1a73e8;color:#fff;font-size:15px;cursor:pointer}</style></head>
+<body><main><h2>Sign in with ${provider.name}</h2><p>(twin provider — no real ${provider.name} account is involved)</p>
+<p><strong>${identity.firstName} ${identity.lastName}</strong><br>${identity.email}</p>
+<form method="post" action="oauth-consent"><input type="hidden" name="attempt" value="${attemptId}"><button type="submit">Continue as ${identity.firstName}</button></form></main></body></html>`;
+            return { status: 200, body: null, html };
+        }
+        if (method === 'POST') {
+            const clientId = cookieClient ?? await newClientId(req);
+            const found = await backend('GET', `/v1/users?email_address=${encodeURIComponent(identity.email)}`, undefined, req);
+            let user = Array.isArray(found.body) ? found.body[0] : undefined;
+            if (user === undefined) {
+                const created = await backend('POST', '/v1/users', { email_address: [identity.email], first_name: identity.firstName, last_name: identity.lastName }, req);
+                if (created.status !== 200)
+                    return { status: created.status, body: created.body };
+                user = record(created.body);
+            }
+            const session = await backend('POST', '/v1/sessions', { user_id: user.id, client_id: clientId }, req);
+            if (session.status !== 200)
+                return { status: session.status, body: session.body };
+            holder.status = 'complete';
+            holder.createdSessionId = String(record(session.body).id);
+            if (su !== undefined) {
+                su.createdUserId = String(user.id);
+                su.fields.email_address = identity.email;
+                await saveSignUp(su, req);
+            }
+            else if (si !== undefined) {
+                si.userId = String(user.id);
+                si.identifier = identity.email;
+                await saveSignIn(si, req);
+            }
+            return { status: 303, body: null, redirect: holder.redirectUrl, setCookies: cookieClient === undefined ? [clientCookie(clientId)] : [] };
+        }
+    }
+    // ── /v1/me — the signed-in user's own profile, password and sessions: what clerk-js's UserProfile writes
+    // through (walks 3 and 4 saw "Unknown route: POST /v1/me" and an empty "Active devices").
+    if (seg[1] === 'me') {
+        const signedOut = { status: 401, body: { errors: [{ message: 'Signed out', long_message: 'You are signed out', code: 'signed_out' }] } };
+        if (cookieClient === undefined)
+            return signedOut;
+        const row = await getClientRow(cookieClient, req);
+        const sessions = row?.sessions ?? [];
+        const current = sessions[sessions.length - 1];
+        if (current === undefined)
+            return signedOut;
+        const userId = String(current.user_id);
+        const me = async () => { const u = await backend('GET', `/v1/users/${encodeURIComponent(userId)}`, undefined, req); return fapiUser(record(u.body)); };
+        const envelope = async (response) => ({ status: 200, body: { response, client: await clientEnvelope(cookieClient, req) } });
+        if (seg.length === 2 && method === 'GET')
+            return envelope(await me());
+        if (seg.length === 2 && (method === 'PATCH' || method === 'POST')) {
+            const patch = {};
+            for (const k of ['first_name', 'last_name', 'username', 'primary_email_address_id', 'unsafe_metadata'])
+                if (params[k] !== undefined)
+                    patch[k] = params[k];
+            const u = await backend('PATCH', `/v1/users/${encodeURIComponent(userId)}`, patch, req);
+            if (u.status !== 200)
+                return { status: u.status, body: u.body };
+            return envelope(fapiUser(record(u.body)));
+        }
+        if (seg.length === 3 && seg[2] === 'change_password' && method === 'POST') {
+            const next = typeof params.new_password === 'string' ? params.new_password : '';
+            if (next.length < 8)
+                return { status: 422, body: { errors: [{ message: 'Passwords must be 8 characters or more.', code: 'form_password_length_too_short', meta: { param_name: 'new_password' } }] } };
+            if (typeof params.current_password === 'string' && params.current_password !== '') {
+                const v = await backend('POST', `/v1/users/${encodeURIComponent(userId)}/verify_password`, { password: params.current_password }, req);
+                if (v.status !== 200)
+                    return { status: 422, body: { errors: [{ message: 'Incorrect password', long_message: 'The current password is incorrect.', code: 'form_password_incorrect', meta: { param_name: 'current_password' } }] } };
+            }
+            const u = await backend('PATCH', `/v1/users/${encodeURIComponent(userId)}`, { password: next }, req);
+            if (u.status !== 200)
+                return { status: u.status, body: u.body };
+            return envelope(fapiUser(record(u.body)));
+        }
+        if (seg.length === 4 && seg[2] === 'sessions' && seg[3] === 'active' && method === 'GET') {
+            const all = await backend('GET', '/v1/sessions', undefined, req);
+            const mine = (Array.isArray(all.body) ? all.body : []).filter((s) => s.user_id === userId && s.status === 'active');
+            const u = await me();
+            return envelope(mine.map((s) => ({ ...fapiSession(s, u), latest_activity: { id: `activity_${String(s.id)}`, object: 'session_activity', device_type: 'Macintosh', is_mobile: false, browser_name: 'Chrome', browser_version: '', ip_address: '127.0.0.1', city: '', country: '' } })));
+        }
+        if (seg.length === 5 && seg[2] === 'sessions' && seg[4] === 'revoke' && method === 'POST') {
+            const r = await backend('POST', `/v1/sessions/${encodeURIComponent(String(seg[3]))}/revoke`, {}, req);
+            if (r.status !== 200)
+                return { status: r.status, body: r.body };
+            return envelope(fapiSession(record(r.body), await me()));
+        }
+        return { status: 404, body: { errors: [{ message: `Unknown route: ${method} ${req.path}`, code: 'resource_not_found' }] } };
+    }
+    if (seg[1] === 'client') {
+        // PUT/POST /v1/client — ensure the browser's client exists.
+        if (seg.length === 2 && (method === 'POST' || method === 'PUT')) {
+            const id = cookieClient ?? await newClientId(req);
+            return { status: 200, body: { response: await clientEnvelope(id, req), client: null }, setCookies: [clientCookie(id)] };
+        }
+        // GET /v1/client — read it (200 with a null response when no cookie yet).
+        if (seg.length === 2 && method === 'GET') {
+            if (cookieClient === undefined)
+                return { status: 200, body: { response: null, client: null } };
+            return { status: 200, body: { response: await clientEnvelope(cookieClient, req), client: null } };
+        }
+        // DELETE /v1/client — sign out everything on this client.
+        if (seg.length === 2 && method === 'DELETE') {
+            if (cookieClient !== undefined) {
+                const row = await getClientRow(cookieClient, req);
+                for (const s of row?.sessions ?? []) {
+                    await backend('POST', `/v1/sessions/${encodeURIComponent(String(s.id))}/revoke`, {}, req);
+                }
+            }
+            const id = cookieClient ?? await newClientId(req);
+            return { status: 200, body: { response: await clientEnvelope(id, req), client: null } };
+        }
+        // The real Frontend API mints the browser's client lazily on first need — a sign-in
+        // beginning IS that need. Everything after an attempt exists rides the minted cookie.
+        const clientId = cookieClient ?? await newClientId(req);
+        const mintedCookies = cookieClient === undefined ? [clientCookie(clientId)] : [];
+        const withMint = (res) => mintedCookies.length === 0 ? res : { ...res, setCookies: [...(res.setCookies ?? []), ...mintedCookies] };
+        // ── sign-ups: the app-visible registration protocol. A sign-up attempt collects
+        // fields progressively; when email + password are present it becomes a REAL user row
+        // (through the Backend door, password scrypt-hashed there) plus an active session.
+        if (seg[2] === 'sign_ups' && (seg.length === 3 || seg.length === 4) && (method === 'POST' || method === 'PATCH')) {
+            const existingId = seg.length === 4 ? seg[3] : undefined;
+            const attempt = existingId === undefined
+                ? { id: fapiId('sua', 'sign_up_attempt', req), fields: {}, status: 'missing_requirements', createdSessionId: null, createdUserId: null }
+                : readSignUp(existingId, req.root);
+            if (attempt === undefined)
+                return ferr('Sign-up attempt not found', 404, 'resource_not_found');
+            // A social strategy hands verification to the (twin) provider: the client navigates
+            // to the consent page, which completes the attempt and redirects back.
+            if (typeof params.strategy === 'string' && params.strategy.startsWith('oauth_')) {
+                if (typeof params.redirect_url !== 'string' || params.redirect_url === '')
+                    return ferr('redirect_url is required for an oauth strategy', 422, 'form_param_missing');
+                attempt.strategy = params.strategy;
+                attempt.redirectUrl = params.redirect_url;
+                attempt.externalIdentity ??= await mintExternalIdentity(params.strategy, clientId, req);
+                attempt.status = 'missing_requirements';
+                await saveSignUp(attempt, req);
+                await rememberClient(clientId, { sign_up_attempt: attempt.id }, req);
+                return withMint({ status: 200, body: { response: signUpView(attempt, atMs(req)), client: await clientEnvelope(clientId, req) } });
+            }
+            for (const key of ['email_address', 'password', 'first_name', 'last_name', 'phone_number', 'unsafe_metadata', 'legal_accepted']) {
+                if (params[key] !== undefined)
+                    attempt.fields[key] = params[key];
+            }
+            if (attempt.status !== 'complete' && attempt.fields.email_address !== undefined && attempt.fields.password !== undefined) {
+                const email = attempt.fields.email_address;
+                const taken = await backend('GET', `/v1/users?email_address=${encodeURIComponent(email)}`, undefined, req);
+                if (Array.isArray(taken.body) && taken.body.length > 0) {
+                    await saveSignUp(attempt, req);
+                    return withMint({ status: 422, body: { errors: [{ code: 'form_identifier_exists', message: 'That email address is taken. Please try another.', long_message: 'That email address is taken. Please try another.', meta: { param_name: 'email_address' } }], clerk_trace_id: 'trace_twin_fapi' } });
+                }
+                const created = await backend('POST', '/v1/users', {
+                    email_address: [email],
+                    password: attempt.fields.password,
+                    ...(attempt.fields.first_name !== undefined ? { first_name: attempt.fields.first_name } : {}),
+                    ...(attempt.fields.last_name !== undefined ? { last_name: attempt.fields.last_name } : {}),
+                }, req);
+                if (created.status !== 200)
+                    return withMint({ status: created.status, body: created.body });
+                const session = await backend('POST', '/v1/sessions', { user_id: record(created.body).id, client_id: clientId }, req);
+                if (session.status !== 200)
+                    return withMint({ status: session.status, body: session.body });
+                attempt.status = 'complete';
+                attempt.createdUserId = String(record(created.body).id);
+                attempt.createdSessionId = String(record(session.body).id);
+            }
+            await saveSignUp(attempt, req);
+            await rememberClient(clientId, { sign_up_attempt: attempt.id }, req);
+            return withMint({ status: 200, body: { response: signUpView(attempt, atMs(req)), client: await clientEnvelope(clientId, req) } });
+        }
+        // GET /v1/client/sign_ups/:id — read an attempt back.
+        if (seg[2] === 'sign_ups' && seg.length === 4 && method === 'GET') {
+            const attempt = readSignUp(String(seg[3]), req.root);
+            if (attempt === undefined)
+                return ferr('Sign-up attempt not found', 404, 'resource_not_found');
+            return withMint({ status: 200, body: { response: signUpView(attempt, atMs(req)), client: await clientEnvelope(clientId, req) } });
+        }
+        // POST /v1/client/sign_ins — begin a sign-in. An oauth strategy hands verification to
+        // the (twin) provider's consent page; the password path checks against a stored user.
+        if (seg[2] === 'sign_ins' && seg.length === 3 && method === 'POST') {
+            if (typeof params.strategy === 'string' && params.strategy.startsWith('oauth_')) {
+                if (typeof params.redirect_url !== 'string' || params.redirect_url === '')
+                    return withMint(ferr('redirect_url is required for an oauth strategy', 422, 'form_param_missing'));
+                const attempt = { id: fapiId('sia', 'sign_in_attempt', req), userId: '', identifier: '', status: 'needs_first_factor', createdSessionId: null, strategy: params.strategy, redirectUrl: params.redirect_url, externalIdentity: await mintExternalIdentity(params.strategy, clientId, req) };
+                await saveSignIn(attempt, req);
+                await rememberClient(clientId, { sign_in_attempt: attempt.id }, req);
+                return withMint({ status: 200, body: { response: signInView(attempt, atMs(req)), client: await clientEnvelope(clientId, req) } });
+            }
+            // The ticket strategy: a sign-in token (minted by the app's backend through the
+            // Backend API) exchanged directly for a session — the twin verifies it against its
+            // own JWKS, so only genuinely minted tickets sign in.
+            if (params.strategy === 'ticket') {
+                const ticket = params.ticket ?? '';
+                if (ticket === '')
+                    return withMint(ferr('ticket is required', 422, 'form_param_missing'));
+                const verdict = verifyJwtWithJwks(ticket, await buildJwks(req.root));
+                if (!verdict.valid)
+                    return withMint(ferr(`Invalid sign-in ticket: ${verdict.reason}`, 422, 'ticket_invalid'));
+                const payload = JSON.parse(Buffer.from(ticket.split('.')[1], 'base64url').toString('utf8'));
+                const userId = payload.sub ?? '';
+                const found = await backend('GET', `/v1/users/${encodeURIComponent(userId)}`, undefined, req);
+                if (found.status !== 200)
+                    return withMint(ferr('The ticket names an unknown user', 422, 'ticket_invalid'));
+                const created = await backend('POST', '/v1/sessions', { user_id: userId, client_id: clientId }, req);
+                if (created.status !== 200)
+                    return withMint({ status: created.status, body: created.body });
+                const attempt = { id: fapiId('sia', 'sign_in_attempt', req), userId, identifier: primaryIdentifier(record(found.body)), status: 'complete', createdSessionId: String(record(created.body).id), strategy: 'ticket' };
+                await saveSignIn(attempt, req);
+                await rememberClient(clientId, { sign_in_attempt: attempt.id }, req);
+                return withMint({ status: 200, body: { response: signInView(attempt, atMs(req)), client: await clientEnvelope(clientId, req, signInView(attempt, atMs(req))) } });
+            }
+            const identifier = params.identifier ?? '';
+            if (identifier === '')
+                return withMint(ferr('identifier is required', 422, 'form_param_missing'));
+            const found = await backend('GET', `/v1/users?email_address=${encodeURIComponent(identifier)}`, undefined, req);
+            const user = Array.isArray(found.body) ? found.body[0] : undefined;
+            if (user === undefined)
+                return withMint(ferr("Couldn't find your account.", 422, 'form_identifier_not_found'));
+            const attempt = { id: fapiId('sia', 'sign_in_attempt', req), userId: String(user.id), identifier, status: 'needs_first_factor', createdSessionId: null };
+            await saveSignIn(attempt, req);
+            await rememberClient(clientId, { sign_in_attempt: attempt.id }, req);
+            // A one-shot sign-in (password supplied inline) completes immediately.
+            if (params.password !== undefined && params.password !== '') {
+                return withMint(await attemptPassword(attempt.id, params.password, clientId, req));
+            }
+            return withMint({ status: 200, body: { response: signInView(attempt, atMs(req)), client: await clientEnvelope(clientId, req, signInView(attempt, atMs(req))) } });
+        }
+        // POST /v1/client/sign_ins/:id/attempt_first_factor — the password check.
+        if (seg[2] === 'sign_ins' && seg.length === 5 && seg[4] === 'attempt_first_factor' && method === 'POST') {
+            if (params.strategy !== undefined && params.strategy !== 'password') {
+                return ferr(`strategy "${params.strategy}" is not enabled on this twin`, 422, 'strategy_for_user_invalid');
+            }
+            return attemptPassword(seg[3], params.password ?? '', clientId, req);
+        }
+        // GET /v1/client/sign_ins/:id — read an attempt back.
+        if (seg[2] === 'sign_ins' && seg.length === 4 && method === 'GET') {
+            const attempt = readSignIn(String(seg[3]), req.root);
+            if (attempt === undefined)
+                return ferr('Sign-in attempt not found', 404, 'resource_not_found');
+            return { status: 200, body: { response: signInView(attempt, atMs(req)), client: await clientEnvelope(clientId, req) } };
+        }
+        // DELETE /v1/client/sessions — sign out of every session on this client (Clerk.signOut()).
+        if (seg[2] === 'sessions' && seg.length === 3 && method === 'DELETE') {
+            const row = await getClientRow(clientId, req);
+            for (const s of row?.sessions ?? []) {
+                await backend('POST', `/v1/sessions/${encodeURIComponent(String(s.id))}/revoke`, {}, req);
+            }
+            return withMint({ status: 200, body: { response: null, client: await clientEnvelope(clientId, req) } });
+        }
+        if (seg[2] === 'sessions' && seg.length >= 4) {
+            const sessionId = seg[3];
+            // POST /v1/client/sessions/:id/tokens[/:template] — delegate to the Backend mint.
+            if (seg[4] === 'tokens' && method === 'POST') {
+                const tmpl = seg[5] !== undefined ? `/${seg[5]}` : '';
+                const minted = await backend('POST', `/v1/sessions/${encodeURIComponent(sessionId)}/tokens${tmpl}`, {}, req);
+                return { status: minted.status, body: minted.body };
+            }
+            // POST /v1/client/sessions/:id/touch
+            if (seg[4] === 'touch' && method === 'POST') {
+                const touched = await backend('POST', `/v1/sessions/${encodeURIComponent(sessionId)}/touch`, {}, req);
+                if (touched.status !== 200)
+                    return { status: touched.status, body: touched.body };
+                const u = await backend('GET', `/v1/users/${encodeURIComponent(String(record(touched.body).user_id))}`, undefined, req);
+                return { status: 200, body: { response: fapiSession(record(touched.body), u.status === 200 ? fapiUser(record(u.body)) : null), client: await clientEnvelope(clientId, req) } };
+            }
+            // DELETE /v1/client/sessions/:id  or  POST .../remove|end — sign out one session.
+            if ((seg.length === 4 && method === 'DELETE') || (seg.length === 5 && (seg[4] === 'remove' || seg[4] === 'end') && method === 'POST')) {
+                const revoked = await backend('POST', `/v1/sessions/${encodeURIComponent(sessionId)}/revoke`, {}, req);
+                if (revoked.status !== 200)
+                    return { status: revoked.status, body: revoked.body };
+                return { status: 200, body: { response: fapiSession(record(revoked.body), null), client: await clientEnvelope(clientId, req) } };
+            }
+        }
+    }
+    return ferr(`Unknown route: ${req.path}`, 404, 'resource_not_found');
+}
+async function attemptPassword(attemptId, password, clientId, req) {
+    const attempt = readSignIn(attemptId, req.root);
+    if (attempt === undefined)
+        return ferr('Sign-in attempt not found', 404, 'resource_not_found');
+    if (password === '')
+        return ferr('password is required', 422, 'form_param_missing');
+    const verified = await backend('POST', `/v1/users/${encodeURIComponent(attempt.userId)}/verify_password`, { password }, req);
+    if (verified.status !== 200) {
+        return { status: 422, body: { errors: [{ code: 'form_password_incorrect', message: 'Password is incorrect. Try again, or use another method.', long_message: 'Password is incorrect. Try again, or use another method.', meta: { param_name: 'password' } }], clerk_trace_id: 'trace_twin_fapi' } };
+    }
+    const created = await backend('POST', '/v1/sessions', { user_id: attempt.userId, client_id: clientId }, req);
+    if (created.status !== 200)
+        return { status: created.status, body: created.body };
+    attempt.status = 'complete';
+    attempt.createdSessionId = String(record(created.body).id);
+    await saveSignIn(attempt, req);
+    return { status: 200, body: { response: signInView(attempt, atMs(req)), client: await clientEnvelope(clientId, req, signInView(attempt, atMs(req))) } };
+}