@volter/twin-clerk 0.1.0

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { readFileSync } from 'node:fs';
+// world-clerk CLI: serve the Clerk Backend API twin, the mirror UI, or run conformance.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createClerkTwinServer } from "./clerk-server.js";
+import { createClerkMirrorServer } from "./clerk-mirror-ui.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const personasFile = optionValue(rest, '--personas') || undefined; // JSON array of {email, password, first_name?, last_name?}
+// The cli is dev-plane and may read the host: the server takes personas as DATA (R12b).
+const personas = personasFile === undefined ? undefined : JSON.parse(readFileSync(personasFile, 'utf8'));
+if (cmd === 'serve') {
+    const s = await createClerkTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(personas ? { personas } : {}) });
+    process.stdout.write(`clerk twin (Backend API + Frontend API + JWKS)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'mirror') {
+    const s = await createClerkMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
+    process.stdout.write(`clerk mirror UI (admin dashboard) at http://127.0.0.1:${s.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    // dev-only; lazy so the bin runs without @volter/world-tooling
+    const { checkClerkConformance, clerkCoverage } = await import("./clerk-conformance.js");
+    const report = checkClerkConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify({ ...report, coverage: clerkCoverage({ ...(root ? { root } : {}) }) }, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-clerk serve|mirror|conformance [--port N] [--root DIR] [--read-only] [--personas FILE]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+export { handleClerkTwinRequest, CLERK_RESOURCE_TYPES } from './clerk-twin.js';
+export type { ClerkRequest, ClerkResponse } from './clerk-twin.js';
+export { createClerkTwinFetch, createClerkTwinServer, type ClerkTwinFetchOptions } from './clerk-server.js';
+export { buildJwks, decodeJwt, ensureKeypair, networklessVerifyToken, setKeypairGenerator, signJwt, signJwtHs256, verifyJwtHs256, verifyJwtWithJwks, } from './clerk-jwt.js';
+export type { ClerkAuthState, ClerkKeypair, Jwk, Jwks, KeypairGenerator, KeypairMaterial } from './clerk-jwt.js';
+export { clearClerkWebhooks, computeSvixSignature, ClerkWebhookVerificationError, emitClerkEvent, eventTypeFor, listClerkWebhooks, registerClerkWebhook, verifyWebhook, } from './clerk-events.js';
+export type { ClerkWebhookDelivery, ClerkWebhookEvent } from './clerk-events.js';
+export { mapMembership, mapOrganization, mapSession, mapUser, pullClerkMemberships, pullClerkOrganizations, pullClerkSessions, pullClerkUsers, pushClerkAction, clerkClientOver, syncClerkFromRemote, performClerkAction, syncClerkFromReal, } from './clerk-connector.js';
+export type { ClerkClient, ClerkMembership, ClerkOrg, ClerkSession, ClerkUser } from './clerk-connector.js';
+export { buildClerkMirrorClient, createClerkMirrorServer, clerkMirrorHtml } from './clerk-mirror-ui.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,56 @@
+// @volter/twin-clerk — the Clerk Backend API twin (one vendor, one package), built on
+// the shared @volter/world-core kernel. REST transport over api.clerk.com shapes, REAL signed
+// JWTs from a persisted local keypair + a JWKS endpoint, svix-style signed webhooks, and
+// a React admin-dashboard UI mirror. (Conformance/capability tooling lives in
+// @volter/world-tooling, a dev dependency — NOT shipped in the runtime API.)
+export { handleClerkTwinRequest, CLERK_RESOURCE_TYPES } from "./clerk-twin.js";
+export { createClerkTwinFetch, createClerkTwinServer } from "./clerk-server.js";
+export { buildJwks, decodeJwt, ensureKeypair, networklessVerifyToken, setKeypairGenerator, signJwt, signJwtHs256, verifyJwtHs256, verifyJwtWithJwks, } from "./clerk-jwt.js";
+export { clearClerkWebhooks, computeSvixSignature, ClerkWebhookVerificationError, emitClerkEvent, eventTypeFor, listClerkWebhooks, registerClerkWebhook, verifyWebhook, } from "./clerk-events.js";
+export { mapMembership, mapOrganization, mapSession, mapUser, pullClerkMemberships, pullClerkOrganizations, pullClerkSessions, pullClerkUsers, pushClerkAction, clerkClientOver, syncClerkFromRemote, performClerkAction, syncClerkFromReal, } from "./clerk-connector.js";
+export { buildClerkMirrorClient, createClerkMirrorServer, clerkMirrorHtml } from "./clerk-mirror-ui.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { performClerkAction as perform, syncClerkFromRemote as refresh } from "./clerk-connector.js";
+export const pack = {
+    vendor: 'clerk',
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+    // state system: perform one entry against Clerk, refresh the root from it. Moved 2026-09-08.
+    protocol: '2',
+    refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
+    stateSystem: { perform, refresh },
+    roundTrip: { method: 'POST', path: '/v1/organizations', body: { name: 'round trip' }, headers: { authorization: 'Bearer sk_test_round_trip' } },
+    // rule 5: an invitation names its organization; when the head adopts Clerk's id for the organization, the kernel resolves it first
+    referenceTrip: { method: 'POST', path: '/v1/organizations/{{id}}/invitations', body: { email_address: 'round@trip.test' }, headers: { authorization: 'Bearer sk_test_round_trip' } },
+    references: [{ type: 'organization_invitation', to: 'organization', key: (f) => (typeof f.organization_id === 'string' ? f.organization_id : undefined), adopt: (_f, vendorId) => ({ organization_id: vendorId }) }],
+    parityOrigin: 'http://twin',
+    shapeParity: 'held',
+    transport: 'rest',
+    archetype: 'crud',
+    // R20 — the vendored clerk-js dist the loader path serves byte-for-byte, through the pack-asset seam.
+    assets: ['client/clerk-js-dist', 'client/clerk.browser.js'],
+    bin: 'world-clerk',
+    resources: ['user', 'session', 'organization', 'organization_membership', 'organization_invitation', 'invitation', 'allowlist_identifier', 'blocklist_identifier', 'jwt_template', 'sign_in_token'],
+    specSource: 'clerk-conformance.ts (inline per-object JSON Schemas from the Clerk Backend API docs)',
+    description: 'Clerk Backend API twin — users/sessions/orgs, real RS256 JWTs + JWKS, svix webhooks, admin UI mirror.',
+    // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31). Every first-party framework client of the same backend API, plus
+    // the whole `@clerk/` scope so an unlisted sibling still detects.
+    adoption: {
+        // Clerk's official Python backend SDK (clerk/clerk-sdk-python), the counterpart of `@clerk/backend`.
+        pypi: ['clerk-backend-api'],
+        sdks: ['@clerk/backend', '@clerk/clerk-sdk-node', '@clerk/nextjs', '@clerk/fastify', '@clerk/express'],
+        scopes: ['@clerk/'],
+        envStems: ['CLERK'],
+    },
+    // Clerk's BROWSER SDK addresses the instance's frontend-API host encoded in the publishable key
+    // (`pk_test_<base64 host$>`), not api.clerk.com — and app CSPs allowlist THAT host. The
+    // dev-instance family is claimed by suffix so a world-issued pk can name a CSP-legal host.
+    // (Peak drive 2026-08-26.)
+    hosts: [{ host: 'api.clerk.com' }, { suffix: '.clerk.accounts.dev' }],
+    // The Clerk frontend SDK calls api.clerk.com; the dev proxy forwards that host to the
+    // twin so calls come back same-origin, and /.well-known/jwks.json is served by the twin.
+    browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.clerk.com' },
+};
+// registered at import: the kernel learns the pack's state system and its references (protocol 2)
+registerPack(pack);

package/dist/test-fixtures/clerk-openapi-operations.SOURCE.md

@@ -0,0 +1,16 @@
+# clerk-openapi-operations.json — provenance
+
+The operation-inventory denominator for `../clerk-spec-census.json`: a scope-filtered subset of
+the vendor's published spec, enumerated by `deriveFromOpenAPI` (`packages/world-tooling/src/derive.ts`).
+
+- **Upstream:** https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/2026-05-12.yml — `clerk-bapi-2026-05-12.yml`.
+- **How it was built:** `bun scripts/spec-census-bootstrap.ts --vendor clerk --from-file <clerk-bapi-2026-05-12.yml> --scope-paths /actor_tokens,/allowlist_identifiers,/beta_features,/blocklist_identifiers,/clients,/domains,/email_addresses,/instance,/invitations,/jwks,/jwt_templates,/oauth_applications,/organization_permissions,/organization_roles,/organizations,/phone_numbers,/proxy_checks,/redirect_urls,/saml_connections,/sessions,/sign_in_tokens,/testing_tokens,/users,/waitlist_entries,/webhooks --apply`
+  over a copy of the upstream file fetched 2026-09-02; operation metadata only (operationId, summary, tags,
+  servers), schemas and response codes dropped. The gate never fetches — refreshing the fixture is
+  `bun scripts/spec-refresh.ts --vendor clerk --from-file <newer spec> --apply` over a newly fetched copy.
+- **Scope (166 of 249 upstream operations):** every operation whose path starts with one of
+  `/actor_tokens`, `/allowlist_identifiers`, `/beta_features`, `/blocklist_identifiers`, `/clients`, `/domains`, `/email_addresses`, `/instance`, `/invitations`, `/jwks`, `/jwt_templates`, `/oauth_applications`, `/organization_permissions`, `/organization_roles`, `/organizations`, `/phone_numbers`, `/proxy_checks`, `/redirect_urls`, `/saml_connections`, `/sessions`, `/sign_in_tokens`, `/testing_tokens`, `/users`, `/waitlist_entries`, `/webhooks`.
+- **Mapping at birth:** 71 operations mapped to done capability ids by the rules in `scripts/spec-census-map.ts`
+  behind the static served-surface probe; 95 left `unmapped`. The census, not this file, records what
+  happened next: hand rulings (a `$ruled` marker, a remap) and the per-operation probe's demotions
+  (`$probeComment`). This fixture changes only through a spec refresh.