@volter/twin-clerk 0.1.0

package/dist/src/clerk-jwt.d.ts

@@ -0,0 +1,109 @@
+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;
+/** 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 declare function setKeypairGenerator(generator: KeypairGenerator | null): void;
+/**
+ * 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 declare function ensureKeypair(root?: string): Promise<ClerkKeypair>;
+/**
+ * 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 declare function signJwt(claims: Record<string, unknown>, opts?: {
+    root?: string;
+    expiresInSeconds?: number;
+    now?: number;
+}): Promise<string>;
+/**
+ * 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 declare function signJwtHs256(claims: Record<string, unknown>, secret: string, opts?: {
+    expiresInSeconds?: number;
+    now?: number;
+}): string;
+/**
+ * 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 declare function verifyJwtHs256(token: string, secret: string, opts?: {
+    now?: number;
+}): {
+    valid: boolean;
+    payload?: Record<string, unknown>;
+    reason?: string;
+};
+/** The decoded parts of a JWT (no verification). */
+export declare function decodeJwt(token: string): {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+};
+/**
+ * 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 declare function verifyJwtWithJwks(token: string, jwks: Jwks, opts?: {
+    now?: number;
+}): {
+    valid: boolean;
+    payload?: Record<string, unknown>;
+    reason?: string;
+};
+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 declare function networklessVerifyToken(token: string, jwks: Jwks, opts?: {
+    now?: number;
+}): ClerkAuthState;
+/**
+ * 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 declare function buildJwks(root?: string): Promise<Jwks>;

package/dist/src/clerk-jwt.js

@@ -0,0 +1,230 @@
+// 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';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+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';
+/** 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() {
+    const { generateKeyPairSync } = nodeCrypto();
+    const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    return { publicKeyPem: publicKey, privateKeyPem: privateKey };
+}
+// 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 }; // 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.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) {
+    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) {
+    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) {
+    return Buffer.from(input).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function base64urlJson(obj) {
+    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, opts = {}) {
+    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, secret, opts = {}) {
+    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, secret, opts = {}) {
+    const { createHmac, timingSafeEqual } = nodeCrypto();
+    let header, payload, parts;
+    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) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('malformed jwt');
+    const dec = (s) => JSON.parse(Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+    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, jwks, opts = {}) {
+    const { createVerify, createPublicKey } = nodeCrypto();
+    let header, payload, parts;
+    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 };
+}
+/**
+ * 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, jwks, opts = {}) {
+    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) {
+    const { createPublicKey } = nodeCrypto();
+    const { kid, publicKeyPem } = await ensureKeypair(root);
+    const jwk = createPublicKey(publicKeyPem).export({ format: 'jwk' });
+    return { keys: [{ kty: 'RSA', use: 'sig', alg: 'RS256', kid, n: String(jwk.n), e: String(jwk.e) }] };
+}

package/dist/src/clerk-mirror-ui.d.ts

@@ -0,0 +1,34 @@
+export type ClerkRow = Record<string, any>;
+/** A user's display name: "First Last", else username, else primary email, else id. */
+export declare function formatUserName(u: ClerkRow): string;
+/** The user's primary email address, resolving primary_email_address_id against the list. */
+export declare function primaryEmail(u: ClerkRow): string;
+/** A short status label for a user (banned/locked override active). */
+export declare function userStatus(u: ClerkRow): string;
+/** Format a Clerk epoch-millis timestamp as a short date, or an em dash. */
+export declare function formatClerkDate(ms: unknown): string;
+/** A status → CSS tone class for the status pill (shared design language). */
+export declare function statusTone(value: string): string;
+/** Flatten a (possibly nested) value into label/value lines for the detail panel. */
+export type FlatLine = {
+    key: string;
+    value: string;
+    depth: number;
+};
+export declare function flattenClerkValue(value: unknown, prefix?: string, depth?: number, out?: FlatLine[]): FlatLine[];
+/** Count members of an org (members_count, with a 0 fallback). */
+export declare function orgMemberCount(o: ClerkRow): number;
+/** Build the React/TSX admin client to browser JS (Bun bundles TSX); cached. */
+export declare function buildClerkMirrorClient(): Promise<string>;
+/** Serve the Clerk admin mirror UI (React app) + its backing REST API. */
+export declare function createClerkMirrorServer(options: {
+    root?: string;
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure, for tests). The dashboard itself is the React client. */
+export declare function clerkMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function clerkMirrorStyles(): Promise<string>;

package/dist/src/clerk-mirror-ui.js

@@ -0,0 +1,160 @@
+// 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.js";
+// 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;
+/** A user's display name: "First Last", else username, else primary email, else id. */
+export function formatUserName(u) {
+    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) {
+    const list = Array.isArray(u?.email_addresses) ? u.email_addresses : [];
+    const primaryId = u?.primary_email_address_id;
+    const found = list.find((e) => 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) {
+    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) {
+    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) {
+    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';
+}
+export function flattenClerkValue(value, prefix = '', depth = 0, out = []) {
+    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)) {
+            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) {
+    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 = null;
+/** Build the React/TSX admin client to browser JS (Bun bundles TSX); cached. */
+export function buildClerkMirrorClient() {
+    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) {
+    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() {
+    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() {
+    return readFile(clientCssPath(), 'utf8');
+}

package/dist/src/clerk-server.d.ts

@@ -0,0 +1,35 @@
+/** 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 declare function createClerkTwinFetch(options?: ClerkTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createClerkTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    personas?: Array<Record<string, unknown>>;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;