@volter/twin-veriff 0.1.0

package/src/veriff-connector.ts

@@ -0,0 +1,406 @@
+// Veriff CONNECTOR — the live-vendor pull/push path that gives the Veriff twin the full
+// "git for SaaS" lifecycle.
+//
+// PULL  (real → twin):  fetch real Veriff decisions / attempts / media metadata, map them to
+//                       SyncResource[], fold into the event log via observeResources (the kernel dedupes —
+//                       a re-pull of identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action, call the real Veriff API and confirmAction
+//                       on success.
+//
+// ── PULL IS HANDLE-DRIVEN, AND THAT IS THE VENDOR'S DOING ───────────────────────────────────
+// Veriff publishes NO account-wide list endpoint: there is no `GET /v1/sessions`, and every read in
+// the reference is scoped to a session/attempt/media id you already hold. So `syncVeriffFromReal`
+// takes the session ids to pull, exactly as a real integration does — the reference consumer (dub)
+// stores `veriffSessionId` on its own partner row and polls
+// `GET /v1/sessions/{id}/decision` from there. An enumeration-driven pull is not "not built yet";
+// it is not offerable against this API, and pull-audit.json records that rather than filing a gap
+// for surface the vendor does not expose.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO
+// Veriff credential and import NO network client. Offline/tests pass a fake executor; live runs pass
+// `liveVeriffExecute(apiKey, sharedSecret)`. Same code path either way.
+import { assertBudgetGuardIntact, confirmAction, deployableEntries, observeResources, ownFields, twinResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { VeriffBudget, VeriffBudgetError, veriffCallWeight, type VeriffBudgetOptions } from './veriff-budget.ts';
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, veriffSignature } from './veriff-signature.ts';
+
+const SERVICE = 'veriff';
+
+/** Subject types that are twin-internal and never pushed to real Veriff. `delivery` is the twin's
+ *  own outbound-webhook log; `attempt` and `media` are vendor-authored — a client can read them
+ *  but never create them, so a local action on one has no real call to become. */
+const INTERNAL_SUBJECT_TYPES = new Set(['delivery', 'attempt', 'media']);
+
+/**
+ * The injected real-Veriff boundary. `execute` issues ONE Veriff API call and returns the parsed
+ * JSON body (the flat `{ status, ... }` envelope). A real client (a raw fetch wrapper — which is
+ * what an integrator writes, since Veriff ships no server SDK) is structurally assignable; tests
+ * pass a fake.
+ */
+export type VeriffExecute = (
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<{ status?: string; code?: string; message?: string; [k: string]: unknown }>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveVeriffOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: VeriffBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: VeriffBudgetOptions;
+  /** The API base. Veriff's URL is ACCOUNT-SPECIFIC (read it off the Customer Portal); the two
+   *  hosts that appear in official material are `stationapi.veriff.com` (the reference consumer's,
+   *  and the media samples') and `api.veriff.me` (`@veriff/js-sdk`'s compiled default). */
+  base?: string;
+};
+
+/**
+ * A live executor against the real Veriff Public API v1.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live Veriff request, and therefore the one place the
+ * rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request
+ * goes out (`checkBudget`, which THROWS `VeriffBudgetError` instead of returning when the ceiling or
+ * a cooldown says stop) and the response is fed back (`recordCall`) so a 429 becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching Veriff. There is deliberately no
+ * OPTION to disable the guard, and no value a caller can pass for `budget` that yields an unguarded
+ * client. That is NOT immunity from a caller who WANTS one: a fresh `budgetOptions.path` per
+ * construction, or an injected clock, restores the allowance, because the seam tests need cannot be
+ * denied to a determined caller in the same process. The kernel header states that limit and this
+ * does not upgrade it.
+ *
+ * It also OWNS THE SIGNING, which is the other reason raw calls must not bypass it: Veriff's payload
+ * rule is asymmetric (POST/PATCH sign the body, GET/DELETE sign the resource id in the path), and a
+ * hand-rolled call that signs the wrong half fails authentication at the vendor for reasons that
+ * look nothing like a signing bug.
+ */
+export function liveVeriffExecute(
+  apiKey: string,
+  sharedSecret: string,
+  opts: LiveVeriffOptions = {},
+): VeriffExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const base = opts.base ?? 'https://stationapi.veriff.com';
+  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+  // UNMODIFIED VeriffBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
+  // Proxy that traps it are all refused, because all three are one-liners that would otherwise hand
+  // back a client with no ceiling at all. The default ledger is keyed by a hash of THIS key —
+  // Veriff limits per integration, so a cwd-scoped ledger would hand the same key a fresh allowance
+  // per checkout/worktree/CI leg.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, VeriffBudget, 'liveVeriffExecute')
+    : new VeriffBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    const serialized = method !== 'GET' && method !== 'DELETE' && body !== undefined ? JSON.stringify(body) : undefined;
+    const headers: Record<string, string> = { [AUTH_CLIENT_HEADER]: apiKey };
+    // POST /sessions is the ONE endpoint the vendor exempts from signing.
+    const isCreateSession = method === 'POST' && path === '/sessions';
+    if (!isCreateSession) {
+      headers[HMAC_SIGNATURE_HEADER] = veriffSignature(signaturePayloadFor(method, path, serialized), sharedSecret);
+    }
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (serialized !== undefined) {
+      headers['content-type'] = 'application/json';
+      init.body = serialized;
+    }
+    const weight = veriffCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${base}/v1${path}`, init);
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const parsed = (await res.json()) as { status?: string };
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted first
+    // either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Veriff ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof VeriffBudgetError) || !res.ok) throw error;
+    }
+    return parsed;
+  };
+}
+
+/**
+ * Which bytes `X-HMAC-SIGNATURE` must cover for this call. The vendor's per-endpoint docs refine
+ * "GET/DELETE sign the session ID" into "sign the RESOURCE id in the path" — `/attempts/{id}/media`
+ * signs the attempt id, `/media/{id}` signs the media id — so this reads the id positionally rather
+ * than assuming a session.
+ */
+export function signaturePayloadFor(method: string, path: string, serializedBody?: string): string {
+  if (method !== 'GET' && method !== 'DELETE') return serializedBody ?? '';
+  const segments = path.replace(/^\/+/, '').split('/');
+  return segments[1] ?? '';
+}
+
+// ── mappers (pure — no client, no network) ──────────────────────────────────
+// Every mapper renames the vendor's `id` to a type-specific key, because the kernel's projection
+// RESERVES `type`, `id` and `updatedAt` as META and silently DROPS a resource field with one of
+// those names. Field names match what veriff-twin.ts stores, so a pulled session and a locally
+// created one project identically.
+
+/** Map a decision document → a `session` SyncResource. */
+export function mapSessionDecision(v: Record<string, any>): SyncResource {
+  return {
+    type: 'session',
+    id: String(v.id),
+    fields: {
+      sessionId: v.id,
+      status: v.status,
+      decisionCode: v.code ?? null,
+      decisionAttemptId: v.attemptId ?? null,
+      decisionTime: v.decisionTime ?? null,
+      acceptanceTime: v.acceptanceTime ?? null,
+      submissionTime: v.submissionTime ?? null,
+      decisionReason: v.reason ?? null,
+      decisionReasonCode: v.reasonCode ?? null,
+      decidedPerson: v.person ?? null,
+      decidedDocument: v.document ?? null,
+      riskLabels: v.riskLabels ?? null,
+      vendorData: v.vendorData ?? null,
+      endUserId: v.endUserId ?? null,
+    },
+  };
+}
+
+/** Map one attempt row (`GET /v1/sessions/{id}/attempts` → `verifications[]`) → a SyncResource. */
+export function mapSessionAttempt(sessionId: string, a: Record<string, any>): SyncResource {
+  return {
+    type: 'attempt',
+    id: String(a.id),
+    fields: { attemptId: a.id, sessionId, status: a.status, userDefinedData: a.userDefinedData ?? [], createdTime: a.createdTime ?? null },
+  };
+}
+
+/** Map one media object → a SyncResource. `kind` separates the images/videos/nfcDocuments buckets
+ *  the media endpoints split their response into. */
+export function mapSessionMedia(sessionId: string, m: Record<string, any>, kind: 'image' | 'video' | 'nfc'): SyncResource {
+  return {
+    type: 'media',
+    id: String(m.id),
+    fields: {
+      mediaId: m.id,
+      sessionId,
+      attemptId: m.attemptId ?? null,
+      kind,
+      name: m.name ?? null,
+      context: m.context ?? null,
+      timestamp: m.timestamp ?? null,
+      size: m.size ?? null,
+      mimetype: m.mimetype ?? null,
+      url: m.url ?? null,
+    },
+  };
+}
+
+// A pinned occurredAt keeps a pull deterministic/idempotent under test.
+const PULL_AT = '2026-08-01T00:00:00.000Z';
+
+/** Fetch + map decisions for the given session ids (no fold) — shared by pull + syncFromReal. */
+async function collectDecisions(execute: VeriffExecute, sessionIds: readonly string[]): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  for (const id of sessionIds) {
+    const res = await execute('GET', `/sessions/${id}/decision`);
+    const v = res.verification as Record<string, any> | null | undefined;
+    // `verification: null` is the documented "no decision yet" answer — not an error, and not
+    // something to fold as an empty session either.
+    if (v && v.id) out.push(mapSessionDecision(v));
+  }
+  return out;
+}
+
+async function collectAttempts(execute: VeriffExecute, sessionIds: readonly string[]): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  for (const id of sessionIds) {
+    const res = await execute('GET', `/sessions/${id}/attempts`);
+    const rows = Array.isArray(res.verifications) ? (res.verifications as Record<string, any>[]) : [];
+    for (const a of rows) if (a?.id) out.push(mapSessionAttempt(id, a));
+  }
+  return out;
+}
+
+async function collectMedia(execute: VeriffExecute, sessionIds: readonly string[]): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  for (const id of sessionIds) {
+    const res = await execute('GET', `/sessions/${id}/media`);
+    for (const [key, kind] of [['images', 'image'], ['videos', 'video'], ['nfcDocuments', 'nfc']] as const) {
+      const rows = Array.isArray(res[key]) ? (res[key] as Record<string, any>[]) : [];
+      for (const m of rows) if (m?.id) out.push(mapSessionMedia(id, m, kind));
+    }
+  }
+  return out;
+}
+
+/** PULL decisions for known session ids into the twin's observed log (idempotent). */
+export async function pullVeriffDecisions(execute: VeriffExecute, sessionIds: readonly string[], root?: string, occurredAt = PULL_AT): Promise<number> {
+  const resources = await collectDecisions(execute, sessionIds);
+  observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return resources.length;
+}
+
+/** PULL the attempt history for known session ids (idempotent). */
+export async function pullVeriffAttempts(execute: VeriffExecute, sessionIds: readonly string[], root?: string, occurredAt = PULL_AT): Promise<number> {
+  const resources = await collectAttempts(execute, sessionIds);
+  observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return resources.length;
+}
+
+/** PULL media METADATA for known session ids (idempotent). The bytes are not pulled — see the
+ *  `veriff.media.pull_bytes` todo. */
+export async function pullVeriffMedia(execute: VeriffExecute, sessionIds: readonly string[], root?: string, occurredAt = PULL_AT): Promise<number> {
+  const resources = await collectMedia(execute, sessionIds);
+  observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return resources.length;
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull from real Veriff (decisions + attempts + media
+ * metadata) and fold into the twin in ONE observation, returning the standard
+ * `{ observed, deltasAppended }` result. Idempotent — a re-pull of identical state appends nothing
+ * (deltasAppended drops to 0).
+ *
+ * `sessionIds` is REQUIRED in substance (an empty list pulls nothing and says so by returning
+ * zeroes) because Veriff exposes no account-wide enumeration — see the module header.
+ */
+export async function syncVeriffFromReal(
+  execute: VeriffExecute,
+  opts: { sessionIds?: readonly string[]; root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const occurredAt = opts.occurredAt ?? PULL_AT;
+  const sessionIds = opts.sessionIds ?? [];
+  const decisions = await collectDecisions(execute, sessionIds);
+  const attempts = await collectAttempts(execute, sessionIds);
+  const media = await collectMedia(execute, sessionIds);
+  const resources = [...decisions, ...attempts, ...media];
+  const result = observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return { observed: resources.length, deltasAppended: result.appended };
+}
+
+/** Translate one pending local action into the real Veriff API call it represents. Returns `null`
+ *  for anything the vendor gives a client no way to write. */
+export function veriffRequestForAction(action: TwinAction): { method: 'GET' | 'POST' | 'PATCH' | 'DELETE'; path: string; body?: Record<string, unknown> } | null {
+  if (INTERNAL_SUBJECT_TYPES.has(action.subject.type)) return null;
+  if (action.subject.type !== 'session') return null;
+  const fields = (action.fields ?? {}) as Record<string, unknown>;
+  const status = fields.status;
+  // A session whose local action only moved it to `submitted` is a PATCH, not a re-create.
+  if (status === 'submitted') return { method: 'PATCH', path: `/sessions/${String(fields.sessionId ?? action.subject.id)}`, body: { verification: { status: 'submitted' } } };
+  if (fields.deleted === true) return { method: 'DELETE', path: `/sessions/${String(fields.sessionId ?? action.subject.id)}` };
+  if (status === 'created') {
+    const verification: Record<string, unknown> = {};
+    if (fields.vendorData != null) verification.vendorData = fields.vendorData;
+    if (fields.endUserId != null) verification.endUserId = fields.endUserId;
+    if (fields.callback != null) verification.callback = fields.callback;
+    if (fields.hintPerson != null) verification.person = fields.hintPerson;
+    if (fields.hintDocument != null) verification.document = fields.hintDocument;
+    return { method: 'POST', path: '/sessions', body: { verification } };
+  }
+  // A decision status is authored by VERIFF, never by a client — there is no endpoint to push it to.
+  return null;
+}
+
+/**
+ * PUSH every pending local action to the real account; confirm each on success.
+ *
+ * HONEST LIMIT: local ids are not remapped. A session created AND submitted locally produces two
+ * pending actions — the create pushes as `POST /sessions` and the real account mints its OWN id,
+ * while the submit pushes as `PATCH /sessions/{LOCAL id}`, which that account has never seen. So a
+ * create converges; a create-then-submit pair does not, until `veriff.connector.push_id_remapping`
+ * is built. Saying so beats a push that silently half-lands.
+ */
+export async function pushPendingVeriffActions(execute: VeriffExecute, root?: string, occurredAt = PULL_AT): Promise<number> {
+  const pending = deployableEntries(SERVICE, root);
+  let pushed = 0;
+  for (const action of pending) {
+    const req = veriffRequestForAction(action);
+    if (!req) continue;
+    const res = await execute(req.method, req.path, req.body);
+    // Veriff signals success with status:"success" and failure with status:"fail". Confirm ONLY on
+    // an explicit success — a `fail` envelope (which still parses as JSON and still has a `status`)
+    // must NOT confirm the local action.
+    if (res.status === 'success') {
+      confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: (action.fields ?? {}) as Record<string, unknown>, occurredAt, ...(root !== undefined ? { root } : {}) });
+      pushed += 1;
+    }
+  }
+  return pushed;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+
+/** A `VeriffExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function veriffExecuteOver(execute: RemoteExecute): VeriffExecute {
+  return async (method, path, body) => {
+    const res = await execute({
+      method,
+      path: path.startsWith('/v1/') ? path : `/v1${path}`,
+      headers: { accept: 'application/json', 'content-type': 'application/json', 'x-auth-client': 'twin' },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    try { return JSON.parse(res.body || '{}'); } catch { return { status: res.status < 300 ? 'success' : 'fail' }; }
+  };
+}
+
+/**
+ * The refresh adapter.
+ *
+ * Veriff exposes NO account-wide enumeration — a session exists because a client created it and is
+ * then addressed by the id that client was handed. So "refresh this world from the real vendor"
+ * means re-reading the sessions the WORLD already holds: its decisions, its attempt history, and
+ * its media metadata. This is not a gap standing in for a list endpoint; it is the shape of the
+ * vendor, and the module header says so.
+ */
+export async function syncVeriffFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string; sessionIds?: readonly string[] } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const held: string[] = [];
+  for (const resource of twinResources(SERVICE, opts.root)) {
+    if (resource.type !== 'session') continue;
+    const fields = ownFields(resource);
+    const sessionId = typeof fields.sessionId === 'string' ? fields.sessionId : resource.id;
+    if (sessionId) held.push(sessionId);
+  }
+  return syncVeriffFromReal(veriffExecuteOver(execute), {
+    sessionIds: [...new Set([...held, ...(opts.sessionIds ?? [])])].sort(),
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  });
+}
+
+/**
+ * The perform adapter.
+ *
+ * This is what closes the pack's standing `push_id_remapping` gap. Under protocol 1 a local session
+ * created AND submitted produced two pending actions: the create pushed as `POST /sessions` and the
+ * real account minted its OWN id, while the submit pushed as `PATCH /sessions/{LOCAL id}` — an id
+ * that account had never seen. Protocol 2's confirmation carries `vendorSubjectId`, so the kernel
+ * records what Veriff called the session and the submit addresses the REAL id.
+ */
+export async function performVeriffAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  const client = veriffExecuteOver(execute);
+  const req = veriffRequestForAction(action);
+  if (!req) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    return { externalId: action.subject.id, data: { performed: false, reason: `${op} is authored by Veriff, never by a client — there is no endpoint to push it to` } };
+  }
+  // Address the session by whatever the account already called it, when the kernel knows.
+  const resolved = ctx.resolve(action.subject.type, action.subject.id);
+  const path = req.path.replace(/\/sessions\/[^/]+/, `/sessions/${encodeURIComponent(resolved)}`);
+  const res = await client(req.method, path, req.body);
+  // Veriff signals success with status:"success" and failure with status:"fail". A `fail` envelope
+  // still parses as JSON and still has a `status`, so anything but an explicit success is a throw.
+  if (res.status !== 'success') {
+    throw new Error(`veriff ${req.method} ${path} refused: ${String(res.status ?? 'no status')} ${String(res.message ?? '')}`.trim());
+  }
+  const verification = (res.verification ?? {}) as Record<string, unknown>;
+  const externalId = typeof verification.id === 'string' ? verification.id : resolved;
+  return { externalId, data: res as Record<string, unknown> };
+}

package/src/veriff-events.ts

@@ -0,0 +1,117 @@
+// Veriff WEBHOOK emission + verification — the twin's outbound half of the integration.
+//
+// Veriff pushes two webhook families to the URLs configured on the account (or per-session via
+// `verification.callback`). Both are signed with the SAME scheme (veriff-signature.ts):
+//
+//   • DECISION webhook — sent once a session reaches a terminal decision. Body is the same
+//     `{ status, verification: {...} }` document `GET /v1/sessions/{id}/decision` serves.
+//   • EVENT webhook — sent as the end user moves through the hosted flow:
+//     `{ id, attemptId, feature, code, action, vendorData }` with `action` ∈ started | submitted.
+//
+// The real consumer distinguishes them exactly the way this twin emits them: dub's
+// `app/api/veriff/webhook/route.ts` routes on `"verification" in body` — decision payloads carry
+// it, event payloads do not.
+//
+// DELIVERY IS INJECTED. This module never opens a socket: the caller passes a
+// `VeriffWebhookDelivery` (a real `fetch` POST in production, a recording fake in tests), so every
+// verify in this pack proves the signing and payload shape OFFLINE. The twin's own handler records
+// each delivery as a `delivery` subject so a test can read back what was sent.
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, veriffSignature, verifyVeriffSignature } from './veriff-signature.ts';
+
+/** What a caller supplies to actually put a delivery on the wire. */
+export type VeriffWebhookDelivery = (url: string, body: string, headers: Record<string, string>) => Promise<void> | void;
+
+/** The `action` values Veriff's EVENT webhook carries. */
+export const VERIFF_EVENT_ACTIONS = ['started', 'submitted'] as const;
+export type VeriffEventAction = (typeof VERIFF_EVENT_ACTIONS)[number];
+
+/** An event-webhook payload (no `verification` key — that is what makes it an event, not a decision). */
+export type VeriffEventPayload = {
+  id: string;
+  attemptId: string;
+  feature: string;
+  code: number;
+  action: VeriffEventAction;
+  vendorData: string | null;
+};
+
+/** A decision-webhook payload — the same document the decision endpoint serves. */
+export type VeriffDecisionPayload = {
+  status: 'success';
+  verification: Record<string, unknown>;
+};
+
+export type VeriffWebhookPayload = VeriffEventPayload | VeriffDecisionPayload;
+
+/**
+ * Build the exact headers + body bytes for one delivery.
+ *
+ * The body is serialized ONCE and the signature is taken over THOSE bytes — signing a
+ * re-serialized copy is the classic way a webhook signature stops verifying against the payload
+ * the receiver actually got (key order alone is enough to break it).
+ */
+export function buildSignedDelivery(
+  payload: VeriffWebhookPayload,
+  opts: { apiKey: string; sharedSecret: string },
+): { body: string; headers: Record<string, string> } {
+  const body = JSON.stringify(payload);
+  return {
+    body,
+    headers: {
+      'content-type': 'application/json',
+      [AUTH_CLIENT_HEADER]: opts.apiKey,
+      [HMAC_SIGNATURE_HEADER]: veriffSignature(body, opts.sharedSecret),
+    },
+  };
+}
+
+/** Thrown when an inbound delivery fails verification. `reason` says which check refused. */
+export class VeriffWebhookVerificationError extends Error {
+  readonly reason: 'missing-signature' | 'bad-signature' | 'missing-auth-client' | 'bad-auth-client';
+  constructor(reason: VeriffWebhookVerificationError['reason'], message: string) {
+    super(message);
+    this.name = 'VeriffWebhookVerificationError';
+    this.reason = reason;
+  }
+}
+
+/**
+ * Verify a delivery the way a real receiver does — BOTH checks dub performs, in dub's order:
+ * the `x-auth-client` header must equal the account's API key, then `x-hmac-signature` must be the
+ * HMAC of the RAW body. Returns the parsed payload; throws `VeriffWebhookVerificationError`
+ * otherwise. Header lookup is case-insensitive because HTTP header names are.
+ */
+export function verifyWebhook(
+  rawBody: string,
+  headers: Record<string, string | undefined>,
+  opts: { apiKey: string; sharedSecret: string },
+): VeriffWebhookPayload {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) if (v !== undefined) lower[k.toLowerCase()] = v;
+
+  const authClient = lower[AUTH_CLIENT_HEADER];
+  if (authClient === undefined || authClient === '') {
+    throw new VeriffWebhookVerificationError('missing-auth-client', `missing ${AUTH_CLIENT_HEADER} header`);
+  }
+  if (authClient !== opts.apiKey) {
+    throw new VeriffWebhookVerificationError('bad-auth-client', `${AUTH_CLIENT_HEADER} does not match this account's API key`);
+  }
+  const failure = verifyVeriffSignature(rawBody, lower[HMAC_SIGNATURE_HEADER], opts.sharedSecret);
+  if (failure === 'missing') throw new VeriffWebhookVerificationError('missing-signature', `missing ${HMAC_SIGNATURE_HEADER} header`);
+  if (failure === 'mismatch') throw new VeriffWebhookVerificationError('bad-signature', `${HMAC_SIGNATURE_HEADER} does not match the delivered body`);
+  return JSON.parse(rawBody) as VeriffWebhookPayload;
+}
+
+/**
+ * Sign and hand ONE delivery to the injected deliverer. Returns the bytes + headers that went out,
+ * so a caller (and the twin's own delivery log) can assert on exactly what a receiver would see.
+ */
+export async function emitVeriffWebhook(
+  url: string,
+  payload: VeriffWebhookPayload,
+  opts: { apiKey: string; sharedSecret: string; deliver: VeriffWebhookDelivery },
+): Promise<{ url: string; body: string; headers: Record<string, string> }> {
+  const { body, headers } = buildSignedDelivery(payload, opts);
+  await opts.deliver(url, body, headers);
+  return { url, body, headers };
+}

package/src/veriff-server.ts

@@ -0,0 +1,112 @@
+// Veriff twin HTTP server — serve the full Veriff Public API v1 twin over HTTP so an unmodified
+// client works against it. Veriff publishes no server-side SDK, so a real integration hand-rolls a
+// `fetch` client (the reference consumer, dub, does exactly that in `apps/web/lib/veriff/client.ts`)
+// and that is what the fidelity test drives.
+//
+// Two things happen HERE rather than in the handler, because both are wire-level:
+//
+//   1. RESPONSE SIGNING. Every documented endpoint declares two response headers — `X-AUTH-CLIENT`
+//      ("API key echoed back in response") and `X-HMAC-SIGNATURE` ("Response body signed with the
+//      shared secret key. Required to authenticate the response sender."). A consumer that verifies
+//      the sender gets the real thing from the twin.
+//   2. BINARY MEDIA. `GET /v1/media/{id}` answers with the media BYTES under the object's own
+//      mimetype, not JSON. The handler's `{status, body}` contract carries the base64 + mimetype;
+//      this is where it becomes a real binary body.
+//
+// Auth is FAKED LOCALLY: `X-AUTH-CLIENT` is required (the vendor 401s without it) but never checked
+// against a real Veriff account. `X-HMAC-SIGNATURE`, by contrast, is verified for real.
+// Writable by default; pass readOnly to reject writes (R4).
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createVeriffTwinFetch` and the
+// SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): every reply is HMAC-signed OVER ITS OWN BODY (a per-response
+// header the adapter's static `responseHeaders` cannot express) and the media route answers raw
+// BYTES — openai-server.ts is the hand-written-fetch reference.
+import { serveHttp } from '@volter/world-core';
+import { handleVeriffTwinRequest, TWIN_API_KEY, TWIN_SHARED_SECRET } from './veriff-twin.ts';
+import { worldNow, statefulTwinManifest} from '@volter/world-core';
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, veriffSignature, veriffSignatureBytes } from './veriff-signature.ts';
+
+/**
+ * The two response headers Veriff documents on every endpoint. Pure, so a test can assert the
+ * signing rule without a socket.
+ */
+export function veriffResponseHeaders(body: string, opts: { apiKey: string; sharedSecret: string }): Record<string, string> {
+  return {
+    'content-type': 'application/json',
+    [AUTH_CLIENT_HEADER]: opts.apiKey,
+    [HMAC_SIGNATURE_HEADER]: veriffSignature(body, opts.sharedSecret),
+  };
+}
+
+/** Is this the binary media-download response shape the handler hands back for `GET /v1/media/{id}`? */
+function isMediaDownload(path: string, out: unknown): out is { mimetype: string; content: string } {
+  if (!/^\/(v1\/)?media\/[^/]+$/.test(path.split('?')[0] ?? '')) return false;
+  const o = out as { mimetype?: unknown; content?: unknown } | null;
+  return typeof o?.mimetype === 'string' && typeof o?.content === 'string';
+}
+
+/** Options every Veriff-twin HTTP surface needs, independent of who owns the socket. */
+export interface VeriffTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  apiKey?: string;
+  sharedSecret?: string;
+}
+
+export function createVeriffTwinFetch(options: VeriffTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  const sharedSecret = options.sharedSecret ?? TWIN_SHARED_SECRET;
+  const apiKey = options.apiKey ?? TWIN_API_KEY;
+  return async function veriffTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(statefulTwinManifest({ vendor: 'veriff', twinOf: "Veriff's Station API v1", stores: 'verification sessions and their decision lifecycle' }));
+    }
+    const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+    const headers: Record<string, string> = {};
+    request.headers.forEach((v, k) => { headers[k.toLowerCase()] = v; });
+    const path = url.pathname + (url.search || '');
+    const { status, body: out } = await handleVeriffTwinRequest({
+      method: request.method,
+      path,
+      body,
+      headers,
+      readOnly,
+      sharedSecret,
+      apiKey,
+      occurredAt: worldNow(),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+    if (status === 200 && isMediaDownload(path, out)) {
+      const bytes = new Uint8Array(Buffer.from(out.content, 'base64'));
+      return new Response(bytes, {
+        status,
+        headers: {
+          'content-type': out.mimetype,
+          [AUTH_CLIENT_HEADER]: apiKey,
+          // Over the BYTES that go on the wire, not over the base64 text the twin stores them as:
+          // the documented header authenticates "the response body", and a consumer re-computing
+          // it over what it received must match.
+          [HMAC_SIGNATURE_HEADER]: veriffSignatureBytes(bytes, sharedSecret),
+        },
+      });
+    }
+    const text = JSON.stringify(out);
+    return new Response(text, { status, headers: veriffResponseHeaders(text, { apiKey, sharedSecret }) });
+  };
+}
+
+export async function createVeriffTwinServer(options: { root?: string; port?: number; hostname?: string; readOnly?: boolean; apiKey?: string; sharedSecret?: string } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    // Callers that fetch this server at 127.0.0.1 (the capability verifies) pass a loopback
+    // hostname so `port: 0` cannot collide with a stranger's 127.0.0.1 listener (the roving
+    // ui-verify flake mechanism — see any *-mirror-ui.ts). Default binding is unchanged.
+    ...(options.hostname !== undefined ? { hostname: options.hostname } : {}),
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createVeriffTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}