@volter/twin-clerk 0.1.0 → 0.1.2

package/dist/src/clerk-events.js

@@ -1,4 +1,5 @@
-import { nodeBuiltin } from '@volter/world-core';
+import { nodeBuiltin, worldNow, deliveryTraceHeaders } from '@volter/world-core';
+import { appDestination, appFetch } from '@volter/world-core/app-route';
 import { worldEgressRefusal } from '@volter/world-core/network-policy';
 function nodeCrypto() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -41,7 +42,7 @@ export function verifyWebhook(payload, headers, secret, opts = {}) {
     if (!id || !sigHeader || !Number.isFinite(ts))
         throw new ClerkWebhookVerificationError('Missing required svix headers');
     if (opts.tolerance !== undefined) {
-        const now = opts.now ?? Math.floor(Date.now() / 1000);
+        const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
         if (Math.abs(now - ts) > opts.tolerance)
             throw new ClerkWebhookVerificationError('Message timestamp too old');
     }
@@ -100,10 +101,10 @@ function svixMessageId(url, timestamp, body) { let h = 0x811c9dc5; const s = `${
     h = Math.imul(h, 0x01000193) >>> 0;
 } return `msg_twin_${h.toString(16).padStart(8, '0')}`; }
 const httpDelivery = async (url, body, headers) => {
-    if (worldEgressRefusal(url) !== null)
-        return; // the World's egress rule: refused like an unreachable endpoint
+    if (!appDestination(url) && worldEgressRefusal(url) !== null)
+        return; // the World's egress rule, the application's own hostnames reaching it inside the World: refused like an unreachable endpoint
     try {
-        await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+        await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers, ...deliveryTraceHeaders() }, body });
     }
     catch {
         /* fire-and-forget, like the real vendor */
@@ -126,7 +127,7 @@ export async function emitClerkEvent(operation, data, opts = {}) {
     if (!type || targets.length === 0)
         return [];
     const deliver = opts.deliver ?? httpDelivery;
-    const timestamp = Math.floor((opts.occurredAt ? Date.parse(opts.occurredAt) : Date.now()) / 1000) || 0;
+    const timestamp = Math.floor((opts.occurredAt ? Date.parse(opts.occurredAt) : Date.parse(worldNow())) / 1000) || 0;
     const event = { type, object: 'event', timestamp, data };
     const body = JSON.stringify(event);
     const out = [];

package/dist/src/clerk-jwt.js

@@ -12,7 +12,7 @@
 // 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';
+import { applyTwinWrite, projectResources, nodeBuiltin, worldNow } from '@volter/world-core';
 function nodeCrypto() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return nodeBuiltin('node:crypto');
@@ -91,7 +91,7 @@ function base64urlJson(obj) {
 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 iat = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     const exp = iat + (opts.expiresInSeconds ?? 60);
     const header = { alg: 'RS256', typ: 'JWT', kid };
     const payload = { iat, exp, nbf: iat, ...claims };
@@ -111,7 +111,7 @@ export async function signJwt(claims, opts = {}) {
  */
 export function signJwtHs256(claims, secret, opts = {}) {
     const { createHmac } = nodeCrypto();
-    const iat = opts.now ?? Math.floor(Date.now() / 1000);
+    const iat = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     const exp = iat + (opts.expiresInSeconds ?? 60);
     const header = { alg: 'HS256', typ: 'JWT' };
     const payload = { iat, exp, nbf: iat, ...claims };
@@ -143,7 +143,7 @@ export function verifyJwtHs256(token, secret, opts = {}) {
     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);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (typeof payload.exp === 'number' && now >= payload.exp)
         return { valid: false, reason: 'expired' };
     if (typeof payload.nbf === 'number' && now < payload.nbf)
@@ -189,7 +189,7 @@ export function verifyJwtWithJwks(token, jwks, opts = {}) {
     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);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (typeof payload.exp === 'number' && now >= payload.exp)
         return { valid: false, reason: 'expired' };
     if (typeof payload.nbf === 'number' && now < payload.nbf)

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

@@ -6,7 +6,7 @@
 // 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 { bundleClient, fileResponse, filePathOf } 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
@@ -14,8 +14,8 @@ import { createClerkTwinFetch } from "./clerk-server.js";
 // `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;
+const clientEntryPath = () => filePathOf(new URL('../client/clerk-mirror.tsx', import.meta.url));
+const clientCssPath = () => filePathOf(new URL('../client/clerk-mirror.css', import.meta.url));
 /** 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();

package/dist/src/clerk-server.js

@@ -7,7 +7,7 @@
 // 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 { runWithRequestTrace, 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";
@@ -89,7 +89,9 @@ export function createClerkTwinFetch(options = {}) {
     // 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) {
+    // a request's W3C trace context scopes everything it writes and delivers (world-core trace-context)
+    return (request) => runWithRequestTrace(request, () => clerkTwinFetch(request));
+    async function clerkTwinFetch(request) {
         await seeded;
         const url = new URL(request.url);
         // GET /twin — the discovery manifest (education inside the twin).
@@ -160,7 +162,7 @@ export function createClerkTwinFetch(options = {}) {
             ...(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({

package/dist/src/clerk-twin.js

@@ -12,7 +12,7 @@
 // THE meaty part: session tokens and JWT-template tokens are REAL RS256 JWTs signed from
 // a persisted local keypair, and /.well-known/jwks.json serves the matching JWKS, so an
 // app verifying a twin-issued token against the twin's JWKS succeeds unmodified.
-import { applyTwinWrite, projectResources, nodeBuiltin, resolveSubjectId } from '@volter/world-core';
+import { applyTwinWrite, projectResources, nodeBuiltin, resolveSubjectId, worldNow } from '@volter/world-core';
 import { buildJwks, signJwt, signJwtHs256, verifyJwtWithJwks } from "./clerk-jwt.js";
 import { emitClerkEvent, eventTypeFor } from "./clerk-events.js";
 const SERVICE = 'clerk';
@@ -53,7 +53,7 @@ function err(message, status = 404, code = 'resource_not_found', longMessage) {
     };
 }
 function nowUnixMs(occurredAt) {
-    return occurredAt ? Date.parse(occurredAt) : Date.now();
+    return occurredAt ? Date.parse(occurredAt) : Date.parse(worldNow());
 }
 function nodeCrypto() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-clerk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local Clerk twin — a faithful, stateful local Clerk Backend API your real `@clerk/backend` SDK talks to unmodified. Users, sessions, orgs, real signed JWTs + a JWKS endpoint. Mirror, simulate, and fork. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -58,10 +58,10 @@
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "@clerk/backend": "^1.15.0",
     "@types/bun": "^1.2.20",

package/src/clerk-events.ts

@@ -1,4 +1,5 @@
-import { nodeBuiltin } from '@volter/world-core';
+import { nodeBuiltin, worldNow, deliveryTraceHeaders } from '@volter/world-core';
+import { appDestination, appFetch } from '@volter/world-core/app-route';
 import { worldEgressRefusal } from '@volter/world-core/network-policy';
 // Clerk webhook emission — svix-style signed webhooks on user/session/org events.
 //
@@ -63,7 +64,7 @@ export function verifyWebhook(payload: string, headers: Record<string, string>,
   const sigHeader = lower['svix-signature'];
   if (!id || !sigHeader || !Number.isFinite(ts)) throw new ClerkWebhookVerificationError('Missing required svix headers');
   if (opts.tolerance !== undefined) {
-    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (Math.abs(now - ts) > opts.tolerance) throw new ClerkWebhookVerificationError('Message timestamp too old');
   }
   const expected = computeSvixSignature(id, ts, payload, secret).slice('v1,'.length);
@@ -121,9 +122,9 @@ export function eventTypeFor(operation: string): string | null {
 /** A stable svix message id for one delivery: FNV-1a over the destination, the instant and the body — no process counter (protocol 2). */
 function svixMessageId(url: string, timestamp: number, body: string): string { let h = 0x811c9dc5; const s = `${url}|${timestamp}|${body}`; for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; } return `msg_twin_${h.toString(16).padStart(8, '0')}`; }
 const httpDelivery: ClerkWebhookDelivery = async (url, body, headers) => {
-  if (worldEgressRefusal(url) !== null) return; // the World's egress rule: refused like an unreachable endpoint
+  if (!appDestination(url) && worldEgressRefusal(url) !== null) return; // the World's egress rule, the application's own hostnames reaching it inside the World: refused like an unreachable endpoint
   try {
-    await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+    await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers, ...deliveryTraceHeaders() }, body });
   } catch {
     /* fire-and-forget, like the real vendor */
   }
@@ -147,7 +148,7 @@ export async function emitClerkEvent(
   for (const r of registry) if (!targets.some((t) => t.url === r.url)) targets.push({ ...r });
   if (!type || targets.length === 0) return [];
   const deliver = opts.deliver ?? httpDelivery;
-  const timestamp = Math.floor((opts.occurredAt ? Date.parse(opts.occurredAt) : Date.now()) / 1000) || 0;
+  const timestamp = Math.floor((opts.occurredAt ? Date.parse(opts.occurredAt) : Date.parse(worldNow())) / 1000) || 0;
   const event: ClerkWebhookEvent = { type, object: 'event', timestamp, data };
   const body = JSON.stringify(event);
   const out: Array<{ url: string; body: string; headers: Record<string, string>; secret: string }> = [];

package/src/clerk-jwt.ts

@@ -12,7 +12,7 @@
 // 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';
+import { applyTwinWrite, projectResources, nodeBuiltin, worldNow } from '@volter/world-core';
 
 type NodeCrypto = typeof import('node:crypto');
 function nodeCrypto(): NodeCrypto {
@@ -112,7 +112,7 @@ function base64urlJson(obj: unknown): string {
 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 iat = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
   const exp = iat + (opts.expiresInSeconds ?? 60);
   const header = { alg: 'RS256', typ: 'JWT', kid };
   const payload = { iat, exp, nbf: iat, ...claims };
@@ -133,7 +133,7 @@ export async function signJwt(claims: Record<string, unknown>, opts: { root?: st
  */
 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 iat = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
   const exp = iat + (opts.expiresInSeconds ?? 60);
   const header = { alg: 'HS256', typ: 'JWT' };
   const payload = { iat, exp, nbf: iat, ...claims };
@@ -162,7 +162,7 @@ export function verifyJwtHs256(token: string, secret: string, opts: { now?: numb
   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);
+  const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 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 };
@@ -202,7 +202,7 @@ export function verifyJwtWithJwks(token: string, jwks: Jwks, opts: { now?: numbe
   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);
+  const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 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 };

package/src/clerk-mirror-ui.ts

@@ -6,7 +6,7 @@
 // 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 { bundleClient, fileResponse, filePathOf } from '@volter/world-core';
 import { serveHttp } from '@volter/world-core';
 import { createClerkTwinFetch } from './clerk-server.ts';
 
@@ -15,8 +15,8 @@ import { createClerkTwinFetch } from './clerk-server.ts';
 // `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;
+const clientEntryPath = () => filePathOf(new URL('../client/clerk-mirror.tsx', import.meta.url));
+const clientCssPath = () => filePathOf(new URL('../client/clerk-mirror.css', import.meta.url));
 
 // ---------------------------------------------------------------------------
 // Pure, dependency-free render/format helpers. Framework-agnostic (plain data in →

package/src/clerk-server.ts

@@ -7,7 +7,7 @@
 // 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 { runWithRequestTrace, 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';
@@ -97,7 +97,9 @@ export function createClerkTwinFetch(options: ClerkTwinFetchOptions = {}): (requ
   // 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> {
+  // a request's W3C trace context scopes everything it writes and delivers (world-core trace-context)
+  return (request: Request): Promise<Response> => runWithRequestTrace(request, () => clerkTwinFetch(request));
+  async function clerkTwinFetch(request: Request): Promise<Response> {
     await seeded;
     const url = new URL(request.url);
     // GET /twin — the discovery manifest (education inside the twin).
@@ -162,7 +164,7 @@ export function createClerkTwinFetch(options: ClerkTwinFetchOptions = {}): (requ
       ...(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 }> {

package/src/clerk-twin.ts

@@ -12,7 +12,7 @@
 // THE meaty part: session tokens and JWT-template tokens are REAL RS256 JWTs signed from
 // a persisted local keypair, and /.well-known/jwks.json serves the matching JWKS, so an
 // app verifying a twin-issued token against the twin's JWKS succeeds unmodified.
-import { applyTwinWrite, projectResources, nodeBuiltin, resolveSubjectId } from '@volter/world-core';
+import { applyTwinWrite, projectResources, nodeBuiltin, resolveSubjectId, worldNow } from '@volter/world-core';
 import { buildJwks, signJwt, signJwtHs256, verifyJwtWithJwks } from './clerk-jwt.ts';
 import { emitClerkEvent, eventTypeFor, type ClerkWebhookTarget } from './clerk-events.ts';
 
@@ -71,7 +71,7 @@ function err(message: string, status = 404, code = 'resource_not_found', longMes
 }
 
 function nowUnixMs(occurredAt?: string): number {
-  return occurredAt ? Date.parse(occurredAt) : Date.now();
+  return occurredAt ? Date.parse(occurredAt) : Date.parse(worldNow());
 }
 
 // ── password hashing (REAL crypto) ──────────────────────────────────────────────