@volter/twin-veriff 0.1.0

package/dist/src/veriff-conformance.d.ts

@@ -0,0 +1,28 @@
+import { type VeriffRequest, type VeriffResponse } from './veriff-twin.js';
+export type VeriffConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    routesDispatched: number;
+    controlsRejected: number;
+    violations: string[];
+};
+/**
+ * The handler under test. Defaults to the pack's real one; a test injects a WRAPPER to prove this
+ * check goes red when a route (or a single method branch) is deleted, and when a route this pack
+ * does NOT model starts answering. Injecting a handler cannot weaken the check — the default is the
+ * real export, and the mutation gate's saboteur replaces that export, so a dead twin is still
+ * measured through this same seam.
+ *
+ * THREADED AS A PARAMETER, never held in a module-level variable. An earlier revision used a
+ * mutable module global reset at the end of the run, and a §9 review reproduced the consequence:
+ * two concurrent `checkVeriffConformance` calls — one clean, one carrying a saboteur that deletes a
+ * whole route branch — BOTH reported conformant. It failed OPEN, in the one check whose entire job
+ * is to prove teeth. Nothing calls it concurrently today, but a `test.concurrent` or a parallel
+ * harness would arm it, and a green that depends on nobody trying is not a green.
+ */
+export type VeriffHandler = (req: VeriffRequest) => Promise<VeriffResponse>;
+export declare function checkVeriffConformance(opts?: {
+    root?: string;
+    handler?: VeriffHandler;
+}): Promise<VeriffConformanceReport>;

package/dist/src/veriff-conformance.js

@@ -0,0 +1,223 @@
+// Veriff conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// The bar this check is written to (ADDING_A_TWIN.md §6, "the conformance check needs the same
+// teeth"): ONE REAL REQUEST per claimed endpoint, asserting the OUTCOME a live handler produces —
+// an expected status plus a predicate over the body — against a throwaway root, with the endpoint
+// census a two-way bijection with the handler's own `VERIFF_IMPLEMENTED_ENDPOINTS`.
+//
+// Two failure shapes this deliberately does NOT fall for, both recorded because both are checks
+// that look plausible and cannot fail:
+//
+//   • Two constants asserting about each other. A hand-written "implemented" array compared against
+//     hand-written expectations in the same file stays green when the entire router is deleted.
+//   • Probing, but grading only "not the router's own miss". Sub-handlers fall through to their own
+//     404, so a whole method branch can be deleted while the probe still looks dispatched.
+//
+// So every probe SEEDS the subjects its path params need — against its OWN fresh root, because the
+// inventory contains destructive routes (PATCH submits, DELETE removes, media upload is refused
+// after submit) and a shared root would have the sweep destroy its own fixtures partway through and
+// reinstate exactly the blind spot the seeding exists to remove. A resource-404 is therefore never
+// a legitimate outcome here: every 404 means the route (or its method branch) is gone.
+//
+// NEGATIVE CONTROLS close the other direction. Without them a behaviourally-dead twin that answered
+// a flat 200 to everything would satisfy "every declared route dispatched" perfectly. Each control
+// is a REAL Veriff endpoint this pack deliberately does not model yet (plus one invented path), and
+// each must report as unmodeled.
+//
+// The honest limit: this proves the routing table and each branch's outcome shape are intact. It
+// does NOT prove the payloads match Veriff field-for-field — that is what the capability manifest's
+// failable verifies and the real-transport fidelity test are for.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleVeriffTwinRequest, TWIN_API_KEY, TWIN_SHARED_SECRET, VERIFF_IMPLEMENTED_ENDPOINTS, VERIFF_RESOURCE_TYPES } from "./veriff-twin.js";
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, veriffSignature } from "./veriff-signature.js";
+/** A monotonic instant source. The kernel dedupes actions by content + MILLISECOND, so re-seeding
+ *  with one fixed timestamp would have later seeds silently swallowed as replays. */
+let tick = 0;
+function nextInstant() {
+    return new Date(Date.UTC(2026, 7, 1, 0, 0, 0, tick++ % 1000)).toISOString();
+}
+const PNG = 'data:image/jpeg;base64,aGVsbG8td29ybGQ=';
+/** Drive one request with correct auth + a correctly-computed signature, so no probe can be masked
+ *  by a 401 that has nothing to do with routing. */
+async function call(handler, root, method, path, body) {
+    const raw = body === undefined ? '' : JSON.stringify(body);
+    const bare = path.split('?')[0] ?? path;
+    const segments = bare.replace(/^\/v1\/?/, '').replace(/^\/+/, '').split('/');
+    const payload = method === 'GET' || method === 'DELETE' ? (segments[1] ?? '') : raw;
+    return handler({
+        method,
+        path,
+        ...(body === undefined ? {} : { body: raw }),
+        headers: { [AUTH_CLIENT_HEADER]: TWIN_API_KEY, [HMAC_SIGNATURE_HEADER]: veriffSignature(payload, TWIN_SHARED_SECRET) },
+        root,
+        occurredAt: nextInstant(),
+    });
+}
+/** Build a fresh root carrying every fixture the probes address. */
+async function seed(handler) {
+    const root = mkdtempSync(join(tmpdir(), 'veriff-conf-'));
+    const open = await call(handler, root, 'POST', '/v1/sessions', { verification: { vendorData: 'conformance', callback: 'https://example.test/hook' } });
+    const sessionId = String(open.body?.verification?.id ?? '');
+    const up = await call(handler, root, 'POST', `/v1/sessions/${sessionId}/media`, { image: { context: 'document-front', content: PNG } });
+    const mediaId = String(up.body?.image?.id ?? '');
+    const second = await call(handler, root, 'POST', '/v1/sessions', { verification: { vendorData: 'conformance-decided' } });
+    const decidedSessionId = String(second.body?.verification?.id ?? '');
+    await call(handler, root, 'PATCH', `/v1/sessions/${decidedSessionId}`, { verification: { status: 'submitted' } });
+    const decided = await call(handler, root, 'POST', `/v1/_twin/sessions/${decidedSessionId}/decision`, { status: 'approved', person: { firstName: 'JOHN', lastName: 'SMITH' } });
+    const attemptId = String(decided.body?.verification?.attemptId ?? '');
+    return { root, sessionId, decidedSessionId, attemptId, mediaId };
+}
+const PROBES = [
+    {
+        endpoint: 'POST /v1/sessions',
+        run: (s, h) => call(h, s.root, 'POST', '/v1/sessions', { verification: { vendorData: 'probe' } }),
+        status: 201,
+        ok: (b) => b?.status === 'success' && typeof b?.verification?.id === 'string' && b.verification.vendorData === 'probe',
+    },
+    {
+        endpoint: 'PATCH /v1/sessions/{sessionId}',
+        run: (s, h) => call(h, s.root, 'PATCH', `/v1/sessions/${s.sessionId}`, { verification: { status: 'submitted' } }),
+        status: 200,
+        ok: (b) => b?.verification?.status === 'submitted',
+    },
+    {
+        endpoint: 'DELETE /v1/sessions/{sessionId}',
+        run: (s, h) => call(h, s.root, 'DELETE', `/v1/sessions/${s.sessionId}`),
+        status: 200,
+        ok: (b) => b?.status === 'success' && typeof b?.verification?.id === 'string',
+    },
+    {
+        endpoint: 'GET /v1/sessions/{sessionId}/decision',
+        run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.decidedSessionId}/decision`),
+        status: 200,
+        ok: (b) => b?.verification?.status === 'approved' && b.verification.code === 9001,
+    },
+    {
+        endpoint: 'GET /v1/sessions/{sessionId}/person',
+        run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.decidedSessionId}/person`),
+        status: 200,
+        ok: (b) => b?.person?.firstName === 'JOHN',
+    },
+    {
+        endpoint: 'GET /v1/sessions/{sessionId}/attempts',
+        run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.decidedSessionId}/attempts`),
+        status: 200,
+        ok: (b) => Array.isArray(b?.verifications) && b.verifications.length === 1 && b.verifications[0].status === 'approved',
+    },
+    {
+        endpoint: 'GET /v1/sessions/{sessionId}/media',
+        run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.sessionId}/media`),
+        status: 200,
+        ok: (b) => Array.isArray(b?.images) && b.images.length === 1 && b.images[0].context === 'document-front',
+    },
+    {
+        endpoint: 'POST /v1/sessions/{sessionId}/media',
+        run: (s, h) => call(h, s.root, 'POST', `/v1/sessions/${s.sessionId}/media`, { image: { context: 'face', content: PNG } }),
+        // 200 — the media endpoint declares exactly one success response and it is not 201 (the
+        // status-code table's 201 row is scoped to SESSION creation).
+        status: 200,
+        ok: (b) => b?.image?.context === 'face' && typeof b?.image?.id === 'string',
+    },
+    {
+        endpoint: 'GET /v1/attempts/{attemptId}/media',
+        run: (s, h) => call(h, s.root, 'GET', `/v1/attempts/${s.attemptId}/media`),
+        status: 200,
+        ok: (b) => Array.isArray(b?.images) && Array.isArray(b?.videos) && Array.isArray(b?.nfcDocuments),
+    },
+    {
+        endpoint: 'GET /v1/media/{mediaId}',
+        run: (s, h) => call(h, s.root, 'GET', `/v1/media/${s.mediaId}`),
+        status: 200,
+        ok: (b) => typeof b?.content === 'string' && b.mimetype === 'image/jpeg',
+    },
+];
+/**
+ * REAL Veriff endpoints this pack does not model yet (each a filed `todo` in the manifest), plus one
+ * invented path. Every one must come back as the unmodeled 404 — if any answers, the sweep above is
+ * measuring nothing.
+ */
+const CONTROLS = [
+    // Veriff has NO `GET /v1/sessions/{id}` — the reference index lists only POST/PATCH/DELETE on
+    // that path. Serving one would be an INVENTED op, so it is a control, not a probe.
+    { label: 'GET /v1/sessions/{id} (no such Veriff endpoint)', run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.sessionId}`) },
+    { label: 'GET /v1/sessions/{id}/watchlist-screening', run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.decidedSessionId}/watchlist-screening`) },
+    { label: 'PATCH /v1/sessions/{id}/watchlist-screening', run: (s, h) => call(h, s.root, 'PATCH', `/v1/sessions/${s.decidedSessionId}/watchlist-screening`, { monitorStatus: 'disabled' }) },
+    { label: 'POST /v1/sessions/{id}/collected-data', run: (s, h) => call(h, s.root, 'POST', `/v1/sessions/${s.sessionId}/collected-data`, { providerName: 'x' }) },
+    { label: 'POST /v1/faces/import', run: (s, h) => call(h, s.root, 'POST', '/v1/faces/import', { images: [] }) },
+    { label: 'POST /v1/validate-registry', run: (s, h) => call(h, s.root, 'POST', '/v1/validate-registry', {}) },
+    // The reference index spells the same unmodeled endpoint differently; BOTH must be unmodeled,
+    // or the twin half-answers a surface it does not implement. Note this one also has to survive
+    // the router's session lookup (`/sessions/<x>` with x='validate-registry'), which is exactly the
+    // kind of accidental dispatch a control is for.
+    { label: 'POST /v1/sessions/validate-registry (index spelling)', run: (s, h) => call(h, s.root, 'POST', '/v1/sessions/validate-registry', {}) },
+    { label: 'GET /v1/sessions/{id}/decision/ine-registry', run: (s, h) => call(h, s.root, 'GET', `/v1/sessions/${s.decidedSessionId}/decision/ine-registry`) },
+    { label: 'POST /v1/sessions/{id}/TOTALLY-FAKE (invented)', run: (s, h) => call(h, s.root, 'POST', `/v1/sessions/${s.sessionId}/TOTALLY-FAKE`, {}) },
+];
+export async function checkVeriffConformance(opts = {}) {
+    void opts.root; // every probe runs against its OWN throwaway root — see the header
+    const handler = opts.handler ?? handleVeriffTwinRequest;
+    const violations = [];
+    // ── census: a two-way bijection with the handler's own inventory ───────────
+    const declared = new Set(VERIFF_IMPLEMENTED_ENDPOINTS);
+    const probed = new Set(PROBES.map((p) => p.endpoint));
+    for (const e of declared)
+        if (!probed.has(e))
+            violations.push(`endpoint declared in VERIFF_IMPLEMENTED_ENDPOINTS but never probed: ${e}`);
+    for (const e of probed)
+        if (!declared.has(e))
+            violations.push(`probe for an endpoint the handler does not declare: ${e}`);
+    if (probed.size !== PROBES.length)
+        violations.push('duplicate endpoint in PROBES');
+    // ── the live sweep ────────────────────────────────────────────────────────
+    let routesDispatched = 0;
+    for (const probe of PROBES) {
+        const s = await seed(handler);
+        try {
+            const res = await probe.run(s, handler);
+            if (res.status !== probe.status) {
+                violations.push(`${probe.endpoint}: expected status ${probe.status}, got ${res.status} (${JSON.stringify(res.body).slice(0, 160)})`);
+                continue;
+            }
+            if (!probe.ok(res.body)) {
+                violations.push(`${probe.endpoint}: status ${res.status} but the body predicate failed (${JSON.stringify(res.body).slice(0, 160)})`);
+                continue;
+            }
+            routesDispatched += 1;
+        }
+        finally {
+            rmSync(s.root, { recursive: true, force: true });
+        }
+    }
+    // ── negative controls ─────────────────────────────────────────────────────
+    let controlsRejected = 0;
+    const controlSeed = await seed(handler);
+    try {
+        for (const control of CONTROLS) {
+            const res = await control.run(controlSeed, handler);
+            const body = res.body;
+            if (res.status === 404 && body?.status === 'fail' && body?.code === '1101')
+                controlsRejected += 1;
+            else
+                violations.push(`negative control ANSWERED (this twin does not model it): ${control.label} → ${res.status} ${JSON.stringify(res.body).slice(0, 120)}`);
+        }
+    }
+    finally {
+        rmSync(controlSeed.root, { recursive: true, force: true });
+    }
+    // ── structural: every projected resource type is produced by some route ───
+    const produced = new Set(['session', 'attempt', 'media', 'delivery']);
+    for (const t of VERIFF_RESOURCE_TYPES) {
+        if (!produced.has(t))
+            violations.push(`resource type ${t} is projected but no modeled route produces it`);
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: PROBES.length,
+        resourceTypesChecked: VERIFF_RESOURCE_TYPES.length,
+        routesDispatched,
+        controlsRejected,
+        violations,
+    };
+}

package/dist/src/veriff-connector.d.ts

@@ -0,0 +1,133 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { VeriffBudget, type VeriffBudgetOptions } from './veriff-budget.js';
+/**
+ * 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 declare function liveVeriffExecute(apiKey: string, sharedSecret: string, opts?: LiveVeriffOptions): VeriffExecute;
+/**
+ * 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 declare function signaturePayloadFor(method: string, path: string, serializedBody?: string): string;
+/** Map a decision document → a `session` SyncResource. */
+export declare function mapSessionDecision(v: Record<string, any>): SyncResource;
+/** Map one attempt row (`GET /v1/sessions/{id}/attempts` → `verifications[]`) → a SyncResource. */
+export declare function mapSessionAttempt(sessionId: string, a: Record<string, any>): SyncResource;
+/** Map one media object → a SyncResource. `kind` separates the images/videos/nfcDocuments buckets
+ *  the media endpoints split their response into. */
+export declare function mapSessionMedia(sessionId: string, m: Record<string, any>, kind: 'image' | 'video' | 'nfc'): SyncResource;
+/** PULL decisions for known session ids into the twin's observed log (idempotent). */
+export declare function pullVeriffDecisions(execute: VeriffExecute, sessionIds: readonly string[], root?: string, occurredAt?: string): Promise<number>;
+/** PULL the attempt history for known session ids (idempotent). */
+export declare function pullVeriffAttempts(execute: VeriffExecute, sessionIds: readonly string[], root?: string, occurredAt?: string): Promise<number>;
+/** PULL media METADATA for known session ids (idempotent). The bytes are not pulled — see the
+ *  `veriff.media.pull_bytes` todo. */
+export declare function pullVeriffMedia(execute: VeriffExecute, sessionIds: readonly string[], root?: string, occurredAt?: string): Promise<number>;
+/**
+ * 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 declare function syncVeriffFromReal(execute: VeriffExecute, opts?: {
+    sessionIds?: readonly string[];
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** 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 declare function veriffRequestForAction(action: TwinAction): {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: Record<string, unknown>;
+} | 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 declare function pushPendingVeriffActions(execute: VeriffExecute, root?: string, occurredAt?: string): Promise<number>;
+/** 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 declare function veriffExecuteOver(execute: RemoteExecute): VeriffExecute;
+/**
+ * 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 declare function syncVeriffFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+    sessionIds?: readonly string[];
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * 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 declare function performVeriffAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;