@volter/twin-clerk 0.1.0

package/src/clerk-fapi.ts

@@ -0,0 +1,673 @@
+// 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.ts';
+import { buildJwks, verifyJwtWithJwks } from './clerk-jwt.ts';
+
+export type ClerkFapiRequest = {
+  method: string;
+  path: string; // pathname only (no query)
+  query?: Record<string, string>;
+  body?: string; // form-encoded or JSON, as the client sent it
+  cookies?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  /** The browser request's Origin header, when it sent one — becomes a session token's `azp`. */
+  origin?: string;
+};
+export type ClerkFapiResponse = { status: number; body: unknown; setCookies?: string[]; html?: string; redirect?: string };
+
+const CLIENT_COOKIE = '__client';
+
+// FAPI error envelope (same shape family as the Backend API).
+function ferr(message: string, status = 400, code = 'request_invalid', meta?: Record<string, unknown>): ClerkFapiResponse {
+  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?: string): Record<string, string> {
+  if (!body) return {};
+  const trimmed = body.trim();
+  if (trimmed.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      return Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+    } catch {
+      return {};
+    }
+  }
+  return Object.fromEntries(new URLSearchParams(trimmed));
+}
+
+async function backend(method: string, path: string, body: Record<string, unknown> | undefined, req: ClerkFapiRequest): Promise<{ status: number; body: unknown }> {
+  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: unknown): Record<string, unknown> => v as Record<string, unknown>;
+
+// ── 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: number): Record<string, unknown> {
+  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: Record<string, unknown>, user: Record<string, unknown> | null, lastTokenJwt?: string | null): Record<string, unknown> {
+  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: Record<string, unknown>): string {
+  const emails = Array.isArray(user.email_addresses) ? user.email_addresses as Array<Record<string, unknown>> : [];
+  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: Record<string, unknown>): Record<string, unknown> {
+  return { ...user, organization_memberships: [] };
+}
+
+// ── client state (a real row: the browser's client with its sessions) ───────────
+async function getClientRow(clientId: string, req: ClerkFapiRequest): Promise<Record<string, unknown> | undefined> {
+  const all = await backend('GET', '/v1/sessions', undefined, req);
+  if (all.status !== 200 || !Array.isArray(all.body)) return undefined;
+  const sessions = (all.body as Array<Record<string, unknown>>).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: ClerkFapiRequest): number => {
+  const parsed = req.occurredAt ? Date.parse(req.occurredAt) : NaN;
+  return Number.isNaN(parsed) ? Date.parse(worldNow()) : parsed;
+};
+type Stored = Record<string, unknown>;
+function readSubject(type: string, id: string, root?: string): Stored | undefined {
+  const r = projectResources(SERVICE, root).find((x) => x.type === type && x.id === id) as (Stored & { type?: string; updatedAt?: string }) | undefined;
+  if (r === undefined) return undefined;
+  const { type: _t, updatedAt: _u, id: _i, ...fields } = r; return fields;
+}
+async function writeSubject(type: string, id: string, fields: Stored, req: ClerkFapiRequest): Promise<void> {
+  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: string, root?: string): SignInAttempt | undefined => (id ? (readSubject('sign_in_attempt', id, root) as SignInAttempt | undefined) : undefined);
+const readSignUp = (id: string, root?: string): SignUpAttempt | undefined => (id ? (readSubject('sign_up_attempt', id, root) as SignUpAttempt | undefined) : undefined);
+const saveSignIn = (a: SignInAttempt, req: ClerkFapiRequest): Promise<void> => writeSubject('sign_in_attempt', a.id, { ...a }, req);
+const saveSignUp = (a: SignUpAttempt, req: ClerkFapiRequest): Promise<void> => writeSubject('sign_up_attempt', a.id, { ...a, fields: { ...a.fields } }, req);
+/** What the browser's client remembers: its current attempts and the social identity it was given per strategy. */
+type ClientMemory = { sign_in_attempt?: string | null; sign_up_attempt?: string | null; identities?: Record<string, { email: string; firstName: string; lastName: string }> };
+const clientMemory = (clientId: string, root?: string): ClientMemory => (readSubject('fapi_client', clientId, root) as ClientMemory | undefined) ?? {};
+const rememberClient = (clientId: string, patch: ClientMemory, req: ClerkFapiRequest): Promise<void> => writeSubject('fapi_client', clientId, { ...clientMemory(clientId, req.root), ...patch }, req);
+
+async function clientEnvelope(clientId: string, req: ClerkFapiRequest, signInAttempt?: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const at = atMs(req);
+  const row = await getClientRow(clientId, req);
+  const sessions = row === undefined ? [] : (row.sessions as Array<Record<string, unknown>>);
+  const withUsers: Array<Record<string, unknown>> = [];
+  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: string, type: string, req: ClerkFapiRequest): string {
+  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: ClerkFapiRequest): Promise<string> {
+  const id = fapiId('client', 'fapi_client', req);
+  await writeSubject('fapi_client', id, {}, req);
+  return id;
+}
+
+function clientCookie(clientId: string): string {
+  // 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`;
+}
+
+// sign-in attempts live in-memory per client: an attempt is a protocol scratchpad, not
+// world state — the world changes only when the attempt completes (session row created).
+type SignInAttempt = { id: string; userId: string; identifier: string; status: string; createdSessionId: string | null; strategy?: string; redirectUrl?: string; externalIdentity?: { email: string; firstName: string; lastName: string } };
+
+// sign-up attempts: the same principle — a scratchpad of collected fields; the world
+// changes only when the attempt completes (a real user row + session, via the Backend).
+type SignUpAttempt = { id: string; fields: Record<string, string>; status: string; createdSessionId: string | null; createdUserId: string | null; strategy?: string; redirectUrl?: string; externalIdentity?: { email: string; firstName: string; lastName: string } };
+
+// 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: Record<string, { name: string; domain: string }> = {
+  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: string, clientId: string | undefined, req: ClerkFapiRequest): Promise<{ email: string; firstName: string; lastName: string }> {
+  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: string, redirectUrl: string): string {
+  // 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: SignUpAttempt, at: number): Record<string, unknown> {
+  const missing: string[] = [];
+  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: { id: string; userId: string; identifier: string; status: string; createdSessionId: string | null; strategy?: string; redirectUrl?: string }, at: number): Record<string, unknown> {
+  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: ClerkFapiRequest): Promise<ClerkFapiResponse> {
+  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 as Array<Record<string, unknown>>)[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 as Array<Record<string, unknown>> | undefined) ?? [];
+    const current = sessions[sessions.length - 1];
+    if (current === undefined) return signedOut;
+    const userId = String(current.user_id);
+    const me = async (): Promise<Record<string, unknown>> => { const u = await backend('GET', `/v1/users/${encodeURIComponent(userId)}`, undefined, req); return fapiUser(record(u.body)); };
+    const envelope = async (response: unknown): Promise<ClerkFapiResponse> => ({ 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: Record<string, unknown> = {};
+      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 as Array<Record<string, unknown>>) : []).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 as Array<Record<string, unknown>> | undefined) ?? []) {
+          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: ClerkFapiResponse): ClerkFapiResponse =>
+      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: SignUpAttempt | undefined = 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'] as const) {
+        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')) as { sub?: string };
+        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 as Array<Record<string, unknown>>)[0] : undefined;
+      if (user === undefined) return withMint(ferr("Couldn't find your account.", 422, 'form_identifier_not_found'));
+      const attempt: SignInAttempt = { 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 as Array<Record<string, unknown>> | undefined) ?? []) {
+        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: string, password: string, clientId: string, req: ClerkFapiRequest): Promise<ClerkFapiResponse> {
+  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))) } };
+}