@volter/twin-clerk 0.1.0

package/src/clerk-conformance.ts

@@ -0,0 +1,172 @@
+// Clerk twin conformance — spec-true validation of the resources the twin serves
+// against per-object JSON Schemas (object discriminator, required fields, types),
+// offline (no key). Clerk's Backend API is one we cannot dual-run against a live
+// sandbox in CI, so the published-shape schemas carry the weight here.
+//
+// For every resource the twin emits, validate its body via the shared specConformance
+// harness: declared TYPES, REQUIRED fields (omission), ENUMS. Twin-internal `_`-prefixed
+// fields are exempt; polymorphic/nested fields are left untyped to avoid false positives.
+import { twinResources } from '@volter/world-core';
+import { specConformance } from '@volter/world-tooling';
+import type { TwinResource } from '@volter/world-core';
+
+type JsonSchema = specConformance.JsonSchema;
+type KnownDeviation = specConformance.KnownDeviation;
+type SpecViolation = specConformance.SpecViolation;
+
+// Per-object Clerk JSON Schemas (the fields/types the Backend API documents for each
+// object). Kept inline (the surface is small + stable); grow as the twin grows. Only
+// scalar/array required fields are typed — nested polymorphic blocks (verification,
+// metadata bags, nested organization) are left untyped to avoid false positives.
+const SCHEMAS: Record<string, JsonSchema> = {
+  user: {
+    type: 'object',
+    required: ['object', 'id', 'email_addresses', 'banned', 'locked'],
+    properties: {
+      object: { type: 'string', enum: ['user'] },
+      id: { type: 'string' },
+      banned: { type: 'boolean' },
+      locked: { type: 'boolean' },
+      created_at: { type: 'integer' },
+      updated_at: { type: 'integer' },
+      email_addresses: { type: 'array' },
+      phone_numbers: { type: 'array' },
+    },
+  },
+  session: {
+    type: 'object',
+    required: ['object', 'id', 'user_id', 'status'],
+    properties: {
+      object: { type: 'string', enum: ['session'] },
+      id: { type: 'string' },
+      user_id: { type: 'string' },
+      status: { type: 'string', enum: ['active', 'revoked', 'ended', 'expired', 'removed', 'abandoned', 'replaced'] },
+      created_at: { type: 'integer' },
+    },
+  },
+  organization: {
+    type: 'object',
+    required: ['object', 'id', 'name', 'slug', 'members_count'],
+    properties: {
+      object: { type: 'string', enum: ['organization'] },
+      id: { type: 'string' },
+      name: { type: 'string' },
+      slug: { type: 'string' },
+      members_count: { type: 'integer' },
+      created_at: { type: 'integer' },
+    },
+  },
+  organization_membership: {
+    type: 'object',
+    required: ['object', 'id', 'role', 'organization_id'],
+    properties: {
+      object: { type: 'string', enum: ['organization_membership'] },
+      id: { type: 'string' },
+      role: { type: 'string' },
+      organization_id: { type: 'string' },
+    },
+  },
+  organization_invitation: {
+    type: 'object',
+    required: ['object', 'id', 'email_address', 'status', 'organization_id'],
+    properties: {
+      object: { type: 'string', enum: ['organization_invitation'] },
+      id: { type: 'string' },
+      email_address: { type: 'string' },
+      status: { type: 'string', enum: ['pending', 'accepted', 'revoked'] },
+      organization_id: { type: 'string' },
+    },
+  },
+  invitation: {
+    type: 'object',
+    required: ['object', 'id', 'email_address', 'status'],
+    properties: {
+      object: { type: 'string', enum: ['invitation'] },
+      id: { type: 'string' },
+      email_address: { type: 'string' },
+      status: { type: 'string', enum: ['pending', 'accepted', 'revoked'] },
+    },
+  },
+  jwt_template: {
+    type: 'object',
+    required: ['object', 'id', 'name', 'lifetime'],
+    properties: {
+      object: { type: 'string', enum: ['jwt_template'] },
+      id: { type: 'string' },
+      name: { type: 'string' },
+      lifetime: { type: 'integer' },
+      signing_algorithm: { type: 'string' },
+    },
+  },
+};
+
+// twin resource type → schema key. Internal/derived types (keypair, sign_in_token,
+// email_address, allow/blocklist) are not schema-checked here.
+const TYPE_TO_OBJECT: Record<string, string> = {
+  user: 'user', session: 'session', organization: 'organization',
+  organization_membership: 'organization_membership', organization_invitation: 'organization_invitation',
+  invitation: 'invitation', jwt_template: 'jwt_template',
+};
+
+export type ClerkViolation = SpecViolation & { object: string; id: string };
+export type ClerkConformanceReport = {
+  ok: boolean;
+  resourcesChecked: number;
+  fieldsChecked: number;
+  violations: ClerkViolation[];
+  knownIgnored: number;
+};
+
+const isTwinExtra = (k: string): boolean => k.startsWith('_');
+
+// The emitted body: drop kernel meta + twin-internal fields, restore the vendor `type`.
+function emitted(r: TwinResource): Record<string, unknown> {
+  const { type, updatedAt, _clerk_type, ...rest } = r as TwinResource & { _clerk_type?: unknown };
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rest)) if (!k.startsWith('_')) out[k] = v;
+  out.id = r.id;
+  if (_clerk_type !== undefined) out.type = _clerk_type;
+  return out;
+}
+
+export function loadClerkSchemas(): Record<string, JsonSchema> {
+  return SCHEMAS;
+}
+
+/**
+ * Validate every Clerk resource the twin serves (in `root`) against its schema. A wrong
+ * type, an undeclared missing-required field, or an enum violation fails the report.
+ */
+export function checkClerkConformance(opts: { root?: string; known?: KnownDeviation[] } = {}): ClerkConformanceReport {
+  const resources = twinResources('clerk', opts.root).filter((r) => !r.type.startsWith('_'));
+  const violations: ClerkViolation[] = [];
+  let fieldsChecked = 0;
+  let knownIgnored = 0;
+  for (const r of resources) {
+    const objectName = TYPE_TO_OBJECT[r.type];
+    if (!objectName) continue;
+    const schema = SCHEMAS[objectName];
+    if (!schema) continue;
+    const rep = specConformance.checkSpecConformance(emitted(r), schema, { exemptKey: isTwinExtra, known: opts.known ?? [], flagExtra: false });
+    fieldsChecked += rep.fieldsChecked;
+    knownIgnored += rep.knownIgnored;
+    for (const v of rep.violations) violations.push({ ...v, object: objectName, id: r.id });
+  }
+  return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored };
+}
+
+export type ClerkCoverageReport = specConformance.SpecCoverageReport & { object: string };
+
+/** Per-object coverage: of the fields each Clerk object declares, which does the twin emit? */
+export function clerkCoverage(opts: { root?: string } = {}): ClerkCoverageReport[] {
+  const byType = new Map<string, TwinResource>();
+  for (const r of twinResources('clerk', opts.root)) if (!r.type.startsWith('_') && !byType.has(r.type)) byType.set(r.type, r);
+  const out: ClerkCoverageReport[] = [];
+  for (const [type, r] of byType) {
+    const objectName = TYPE_TO_OBJECT[type];
+    const schema = objectName ? SCHEMAS[objectName] : undefined;
+    if (!objectName || !schema) continue;
+    out.push({ object: objectName, ...specConformance.specCoverage(schema, emitted(r), { exemptKey: isTwinExtra }) });
+  }
+  return out;
+}

package/src/clerk-connector.ts

@@ -0,0 +1,268 @@
+// Clerk CONNECTOR — the live-vendor pull/push path that gives the Clerk twin the full
+// "git for SaaS" lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL  (real → twin):  fetch real Clerk objects via the injected client, map them to
+//                       SyncResource[], and fold them into the event log via syncPull
+//                       (shadow-diff dedup, so a re-pull of identical state is a no-op).
+// PUSH  (twin → real):  for every PENDING local action, call the injected client and
+//                       confirmAction on success — recording the confirmed fields as an
+//                       observed event and suppressing the local projection.
+//
+// The vendor I/O is an INJECTED client interface (`ClerkClient`): a fake in tests, the
+// real `@clerk/backend` createClerkClient(...) in prod. The pack imports NO SDK and holds
+// NO key. The shape below is structurally satisfied by `createClerkClient(...)`.
+import { observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+
+const SERVICE = 'clerk';
+
+/**
+ * The injected real-Clerk boundary — a minimal subset of `@clerk/backend`'s ClerkClient
+ * that the connector uses. The real client (createClerkClient({ secretKey })) is
+ * structurally assignable; tests pass a fake. Only the methods the connector calls are
+ * declared, so the surface stays honest.
+ */
+export interface ClerkClient {
+  users: {
+    getUserList(params?: { limit?: number; offset?: number }): Promise<{ data: ClerkUser[]; totalCount: number } | ClerkUser[]>;
+    createUser(params: Record<string, unknown>): Promise<ClerkUser>;
+    updateUser(userId: string, params: Record<string, unknown>): Promise<ClerkUser>;
+    deleteUser(userId: string): Promise<{ id: string; deleted?: boolean }>;
+  };
+  organizations: {
+    getOrganizationList(params?: { limit?: number; offset?: number }): Promise<{ data: ClerkOrg[]; totalCount: number } | ClerkOrg[]>;
+    createOrganization(params: Record<string, unknown>): Promise<ClerkOrg>;
+    updateOrganization(orgId: string, params: Record<string, unknown>): Promise<ClerkOrg>;
+    deleteOrganization(orgId: string): Promise<{ id: string; deleted?: boolean }>;
+    getOrganizationMembershipList?(params: { organizationId: string; limit?: number; offset?: number }): Promise<{ data: ClerkMembership[]; totalCount: number } | ClerkMembership[]>;
+  };
+  // Optional: the sessions resource is only used by the sessions/memberships pull path.
+  sessions?: {
+    getSessionList(params?: { userId?: string; status?: string; limit?: number; offset?: number }): Promise<{ data: ClerkSession[]; totalCount: number } | ClerkSession[]>;
+  };
+}
+
+export type ClerkUser = {
+  id: string; firstName?: string | null; lastName?: string | null; username?: string | null;
+  emailAddresses?: Array<{ emailAddress: string }>; banned?: boolean; locked?: boolean;
+  createdAt?: number; externalId?: string | null;
+};
+export type ClerkOrg = {
+  id: string; name?: string; slug?: string; membersCount?: number; maxAllowedMemberships?: number; createdAt?: number;
+  updatedAt?: number; imageUrl?: string; hasImage?: boolean; pendingInvitationsCount?: number; adminDeleteEnabled?: boolean; createdBy?: string | null; publicMetadata?: Record<string, unknown>; privateMetadata?: Record<string, unknown>;
+};
+export type ClerkSession = {
+  id: string; userId?: string; status?: string; clientId?: string;
+  lastActiveAt?: number; expireAt?: number; createdAt?: number; lastActiveOrganizationId?: string | null;
+};
+export type ClerkMembership = {
+  id: string; role?: string; organization?: { id?: string } | null; orgId?: string;
+  publicUserData?: { userId?: string } | null; createdAt?: number;
+};
+
+function listOf<T>(res: { data?: T[] } | T[]): T[] {
+  return Array.isArray(res) ? res : Array.isArray(res?.data) ? res.data : [];
+}
+
+// ── PULL ──────────────────────────────────────────────────────────────────────
+/** Map a real-Clerk user (camelCase SDK shape) → a twin sync resource (snake_case). */
+export function mapUser(u: ClerkUser): SyncResource {
+  return {
+    type: 'user',
+    id: String(u.id),
+    fields: {
+      first_name: u.firstName ?? null,
+      last_name: u.lastName ?? null,
+      username: u.username ?? null,
+      primary_email: u.emailAddresses?.[0]?.emailAddress ?? null,
+      banned: typeof u.banned === 'boolean' ? u.banned : false,
+      locked: typeof u.locked === 'boolean' ? u.locked : false,
+      external_id: u.externalId ?? null,
+      created_at: typeof u.createdAt === 'number' ? u.createdAt : null,
+      object: 'user',
+    },
+  };
+}
+
+/** Map a real-Clerk organization → a twin sync resource. */
+export function mapOrganization(o: ClerkOrg): SyncResource {
+  return {
+    type: 'organization',
+    id: String(o.id),
+    fields: {
+      name: o.name ?? null,
+      slug: o.slug ?? null,
+      members_count: typeof o.membersCount === 'number' ? o.membersCount : 0,
+      max_allowed_memberships: typeof o.maxAllowedMemberships === 'number' ? o.maxAllowedMemberships : null,
+      created_at: typeof o.createdAt === 'number' ? o.createdAt : null,
+      updated_at: typeof o.updatedAt === 'number' ? o.updatedAt : (typeof o.createdAt === 'number' ? o.createdAt : null),
+      // the twin's own write stores these too — shape parity (protocol 2) holds the two mappings equal
+      image_url: o.imageUrl ?? '', has_image: Boolean(o.hasImage), pending_invitations_count: o.pendingInvitationsCount ?? 0, admin_delete_enabled: o.adminDeleteEnabled ?? true, created_by: o.createdBy ?? null,
+      public_metadata: o.publicMetadata ?? {}, private_metadata: o.privateMetadata ?? {},
+      object: 'organization',
+    },
+  };
+}
+
+/** Map a real-Clerk session → a twin sync resource. */
+export function mapSession(s: ClerkSession): SyncResource {
+  return {
+    type: 'session',
+    id: String(s.id),
+    fields: {
+      user_id: s.userId ?? null,
+      status: s.status ?? 'active',
+      client_id: s.clientId ?? null,
+      last_active_at: typeof s.lastActiveAt === 'number' ? s.lastActiveAt : null,
+      expire_at: typeof s.expireAt === 'number' ? s.expireAt : null,
+      last_active_organization_id: s.lastActiveOrganizationId ?? null,
+      created_at: typeof s.createdAt === 'number' ? s.createdAt : null,
+      object: 'session',
+    },
+  };
+}
+/** Map a real-Clerk organization membership → a twin sync resource. */
+export function mapMembership(m: ClerkMembership): SyncResource {
+  return {
+    type: 'organization_membership',
+    id: String(m.id),
+    fields: {
+      role: m.role ?? 'basic_member',
+      organization_id: m.organization?.id ?? m.orgId ?? null,
+      _user_id: m.publicUserData?.userId ?? null,
+      created_at: typeof m.createdAt === 'number' ? m.createdAt : null,
+      object: 'organization_membership',
+    },
+  };
+}
+
+export async function pullClerkUsers(client: ClerkClient, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  const res = await client.users.getUserList({ limit: opts.limit ?? 100 });
+  return listOf<ClerkUser>(res).map(mapUser);
+}
+export async function pullClerkOrganizations(client: ClerkClient, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  const res = await client.organizations.getOrganizationList({ limit: opts.limit ?? 100 });
+  return listOf<ClerkOrg>(res).map(mapOrganization);
+}
+/** Pull active sessions from real Clerk (no-op if the client doesn't expose the resource). */
+export async function pullClerkSessions(client: ClerkClient, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  if (!client.sessions?.getSessionList) return [];
+  const res = await client.sessions.getSessionList({ limit: opts.limit ?? 100 });
+  return listOf<ClerkSession>(res).map(mapSession);
+}
+/** Pull organization memberships from real Clerk for the given orgs (best-effort per org). */
+export async function pullClerkMemberships(client: ClerkClient, orgIds: string[], opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  if (!client.organizations.getOrganizationMembershipList) return [];
+  const out: SyncResource[] = [];
+  for (const organizationId of orgIds) {
+    const res = await client.organizations.getOrganizationMembershipList({ organizationId, limit: opts.limit ?? 100 });
+    for (const m of listOf<ClerkMembership>(res)) out.push(mapMembership(m));
+  }
+  return out;
+}
+
+/**
+ * Pull from real Clerk (users + organizations, plus sessions + memberships when the
+ * injected client exposes them) and fold into the twin (mirror seeding).
+ */
+export async function syncClerkFromReal(
+  client: ClerkClient,
+  opts: { root?: string; occurredAt: string; limit?: number; includeSessions?: boolean },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const limitOpt = opts.limit ? { limit: opts.limit } : {};
+  const users = await pullClerkUsers(client, limitOpt);
+  const orgs = await pullClerkOrganizations(client, limitOpt);
+  const resources = [...users, ...orgs];
+  if (opts.includeSessions !== false) {
+    const sessions = await pullClerkSessions(client, limitOpt);
+    const memberships = await pullClerkMemberships(client, orgs.map((o) => o.id), limitOpt);
+    resources.push(...sessions, ...memberships);
+  }
+  // protocol 2: an observation lands on the head through the kernel's fold — one batch, one instant
+  const report = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}` });
+  return { observed: report.observed, deltasAppended: report.appended };
+}
+
+// ── PROTOCOL 2: the state system's two adapters, over the kernel's executor ──────────
+/** Clerk's Backend API answers snake_case; the SDK's objects are camelCase, and the maps read the SDK's shape. */
+function camel(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(camel);
+  if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v as Record<string, unknown>).map(([k, x]) => [k.replace(/_([a-z])/g, (_m, ch: string) => ch.toUpperCase()), camel(x)]));
+  return v;
+}
+/** A ClerkClient over a RemoteExecute: the calls the SDK makes, as wire requests the executor carries. */
+export function clerkClientOver(execute: RemoteExecute): ClerkClient {
+  const call = async <T>(method: string, path: string, body?: Record<string, unknown>): Promise<T> => {
+    const res = await execute({ method, path, headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+    if (res.status >= 300) throw new Error(`clerk: ${method} ${path} answered ${res.status}: ${res.body.slice(0, 200)}`);
+    return camel(res.body === '' ? {} : JSON.parse(res.body)) as T;
+  };
+  const listOf = async <T>(path: string, params?: Record<string, unknown>): Promise<T[]> => { const q = new URLSearchParams(); for (const [k, v] of Object.entries(params ?? {})) if (v !== undefined) q.set(k, String(v)); const r = await call<T[] | { data: T[] }>('GET', `${path}${q.size ? `?${q}` : ''}`); return Array.isArray(r) ? r : (r.data ?? []); };
+  return {
+    users: { getUserList: (p) => listOf<ClerkUser>('/v1/users', p), createUser: (p) => call<ClerkUser>('POST', '/v1/users', p), updateUser: (id, p) => call<ClerkUser>('PATCH', `/v1/users/${encodeURIComponent(id)}`, p), deleteUser: (id) => call<{ id: string }>('DELETE', `/v1/users/${encodeURIComponent(id)}`) },
+    organizations: { getOrganizationList: (p) => listOf<ClerkOrg>('/v1/organizations', p), createOrganization: (p) => call<ClerkOrg>('POST', '/v1/organizations', p), updateOrganization: (id, p) => call<ClerkOrg>('PATCH', `/v1/organizations/${encodeURIComponent(id)}`, p), deleteOrganization: (id) => call<{ id: string }>('DELETE', `/v1/organizations/${encodeURIComponent(id)}`), getOrganizationMembershipList: ({ organizationId, ...p }) => listOf<ClerkMembership>(`/v1/organizations/${encodeURIComponent(organizationId)}/memberships`, p) },
+    sessions: { getSessionList: (p) => listOf<ClerkSession>('/v1/sessions', p) },
+  };
+}
+/** The refresh adapter: pull Clerk's users, organizations, sessions and memberships through the executor and fold them into the root. */
+export async function syncClerkFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  return syncClerkFromReal(clerkClientOver(execute), { ...(opts.root !== undefined ? { root: opts.root } : {}), occurredAt: opts.occurredAt ?? new Date().toISOString() });
+}
+/** The perform adapter: one entry crosses to Clerk through the executor; an entry that is the twin's own (an attempt, a session, a totp) crosses nothing. */
+export async function performClerkAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  if (!PUSHABLE.has(op)) return { externalId: action.subject.id, data: { performed: false, reason: 'the twin\'s own record — nothing at Clerk to write' } };
+  const fields = { ...(action.fields ?? {}) };
+  if (typeof fields.organization_id === 'string') fields.organization_id = ctx.resolve('organization', fields.organization_id);
+  if (typeof fields.created_by === 'string') fields.created_by = ctx.resolve('user', fields.created_by);
+  const { externalId } = await pushClerkAction(clerkClientOver(execute), { operation: op, subject: action.subject, fields });
+  return { externalId };
+}
+
+// ── PUSH ──────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Clerk. Anything not here
+// FAILS LOUDLY rather than being silently dropped.
+const PUSHABLE = new Set([
+  'user.create', 'user.update', 'user.delete',
+  'organization.create', 'organization.update', 'organization.delete',
+]);
+
+function assertPushable(op: string): void {
+  if (!PUSHABLE.has(op)) {
+    throw new Error(`clerk push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+}
+
+/**
+ * Push ONE pending action to REAL Clerk via the injected client. Returns the real
+ * external id (the Clerk object id from the response — a fresh id for a create, the
+ * subject id otherwise). WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushClerkAction(
+  client: ClerkClient,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+): Promise<{ externalId: string }> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  assertPushable(op);
+  const { type, id } = action.subject;
+  const fields = action.fields ?? {};
+  let externalId = id;
+  if (type === 'user') {
+    if (op === 'user.create') externalId = (await client.users.createUser(fields)).id;
+    else if (op === 'user.update') externalId = (await client.users.updateUser(id, fields)).id;
+    else if (op === 'user.delete') await client.users.deleteUser(id);
+  } else if (type === 'organization') {
+    if (op === 'organization.create') externalId = (await client.organizations.createOrganization(fields)).id;
+    else if (op === 'organization.update') externalId = (await client.organizations.updateOrganization(id, fields)).id;
+    else if (op === 'organization.delete') await client.organizations.deleteOrganization(id);
+  }
+  return { externalId: externalId || id };
+}
+
+/**
+ * Push the twin's PENDING local actions to real Clerk and CONFIRM each (R18). A confirmed
+ * action is no longer pending, so a re-push enacts NOTHING. `client` is injected (fake
+ * offline / real SDK live). Unpushable ops are skipped (only modeled write ops are pushed).
+ */
+// protocol 2: the pending-actions loop is the kernel's (the head performs each entry through `performClerkAction`);
+// the v1 `pushPendingClerkActions` is gone with the log it read.

package/src/clerk-events.ts

@@ -0,0 +1,166 @@
+import { nodeBuiltin } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+// Clerk webhook emission — svix-style signed webhooks on user/session/org events.
+//
+// Real Clerk delivers webhooks through Svix: each delivery carries `svix-id`,
+// `svix-timestamp`, and `svix-signature` headers, where the signature is
+// base64(HMAC-SHA256(secret, `${svix-id}.${svix-timestamp}.${payload}`)) prefixed
+// `v1,`. The signing secret is `whsec_<base64>`; the HMAC key is the base64-decoded
+// portion. An app verifies with the `svix` library; we reproduce the scheme
+// byte-for-byte so a real consumer verifies twin-delivered webhooks unchanged.
+//
+// `node:crypto` is required LAZILY (server-only), like the JWT helpers, so this module
+// is safe to pull into the browser bundle.
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+export type ClerkWebhookEvent = {
+  type: string;
+  object: 'event';
+  timestamp: number;
+  data: Record<string, unknown>;
+};
+export type ClerkWebhookDelivery = (url: string, body: string, headers: Record<string, string>) => Promise<void> | void;
+
+/** Decode a `whsec_<base64>` signing secret to its raw HMAC key bytes. */
+function secretKeyBytes(secret: string): Buffer {
+  const b64 = secret.startsWith('whsec_') ? secret.slice('whsec_'.length) : secret;
+  return Buffer.from(b64, 'base64');
+}
+
+/**
+ * Compute the Svix `svix-signature` header value for a delivery: `v1,<base64 sig>`
+ * over `${id}.${timestamp}.${payload}` keyed by the (base64-decoded) signing secret.
+ * Mirrors what `svix`'s Webhook.sign produces, so `wh.verify(payload, headers)` passes.
+ */
+export function computeSvixSignature(id: string, timestamp: number, payload: string, secret: string): string {
+  const key = secretKeyBytes(secret);
+  const signed = `${id}.${timestamp}.${payload}`;
+  const sig = nodeCrypto().createHmac('sha256', key).update(signed, 'utf8').digest('base64');
+  return `v1,${sig}`;
+}
+
+export class ClerkWebhookVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ClerkWebhookVerificationError';
+  }
+}
+
+/**
+ * Verify a webhook payload + Svix headers against the signing secret and return the
+ * parsed event (mirrors `svix` `Webhook.verify`). Throws on a missing/malformed
+ * header, a signature mismatch, or (when `tolerance` is given) a stale timestamp.
+ */
+export function verifyWebhook(payload: string, headers: Record<string, string>, secret: string, opts: { tolerance?: number; now?: number } = {}): ClerkWebhookEvent {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+  const id = lower['svix-id'];
+  const ts = Number(lower['svix-timestamp']);
+  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);
+    if (Math.abs(now - ts) > opts.tolerance) throw new ClerkWebhookVerificationError('Message timestamp too old');
+  }
+  const expected = computeSvixSignature(id, ts, payload, secret).slice('v1,'.length);
+  const expectedBuf = Buffer.from(expected, 'utf8');
+  // The header may carry multiple space-separated `v<n>,<sig>` pairs.
+  const matched = sigHeader.split(' ').some((part) => {
+    const comma = part.indexOf(',');
+    if (comma === -1) return false;
+    const sig = part.slice(comma + 1);
+    const sigBuf = Buffer.from(sig, 'utf8');
+    return sigBuf.length === expectedBuf.length && nodeCrypto().timingSafeEqual(sigBuf, expectedBuf);
+  });
+  if (!matched) throw new ClerkWebhookVerificationError('No matching signature found');
+  return JSON.parse(payload) as ClerkWebhookEvent;
+}
+
+// ── endpoint registry + event mapping ───────────────────────────────────────────
+/** A webhook endpoint a World holds in its tree: where to POST, what to sign with, which event types it filters to. */
+export type ClerkWebhookTarget = { url: string; secret: string; filterTypes?: string[] };
+// URLs a HOST registered directly (registerClerkWebhook). A World's own endpoints are not here:
+// POST /v1/webhooks/endpoints writes the webhook_endpoint to the tree, and every emit reads the tree
+// (the caller passes them as `endpoints`), so delivery survives a restart and belongs to one World.
+const registry: Array<{ url: string; secret: string }> = [];
+export function registerClerkWebhook(url: string, secret = 'whsec_dGVzdHNlY3JldHRlc3RzZWNyZXQ='): void {
+  if (!registry.some((r) => r.url === url)) registry.push({ url, secret });
+}
+export function clearClerkWebhooks(): void {
+  registry.length = 0;
+}
+export function listClerkWebhooks(): Array<{ url: string; secret: string }> {
+  return registry.map((r) => ({ ...r }));
+}
+
+// twin write operation → Clerk webhook event type (the ones an app's webhooks care about).
+export function eventTypeFor(operation: string): string | null {
+  switch (operation) {
+    case 'user.create': return 'user.created';
+    case 'user.update': return 'user.updated';
+    case 'user.delete': return 'user.deleted';
+    case 'session.create': return 'session.created';
+    case 'session.revoke': return 'session.revoked';
+    case 'session.end': return 'session.ended';
+    case 'organization.create': return 'organization.created';
+    case 'organization.update': return 'organization.updated';
+    case 'organization.delete': return 'organization.deleted';
+    case 'organization_membership.create': return 'organizationMembership.created';
+    case 'organization_membership.update': return 'organizationMembership.updated';
+    case 'organization_membership.delete': return 'organizationMembership.deleted';
+    case 'organization_invitation.create': return 'organizationInvitation.created';
+    case 'email.create': return 'email.created';
+    default: return 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
+  try {
+    await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+  } catch {
+    /* fire-and-forget, like the real vendor */
+  }
+};
+
+/**
+ * Emit a Clerk webhook for a twin write to the World's endpoints (`endpoints`, read from its
+ * tree; an endpoint with `filter_types` receives only those types) and host-registered URLs. Builds the Svix
+ * envelope + signed headers and delivers it (injected delivery: fake in tests, HTTP
+ * POST live). Returns the delivered bodies+headers (for assertions); no-op when nothing
+ * is registered or the operation has no mapped event type.
+ */
+export async function emitClerkEvent(
+  operation: string,
+  data: Record<string, unknown>,
+  opts: { occurredAt?: string; deliver?: ClerkWebhookDelivery; endpoints?: ClerkWebhookTarget[] } = {},
+): Promise<Array<{ url: string; body: string; headers: Record<string, string>; secret: string }>> {
+  const type = eventTypeFor(operation);
+  // the World's own endpoints (its tree is the record), then any URL a host registered directly
+  const targets: ClerkWebhookTarget[] = [...(opts.endpoints ?? [])];
+  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 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 }> = [];
+  for (const { url, secret, filterTypes } of targets) {
+    if (filterTypes && filterTypes.length > 0 && !filterTypes.includes(type)) continue;
+    const svixId = svixMessageId(url, timestamp, body);
+    const headers = {
+      'svix-id': svixId,
+      'svix-timestamp': String(timestamp),
+      'svix-signature': computeSvixSignature(svixId, timestamp, body, secret),
+    };
+    await deliver(url, body, headers);
+    out.push({ url, body, headers, secret });
+  }
+  return out;
+}