@volter/twin-veriff 0.1.0

package/src/veriff-twin.ts

@@ -0,0 +1,795 @@
+// Veriff twin REQUEST HANDLER — the canonical Veriff Public API v1 surface for the twin.
+// Contract: handleVeriffTwinRequest({method, path, body, headers}) -> {status, body}. Backed by the
+// @volter/world-core event/action-log kernel; response SHAPES are faithful to the published Station API
+// (devdocs.veriff.com/apidocs/*, whose pages embed the real OpenAPI 3.0.0 documents), not invented.
+// HTTP wrapper: veriff-server.ts.
+//
+// State lives in the action log (R18): writes are local actions, reads fold the projection. No real
+// Veriff is ever called.
+//
+// ── THE API URL IS ACCOUNT-SPECIFIC ─────────────────────────────────────────────────────────
+// Veriff deliberately does NOT publish one canonical API host — the reference tells you to read
+// your BaseURL off the Customer Portal, and its OpenAPI `servers` entry is the placeholder
+// `https://example-base-url`. Two real hosts appear in official material: `stationapi.veriff.com`
+// (hardcoded in the media-endpoint code samples, and the host the reference consumer dub uses) and
+// `api.veriff.me` (the default `host` compiled into `@veriff/js-sdk` v2.0.0). The twin serves the
+// PATHS, which are identical either way, and the injection map routes BOTH hosts here.
+//
+// ── AUTH ────────────────────────────────────────────────────────────────────────────────────
+// `X-AUTH-CLIENT` (the public API key) is REQUIRED but faked locally — accepted, never checked
+// against a real Veriff account. `X-HMAC-SIGNATURE` is a different matter: it is a pure local HMAC
+// over a shared secret, so the twin verifies it FOR REAL (veriff-signature.ts) — and this pack's
+// implementation is pinned against Veriff's own PUBLISHED mock vector. A consumer that signs the
+// wrong payload fails here exactly as it would at the vendor, which is the single most valuable
+// thing this twin can prove about a Veriff integration.
+//
+// ── THE DECISION IS NOT SOMETHING A LOCAL TWIN CAN MAKE ─────────────────────────────────────
+// Real Veriff decides a session with document OCR, face matching, liveness and (for some flows) a
+// human reviewer. What the twin models
+// faithfully is the LIFECYCLE those decisions move through, driven deterministically by the caller:
+//
+//     created ──PATCH {status:'submitted'}──> submitted ──POST /v1/_twin/…/decision──> approved
+//        │                                                                             declined
+//        └──POST /v1/_twin/…/decision (expired|abandoned)──────────────────────────────> resubmission_requested
+//                                                                                        review / expired / abandoned
+//
+// `POST /v1/_twin/sessions/{id}/decision` is TWIN-ONLY SCAFFOLDING, namespaced out of the vendor's
+// surface and deliberately absent from the capability manifest (the figma / openweather
+// convention): a real client never calls it, and counting it as coverage would be padding.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { buildSignedDelivery, type VeriffDecisionPayload, type VeriffEventPayload } from './veriff-events.ts';
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, verifyVeriffSignature } from './veriff-signature.ts';
+
+const SERVICE = 'veriff';
+
+export type VeriffRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string | undefined>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The shared secret this twin verifies `X-HMAC-SIGNATURE` against and signs webhooks with. */
+  sharedSecret?: string;
+  /** The API key this twin stamps into `x-auth-client` on outbound webhook deliveries. */
+  apiKey?: string;
+};
+export type VeriffResponse = { status: number; body: unknown };
+
+/**
+ * The default local credentials. A twin fakes auth, so these are FIXTURES, not secrets: the point
+ * of pinning them is that a consumer's `.env` can point `VERIFF_API_KEY` / `VERIFF_SHARED_SECRET`
+ * at the twin and the HMAC round-trip works end to end with no per-run coordination. Shaped like
+ * the real thing — Veriff's API key and shared secret are both UUIDs.
+ */
+export const TWIN_API_KEY = '11111111-2222-4333-8444-555555555555';
+export const TWIN_SHARED_SECRET = 'abcdef12-abcd-abcd-abcd-abcdef012345';
+
+/** The host Veriff serves the end-user verification flow from — `verification.host`, and the base
+ *  of `verification.url`. Grounded in the published `PATCH /v1/sessions/{id}` response example
+ *  (`"host": "https://alchemy.veriff.com"`). */
+const FLOW_HOST = 'https://alchemy.veriff.com';
+
+/** The base `url` a media object reports itself downloadable from. */
+const MEDIA_HOST = 'https://stationapi.veriff.com';
+
+// ── the Veriff envelope ──────────────────────────────────────────────────────
+// Every response is a FLAT object whose `status` is the envelope discriminator ("success" on the
+// happy path, "fail" on an error) with the payload hung off a sibling key named for the resource
+// (`verification`, `image`, `images`, `person`, `verifications`). There is no `data` wrapper — the
+// real consumer's zod schema (dub's `veriffCreateSessionOutputSchema`) reads
+// `{ status: 'success', verification: {...} }` straight off the top level.
+function success(payload: Record<string, unknown>, status = 200): VeriffResponse {
+  return { status, body: { status: 'success', ...payload } };
+}
+
+/**
+ * Veriff's failure envelope: `{ status: 'fail', code, message }`, all three REQUIRED.
+ *
+ * `code` is a STRING in the published schema (`"type": "string"`, examples `"1101"`, `"1812"`,
+ * `"1305"`) even though every value looks numeric — a detail that is easy to get wrong and that a
+ * consumer doing `code === '1812'` would notice immediately.
+ */
+function failure(message: string, status: number, code: VeriffErrorCode): VeriffResponse {
+  return { status, body: { status: 'fail', code, message } };
+}
+
+/**
+ * The troubleshooting/credential codes this twin actually emits, each with the verbatim message
+ * from the endpoint's own published example. `1101` is heavily overloaded by the vendor — it is the
+ * generic code across 400 (validation), 401 (missing key), 404 (not found) and 500.
+ */
+/**
+ * The verbatim message the vendor's troubleshooting-codes table pairs with each code this twin
+ * emits. Kept as data next to the codes so the two can never drift apart, and so a consumer that
+ * surfaces `message` to a support engineer sees the string Veriff's own docs use.
+ */
+// NB the verifies in veriff-capabilities.ts assert these strings as LITERALS, never by importing
+// this object. That asymmetry is deliberate: a §9 round-two review corrupted all five constants and
+// got ZERO regressions back, because handler and verify were reading the same value — two constants
+// agreeing with each other is not a check.
+export const VERIFF_ERROR_MESSAGES = {
+  '1302': 'Only HTTPS return URLs are allowed.',
+  '1401': 'Image is not in valid `base64`.',
+  '1402': 'Image context is not supported.',
+  '1500': '`vendorData` field cannot be more than 1000 symbols. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer\'s domain)',
+  '1501': '`vendorData` must be a string. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer\'s domain)',
+} as const;
+
+export const VERIFF_ERROR_CODES = {
+  generic: '1101',
+  invalidHmac: '1812',
+  notCompleted: '1305',
+  inProgress: '1306',
+  badTransition: '1304',
+  invalidBase64: '1401',
+  unsupportedContext: '1402',
+  httpsOnlyCallback: '1302',
+  vendorDataLength: '1500',
+  vendorDataType: '1501',
+} as const;
+type VeriffErrorCode = (typeof VERIFF_ERROR_CODES)[keyof typeof VERIFF_ERROR_CODES];
+
+/** A route this twin does not model. Fails like the vendor (404) — never a fake success. */
+function unmodeled(method: string, path: string): VeriffResponse {
+  void method; void path;
+  return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+}
+
+// ── the session lifecycle ────────────────────────────────────────────────────
+
+/** Every state a session can be in, across both halves of the lifecycle. */
+export const VERIFF_SESSION_STATUSES = [
+  'created',
+  'started',
+  'submitted',
+  'approved',
+  'declined',
+  'resubmission_requested',
+  'review',
+  'expired',
+  'abandoned',
+] as const;
+export type VeriffSessionStatus = (typeof VERIFF_SESSION_STATUSES)[number];
+
+/** The terminal decision statuses — the exact set the decision webhook documents, and the exact set
+ *  the reference consumer's zod enum accepts (dub's `veriffDecisionEventSchema`). */
+export const VERIFF_DECISION_STATUSES = [
+  'approved',
+  'declined',
+  'resubmission_requested',
+  'review',
+  'expired',
+  'abandoned',
+] as const;
+export type VeriffDecisionStatus = (typeof VERIFF_DECISION_STATUSES)[number];
+
+const DECISION_SET: ReadonlySet<string> = new Set<string>(VERIFF_DECISION_STATUSES);
+
+/**
+ * The numeric `code` Veriff carries alongside a decision status.
+ *
+ * Grounded four ways in the decision endpoint's own published document, which is the endpoint this
+ * twin serves: its prose list ("`9104` - Expired", "`9121` - Abandoned"), its
+ * `session_abandoned_generic` example (`"code":"9121"` with `"status":"abandoned"`), its
+ * `session_expired_generic` example (`"code":"9104"` with `"status":"expired"`), and the schema's
+ * `code` enum, which is exactly [9001, 9102, 9103, 9104, 9121].
+ *
+ * `review` therefore gets **null**, not a borrowed code. It is a real status — the decision-webhook
+ * page lists it among `approved|declined|resubmission_requested|review|expired|abandoned`, and it is
+ * opt-in ("Only if previously agreed with Veriff") — but it appears in NEITHER the decision schema's
+ * `status` enum NOR its `code` enum, so no published number belongs to it. Handing it another
+ * status's code would be invention, and a consumer branching on `code` would silently treat a
+ * manual-review case as abandoned. `veriff.decisions.review_code` is the filed todo.
+ *
+ * (An earlier revision of this pack mapped `abandoned: 9104` / `review: 9121` on the strength of a
+ * status-codes table it had not actually read — a §9 review caught it. Recorded because the lesson
+ * generalises: prefer the document you can quote over the one you were told about.)
+ *
+ * Emitted as a NUMBER, matching the decision-webhook sample (`"code": 9001`) and the schema's
+ * declared `"type": "integer"`.
+ */
+export const VERIFF_DECISION_CODES: Record<VeriffDecisionStatus, number | null> = {
+  approved: 9001,
+  declined: 9102,
+  resubmission_requested: 9103,
+  expired: 9104,
+  abandoned: 9121,
+  review: null,
+};
+
+/** The event-webhook `code` per action. 7001/7002 are the two the event-webhook page documents as
+ *  needing no extra configuration; the 7007-7011 web-flow actions are a filed todo. */
+export const VERIFF_EVENT_CODES: Record<'started' | 'submitted', number> = { started: 7001, submitted: 7002 };
+
+/** `PATCH /v1/sessions/{id}` accepts exactly ONE target status — the published schema's
+ *  `"Valid values": ["submitted"]`. Anything else is a validation failure, not a transition error. */
+const PATCH_TARGET = 'submitted';
+
+/**
+ * The statuses `DELETE /v1/sessions/{id}` accepts, verbatim from the endpoint's normative "Session
+ * deletion logic" list. `submitted` and `review` are the two that are NOT deletable.
+ *
+ * ⚠️ The SAME PAGE contradicts itself: its `session_not_completed` example says "Session must be in
+ * a completed state (`approved`, `declined`, `expired`, `abandoned`) before deletion", which would
+ * also exclude `created`, `started` and `resubmission_requested` — the three the prose list
+ * explicitly allows, and for which the same page describes an expired/abandoned decision webhook
+ * being fired. This twin follows the PROSE LIST, because it is the section whose job is to state the
+ * rule and because the webhook behaviour only makes sense if those states are deletable.
+ */
+const DELETABLE: ReadonlySet<string> = new Set(['created', 'started', 'approved', 'declined', 'resubmission_requested', 'expired', 'abandoned']);
+
+/** Legal transitions, keyed by the state being left. A move not listed here is a 400. */
+const TRANSITIONS: Record<string, ReadonlySet<string>> = {
+  created: new Set(['started', 'submitted', 'expired', 'abandoned']),
+  started: new Set(['submitted', 'expired', 'abandoned']),
+  submitted: new Set([...VERIFF_DECISION_STATUSES]),
+  // A resubmission is an explicit invitation to try again, so the session re-opens for capture.
+  resubmission_requested: new Set(['started', 'submitted', 'expired', 'abandoned']),
+};
+
+function canTransition(from: string, to: string): boolean {
+  return TRANSITIONS[from]?.has(to) ?? false;
+}
+
+// ── kernel plumbing ──────────────────────────────────────────────────────────
+
+/**
+ * The subject types this twin projects.
+ *
+ * `delivery` is the twin's own outbound-webhook log: every decision/event webhook the twin would
+ * have PUSHED is recorded here, signed exactly as it would go on the wire, so a consumer can read
+ * one back and verify it offline instead of standing up a receiver.
+ */
+export const VERIFF_RESOURCE_TYPES = ['session', 'attempt', 'media', 'delivery'] as const;
+
+function list(type: string, root?: string): Record<string, unknown>[] {
+  return (projectResources(SERVICE, root).filter((r) => r.type === type) as unknown as Record<string, unknown>[])
+    .filter((r) => r.deleted !== true);
+}
+function getById(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return list(type, root).find((r) => (r as { id: string }).id === id);
+}
+
+async function write(type: string, id: string, fields: Record<string, unknown>, root?: string, occurredAt?: string): Promise<void> {
+  await applyTwinWrite(SERVICE, { operation: `set.${type}`, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
+}
+
+/**
+ * Strip the kernel's three RESERVED projection keys before a record is rendered.
+ *
+ * `type`, `id` and `updatedAt` are META in `@volter/world-core`'s projection — a resource field with one
+ * of those names is silently DROPPED on the way in. Veriff's documents are full of `id`s
+ * (`verification.id`, `image.id`, an attempt's `id`), so every one of them is STORED under a
+ * renamed key (`sessionId`, `mediaId`, `attemptId`) and mapped back here at the boundary. Getting
+ * this wrong produces no error at all, just a missing field.
+ */
+function emit(r: Record<string, unknown>): Record<string, unknown> {
+  const { type, updatedAt, id, deleted, ...rest } = r as Record<string, unknown>;
+  void type; void updatedAt; void id; void deleted;
+  return rest;
+}
+
+function parseBody(body?: string): Record<string, unknown> | null {
+  if (body === undefined || body === '') return {};
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch { return null; }
+}
+
+/**
+ * Mint a session/attempt/media/delivery id.
+ *
+ * UUID-v4 SHAPED, because that is what Veriff's ids ARE (`"format": "uuid"` on every id in the
+ * published schemas) — but DETERMINISTIC (R9, resource level): the bytes are a stable hash of
+ * `${type}:${occurredAt}:${ordinal}`, the world instant the write happens at plus the count of ids
+ * the type already holds. It used to be a fresh `crypto.randomUUID()` per call, so two identical
+ * worlds never agreed on a session, attempt, media or delivery id and no replay of this pack could
+ * be byte-identical.
+ *
+ * The two properties the old comment credited to entropy are kept by the PROBE, not by the mint:
+ * `taken` is every id this type has ever held, soft-deleted ones INCLUDED, and the attempt counter
+ * goes into the seed until the candidate lands clear. So a connector-pulled vendor id sitting where
+ * a local mint would land is skipped, and a delete→recreate cycle can never re-issue a retired id.
+ */
+function mintId(type: string, ctx: Ctx): string {
+  const taken = new Set(
+    (projectResources(SERVICE, ctx.root) as unknown as Array<{ type: string; id: string }>)
+      .filter((r) => r.type === type).map((r) => r.id),
+  );
+  for (let attempt = 0; ; attempt += 1) {
+    const h = createHash('sha256').update(`${type}:${ctx.occurredAt ?? ''}:${taken.size}:${attempt}`).digest('hex');
+    const id = `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${((parseInt(h[16]!, 16) & 0x3) | 0x8).toString(16)}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+    if (!taken.has(id)) return id;
+  }
+}
+
+// ── views ────────────────────────────────────────────────────────────────────
+
+/** The `verification` object session create / get / patch answer with. All seven fields are
+ *  `required` in the published `SessionCreatedVerification` schema, so none may be omitted —
+ *  `endUserId` and `vendorData` are returned as `null` when they were not supplied. */
+function sessionVerificationView(s: Record<string, unknown>): Record<string, unknown> {
+  return {
+    status: s.status,
+    id: s.sessionId,
+    url: s.url,
+    sessionToken: s.sessionToken,
+    host: s.host,
+    endUserId: s.endUserId ?? null,
+    vendorData: s.vendorData ?? null,
+  };
+}
+
+/** The `verification` object the decision endpoint and the decision webhook both carry. */
+function decisionVerificationView(s: Record<string, unknown>): Record<string, unknown> {
+  return {
+    id: s.sessionId,
+    attemptId: s.decisionAttemptId ?? null,
+    vendorData: s.vendorData ?? null,
+    endUserId: s.endUserId ?? null,
+    status: s.status,
+    code: s.decisionCode ?? null,
+    reason: s.decisionReason ?? null,
+    reasonCode: s.decisionReasonCode ?? null,
+    decisionTime: s.decisionTime ?? null,
+    acceptanceTime: s.acceptanceTime ?? null,
+    submissionTime: s.submissionTime ?? null,
+    person: s.decidedPerson ?? null,
+    document: s.decidedDocument ?? null,
+    additionalVerifiedData: s.additionalVerifiedData ?? null,
+    riskLabels: s.riskLabels ?? null,
+    comments: s.comments ?? [],
+  };
+}
+
+function mediaView(m: Record<string, unknown>): Record<string, unknown> {
+  const { mediaId, kind, content, ...rest } = emit(m);
+  void kind; void content;
+  return { id: mediaId, ...rest };
+}
+
+/** An attempt row, as `GET /v1/sessions/{id}/attempts` renders it. */
+function attemptView(a: Record<string, unknown>): Record<string, unknown> {
+  return {
+    id: a.attemptId,
+    status: a.status,
+    userDefinedData: a.userDefinedData ?? [],
+    createdTime: a.createdTime ?? null,
+  };
+}
+
+// ── the router ───────────────────────────────────────────────────────────────
+
+/**
+ * Every endpoint this twin DISPATCHES, as a `METHOD /path` template. The conformance check drives
+ * one real request per entry and asserts the OUTCOME a live handler produces, so deleting a route —
+ * or a single method branch — from the switchboard below turns it red. Its census is a two-way
+ * bijection with this list, so adding a route here without implementing it is red too.
+ */
+export const VERIFF_IMPLEMENTED_ENDPOINTS = [
+  // NOTE the absence of `GET /v1/sessions/{sessionId}`. Veriff HAS NO SUCH ENDPOINT — its API
+  // reference index lists POST/PATCH/DELETE on that path and GETs only on the sub-resources
+  // (/decision, /person, /attempts, /media, /watchlist-screening). An integration reads a session's
+  // state from the webhooks and the decision endpoint, which is exactly why the reference consumer
+  // stores its own `veriffSessionId` + status. Serving a convenient read here would be an INVENTED
+  // op — the mirror image of the "unmodeled ops fail like the vendor" rule — so a GET on that path
+  // answers the vendor's 404, and `veriff.sessions.no_get_endpoint` pins it. The twin-only
+  // `GET /v1/_twin/sessions/{id}` exists for test readback and is not vendor surface.
+  'POST /v1/sessions',
+  'PATCH /v1/sessions/{sessionId}',
+  'DELETE /v1/sessions/{sessionId}',
+  'GET /v1/sessions/{sessionId}/decision',
+  'GET /v1/sessions/{sessionId}/person',
+  'GET /v1/sessions/{sessionId}/attempts',
+  'GET /v1/sessions/{sessionId}/media',
+  'POST /v1/sessions/{sessionId}/media',
+  'GET /v1/attempts/{attemptId}/media',
+  'GET /v1/media/{mediaId}',
+] as const;
+
+/**
+ * Does this request need `X-HMAC-SIGNATURE`?
+ *
+ * Everything does EXCEPT `POST /v1/sessions` — the vendor states the exception verbatim ("Exception
+ * is POST /sessions … which does not require the X-HMAC-SIGNATURE header") and `@veriff/js-sdk`
+ * corroborates it by sending only `x-auth-client` on that call.
+ */
+function requiresSignature(method: string, parts: string[]): boolean {
+  return !(method === 'POST' && parts.length === 1 && parts[0] === 'sessions');
+}
+
+/**
+ * The payload `X-HMAC-SIGNATURE` must be computed over.
+ *
+ * The vendor's rule of thumb is "POST/PATCH sign the request body, GET/DELETE sign the session ID",
+ * but the per-endpoint header docs refine it to **the resource id in the path**: `GET
+ * /v1/attempts/{id}/media` signs the ATTEMPT id and `GET /v1/media/{id}` signs the MEDIA id. So the
+ * payload is the raw body for a body-bearing write, and `parts[1]` — whichever resource the path
+ * addresses — for a read or a delete.
+ */
+function signaturePayload(method: string, parts: string[], rawBody: string): string {
+  if (method !== 'GET' && method !== 'DELETE') return rawBody;
+  return parts[1] ?? '';
+}
+
+export async function handleVeriffTwinRequest(req: VeriffRequest): Promise<VeriffResponse> {
+  const { method, root, occurredAt } = req;
+  const readOnly = req.readOnly ?? false;
+  const sharedSecret = req.sharedSecret ?? TWIN_SHARED_SECRET;
+  const apiKey = req.apiKey ?? TWIN_API_KEY;
+  const rawBody = req.body ?? '';
+
+  let url: URL;
+  try { url = new URL(req.path, 'http://twin.local'); } catch { return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic); }
+  const parts = url.pathname.replace(/^\/v1(\/|$)/, '/').replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+
+  const headers: Record<string, string> = {};
+  for (const [k, v] of Object.entries(req.headers ?? {})) if (v !== undefined) headers[k.toLowerCase()] = v;
+
+  const ctx: Ctx = { root, occurredAt, apiKey, sharedSecret };
+
+  // ── twin-only control plane (NOT vendor surface, NOT in the manifest) ──────
+  // Checked before auth: these routes are test scaffolding a real client never calls, and requiring
+  // a signature to arm a fixture would only make the scaffolding harder to use than the API.
+  if (parts[0] === '_twin') {
+    if (readOnly && method !== 'GET') return failure('this twin was started read-only; omit readOnly to accept writes', 405, VERIFF_ERROR_CODES.generic);
+    const twinBody = parseBody(rawBody);
+    if (twinBody === null) return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+    return twinControl(req, parts, twinBody, ctx);
+  }
+
+  // ── auth (faked locally, but STRUCTURALLY enforced) ────────────────────────
+  // The public API key must be PRESENT — the vendor 401s without it — but is never checked against
+  // a real account. The HMAC, by contrast, is verified for real.
+  if (!headers[AUTH_CLIENT_HEADER]) {
+    return failure('Mandatory X-AUTH-CLIENT header containing the API key is missing from the request.', 401, VERIFF_ERROR_CODES.generic);
+  }
+  if (requiresSignature(method, parts)) {
+    const outcome = verifyVeriffSignature(signaturePayload(method, parts, rawBody), headers[HMAC_SIGNATURE_HEADER], sharedSecret);
+    if (outcome !== null) return failure('Invalid HMAC signature', 401, VERIFF_ERROR_CODES.invalidHmac);
+  }
+
+  const isWrite = method !== 'GET' && method !== 'HEAD';
+  if (readOnly && isWrite) return failure('this twin was started read-only; omit readOnly to accept writes', 405, VERIFF_ERROR_CODES.generic);
+
+  const body = parseBody(rawBody);
+  if (body === null) return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+
+  // ── /v1/sessions ───────────────────────────────────────────────────────────
+  if (parts[0] === 'sessions') {
+    if (method === 'POST' && parts.length === 1) return createSession(body, ctx);
+    if (parts.length >= 2 && parts.length <= 3) {
+      const sessionId = parts[1]!;
+      const session = getById('session', sessionId, root);
+      if (!session) return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+
+      if (parts.length === 2) {
+        // Deliberately NO `GET` branch — see the note on VERIFF_IMPLEMENTED_ENDPOINTS.
+        if (method === 'PATCH') return patchSession(session, body, ctx);
+        if (method === 'DELETE') return deleteSession(session, ctx);
+        return unmodeled(method, req.path);
+      }
+      const sub = parts[2]!;
+      if (method === 'GET' && sub === 'decision') return getDecision(session);
+      if (method === 'GET' && sub === 'person') return success({ person: session.decidedPerson ?? null });
+      if (method === 'GET' && sub === 'attempts') {
+        // Reverse-chronological, as the endpoint documents ("most recent attempt first").
+        const rows = list('attempt', root)
+          .filter((a) => a.sessionId === sessionId)
+          .sort((a, b) => String(b.createdTime ?? '').localeCompare(String(a.createdTime ?? '')))
+          .map(attemptView);
+        return success({ verifications: rows });
+      }
+      if (sub === 'media') {
+        if (method === 'GET') return listMedia((m) => m.sessionId === sessionId, root);
+        if (method === 'POST') return uploadMedia(session, body, ctx);
+      }
+      return unmodeled(method, req.path);
+    }
+    return unmodeled(method, req.path);
+  }
+
+  // ── /v1/attempts/{attemptId}/media ─────────────────────────────────────────
+  if (parts[0] === 'attempts' && parts.length === 3 && parts[2] === 'media' && method === 'GET') {
+    const attemptId = parts[1]!;
+    if (!getById('attempt', attemptId, root)) return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+    return listMedia((m) => m.attemptId === attemptId, root);
+  }
+
+  // ── /v1/media/{mediaId} ────────────────────────────────────────────────────
+  if (parts[0] === 'media' && parts.length === 2 && method === 'GET') {
+    const found = getById('media', parts[1]!, root);
+    if (!found) return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+    // The real endpoint answers with the media BYTES under the object's own mimetype, not JSON.
+    // The handler contract here is `{status, body}`, so the bytes are surfaced as the base64
+    // `content` the upload supplied plus its `mimetype`; veriff-server.ts is what turns that back
+    // into a real binary body with the right Content-Type on the wire.
+    return { status: 200, body: { mimetype: found.mimetype, content: found.content } };
+  }
+
+  return unmodeled(method, req.path);
+}
+
+// ── handlers ─────────────────────────────────────────────────────────────────
+
+type Ctx = { root?: string | undefined; occurredAt?: string | undefined; apiKey?: string; sharedSecret?: string };
+
+/** `vendorData` is documented as max 1,000 characters and string-typed, with dedicated codes. */
+const VENDOR_DATA_MAX = 1000;
+
+async function createSession(body: Record<string, unknown>, ctx: Ctx): Promise<VeriffResponse> {
+  const verification = body.verification;
+  if (verification === undefined || verification === null || typeof verification !== 'object' || Array.isArray(verification)) {
+    return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+  }
+  const v = verification as Record<string, unknown>;
+  if (v.vendorData !== undefined && v.vendorData !== null) {
+    if (typeof v.vendorData !== 'string') return failure(VERIFF_ERROR_MESSAGES['1501'], 400, VERIFF_ERROR_CODES.vendorDataType);
+    if (v.vendorData.length > VENDOR_DATA_MAX) return failure(VERIFF_ERROR_MESSAGES['1500'], 400, VERIFF_ERROR_CODES.vendorDataLength);
+  }
+  if (v.callback !== undefined && v.callback !== null) {
+    // Documented as code 1302: "Only HTTPS return URLs are allowed."
+    if (typeof v.callback !== 'string') return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+    let parsed: URL;
+    try { parsed = new URL(v.callback); } catch { return failure(VERIFF_ERROR_MESSAGES['1302'], 400, VERIFF_ERROR_CODES.httpsOnlyCallback); }
+    if (parsed.protocol !== 'https:') return failure(VERIFF_ERROR_MESSAGES['1302'], 400, VERIFF_ERROR_CODES.httpsOnlyCallback);
+  }
+  const sessionId = mintId('session', ctx);
+  // A real sessionToken is a JWT. The twin mints a structurally-real one (three base64url segments)
+  // whose payload carries the session id, so `verification.url` is `host + '/v/' + sessionToken`
+  // exactly as the schema describes and a consumer splitting the token still finds its session.
+  const sessionToken = mintSessionToken(sessionId);
+  await write('session', sessionId, {
+    sessionId,
+    status: 'created' satisfies VeriffSessionStatus,
+    url: `${FLOW_HOST}/v/${sessionToken}`,
+    host: FLOW_HOST,
+    sessionToken,
+    vendorData: (v.vendorData as string | undefined) ?? null,
+    endUserId: (v.endUserId as string | undefined) ?? null,
+    callback: (v.callback as string | undefined) ?? null,
+    tag: (v.tag as string | undefined) ?? null,
+    // The person/document HINTS supplied at creation are NOT the decision's extracted data — they
+    // are stored separately so a decision can never be confused with the caller's own input.
+    hintPerson: (v.person as Record<string, unknown> | undefined) ?? null,
+    hintDocument: (v.document as Record<string, unknown> | undefined) ?? null,
+    createdTime: ctx.occurredAt ?? null,
+  }, ctx.root, ctx.occurredAt);
+  const created = getById('session', sessionId, ctx.root)!;
+  // 201, not 200. The published OpenAPI declares this response 200 while the vendor's own HTTP
+  // status-code table says 201 ("returned when session creation was a success") — and
+  // `@veriff/js-sdk` v2.0.0 hard-checks `201 === xhr.status`, so a twin that answered 200 would
+  // break the real SDK. The conflict is recorded in spec-sources.json and README ## Coverage.
+  return success({ verification: sessionVerificationView(created) }, 201);
+}
+
+/** Three base64url segments — structurally a JWT, deterministic in its payload, never signed with
+ *  anything meaningful (a twin fakes auth; the token is a handle, not a credential). */
+function mintSessionToken(sessionId: string): string {
+  const seg = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64url');
+  return `${seg({ alg: 'HS256', typ: 'JWT' })}.${seg({ session_id: sessionId })}.${Buffer.from(sessionId).toString('base64url')}`;
+}
+
+async function patchSession(session: Record<string, unknown>, body: Record<string, unknown>, ctx: Ctx): Promise<VeriffResponse> {
+  const v = (body.verification ?? {}) as Record<string, unknown>;
+  const target = v.status;
+  // `submitted` is the schema's ONLY valid value; anything else is a validation failure.
+  if (typeof target !== 'string' || target !== PATCH_TARGET) {
+    return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+  }
+  const from = String(session.status);
+  if (from === PATCH_TARGET) return failure('Session has already been submitted', 400, VERIFF_ERROR_CODES.generic);
+  if (!canTransition(from, PATCH_TARGET)) {
+    return failure(`Cannot transition to "${PATCH_TARGET}" status.`, 400, VERIFF_ERROR_CODES.badTransition);
+  }
+  await write('session', String(session.sessionId), { status: PATCH_TARGET, submissionTime: ctx.occurredAt ?? null }, ctx.root, ctx.occurredAt);
+  const updated = getById('session', String(session.sessionId), ctx.root)!;
+  // Veriff pushes the 7002 `submitted` EVENT webhook at exactly this point — "before the end-user
+  // is directed to the callback URL specified on session creation".
+  await recordEventDelivery(updated, 'submitted', ctx);
+  return success({ verification: sessionVerificationView(updated) });
+}
+
+async function deleteSession(session: Record<string, unknown>, ctx: Ctx): Promise<VeriffResponse> {
+  const from = String(session.status);
+  if (!DELETABLE.has(from)) {
+    // ⚠️ A DISAMBIGUATION, not a documented rule — said plainly because the difference matters.
+    // The endpoint documents ONE blanket refusal for every non-deletable status ("Session is not in
+    // a completed status.", 1305) while ALSO publishing a 1306 "Session in progress." example whose
+    // stated trigger is "while the end-user is actively completing verification". Since `started` is
+    // on the DELETABLE list, 1306 has no documented trigger left, and `submitted` is the only state
+    // that fits its description — so this twin routes `submitted` there and everything else to 1305.
+    // `veriff.sessions.delete_refusal_codes` is the filed todo to pin it against a live account.
+    return from === 'submitted'
+      ? failure('Session in progress.', 400, VERIFF_ERROR_CODES.inProgress)
+      : failure('Session is not in a completed status.', 400, VERIFF_ERROR_CODES.notCompleted);
+  }
+  await write('session', String(session.sessionId), { deleted: true }, ctx.root, ctx.occurredAt);
+  // The success body is deliberately just the id — the endpoint's published example is
+  // `{"status":"success","verification":{"id":"…"}}` and nothing more.
+  return success({ verification: { id: session.sessionId } });
+}
+
+function getDecision(session: Record<string, unknown>): VeriffResponse {
+  // A session with no decision yet answers 200 with a NULL verification — the endpoint documents
+  // exactly this ("`null` = decision not yet available, try again later"), which is why it is safe
+  // to poll from the moment the session exists.
+  if (!DECISION_SET.has(String(session.status))) return success({ verification: null });
+  return success({ verification: decisionVerificationView(session) });
+}
+
+function listMedia(match: (m: Record<string, unknown>) => boolean, root?: string): VeriffResponse {
+  const rows = list('media', root).filter(match);
+  return success({
+    images: rows.filter((m) => m.kind === 'image').map(mediaView),
+    videos: rows.filter((m) => m.kind === 'video').map(mediaView),
+    nfcDocuments: rows.filter((m) => m.kind === 'nfc').map(mediaView),
+  });
+}
+
+/** The image/video contexts the upload schema enumerates. An unlisted one is code 1402. */
+const MEDIA_CONTEXTS: ReadonlySet<string> = new Set([
+  'address-front', 'document-and-face', 'document-and-face-pre', 'document-back',
+  'document-back-barcode', 'document-back-barcode-pre', 'document-back-pre', 'document-back-qrcode',
+  'document-back-qrcode-pre', 'document-front', 'document-front-face-cropped', 'document-front-pre',
+  'document-front-qrcode', 'document-front-qrcode-pre', 'face', 'face-cropped', 'face-nfc',
+  'face-pre', 'face-reference', 'registry-face',
+]);
+
+/** `content` is documented as carrying the data-URI scheme prefix (`data:image/jpeg;base64,…`). */
+const DATA_URI = /^data:([\w.+-]+\/[\w.+-]+);base64,(.*)$/s;
+
+async function uploadMedia(session: Record<string, unknown>, body: Record<string, unknown>, ctx: Ctx): Promise<VeriffResponse> {
+  const image = body.image;
+  if (image === undefined || image === null || typeof image !== 'object' || Array.isArray(image)) {
+    return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+  }
+  const img = image as Record<string, unknown>;
+  if (typeof img.context !== 'string' || !MEDIA_CONTEXTS.has(img.context)) {
+    return failure(VERIFF_ERROR_MESSAGES['1402'], 400, VERIFF_ERROR_CODES.unsupportedContext);
+  }
+  if (typeof img.content !== 'string' || img.content === '') {
+    return failure(VERIFF_ERROR_MESSAGES['1401'], 400, VERIFF_ERROR_CODES.invalidBase64);
+  }
+  const parsed = DATA_URI.exec(img.content);
+  const mimetype = parsed?.[1] ?? 'image/jpeg';
+  const base64 = parsed?.[2] ?? img.content;
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64) || base64.length === 0) {
+    return failure(VERIFF_ERROR_MESSAGES['1401'], 400, VERIFF_ERROR_CODES.invalidBase64);
+  }
+  // "If you have already submitted the session, you may encounter the 409 - conflict error."
+  if (String(session.status) !== 'created' && String(session.status) !== 'started' && String(session.status) !== 'resubmission_requested') {
+    return failure('Session has already been submitted', 409, VERIFF_ERROR_CODES.generic);
+  }
+  const mediaId = mintId('media', ctx);
+  await write('media', mediaId, {
+    mediaId,
+    sessionId: session.sessionId,
+    attemptId: session.currentAttemptId ?? null,
+    kind: 'image',
+    // `name` mirrors `context` in every published example.
+    name: img.context,
+    context: img.context,
+    // Documented as DEPRECATED and always returned as null, whatever the caller sent.
+    timestamp: null,
+    size: Buffer.from(base64, 'base64').length,
+    mimetype,
+    content: base64,
+    url: `${MEDIA_HOST}/v1/media/${mediaId}`,
+  }, ctx.root, ctx.occurredAt);
+  // 200, NOT 201. The media endpoint's own document declares exactly one success response —
+  // "Responses 200 / Media uploaded successfully." — and 201 appears nowhere in it. The
+  // status-code table's 201 row is scoped specifically to SESSION creation, so it does not carry
+  // over here, and unlike POST /v1/sessions there is no shipped SDK asserting otherwise.
+  return success({ image: mediaView(getById('media', mediaId, ctx.root)!) });
+}
+
+// ── outbound webhook deliveries (recorded, signed, never on a socket) ────────
+
+async function recordDelivery(session: Record<string, unknown>, payload: VeriffDecisionPayload | VeriffEventPayload, kind: 'decision' | 'event', ctx: Ctx): Promise<void> {
+  const callback = session.callback;
+  if (typeof callback !== 'string' || callback === '') return; // no callback configured → nothing to deliver
+  const signed = buildSignedDelivery(payload, { apiKey: ctx.apiKey ?? TWIN_API_KEY, sharedSecret: ctx.sharedSecret ?? TWIN_SHARED_SECRET });
+  const deliveryId = mintId('delivery', ctx);
+  await write('delivery', deliveryId, {
+    deliveryId,
+    sessionId: session.sessionId,
+    kind,
+    url: callback,
+    body: signed.body,
+    headers: signed.headers,
+  }, ctx.root, ctx.occurredAt);
+}
+
+async function recordEventDelivery(session: Record<string, unknown>, action: 'started' | 'submitted', ctx: Ctx): Promise<void> {
+  const payload: VeriffEventPayload = {
+    id: String(session.sessionId),
+    attemptId: String(session.currentAttemptId ?? session.sessionId),
+    feature: 'selfid',
+    code: VERIFF_EVENT_CODES[action],
+    action,
+    vendorData: (session.vendorData as string | null) ?? null,
+  };
+  await recordDelivery(session, payload, 'event', ctx);
+}
+
+// ── twin-only control plane ──────────────────────────────────────────────────
+
+async function twinControl(req: VeriffRequest, parts: string[], body: Record<string, unknown>, ctx: Ctx): Promise<VeriffResponse> {
+  const { method } = req;
+  // POST /v1/_twin/sessions/{sessionId}/decision — drive the terminal transition a real Veriff
+  // reaches by OCR + face match + liveness + (sometimes) a human reviewer.
+  if (method === 'POST' && parts[1] === 'sessions' && parts[3] === 'decision' && parts.length === 4) {
+    const sessionId = parts[2]!;
+    const session = getById('session', sessionId, ctx.root);
+    if (!session) return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+    const target = body.status;
+    if (typeof target !== 'string' || !DECISION_SET.has(target)) {
+      return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+    }
+    const from = String(session.status);
+    if (!canTransition(from, target)) return failure(`Cannot transition to "${target}" status.`, 400, VERIFF_ERROR_CODES.badTransition);
+    const attemptId = mintId('attempt', ctx);
+    const decisionTime = ctx.occurredAt ?? null;
+    await write('attempt', attemptId, {
+      attemptId,
+      sessionId,
+      status: target,
+      userDefinedData: (body.userDefinedData as unknown[] | undefined) ?? [],
+      createdTime: decisionTime,
+    }, ctx.root, ctx.occurredAt);
+    await write('session', sessionId, {
+      status: target,
+      decisionCode: VERIFF_DECISION_CODES[target as VeriffDecisionStatus],
+      decisionAttemptId: attemptId,
+      currentAttemptId: attemptId,
+      decisionTime,
+      acceptanceTime: decisionTime,
+      decisionReason: (body.reason as string | undefined) ?? null,
+      decisionReasonCode: (body.reasonCode as number | undefined) ?? null,
+      ...(body.person !== undefined ? { decidedPerson: body.person } : {}),
+      ...(body.document !== undefined ? { decidedDocument: body.document } : {}),
+      ...(body.riskLabels !== undefined ? { riskLabels: body.riskLabels } : {}),
+      ...(body.additionalVerifiedData !== undefined ? { additionalVerifiedData: body.additionalVerifiedData } : {}),
+    }, ctx.root, ctx.occurredAt);
+    const decided = getById('session', sessionId, ctx.root)!;
+    const payload: VeriffDecisionPayload = { status: 'success', verification: decisionVerificationView(decided) };
+    await recordDelivery(decided, payload, 'decision', ctx);
+    return success({ verification: decisionVerificationView(decided) });
+  }
+  // POST /v1/_twin/sessions/{sessionId}/event — fire the 7001 `started` flow event.
+  if (method === 'POST' && parts[1] === 'sessions' && parts[3] === 'event' && parts.length === 4) {
+    const session = getById('session', parts[2]!, ctx.root);
+    if (!session) return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+    const action = body.action;
+    if (action !== 'started') return failure('Validation failed', 400, VERIFF_ERROR_CODES.generic);
+    if (!canTransition(String(session.status), 'started')) return failure(`Cannot transition to "started" status.`, 400, VERIFF_ERROR_CODES.badTransition);
+    await write('session', String(session.sessionId), { status: 'started' }, ctx.root, ctx.occurredAt);
+    const started = getById('session', String(session.sessionId), ctx.root)!;
+    await recordEventDelivery(started, 'started', ctx);
+    return success({ verification: sessionVerificationView(started) });
+  }
+  // GET /v1/_twin/sessions/{sessionId} — TEST READBACK ONLY. Veriff exposes no GET for a session,
+  // so a verify that wants to assert "the status really moved" has no vendor endpoint to use; this
+  // is the twin-only stand-in (the figma / openweather `_twin` convention). Namespaced out of the
+  // vendor's surface and deliberately absent from the capability manifest.
+  if (method === 'GET' && parts[1] === 'sessions' && parts.length === 3) {
+    const session = getById('session', parts[2]!, ctx.root);
+    if (!session) return failure('Resource not found', 404, VERIFF_ERROR_CODES.generic);
+    return success({ verification: sessionVerificationView(session) });
+  }
+  // GET /v1/_twin/deliveries[?sessionId=] — read back what the twin WOULD have pushed, signed
+  // exactly as it would go on the wire, so a consumer can verify a real delivery offline.
+  if (method === 'GET' && parts[1] === 'deliveries' && parts.length === 2) {
+    const wanted = new URL(req.path, 'http://twin.local').searchParams.get('sessionId');
+    const rows = list('delivery', ctx.root)
+      .filter((d) => wanted === null || d.sessionId === wanted)
+      .map((d) => emit(d));
+    return success({ deliveries: rows });
+  }
+  return unmodeled(method, req.path);
+}