@volter/twin-veriff 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@volter/twin-veriff",
+  "version": "0.1.0",
+  "description": "Local Veriff identity-verification twin — a faithful, stateful local stationapi.veriff.com/v1 your KYC integration talks to unmodified: sessions, the decision lifecycle, HMAC-signed decision/event webhooks, attempts, media and watchlist screening. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "api",
+    "veriff",
+    "identity-verification",
+    "kyc",
+    "aml",
+    "webhooks"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/veriff"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/veriff#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-veriff": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-veriff CLI: serve the Veriff Station API twin, or run conformance.
+//
+// No `mirror` command: Veriff is an API-first vendor (the integrator's work is code — create a
+// session, embed the hosted flow, receive the decision webhook), so this pack ships no React
+// mirror. See README.md `## Coverage` → `### No UI mirror`.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createVeriffTwinServer } from './veriff-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const sharedSecret = optionValue(rest, '--shared-secret') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve') {
+  const s = await createVeriffTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(sharedSecret ? { sharedSecret } : {}) });
+  process.stdout.write(`veriff twin (Station API v1)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+  const { checkVeriffConformance } = await import('./veriff-conformance.ts');
+  const report = await checkVeriffConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-veriff serve|conformance [--port N] [--root DIR] [--shared-secret S] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,172 @@
+// @volter/twin-veriff — the Veriff identity-verification twin (one vendor, one package), built on
+// the shared @volter/world-core kernel. REST transport over Veriff's Station API
+// (`https://stationapi.veriff.com/v1`), a stateful session→attempt→decision lifecycle, REAL
+// `X-HMAC-SIGNATURE` request signing and HMAC-signed decision/event webhooks.
+//
+// Veriff publishes NO server-side SDK — a real integration hand-rolls a `fetch` client (the
+// reference consumer, dub, does exactly that in `apps/web/lib/veriff/client.ts`) — so this pack
+// declares no vendor devDependency and proves fidelity over real-transport `fetch` instead.
+//
+// NO React mirror: Veriff is an API-first vendor for the party that integrates it (create a
+// session, embed the hosted flow, receive the decision webhook, read the decision). See
+// README.md `## Coverage` → `### No UI mirror`. Coverage = API + connector.
+// (Conformance/capability tooling lives in @volter/world-tooling, a dev dependency.)
+export {
+  handleVeriffTwinRequest,
+  TWIN_API_KEY,
+  TWIN_SHARED_SECRET,
+  VERIFF_DECISION_CODES,
+  VERIFF_DECISION_STATUSES,
+  VERIFF_ERROR_CODES,
+  VERIFF_ERROR_MESSAGES,
+  VERIFF_EVENT_CODES,
+  VERIFF_IMPLEMENTED_ENDPOINTS,
+  VERIFF_RESOURCE_TYPES,
+  VERIFF_SESSION_STATUSES,
+} from './veriff-twin.ts';
+export type { VeriffRequest, VeriffResponse, VeriffSessionStatus, VeriffDecisionStatus } from './veriff-twin.ts';
+export { createVeriffTwinFetch, createVeriffTwinServer, veriffResponseHeaders, type VeriffTwinFetchOptions } from './veriff-server.ts';
+export {
+  AUTH_CLIENT_HEADER,
+  HMAC_SIGNATURE_HEADER,
+  signaturesMatch,
+  veriffSignature,
+  veriffSignatureBytes,
+  verifyVeriffSignature,
+} from './veriff-signature.ts';
+export {
+  buildSignedDelivery,
+  emitVeriffWebhook,
+  VERIFF_EVENT_ACTIONS,
+  verifyWebhook,
+  VeriffWebhookVerificationError,
+} from './veriff-events.ts';
+export type { VeriffDecisionPayload, VeriffEventAction, VeriffEventPayload, VeriffWebhookDelivery, VeriffWebhookPayload } from './veriff-events.ts';
+export {
+  liveVeriffExecute,
+  mapSessionDecision,
+  mapSessionAttempt,
+  mapSessionMedia,
+  pullVeriffAttempts,
+  pullVeriffDecisions,
+  pullVeriffMedia,
+  pushPendingVeriffActions,
+  signaturePayloadFor,
+  syncVeriffFromReal,
+  veriffRequestForAction,
+} from './veriff-connector.ts';
+export type { LiveVeriffOptions, VeriffExecute } from './veriff-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveVeriffExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Veriff's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `VeriffBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  VERIFF_BUDGET_CEILING,
+  VERIFF_BUDGET_MAX_RETRY_AFTER_S,
+  VERIFF_BUDGET_WINDOW_MS,
+  VERIFF_CALL_WEIGHTS,
+  VERIFF_RATE_BUDGET,
+  VeriffBudget,
+  VeriffBudgetError,
+  veriffBudgetPath,
+  veriffCallWeight,
+} from './veriff-budget.ts';
+export type { VeriffBudgetErrorKind, VeriffBudgetOptions, VeriffBudgetReservation, VeriffBudgetSnapshot } from './veriff-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { signaturePayloadFor } from './veriff-connector.ts';
+import { HMAC_SIGNATURE_HEADER } from './veriff-signature.ts';
+import { performVeriffAction, syncVeriffFromRemote } from './veriff-connector.ts';
+import { VERIFF_RATE_BUDGET as RATE_BUDGET } from './veriff-budget.ts';
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system. Moved 2026-09-08.
+  protocol: '2',
+  // Veriff DOES publish webhooks (the decision callback is the whole integration), so a world that
+  // wires them hears about a decision as it lands; the poll is the backstop for one that has not.
+  refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performVeriffAction, refresh: syncVeriffFromRemote },
+  // The round trip is a session create — Veriff's own write, and the vendor mints a fresh id for
+  // every one, so a second send on a branch is a second session rather than a collision.
+  roundTrip: { method: 'POST', path: '/v1/sessions', body: { verification: { vendorData: 'round-trip' } }, headers: { 'x-auth-client': 'round-trip' } },
+  // Veriff signs EVERY call but one: `X-HMAC-SIGNATURE` over the request body for a write, and over
+  // the resource id in the path for a GET/DELETE. `signaturePayloadFor` is the pack's own pure
+  // statement of which bytes those are — it takes no secret, so the secret stays in the kernel
+  // (docs/concepts/the-model.md#the-rules, rule 5, "the secret never crossing into pack code").
+  //
+  // TWO THINGS THIS LINE HAS TO GET RIGHT, both measured against the pack's live executor:
+  //   • `POST /sessions` is the one endpoint the vendor EXEMPTS from signing — there is no session
+  //     to sign for yet — so the canonical answers `null` and the request goes out unsigned.
+  //   • `signaturePayloadFor` reads the resource id POSITIONALLY out of a path with no version
+  //     prefix (`/sessions/{id}` → the id). The kernel sends `/v1/...`, so the prefix comes off
+  //     first; signing `sessions` instead of the session id would verify against nothing.
+  auth: {
+    in: 'signature',
+    algorithm: 'hmac-sha256',
+    encoding: 'hex',
+    header: HMAC_SIGNATURE_HEADER,
+    canonical: ({ method, path, body }) => {
+      const bare = path.replace(/^\/v1(?=\/|$)/, '');
+      if (method === 'POST' && bare === '/sessions') return null;
+      return signaturePayloadFor(method, bare, body);
+    },
+  },
+  parityOrigin: 'http://twin',
+
+  vendor: 'veriff',
+  // The SAME object veriff-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-veriff',
+  resources: ['session', 'attempt', 'media', 'delivery'],
+  specSource: 'docs.veriff.com / devdocs.veriff.com (hand-authored from the published Station API reference), cross-checked against the real consumer dub (apps/web/lib/veriff/*, app/api/veriff/webhook/*)',
+  description: 'Veriff Station API twin — sessions, the created→submitted→approved/declined decision lifecycle, HMAC-signed request auth and decision/event webhooks, attempts and media. Watchlist/AML screening is a filed todo area, deliberately unmodeled.',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  //
+  // Veriff publishes NO server-side SDK — a real integration hand-rolls a `fetch` client against
+  // the Station API (the reference consumer, dub, does exactly that in
+  // apps/web/lib/veriff/client.ts) — so the only npm package that is genuinely a CLIENT OF THE
+  // MODELED SURFACE is `@veriff/js-sdk`: v2.0.0's `createSession` XHRs `POST {host}/v1/sessions`
+  // straight from the browser with `x-auth-client`, and its `host` is a constructor option, so
+  // pointing it at a twin is configuration. Its siblings are covered by the `@veriff/` SCOPE
+  // rather than listed as sdks, because they are NOT API clients: `@veriff/incontext-sdk` makes
+  // ZERO network calls of its own (verified against the published v2.5.0 bundle: no fetch, no
+  // XMLHttpRequest, no hardcoded URL) — it iframes the session `url` the API already returned and
+  // listens for postMessage — and the react-native/Cordova packages launch the native capture
+  // flow. Listing them as sdks would claim the twin intercepts traffic they never send; leaving
+  // them out of the scope entirely would report the exact package the reference consumer installs
+  // as unknown-sdk.
+  //
+  // VERIFF_API_KEY is the credential that stems here — the name the reference consumer uses
+  // verbatim (dub's apps/web/.env.example). Its sibling VERIFF_SHARED_SECRET deliberately does
+  // NOT: it stems to `veriffshared` under the broad suffix list (`_SECRET` splits before
+  // `SHARED`), and it matches no STRICT suffix at all, so it never reaches the lookup and cannot
+  // raise a false unknown-vendor alarm either.
+  adoption: {
+    // Veriff ships no Python SDK - its clients are the JS `@veriff/js-sdk` and the raw REST API.
+    pypi: [],
+    sdks: ['@veriff/js-sdk'], scopes: ['@veriff/'], envStems: ['VERIFF'],
+  },
+  // The API URL is ACCOUNT-SPECIFIC by design — Veriff's reference tells you to read your BaseURL
+  // off the Customer Portal and its OpenAPI `servers` entry is the placeholder
+  // `https://example-base-url` — so BOTH hosts that appear in official material are routed: the
+  // reference consumer and the media code samples use `stationapi.veriff.com`, while
+  // `@veriff/js-sdk` v2.0.0 compiles in `api.veriff.me` as its default. Deliberately EXACT
+  // matches, not a `.veriff.com`/`.veriff.me` suffix: `magic.veriff.me` and `alchemy.veriff.com`
+  // serve the HOSTED end-user capture flow (Veriff's own first-party web app; the twin returns a
+  // real session `url` rather than rendering it), `cdn.veriff.me` serves the browser SDK bundles,
+  // and `feedback.api.veriff.com` is the separate Fraud API with its own VRF-* header scheme that
+  // this pack does not model. Routing any of those into the twin would intercept requests it
+  // cannot answer.
+  hosts: [{ host: 'stationapi.veriff.com' }, { host: 'api.veriff.me' }],
+  // A Veriff client calls stationapi.veriff.com/v1/… — the dev proxy forwards '/v1/' to the twin
+  // and strips the absolute host so calls come back same-origin.
+  browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://stationapi.veriff.com' },
+};
+
+registerPack(pack);

package/src/veriff-budget.ts

@@ -0,0 +1,177 @@
+// Veriff's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveVeriffExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice). This module
+// is modeled on calcom-budget.ts, the reference "the pack builds its own HTTP client" shape.
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not. For an identity vendor the stakes are not
+// only the lockout: every session created is a BILLED verification against a real end user.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// Veriff DOES publish scalar limits — unusually — but not in the API reference. Two, both read
+// 2026-08-20:
+//
+//   • devdocs.veriff.com/docs/general-faq, "How many sessions can I create per minute?":
+//       "Enterprise customer: 600 sessions per minute" / "Self-Serve customer: 30 sessions per
+//       minute".
+//   • devdocs.veriff.com/apidocs/v1sessionsid-3 (DELETE /v1/sessions/{id}), "Rate limiting":
+//       "This endpoint is rate limited: 10 sessions per 24 hours and 5 sessions per 1 hour".
+//
+// The ceiling is pinned to the SELF-SERVE tier, because a pack cannot know which contract the
+// credential in front of it is on and the enterprise number is not a floor anyone is entitled to.
+// 60 weighted units / 60s at the default weight of 2 is 30 calls a minute — exactly the documented
+// self-serve session ceiling, and identical to the kernel's undeclared fallback. Being MORE
+// permissive would require a documented number that applies to every account, and there isn't one.
+//
+// Veriff publishes NO limit at all for the read endpoints (decision polling, attempts, media), so
+// those are not widened either: they spend from the same conservative allowance rather than being
+// declared free on the strength of an absence.
+//
+// ── WHAT THIS DOES NOT DO: PACE ─────────────────────────────────────────────────────────────
+// It bounds the 60s AVERAGE; it does NOT bound the instantaneous rate. In a tight `await` loop the
+// vendor's own 429 can arrive first, and the backstop is then the COOLDOWN armed from that
+// response. Veriff documents its 429 body (`{"status":"fail","code":"1004","message":"Too many
+// requests."}`) but documents NO `Retry-After` and NO `X-RateLimit-*` response headers — checked
+// across the whole published reference. The kernel reads those headers IF PRESENT and never assumes
+// them; on a bare 429 the cooldown still arms. Do not read the header names below as a vendor fact.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ──────────────────────────────
+//   • `POST /sessions` costs the default 2 — the faithful price, since 30/min at weight 2 is
+//     exactly the documented self-serve cap.
+//   • `DELETE /sessions/{id}` costs 12, so one window admits 5 rather than 30. That is a JUDGEMENT
+//     CALL standing in for a cap this ledger structurally cannot enforce: the documented limit is
+//     5 per HOUR and 10 per 24 HOURS, and a 60-second rolling window cannot express either. What
+//     weight 12 buys is that a delete LOOP is stopped inside the first window instead of burning
+//     the whole daily allowance in seconds; staying under 5/hour remains the caller's
+//     responsibility, and this module says so rather than implying enforcement it does not have.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'veriff';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const VERIFF_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s = 30 calls a minute at the default weight —
+ * exactly Veriff's documented SELF-SERVE session-creation cap, and no more permissive than the
+ * kernel's undeclared fallback.
+ */
+export const VERIFF_BUDGET_CEILING = 60;
+
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly, don't
+ *  sleep. Veriff documents no `Retry-After`; this caps one if a live response ever carries it. */
+export const VERIFF_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const VERIFF_CALL_WEIGHTS = {
+  /** `DELETE /sessions/{id}` — documented at 5/hour + 10/day, which a 60s window cannot express. */
+  deleteSession: 12,
+  /** Everything else: session create (the documented 30/min tier), decision/attempt/media reads. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Veriff-specific thing in the whole budget. */
+export const VERIFF_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: VERIFF_BUDGET_WINDOW_MS,
+  ceiling: VERIFF_BUDGET_CEILING,
+  defaultWeight: VERIFF_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: VERIFF_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^DELETE /sessions/', weight: VERIFF_CALL_WEIGHTS.deleteSession },
+  ],
+  reason:
+    'Veriff publishes two scalar limits, neither of them in the API reference (both read 2026-08-20). ' +
+    'devdocs.veriff.com/docs/general-faq: "Enterprise customer: 600 sessions per minute", "Self-Serve ' +
+    'customer: 30 sessions per minute". devdocs.veriff.com/apidocs/v1sessionsid-3 (DELETE ' +
+    '/v1/sessions/{id}): "This endpoint is rate limited: 10 sessions per 24 hours and 5 sessions per ' +
+    '1 hour". The ceiling is pinned to the SELF-SERVE tier — 60 weighted units / 60s at defaultWeight ' +
+    '2 = 30 calls a minute, exactly that documented cap — because a pack cannot know which contract ' +
+    "the credential in front of it is on, and the enterprise number is not a floor anyone is " +
+    'entitled to. That is also identical to the kernel\'s undeclared fallback, so this declaration ' +
+    'buys weighting, not permission. Veriff publishes NO limit for the read endpoints (decision ' +
+    'polling, attempts, media), so those are not widened on the strength of an absence. DELETE costs ' +
+    '12 so one window admits 5 rather than 30 — a JUDGEMENT CALL, not a published cost: the real cap ' +
+    'is 5/hour and 10/day, which a 60-second rolling window structurally cannot enforce, so staying ' +
+    "under it remains the caller's responsibility and the weight only stops a delete LOOP inside the " +
+    'first window. Veriff documents its 429 body ({"status":"fail","code":"1004","message":"Too many ' +
+    'requests."}) but NO Retry-After and NO X-RateLimit-* response headers anywhere in the published ' +
+    'reference; the kernel reads those names if present and never assumes them, and a bare 429 still ' +
+    'arms the cooldown.',
+};
+
+// Declared at module load, so merely importing this module (which `veriff-connector.ts` does) is
+// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
+// takes effect the moment it lands, and constructing through the subclass below (which imports this
+// module) is what makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, VERIFF_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` (the v1 path as the connector states it, without
+ * the `/v1` prefix the live executor adds) with the query string split off.
+ *
+ * NORMALIZED: `fetch` upper-cases a known method before sending, so `execute('delete', …)` really
+ * does issue a DELETE and must be priced as one; and a trailing slash otherwise makes a path miss
+ * an anchored rule while every router treats it as the same endpoint. Both are input variations,
+ * not attacks, and either one silently voids the "expensive endpoints are priced up" claim.
+ */
+export function veriffCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/** `/x?a=1` -> `{ bare: '/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the query. */
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where Veriff's ledger lives. Token-keyed and cwd-independent by default (the limits are per
+ *  integration/API key, so a cwd-scoped ledger would hand the same key a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function veriffBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for Veriff's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type VeriffBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Veriff's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof VeriffBudget` in `liveVeriffExecute` means "a budget that
+ * accounts against VERIFF's ledger under VERIFF's ceiling": another vendor's `RateBudget` (with its
+ * own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class VeriffBudget extends RateBudget {
+  constructor(opts: VeriffBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as VeriffBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as VeriffBudgetErrorKind } from '@volter/world-core';
+export type VeriffBudgetReservation = RateBudgetReservation;
+export type VeriffBudgetSnapshot = RateBudgetSnapshot;