@volter/twin-fal 0.1.0

package/src/fal-webhooks.ts

@@ -0,0 +1,234 @@
+// fal.ai webhooks — REAL ed25519-signed delivery + JWKS, written FRESH for this pack (the build
+// spec is explicit: do NOT port replicate-webhooks.ts, which is Standard-Webhooks HMAC — fal uses
+// a completely different, asymmetric scheme).
+//
+// GROUNDED (2026-07-09, read-only) from fal.ai/docs/model-endpoints/webhooks:
+//   - Four request headers on every webhook delivery: `X-Fal-Webhook-Request-Id`,
+//     `X-Fal-Webhook-User-Id`, `X-Fal-Webhook-Timestamp` (unix seconds), `X-Fal-Webhook-Signature`
+//     (HEX-encoded, not base64 — unlike replicate's Standard-Webhooks base64 HMAC).
+//   - Signed message: `${request_id}\n${user_id}\n${timestamp}\n${sha256hex(raw_body)}` — four
+//     newline-joined fields, the last being a SHA-256 hex digest of the raw request body (not the
+//     body itself).
+//   - Public keys are served as a JWKS document at `https://rest.fal.ai/.well-known/jwks.json`
+//     (NOT rest.alpha.fal.ai) — `{keys: [{kty:'OKP', crv:'Ed25519', x: <base64url raw pubkey>}]}`
+//     (RFC 8037 OKP/Ed25519 JWK — modeled per the RFC's standard shape; the doc confirms the
+//     endpoint + field names, not byte-for-byte against a captured live document, so the exact
+//     document shape carries the same doc-UNVERIFIED caveat routine capture-verify would close).
+//   - ±300s (5 minute) timestamp leeway.
+//   - Payload shape: `{request_id, gateway_request_id, status: 'OK'|'ERROR', payload, error?,
+//     payload_error?}`.
+//   - Retry policy: 15s per-attempt timeout, up to 10 retries over a 2h window (`todo` —
+//     `fal.webhooks.retry_policy` — this pack signs/verifies deliveries; it does not implement
+//     the delivery/retry loop itself, the same shape replicate's `webhooks.delivery` todo takes).
+//
+// ENTROPY-BORN, PERSISTED KEYPAIR (the googleoauth-jwt.ts `ensureKeypair` precedent). The ed25519
+// SEED is 32 bytes of REAL entropy, generated ONCE per root and PERSISTED as twin state — the
+// `signing_key` resource FAL_RESOURCE_TYPES already declares, folded on first touch through the
+// kernel action log (so it rides snapshots/hydrate/flush like every other fact this twin holds,
+// and no `node:fs` is on the serve path). Every later read derives the keypair from that stored
+// seed: the seed is wrapped in the fixed PKCS8 DER prefix for an Ed25519 private key (RFC 8410 —
+// `302e020100300506032b657004220420` + 32-byte seed = 48 bytes total) and imported via
+// `crypto.createPrivateKey`, so signing and the served JWKS are always the SAME key and both
+// survive a process restart.
+//
+// This is the runtime contract's ONE NAMED EXCEPTION to R9 (keying material generated once per
+// root and persisted, exactly like googleoauth's RSA pair): same-root byte-identical, cross-root
+// divergent BY CONSTRUCTION. The reads that serve it — `/.well-known/jwks.json` — therefore stay
+// out of this pack's replay, which gate.ts states. The seed is never derived from the root PATH:
+// a key computed from where a world happens to sit is a key the environment owns, and it moves
+// with the directory instead of with the state.
+//
+// `node:crypto` is required LAZILY (server-only), same convention as replicate-webhooks.ts, so
+// this module stays browser-bundle safe.
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin } from '@volter/world-core';
+
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+const ED25519_PKCS8_PREFIX_HEX = '302e020100300506032b657004220420';
+// The fixed 12-byte ASN.1 header every Ed25519 SPKI (public-key) DER encoding starts with (RFC
+// 8410) — followed by exactly 32 raw public-key bytes (44 bytes total). Slicing it off recovers
+// the raw key JWKS wants in its `x` field.
+const ED25519_SPKI_HEADER_LEN = 12;
+
+export type FalWebhookEvent = {
+  request_id: string;
+  gateway_request_id: string;
+  status: 'OK' | 'ERROR';
+  payload: unknown;
+  error?: string;
+  payload_error?: string;
+};
+
+export class FalWebhookVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FalWebhookVerificationError';
+  }
+}
+
+type FalKeyPair = { privateKey: import('node:crypto').KeyObject; publicKey: import('node:crypto').KeyObject };
+
+const SERVICE = 'fal';
+// The seed is stored as the pack's declared `signing_key` resource — the SAME substrate every
+// other fal fact uses, no parallel side-store (D1). Subject ids are type-prefixed exactly like
+// fal-twin.ts's `kid()`; `_`-prefixed fields are twin-internal and never served (fal-twin.ts's
+// `view()` strips them, and no route projects this type at all).
+const SIGNING_KEY_TYPE = 'signing_key';
+const SIGNING_KEY_SUBJECT = 'signing_key:webhook';
+const SEED_BYTES = 32; // ed25519's seed length, exactly
+
+function storedSeed(resources: readonly { type: string; id: string }[]): string | undefined {
+  const row = resources.find((r) => r.type === SIGNING_KEY_TYPE && r.id === SIGNING_KEY_SUBJECT) as Record<string, unknown> | undefined;
+  const seed = row?.['_seed'];
+  return typeof seed === 'string' && seed.length > 0 ? seed : undefined;
+}
+
+/**
+ * The base64 ed25519 SEED for `root` — generated with real entropy on FIRST use and persisted,
+ * stable forever after (across calls AND across processes). The decide-and-append runs inside the
+ * kernel's own action lock (`applyTwinWriteAtomic`), so two processes racing a first use agree on
+ * ONE seed rather than each signing with a seed the other's state does not hold.
+ */
+async function ensureFalSigningSeed(root?: string): Promise<string> {
+  const fast = storedSeed(projectResources(SERVICE, root));
+  if (fast) return fast;
+  const { value } = await applyTwinWriteAtomic<string>(SERVICE, (resources) => {
+    const existing = storedSeed(resources);
+    if (existing) return { kind: 'skip', value: existing };
+    const seed = nodeCrypto().randomBytes(SEED_BYTES).toString('base64');
+    return {
+      kind: 'write',
+      value: seed,
+      write: {
+        operation: 'signing_key.create',
+        subjectType: SIGNING_KEY_TYPE,
+        subjectId: SIGNING_KEY_SUBJECT,
+        fields: { _seed: seed },
+        actor: { kind: 'system' },
+      },
+    };
+  }, root);
+  return value;
+}
+
+/** The per-root ed25519 keypair, derived from the PERSISTED seed. */
+async function falSigningKey(root?: string): Promise<FalKeyPair> {
+  const crypto = nodeCrypto();
+  const seed = Buffer.from(await ensureFalSigningSeed(root), 'base64');
+  if (seed.length !== SEED_BYTES) throw new Error(`fal signing key: persisted seed is ${seed.length} bytes, expected ${SEED_BYTES}`);
+  const der = Buffer.concat([Buffer.from(ED25519_PKCS8_PREFIX_HEX, 'hex'), seed]);
+  const privateKey = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  const publicKey = crypto.createPublicKey(privateKey);
+  return { privateKey, publicKey };
+}
+
+function rawPublicKeyBytes(publicKey: import('node:crypto').KeyObject): Buffer {
+  const spki = publicKey.export({ format: 'der', type: 'spki' }) as Buffer;
+  return spki.subarray(ED25519_SPKI_HEADER_LEN);
+}
+
+/** The JWKS document served at GET /.well-known/jwks.json — stable per root, across processes. */
+export async function falJwks(root?: string): Promise<{ keys: Array<{ kty: 'OKP'; crv: 'Ed25519'; x: string }> }> {
+  const { publicKey } = await falSigningKey(root);
+  const x = rawPublicKeyBytes(publicKey).toString('base64url');
+  return { keys: [{ kty: 'OKP', crv: 'Ed25519', x }] };
+}
+
+/** Reconstruct a public key from a served JWKS entry — used to verify a signature using ONLY
+ *  what the JWKS *endpoint* returned (not a fresh local re-derivation from `root`), so a
+ *  signature-verification capability that routes through this has real teeth against a
+ *  sabotaged handler (build spec §3: "through handler → teeth"). */
+export function falWebhookPublicKeyFromJwk(jwk: { x: string }): import('node:crypto').KeyObject {
+  return nodeCrypto().createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' });
+}
+
+/** Build the exact signed message fal signs: id \n user \n ts \n sha256hex(body). */
+function signingMessage(requestId: string, userId: string, timestamp: number, rawBody: string): string {
+  const bodyHash = nodeCrypto().createHash('sha256').update(rawBody, 'utf8').digest('hex');
+  return `${requestId}\n${userId}\n${timestamp}\n${bodyHash}`;
+}
+
+/** Compute the hex ed25519 signature for a webhook delivery (real crypto, not a stub — a real
+ *  Ed25519/JWKS verifier accepts this unchanged). */
+export async function computeFalWebhookSignature(requestId: string, userId: string, timestamp: number, rawBody: string, root?: string): Promise<string> {
+  const { privateKey } = await falSigningKey(root);
+  const message = signingMessage(requestId, userId, timestamp, rawBody);
+  // Node's `crypto.sign(algorithm, data, key)` takes `null` for the one-shot Ed25519 signing
+  // algorithm (Ed25519 has no separate digest step — verified against Node's own crypto docs).
+  return nodeCrypto().sign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
+}
+
+function verifyRaw(rawBody: string, headers: Record<string, string>, publicKey: import('node:crypto').KeyObject, opts: { tolerance?: number; now?: number }): FalWebhookEvent {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+  const requestId = lower['x-fal-webhook-request-id'];
+  const userId = lower['x-fal-webhook-user-id'];
+  const ts = Number(lower['x-fal-webhook-timestamp']);
+  const sigHex = lower['x-fal-webhook-signature'];
+  if (!requestId || !userId || !sigHex || !Number.isFinite(ts)) {
+    throw new FalWebhookVerificationError('Missing required webhook headers (X-Fal-Webhook-Request-Id / X-Fal-Webhook-User-Id / X-Fal-Webhook-Timestamp / X-Fal-Webhook-Signature).');
+  }
+  const tolerance = opts.tolerance ?? 300;
+  const now = opts.now ?? Math.floor(Date.now() / 1000);
+  if (Math.abs(now - ts) > tolerance) {
+    throw new FalWebhookVerificationError(`Webhook timestamp outside the ${tolerance}s tolerance.`);
+  }
+  const message = signingMessage(requestId, userId, ts, rawBody);
+  let sigBuf: Buffer;
+  try {
+    sigBuf = Buffer.from(sigHex, 'hex');
+  } catch {
+    throw new FalWebhookVerificationError('Malformed hex signature.');
+  }
+  const ok = sigBuf.length > 0 && nodeCrypto().verify(null, Buffer.from(message, 'utf8'), publicKey, sigBuf);
+  if (!ok) throw new FalWebhookVerificationError('Signature verification failed.');
+  return JSON.parse(rawBody) as FalWebhookEvent;
+}
+
+/** Verify a webhook delivery against a caller-provided public key (e.g. one recovered from a
+ *  served JWKS document via `falWebhookPublicKeyFromJwk`). Throws `FalWebhookVerificationError`
+ *  on any missing header, stale timestamp, or signature mismatch. */
+export function verifyFalWebhookSignatureWithKey(rawBody: string, headers: Record<string, string>, publicKey: import('node:crypto').KeyObject, opts: { tolerance?: number; now?: number } = {}): FalWebhookEvent {
+  return verifyRaw(rawBody, headers, publicKey, opts);
+}
+
+/** Verify a webhook delivery against the root's persisted keypair directly (pure local crypto —
+ *  does not touch the twin handler/JWKS route at all). */
+export async function verifyFalWebhook(rawBody: string, headers: Record<string, string>, root?: string, opts: { tolerance?: number; now?: number } = {}): Promise<FalWebhookEvent> {
+  const { publicKey } = await falSigningKey(root);
+  return verifyRaw(rawBody, headers, publicKey, opts);
+}
+
+/**
+ * Build a SIGNED webhook delivery for a completed (or failed) request: the fal webhook payload +
+ * the real ed25519-signed X-Fal-Webhook-* headers. Deterministic + offline.
+ */
+export async function buildSignedFalWebhook(args: {
+  requestId: string;
+  userId?: string;
+  gatewayRequestId?: string;
+  status: 'OK' | 'ERROR';
+  payload?: unknown;
+  error?: string;
+  occurredAt: string;
+  root?: string;
+}): Promise<{ headers: Record<string, string>; body: string; event: FalWebhookEvent }> {
+  const userId = args.userId ?? 'twin-user';
+  const ts = Math.floor(Date.parse(args.occurredAt) / 1000);
+  const event: FalWebhookEvent =
+    args.status === 'OK'
+      ? { request_id: args.requestId, gateway_request_id: args.gatewayRequestId ?? args.requestId, status: 'OK', payload: args.payload ?? null }
+      : { request_id: args.requestId, gateway_request_id: args.gatewayRequestId ?? args.requestId, status: 'ERROR', payload: null, error: args.error ?? 'unknown error' };
+  const body = JSON.stringify(event);
+  const headers = {
+    'x-fal-webhook-request-id': args.requestId,
+    'x-fal-webhook-user-id': userId,
+    'x-fal-webhook-timestamp': String(ts),
+    'x-fal-webhook-signature': await computeFalWebhookSignature(args.requestId, userId, ts, body, args.root),
+  };
+  return { headers, body, event };
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+// @volter/twin-fal — the fal.ai (fal.run / queue.fal.run) model-inference queue-lifecycle twin,
+// built on the shared @volter/world-core kernel. REST transport over the queue.fal.run / fal.run /
+// rest.fal.ai host-split shapes; state lives entirely in the kernel action log (no side-store).
+// Queue lifecycle (submit → status polls with logs → response → cancel), the synchronous
+// `fal.run` variant, host-split surface routing (incl. the real fal-js `x-fal-target-url` proxy
+// protocol), and ed25519-signed webhooks + JWKS.
+//
+// THE GENERATIVE STUB: a request's output is a clearly-labeled DETERMINISTIC stub
+// (`[twin-stub:fal:…]`) derived from hash(model_id, input), while the protocol envelope (status
+// machine, queue_position, logs, urls, metrics) is faithful. The stub is also the ONE thing a
+// scenario handler may replace: a world
+// dir's handlers/fal.json scripts what a submitted request settles to, run by the ONE kernel
+// engine through this pack's adapter (fal-scenario.ts) and inspectable at GET /twin/scenario.
+// (Conformance/capability tooling lives in @volter/world-tooling, a dev dependency — NOT shipped.)
+export {
+  handleFalTwinRequest,
+  routeFalSurface,
+  falTwinSnapshot,
+  FAL_RESOURCE_TYPES,
+} from './fal-twin.ts';
+export type {
+  FalRequest,
+  FalResponse,
+  FalResourceType,
+  FalSurface,
+  FalTwinSnapshot,
+} from './fal-twin.ts';
+export { createFalTwinFetch, createFalTwinServer, type FalTwinFetchOptions } from './fal-server.ts';
+// The pack's HALF of the scenario system (the grammar is the kernel's ONE engine). Exported so a
+// test can build an engine and `use()` handlers in-process, and so the fetch adapter can mount it.
+export { canonicalInputText, createFalScenarioEngine, falScenarioAdapter, loadFalScenarioDocument } from './fal-scenario.ts';
+export type { FalScenarioEngine, FalScenarioRequest, FalScenarioRespond } from './fal-scenario.ts';
+export {
+  mapQueueRequest,
+  pullFalRequests,
+  syncFalFromReal,
+} from './fal-connector.ts';
+export type { FalLikeClient, FalRequestHandle, FalRealQueueStatus, FalRealQueueLog, FalBudgetedOptions } from './fal-connector.ts';
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION (window/ceiling/per-method weights) plus `guardFalClient`, the choke point the
+// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `FalBudgetError` by type; there is deliberately no export
+// that disables the guard.
+export {
+  FAL_BUDGETED_METHODS,
+  FAL_BUDGET_CEILING,
+  FAL_BUDGET_MAX_RETRY_AFTER_S,
+  FAL_BUDGET_WINDOW_MS,
+  FAL_CALL_WEIGHTS,
+  FAL_RATE_BUDGET,
+  FalBudget,
+  FalBudgetError,
+  falBudgetPath,
+  falCallWeight,
+  falClientBudget,
+  guardFalClient,
+} from './fal-budget.ts';
+export type { FalBudgetErrorKind, FalBudgetOptions, FalBudgetReservation, FalBudgetSnapshot } from './fal-budget.ts';
+export {
+  falJwks,
+  falWebhookPublicKeyFromJwk,
+  computeFalWebhookSignature,
+  verifyFalWebhook,
+  verifyFalWebhookSignatureWithKey,
+  buildSignedFalWebhook,
+  FalWebhookVerificationError,
+} from './fal-webhooks.ts';
+export type { FalWebhookEvent } from './fal-webhooks.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import type { TwinPack } from '@volter/world-core';
+import { FAL_RATE_BUDGET as RATE_BUDGET } from './fal-budget.ts';
+export const pack: TwinPack = {
+  // The SAME object fal-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  vendor: 'fal',
+  transport: 'rest',
+  archetype: 'generative',
+  bin: 'world-fal',
+  resources: ['request', 'signing_key'],
+  specSource: 'fal-conformance.ts (self-referential endpoint/resource inventory) — grounded read-only against fal.ai/docs/model-endpoints/{queue,webhooks} and the fal-js client source (github.com/fal-ai/fal-js) fetched during the build; see spec-sources.json.',
+  description: 'fal.ai model-inference queue-lifecycle twin — submit/status/response/cancel on queue.fal.run, the synchronous fal.run variant, host-split surface routing (incl. the real fal-js x-fal-target-url proxy protocol), and ed25519-signed webhooks + JWKS. Request output is a deterministic [twin-stub] value (no GPU/model weights) with a faithful protocol envelope. Kernel-backed.',
+  browserRouting: { apiPathPrefix: '/', loaderHost: 'https://queue.fal.run' },
+  // INTERCEPTION RULING — hostsNone, the pack's own home for it: host-split surface (fal.run /
+  // queue.fal.run) with no injector entry grounded yet — worlds wire the twin via the client's
+  // explicit endpoint config; a visible gap until its hosts are grounded here.
+  hostsNone:
+    "host-split surface (fal.run / queue.fal.run) with no injector entry grounded yet — worlds wire the twin via the client's explicit endpoint config; a visible gap until its hosts are grounded here",
+  // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  adoption: {
+    // Both official fal.ai distributions: the API client and the serverless framework.
+    pypi: ['fal-client', 'fal'],
+    sdks: ['@fal-ai/client', '@fal-ai/serverless-client'],
+    scopes: ['@fal-ai/'],
+    envStems: ['FAL'],
+  },
+};