@volter/twin-clerk 0.1.0

package/src/clerk-jwt.ts

@@ -0,0 +1,256 @@
+// Clerk JWT / JWKS — the highest-value capability of the Clerk twin.
+//
+// Real Clerk issues RS256-signed JWTs for sessions and JWT templates, and serves a
+// JWKS document (/.well-known/jwks.json) an app verifies those tokens against. A
+// faithful twin must do the SAME with REAL crypto: generate an RSA keypair on first
+// use, persist it (via the kernel state, so it survives a process restart and is the
+// SAME key for both signing and the served JWKS), sign tokens as genuine JWTs, and
+// serve a genuine JWKS — so an app verifying a twin-issued token against the twin's
+// JWKS succeeds UNMODIFIED (`jwt.verify(token, jwks)` works, claims round-trip).
+//
+// `node:crypto` is required LAZILY (inside the functions that use it), NOT as a
+// top-level static import, so this module can be pulled into the browser bundle of
+// the UI mirror without Bun's browser target choking on `node:crypto` — the signing
+// helpers are server-only and never reached in the browser path.
+import { applyTwinWrite, projectResources, nodeBuiltin } from '@volter/world-core';
+
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+const SERVICE = 'clerk';
+// The keypair is stored as a single twin-internal resource so it persists in kernel
+// state (the SAME substrate the rest of the twin uses — no parallel store). Its id is
+// fixed; the `_`-prefixed fields are twin-internal (the conformance gate exempts them).
+const KEYPAIR_TYPE = '_keypair';
+const KEYPAIR_ID = 'clerk_signing_key';
+
+export type ClerkKeypair = { kid: string; publicKeyPem: string; privateKeyPem: string };
+
+/** The PEM material of an RSA signing keypair (no kid — the kid is derived from it). */
+export type KeypairMaterial = { publicKeyPem: string; privateKeyPem: string };
+/** How `ensureKeypair` mints a NEW keypair on first use. */
+export type KeypairGenerator = () => KeypairMaterial;
+
+/** DEFAULT keypair source: a fresh RSA-2048 keypair from node:crypto. This is what every
+ *  Node/Bun twin uses — generate-on-first-use, unchanged. */
+function nodeGenerateKeypair(): KeypairMaterial {
+  const { generateKeyPairSync } = nodeCrypto();
+  const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { publicKeyPem: publicKey as string, privateKeyPem: privateKey as string };
+}
+
+// Injectable keypair seam (mirrors the WorldStore seam). The DEFAULT is node:crypto keygen,
+// so the Node/Bun path and the conformance suite are byte-identical. A serverless host where
+// RUNTIME RSA keygen is not viable installs a provider returning a PRE-GENERATED keypair:
+// measured on the real Cloudflare edge, a single RSA-2048 `generateKeyPairSync` trips the
+// free-plan 10ms CPU limit (HTTP 503, error 1102) ~28% of the time, whereas SIGNING once,
+// `createPublicKey`/`createHash`, and the JWK export are all cheap and reliable. Baking the
+// keypair removes the only heavyweight op from the edge; the kid is still derived from the
+// public key by `kidFor`, so a stable baked key yields a STABLE kid (and it is persisted in
+// kernel state on first use exactly as a generated one would be).
+const keypairGenerator = { current: nodeGenerateKeypair as KeypairGenerator }; // a slot, not module truth (protocol 2)
+
+/** Override how `ensureKeypair` mints a new keypair; pass `null` to restore the node:crypto
+ *  default. Workers-only wiring — the default keeps generate-on-first-use behavior. */
+export function setKeypairGenerator(generator: KeypairGenerator | null): void {
+  keypairGenerator.current = generator ?? nodeGenerateKeypair;
+}
+
+/**
+ * The twin's RSA signing keypair for `root`, generated + persisted on first use and
+ * stable thereafter (persisted in kernel state, so signing and the served JWKS share
+ * ONE key). Deterministic kid derived from the public key's modulus, so the JWKS `kid`
+ * matches the token header `kid` — what a verifier uses to pick the key.
+ */
+export async function ensureKeypair(root?: string): Promise<ClerkKeypair> {
+  const existing = projectResources(SERVICE, root).find((r) => r.type === KEYPAIR_TYPE && r.id === KEYPAIR_ID);
+  if (existing && typeof existing._privateKeyPem === 'string' && typeof existing._publicKeyPem === 'string') {
+    return { kid: String(existing._kid), publicKeyPem: existing._publicKeyPem, privateKeyPem: existing._privateKeyPem };
+  }
+  const { publicKeyPem, privateKeyPem } = keypairGenerator.current();
+  const kid = kidFor(publicKeyPem);
+  await applyTwinWrite(
+    SERVICE,
+    {
+      operation: '_keypair.create',
+      subjectType: KEYPAIR_TYPE,
+      subjectId: KEYPAIR_ID,
+      fields: { _kid: kid, _publicKeyPem: publicKeyPem, _privateKeyPem: privateKeyPem },
+      actor: { kind: 'system' },
+    },
+    root,
+  );
+  return { kid, publicKeyPem, privateKeyPem };
+}
+
+/** Stable key id = first 16 hex of SHA-256 over the public key DER (deterministic per key). */
+function kidFor(publicKeyPem: string): string {
+  const { createHash, createPublicKey } = nodeCrypto();
+  const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  return `ins_${createHash('sha256').update(der).digest('hex').slice(0, 16)}`;
+}
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function base64urlJson(obj: unknown): string {
+  return base64url(JSON.stringify(obj));
+}
+
+/**
+ * Sign a JWT (RS256) with the twin's persisted private key. The header carries the
+ * `kid` of the served JWKS so a verifier picks the right key. Returns the compact
+ * `header.payload.signature` token. Pure local crypto — no network.
+ */
+export async function signJwt(claims: Record<string, unknown>, opts: { root?: string; expiresInSeconds?: number; now?: number } = {}): Promise<string> {
+  const { createSign } = nodeCrypto();
+  const { kid, privateKeyPem } = await ensureKeypair(opts.root);
+  const iat = opts.now ?? Math.floor(Date.now() / 1000);
+  const exp = iat + (opts.expiresInSeconds ?? 60);
+  const header = { alg: 'RS256', typ: 'JWT', kid };
+  const payload = { iat, exp, nbf: iat, ...claims };
+  const signingInput = `${base64urlJson(header)}.${base64urlJson(payload)}`;
+  const signer = createSign('RSA-SHA256');
+  signer.update(signingInput);
+  signer.end();
+  const signature = base64url(signer.sign(privateKeyPem));
+  return `${signingInput}.${signature}`;
+}
+
+/**
+ * Sign a JWT with a bring-your-own HS256 secret (a JWT template's `custom_signing_key`).
+ * Real Clerk lets a template carry its own signing algorithm + secret (e.g. Supabase's
+ * shared HS256 secret); the twin signs with genuine HMAC-SHA256 so the downstream service
+ * verifies it with the SAME secret unmodified. No persisted keypair, no JWKS (HS256 is
+ * symmetric). Pure local crypto — no network.
+ */
+export function signJwtHs256(claims: Record<string, unknown>, secret: string, opts: { expiresInSeconds?: number; now?: number } = {}): string {
+  const { createHmac } = nodeCrypto();
+  const iat = opts.now ?? Math.floor(Date.now() / 1000);
+  const exp = iat + (opts.expiresInSeconds ?? 60);
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const payload = { iat, exp, nbf: iat, ...claims };
+  const signingInput = `${base64urlJson(header)}.${base64urlJson(payload)}`;
+  const signature = base64url(createHmac('sha256', secret).update(signingInput).digest());
+  return `${signingInput}.${signature}`;
+}
+
+/**
+ * Verify an HS256 JWT against the shared secret (constant-time) and check exp/nbf —
+ * what a downstream service does with a `custom_signing_key` template token. Pure local
+ * crypto — no network.
+ */
+export function verifyJwtHs256(token: string, secret: string, opts: { now?: number } = {}): { valid: boolean; payload?: Record<string, unknown>; reason?: string } {
+  const { createHmac, timingSafeEqual } = nodeCrypto();
+  let header: Record<string, unknown>, payload: Record<string, unknown>, parts: string[];
+  try {
+    parts = token.split('.');
+    if (parts.length !== 3) return { valid: false, reason: 'malformed' };
+    ({ header, payload } = decodeJwt(token));
+  } catch {
+    return { valid: false, reason: 'malformed' };
+  }
+  if (header.alg !== 'HS256') return { valid: false, reason: 'unexpected_alg' };
+  const expected = base64url(createHmac('sha256', secret).update(`${parts[0]}.${parts[1]}`).digest());
+  const a = Buffer.from(parts[2]!, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return { valid: false, reason: 'bad_signature' };
+  const now = opts.now ?? Math.floor(Date.now() / 1000);
+  if (typeof payload.exp === 'number' && now >= payload.exp) return { valid: false, reason: 'expired' };
+  if (typeof payload.nbf === 'number' && now < payload.nbf) return { valid: false, reason: 'not_yet_valid' };
+  return { valid: true, payload };
+}
+
+/** The decoded parts of a JWT (no verification). */
+export function decodeJwt(token: string): { header: Record<string, unknown>; payload: Record<string, unknown> } {
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new Error('malformed jwt');
+  const dec = (s: string) => JSON.parse(Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8')) as Record<string, unknown>;
+  return { header: dec(parts[0]!), payload: dec(parts[1]!) };
+}
+
+/**
+ * Verify a token's RS256 signature against a JWKS document (the SAME shape the twin
+ * serves), and check exp/nbf. This is what an app does to trust a twin-issued token:
+ * `verifyJwtWithJwks(token, fetch('/.well-known/jwks.json'))` succeeds for a valid
+ * token, fails for a tampered/expired one. Pure local crypto — no network.
+ */
+export function verifyJwtWithJwks(token: string, jwks: Jwks, opts: { now?: number } = {}): { valid: boolean; payload?: Record<string, unknown>; reason?: string } {
+  const { createVerify, createPublicKey } = nodeCrypto();
+  let header: Record<string, unknown>, payload: Record<string, unknown>, parts: string[];
+  try {
+    parts = token.split('.');
+    if (parts.length !== 3) return { valid: false, reason: 'malformed' };
+    ({ header, payload } = decodeJwt(token));
+  } catch {
+    return { valid: false, reason: 'malformed' };
+  }
+  if (header.alg !== 'RS256') return { valid: false, reason: 'unexpected_alg' };
+  const key = jwks.keys.find((k) => k.kid === header.kid) ?? jwks.keys[0];
+  if (!key) return { valid: false, reason: 'no_matching_key' };
+  // Reconstruct the public key from the JWK (n, e) — exactly what a real verifier does.
+  const publicKey = createPublicKey({ key: { kty: 'RSA', n: key.n, e: key.e }, format: 'jwk' });
+  const verifier = createVerify('RSA-SHA256');
+  verifier.update(`${parts[0]}.${parts[1]}`);
+  verifier.end();
+  const sig = Buffer.from(parts[2]!.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+  if (!verifier.verify(publicKey, sig)) return { valid: false, reason: 'bad_signature' };
+  const now = opts.now ?? Math.floor(Date.now() / 1000);
+  if (typeof payload.exp === 'number' && now >= payload.exp) return { valid: false, reason: 'expired' };
+  if (typeof payload.nbf === 'number' && now < payload.nbf) return { valid: false, reason: 'not_yet_valid' };
+  return { valid: true, payload };
+}
+
+export type Jwk = { kty: 'RSA'; use: 'sig'; alg: 'RS256'; kid: string; n: string; e: string };
+export type Jwks = { keys: Jwk[] };
+
+/** The Clerk-shaped result of authenticating a request (mirrors `RequestState`). */
+export type ClerkAuthState = {
+  isSignedIn: boolean;
+  userId: string | null;
+  sessionId: string | null;
+  orgId: string | null;
+  claims: Record<string, unknown> | null;
+  reason?: string;
+};
+
+/**
+ * Networkless verification of a Clerk session token — what `@clerk/backend`'s
+ * `authenticateRequest()` does on the server WITHOUT an extra API round-trip: verify the
+ * token's RS256 signature + exp/nbf against a (locally cached) JWKS, then derive the
+ * signed-in actor (sub→userId, sid→sessionId, org_id→orgId) from the claims. No network.
+ */
+export function networklessVerifyToken(token: string, jwks: Jwks, opts: { now?: number } = {}): ClerkAuthState {
+  const result = verifyJwtWithJwks(token, jwks, opts);
+  if (!result.valid || !result.payload) {
+    return { isSignedIn: false, userId: null, sessionId: null, orgId: null, claims: null, ...(result.reason ? { reason: result.reason } : {}) };
+  }
+  const p = result.payload;
+  return {
+    isSignedIn: true,
+    userId: typeof p.sub === 'string' ? p.sub : null,
+    sessionId: typeof p.sid === 'string' ? p.sid : null,
+    orgId: typeof p.org_id === 'string' ? p.org_id : null,
+    claims: p,
+  };
+}
+
+/**
+ * Build the JWKS document the twin serves at /.well-known/jwks.json — the real Clerk
+ * JWKS shape. The RSA modulus/exponent are exported as base64url JWK members from the
+ * SAME persisted key used to sign, so a verifier picks the matching `kid` and trusts
+ * twin-issued tokens.
+ */
+export async function buildJwks(root?: string): Promise<Jwks> {
+  const { createPublicKey } = nodeCrypto();
+  const { kid, publicKeyPem } = await ensureKeypair(root);
+  const jwk = createPublicKey(publicKeyPem).export({ format: 'jwk' }) as { n?: string; e?: string };
+  return { keys: [{ kty: 'RSA', use: 'sig', alg: 'RS256', kid, n: String(jwk.n), e: String(jwk.e) }] };
+}

package/src/clerk-mirror-ui.ts

@@ -0,0 +1,165 @@
+// Clerk MIRROR UI — a Clerk-dashboard-like admin view served as a React/TSX app
+// (Bun-bundled, the repo convention). It renders by consuming the twin's OWN REST API on
+// the same origin (/v1/<collection>) — the same endpoints an app uses. Per-vendor + concrete.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the
+// pack's OWN fetch adapter (createClerkTwinFetch) as its API backend and reads every byte of
+// state back over the wire, exactly as the browser client does.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createClerkTwinFetch } from './clerk-server.ts';
+
+// Resolved LAZILY (on first serve), not at module load: `new URL(..., import.meta.url)` at
+// module scope evaluates at import time, which throws in a bundled/serverless context where
+// `import.meta.url` is not a valid file base (e.g. workerd) even though the mirror UI is never
+// served there. Computing them on demand keeps Node/Bun behavior identical while letting a
+// serverless host import this module's barrel without a startup crash.
+const clientEntryPath = () => new URL('../client/clerk-mirror.tsx', import.meta.url).pathname;
+const clientCssPath = () => new URL('../client/clerk-mirror.css', import.meta.url).pathname;
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers. Framework-agnostic (plain data in →
+// plain data out) so they can be unit-tested AND imported by the React/TSX client
+// (Bun tree-shakes the server-only exports below out of the browser bundle). Keep them
+// free of any `@volter/world-core` / `Bun` / fetch-adapter usage.
+// ---------------------------------------------------------------------------
+
+export type ClerkRow = Record<string, any>;
+
+/** A user's display name: "First Last", else username, else primary email, else id. */
+export function formatUserName(u: ClerkRow): string {
+  const name = [u?.first_name, u?.last_name].filter(Boolean).join(' ').trim();
+  if (name) return name;
+  if (u?.username) return String(u.username);
+  const email = primaryEmail(u);
+  return email || String(u?.id ?? '—');
+}
+
+/** The user's primary email address, resolving primary_email_address_id against the list. */
+export function primaryEmail(u: ClerkRow): string {
+  const list = Array.isArray(u?.email_addresses) ? u.email_addresses : [];
+  const primaryId = u?.primary_email_address_id;
+  const found = list.find((e: any) => e?.id === primaryId) ?? list[0];
+  if (found?.email_address) return String(found.email_address);
+  if (u?.primary_email) return String(u.primary_email);
+  return '';
+}
+
+/** A short status label for a user (banned/locked override active). */
+export function userStatus(u: ClerkRow): string {
+  if (u?.banned) return 'banned';
+  if (u?.locked) return 'locked';
+  return 'active';
+}
+
+/** Format a Clerk epoch-millis timestamp as a short date, or an em dash. */
+export function formatClerkDate(ms: unknown): string {
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return '—';
+  try {
+    return new Date(ms).toISOString().slice(0, 10);
+  } catch {
+    return '—';
+  }
+}
+
+/** A status → CSS tone class for the status pill (shared design language). */
+export function statusTone(value: string): string {
+  const v = value.toLowerCase();
+  if (['active', 'verified', 'accepted', 'admin'].includes(v)) return 'ok';
+  if (['pending', 'queued', 'locked', 'basic_member'].includes(v)) return 'warn';
+  if (['banned', 'revoked', 'expired', 'ended'].includes(v)) return 'bad';
+  return 'neutral';
+}
+
+/** Flatten a (possibly nested) value into label/value lines for the detail panel. */
+export type FlatLine = { key: string; value: string; depth: number };
+export function flattenClerkValue(value: unknown, prefix = '', depth = 0, out: FlatLine[] = []): FlatLine[] {
+  if (value === null || value === undefined) {
+    out.push({ key: prefix || '(value)', value: '—', depth });
+  } else if (Array.isArray(value)) {
+    if (value.length === 0) out.push({ key: prefix, value: '[]', depth });
+    else value.forEach((v, i) => flattenClerkValue(v, `${prefix}[${i}]`, depth, out));
+  } else if (typeof value === 'object') {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      flattenClerkValue(v, prefix ? `${prefix}.${k}` : k, depth, out);
+    }
+  } else {
+    out.push({ key: prefix || '(value)', value: String(value), depth });
+  }
+  return out;
+}
+
+/** Count members of an org (members_count, with a 0 fallback). */
+export function orgMemberCount(o: ClerkRow): number {
+  return typeof o?.members_count === 'number' ? o.members_count : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Server-only (Bun) below — NOT imported by the browser client.
+// ---------------------------------------------------------------------------
+
+const APP_SHELL = `<!doctype html><html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<base href="/"><title>Clerk twin — admin mirror</title>
+<link rel="stylesheet" href="assets/styles.css" /></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+// cache: the built client bundle, memoized per process — a build artifact, never twin state (the tree
+// holds what this UI renders); cleared on a failed build so the next request rebuilds.
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX admin client to browser JS (Bun bundles TSX); cached. */
+export function buildClerkMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(clientEntryPath())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the Clerk admin mirror UI (React app) + its backing REST API. */
+export async function createClerkMirrorServer(options: { root?: string; port?: number }): Promise<{ port: number; stop: () => void }> {
+  const twin = createClerkTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}) });
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+    // on loopback, so the verify's fetches deterministically reach THIS server.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildClerkMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(clientCssPath(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // everything else → the twin's OWN FETCH ADAPTER (composition, R2): the Backend API the
+      // React client calls (/v1/<collection>), the Frontend API collections, the vendored
+      // clerk-js loader path and the uniform door (GET /twin) all come from the SAME closure
+      // `createClerkTwinServer` serves, so the mirror port cannot drift from the API port —
+      // one serving code path, one truth.
+      return twin(request);
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). The dashboard itself is the React client. */
+export function clerkMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function clerkMirrorStyles(): Promise<string> {
+  return readFile(clientCssPath(), 'utf8');
+}

package/src/clerk-server.ts

@@ -0,0 +1,175 @@
+// Clerk twin HTTP server — ONE host serving both real Clerk surfaces:
+//  - the Backend API (api.clerk.com shape) for `@clerk/backend`, plus /.well-known/jwks.json
+//  - the Frontend API (clerk.<domain> shape) for the REAL `@clerk/clerk-js` browser bundle,
+//    which this server also serves at the /npm/@clerk/clerk-js loader path (vendored, pinned)
+// The surfaces project the same row store (clerk-fapi delegates every mutation to the
+// Backend handler), so a user created through either door signs in through the other.
+// Personas are world state: pass `personas` (a JSON file of users with passwords) and the
+// server seeds them as ordinary user rows at start — sign-in is a protocol, never a default.
+// JSON bodies pass through to the handler. Writable by default; readOnly rejects writes (R4).
+import { serveHttp } from '@volter/world-core';
+import { handleClerkTwinRequest } from './clerk-twin.ts';
+import { worldNow, statefulTwinManifest, packAsset } from '@volter/world-core';
+import { handleClerkFapiRequest } from './clerk-fapi.ts';
+
+const FAPI_COLLECTIONS = new Set(['environment', 'client', 'dev_browser', 'oauth-consent']);
+
+function parseCookies(header: string | null): Record<string, string> {
+  if (header === null || header === '') return {};
+  return Object.fromEntries(
+    header.split(';').map((pair) => {
+      const eq = pair.indexOf('=');
+      return eq === -1 ? [pair.trim(), ''] : [pair.slice(0, eq).trim(), pair.slice(eq + 1).trim()];
+    }),
+  );
+}
+
+/** Personas arrive as DATA (the cli reads the file — the serve closure reads no host file, R12b). */
+async function seedPersonas(personas: unknown, root?: string): Promise<void> {
+  if (!Array.isArray(personas)) throw new Error('clerk personas must be a JSON array of {email, password, …}');
+  for (const persona of personas) {
+    const email = typeof persona.email === 'string' ? persona.email : undefined;
+    const password = typeof persona.password === 'string' ? persona.password : undefined;
+    if (email === undefined || password === undefined) throw new Error('each clerk persona needs an email and a password');
+    const existing = await handleClerkTwinRequest({ method: 'GET', path: `/v1/users?email_address=${encodeURIComponent(email)}`, ...(root !== undefined ? { root } : {}) });
+    if (Array.isArray(existing.body) && existing.body.length > 0) {
+      // A persisted user may predate this personas file or carry no password at
+      // all (measured live 2026-08-31: a five-day-old persona had
+      // password_enabled false, so every tester sign-in failed "incorrect").
+      // The personas file is the declared truth for seeded identities: an
+      // existing user is RECONCILED, never skipped — the declared password is
+      // (re)applied idempotently.
+      const user = existing.body[0] as Record<string, unknown>;
+      const patched = await handleClerkTwinRequest({
+        method: 'PATCH',
+        path: `/v1/users/${String(user.id)}`,
+        body: JSON.stringify({ password }),
+        ...(root !== undefined ? { root } : {}),
+      });
+      if (patched.status < 200 || patched.status >= 300) throw new Error(`failed to reconcile clerk persona "${email}": ${JSON.stringify(patched.body)}`);
+      continue;
+    }
+    const created = await handleClerkTwinRequest({
+      method: 'POST',
+      path: '/v1/users',
+      body: JSON.stringify({
+        email_address: [email],
+        password,
+        ...(typeof persona.first_name === 'string' ? { first_name: persona.first_name } : {}),
+        ...(typeof persona.last_name === 'string' ? { last_name: persona.last_name } : {}),
+      }),
+      ...(root !== undefined ? { root } : {}),
+    });
+    if (created.status < 200 || created.status >= 300) throw new Error(`failed to seed clerk persona "${email}": ${JSON.stringify(created.body)}`);
+  }
+}
+
+/** Options every Clerk-twin HTTP surface needs, independent of who owns the socket. */
+export interface ClerkTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  personas?: Array<Record<string, unknown>>;
+}
+
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createClerkTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift.
+ *
+ * Personas are seeded ONCE, when the factory is called; the per-request path only awaits that
+ * settled promise. A caller that passes no `personas` file seeds nothing.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): GET /twin is built from constants, and the only
+ * clock on the path is `worldNow()`, the world's frozen instant.
+ *
+ * Workerd-clean since R20: the `/npm/@clerk/clerk-js` loader path serves the REAL
+ * pinned browser dist through the pack-asset seam (R20), because this pack's whole point is that the
+ * unmodified clerk-js bundle loads from it. That route is a local-CDN affordance for a browser
+ * lane; the API doors above it touch no filesystem.
+ */
+export function createClerkTwinFetch(options: ClerkTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  const seeded = options.personas === undefined ? Promise.resolve() : seedPersonas(options.personas, options.root);
+  // The vendored dist is resolved LAZILY inside its route: the factory body names no Bun API, so
+  // the pack CONSTRUCTS on any host (workerd included) and only the local-CDN route itself needs
+  // Bun — until the dist rides a pack-asset seam (`TwinPack.assets`, the pack-asset seam), that route is the
+  // pack's one host-bound surface, not the whole pack.
+  return async function clerkTwinFetch(request: Request): Promise<Response> {
+    await seeded;
+    const url = new URL(request.url);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(statefulTwinManifest({ vendor: 'clerk', twinOf: 'the Clerk Backend API', stores: 'users, sessions and organizations' }));
+    }
+    const corsOrigin = request.headers.get('origin') ?? '*';
+    const cors = {
+      'access-control-allow-origin': corsOrigin,
+      'access-control-allow-credentials': 'true',
+      'access-control-allow-headers': 'authorization, content-type',
+      'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+    };
+    if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: cors });
+    // The loader path: the REAL pinned dist, exactly as a CDN would serve it. clerk-js
+    // lazy-loads sibling chunk files from the same directory, so every dist file is
+    // vendored and served by name; the main bundle is the fallback for the bare path.
+    if (request.method === 'GET' && url.pathname.startsWith('/npm/@clerk/clerk-js')) {
+      const requested = url.pathname.split('/').at(-1) ?? '';
+      const safe = /^[A-Za-z0-9._-]+\.js$/.test(requested) ? requested : 'clerk.browser.js';
+      // Through the PACK-ASSET seam (R20): the Bun shell reads this pack's own tree, workerd the
+      // assets binding — this route no longer binds the pack to a host (R12b).
+      const asset = await packAsset('clerk', `client/clerk-js-dist/${safe}`, 'client/clerk.browser.js');
+      if (asset === null) return new Response('clerk-js dist is not shipped with this build', { status: 404, headers: cors });
+      return new Response(asset.body, {
+        status: 200,
+        headers: { 'content-type': 'application/javascript; charset=utf-8', ...cors },
+      });
+    }
+    const seg = url.pathname.split('/').filter((s) => s.length > 0);
+    const body = request.method === 'GET' ? '' : await request.text();
+    // Frontend API collections dispatch to the FAPI branch; everything else is Backend.
+    if (seg[0] === 'v1' && FAPI_COLLECTIONS.has(seg[1] ?? '')) {
+      if (readOnly && request.method !== 'GET') {
+        return new Response(JSON.stringify({ errors: [{ code: 'read_only', message: 'twin is read-only; omit readOnly to accept writes' }] }), { status: 405, headers: { 'content-type': 'application/json', ...cors } });
+      }
+      // clerk-js tunnels non-simple verbs through POST + ?_method= to stay preflight-free.
+      const methodOverride = url.searchParams.get('_method');
+      const { status, body: out, setCookies, html, redirect } = await handleClerkFapiRequest({
+        method: request.method === 'POST' && methodOverride !== null ? methodOverride.toUpperCase() : request.method,
+        path: url.pathname,
+        query: Object.fromEntries(url.searchParams),
+        body,
+        cookies: parseCookies(request.headers.get('cookie')),
+        occurredAt: worldNow(),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(request.headers.get('origin') !== null ? { origin: request.headers.get('origin')! } : {}),
+      });
+      const headers = new Headers({ 'content-type': html === undefined ? 'application/json' : 'text/html; charset=utf-8', 'clerk-trace-id': 'trace_twin', ...cors });
+      for (const cookie of setCookies ?? []) headers.append('set-cookie', cookie);
+      if (redirect !== undefined) { headers.set('location', redirect); return new Response(null, { status, headers }); }
+      return new Response(html ?? JSON.stringify(out), { status, headers });
+    }
+    const { status, body: out } = await handleClerkTwinRequest({
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      // The origin this request actually arrived on — never a baked host:port (R7).
+      host: request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? url.host,
+      readOnly,
+      occurredAt: worldNow(),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'clerk-trace-id': 'trace_twin', ...cors } });
+  };
+}
+
+export async function createClerkTwinServer(options: { root?: string; port?: number; readOnly?: boolean; personas?: Array<Record<string, unknown>> }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createClerkTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}