@volter/twin-veriff 0.1.0

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

@@ -0,0 +1,55 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const VERIFF_BUDGET_WINDOW_MS = 60000;
+/**
+ * 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 declare 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 declare 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 declare const VERIFF_CALL_WEIGHTS: {
+    /** `DELETE /sessions/{id}` — documented at 5/hour + 10/day, which a 60s window cannot express. */
+    readonly deleteSession: 12;
+    /** Everything else: session create (the documented 30/min tier), decision/attempt/media reads. */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, the only Veriff-specific thing in the whole budget. */
+export declare const VERIFF_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * 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 declare function veriffCallWeight(method: string, path: string): number;
+/** 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 declare function veriffBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** 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 declare class VeriffBudget extends RateBudget {
+    constructor(opts?: VeriffBudgetOptions);
+}
+/** 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;

package/dist/src/veriff-budget.js

@@ -0,0 +1,151 @@
+// 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, } 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,
+};
+/** THE PACK'S DECLARATION — pure data, the only Veriff-specific thing in the whole budget. */
+export const VERIFF_RATE_BUDGET = {
+    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, path) {
+    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) {
+    const at = path.indexOf('?');
+    const query = {};
+    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 = {}) {
+    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 });
+}
+/**
+ * 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 = {}) {
+        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';

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

@@ -0,0 +1,10 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+/**
+ * The AREA CENSUS — enumerated TOP-DOWN from Veriff's own documentation navigation (the
+ * `llms.txt` index: API reference groups + one page per solution), NOT derived from the manifest
+ * below. Deriving it from the manifest would make the bijection check a tautology; the point is
+ * that a whole Veriff product area cannot silently vanish from the denominator.
+ */
+export declare const VERIFF_AREAS: readonly ["sessions", "decisions", "attempts", "person", "media", "auth", "webhooks", "errors", "watchlist", "idv", "proof_of_address", "database_verification", "fraud", "collected_data", "faces", "registry", "platform", "sdk", "connector"];
+export declare const VERIFF_CAPABILITIES: CapabilitySpec[];
+export declare function veriffCapabilities(): Promise<CapabilityReport>;