@volter/twin-veriff 0.1.0

package/src/veriff-conformance.ts

@@ -0,0 +1,264 @@
+// 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, type VeriffRequest, type VeriffResponse } from './veriff-twin.ts';
+import { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, veriffSignature } from './veriff-signature.ts';
+
+export type VeriffConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  resourceTypesChecked: number;
+  routesDispatched: number;
+  controlsRejected: number;
+  violations: string[];
+};
+
+/** The seeded fixture ids a probe can address. */
+type Seed = { root: string; sessionId: string; decidedSessionId: string; attemptId: string; mediaId: string };
+
+/** 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(): string {
+  return new Date(Date.UTC(2026, 7, 1, 0, 0, 0, tick++ % 1000)).toISOString();
+}
+
+const PNG = 'data:image/jpeg;base64,aGVsbG8td29ybGQ=';
+
+/**
+ * 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>;
+
+/** 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: VeriffHandler, root: string, method: string, path: string, body?: unknown): Promise<VeriffResponse> {
+  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: VeriffHandler): Promise<Seed> {
+  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 as any)?.verification?.id ?? '');
+  const up = await call(handler, root, 'POST', `/v1/sessions/${sessionId}/media`, { image: { context: 'document-front', content: PNG } });
+  const mediaId = String((up.body as any)?.image?.id ?? '');
+
+  const second = await call(handler, root, 'POST', '/v1/sessions', { verification: { vendorData: 'conformance-decided' } });
+  const decidedSessionId = String((second.body as any)?.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 as any)?.verification?.attemptId ?? '');
+  return { root, sessionId, decidedSessionId, attemptId, mediaId };
+}
+
+type Probe = {
+  /** The census key — must match a `VERIFF_IMPLEMENTED_ENDPOINTS` entry exactly. */
+  endpoint: (typeof VERIFF_IMPLEMENTED_ENDPOINTS)[number];
+  run: (s: Seed, h: VeriffHandler) => Promise<VeriffResponse>;
+  /** The status a LIVE handler answers with. A 404 is never in this set (see the header). */
+  status: number;
+  /** A predicate over the body that a `return {}` handler cannot satisfy. */
+  ok: (body: any) => boolean;
+};
+
+const PROBES: Probe[] = [
+  {
+    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: { label: string; run: (s: Seed, h: VeriffHandler) => Promise<VeriffResponse> }[] = [
+  // 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: { root?: string; handler?: VeriffHandler } = {}): Promise<VeriffConformanceReport> {
+  void opts.root; // every probe runs against its OWN throwaway root — see the header
+  const handler: VeriffHandler = opts.handler ?? handleVeriffTwinRequest;
+  const violations: string[] = [];
+
+  // ── census: a two-way bijection with the handler's own inventory ───────────
+  const declared = new Set<string>(VERIFF_IMPLEMENTED_ENDPOINTS);
+  const probed = new Set(PROBES.map((p) => p.endpoint));
+  for (const e of declared) if (!probed.has(e as any)) 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 as any)) {
+        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 as { status?: string; code?: string };
+      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,
+  };
+}