@volter/twin-clerk 0.1.0

package/dist/src/clerk-events.js

@@ -0,0 +1,146 @@
+import { nodeBuiltin } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+/** Decode a `whsec_<base64>` signing secret to its raw HMAC key bytes. */
+function secretKeyBytes(secret) {
+    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, timestamp, payload, secret) {
+    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) {
+        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, headers, secret, opts = {}) {
+    const lower = {};
+    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);
+}
+// 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 = [];
+export function registerClerkWebhook(url, secret = 'whsec_dGVzdHNlY3JldHRlc3RzZWNyZXQ=') {
+    if (!registry.some((r) => r.url === url))
+        registry.push({ url, secret });
+}
+export function clearClerkWebhooks() {
+    registry.length = 0;
+}
+export function listClerkWebhooks() {
+    return registry.map((r) => ({ ...r }));
+}
+// twin write operation → Clerk webhook event type (the ones an app's webhooks care about).
+export function eventTypeFor(operation) {
+    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, timestamp, body) { 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 = 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, data, opts = {}) {
+    const type = eventTypeFor(operation);
+    // the World's own endpoints (its tree is the record), then any URL a host registered directly
+    const targets = [...(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 = { type, object: 'event', timestamp, data };
+    const body = JSON.stringify(event);
+    const out = [];
+    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;
+}

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

@@ -0,0 +1,19 @@
+export type ClerkFapiRequest = {
+    method: string;
+    path: string;
+    query?: Record<string, string>;
+    body?: string;
+    cookies?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    /** The browser request's Origin header, when it sent one — becomes a session token's `azp`. */
+    origin?: string;
+};
+export type ClerkFapiResponse = {
+    status: number;
+    body: unknown;
+    setCookies?: string[];
+    html?: string;
+    redirect?: string;
+};
+export declare function handleClerkFapiRequest(req: ClerkFapiRequest): Promise<ClerkFapiResponse>;