@volter/twin-clerk 0.1.0

package/dist/src/clerk-server.js

@@ -0,0 +1,172 @@
+// 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.js";
+import { worldNow, statefulTwinManifest, packAsset } from '@volter/world-core';
+import { handleClerkFapiRequest } from "./clerk-fapi.js";
+const FAPI_COLLECTIONS = new Set(['environment', 'client', 'dev_browser', 'oauth-consent']);
+function parseCookies(header) {
+    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, root) {
+    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];
+            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)}`);
+    }
+}
+/**
+ * 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 = {}) {
+    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) {
+        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) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createClerkTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

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

@@ -0,0 +1,28 @@
+export type ClerkRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The Host this request arrived on (`host` / `x-forwarded-host`), so self-referential URLs the
+     *  API emits point back at wherever this twin is actually bound. Runtime contract R7: a twin
+     *  learns its own origin from the request and never assumes a port. */
+    host?: string;
+    /** The Origin of the browser request that asked for this work, set only by the Frontend API
+     *  door (clerk-js runs in a page). Real Clerk puts it in a session token's `azp`; a Backend
+     *  API call has no browser behind it and carries none. */
+    origin?: string;
+};
+/** The instance's issuer: the `iss` of every token the twin signs, and the `issuer` its OIDC
+ *  discovery document names. One value, so a verifier's `iss === discovery.issuer` holds. */
+export declare const CLERK_TWIN_ISSUER = "https://twin.clerk.accounts.dev";
+export type ClerkResponse = {
+    status: number;
+    body: unknown;
+};
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist.
+ *  The resend exemplar's helper — the only entropy source an id is allowed on the serve path. */
+export declare function stableHex(seed: string, n: number): string;
+export declare function handleClerkTwinRequest(req: ClerkRequest): Promise<ClerkResponse>;
+export declare const CLERK_RESOURCE_TYPES: readonly ["user", "session", "organization", "organization_membership", "organization_invitation", "invitation", "allowlist_identifier", "blocklist_identifier", "jwt_template", "sign_in_token", "email_address", "actor_token", "redirect_url", "oauth_application", "saml_connection", "domain", "webhook_endpoint"];