@volter/twin-veriff 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,247 @@
+# @volter/twin-veriff
+
+A local, stateful, vendor-faithful twin of **Veriff's Public API v1** — the identity-verification
+Station API (`stationapi.veriff.com` / `api.veriff.me`). Point your unmodified KYC client at it and
+get vendor-correct responses — sessions, the `created → submitted → approved/declined` decision
+lifecycle, HMAC-signed decision and event webhooks, attempts, media and the vendor's exact error
+envelope — entirely offline, with no real API key, no real end user and no billed verification.
+Built on the shared [`@volter/world-core`](../../..) kernel; see [the model](../../../docs/concepts/the-model.md) for storage and branching, not an
+ad-hoc mock.
+
+**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`.
+Two hosts appear in official material — `stationapi.veriff.com` (the media code samples, and the
+real consumer) and `api.veriff.me` (`@veriff/js-sdk` v2.0.0's compiled default) — and the injection
+map routes **both** here. The paths are identical either way.
+
+**The HMAC is real, not faked.** `X-AUTH-CLIENT` is accepted-but-never-checked (a twin fakes auth
+locally), but `X-HMAC-SIGNATURE` is verified for real, including the vendor's asymmetric payload
+rule: **POST/PATCH sign the request body; GET/DELETE sign the resource id in the path** — the
+*attempt* id for `/v1/attempts/{id}/media`, the *media* id for `/v1/media/{id}`. The implementation
+is pinned against **Veriff's own published mock vector**, and responses carry the documented
+`X-AUTH-CLIENT` + `X-HMAC-SIGNATURE` sender headers, so a consumer that authenticates the sender
+gets the real thing.
+
+## Usage
+
+```bash
+# serve the twin (writable by default; --read-only to reject writes with 405)
+bun packages/twin/veriff/src/cli.ts serve --port 8123
+
+# check the routing table against the handler (dev-only)
+bun packages/twin/veriff/src/cli.ts conformance
+```
+
+Point a client at it exactly as you would at Veriff — the reference consumer's shape:
+
+```ts
+const res = await fetch('http://127.0.0.1:8123/v1/sessions', {
+  method: 'POST',
+  headers: { 'X-AUTH-CLIENT': process.env.VERIFF_API_KEY!, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ verification: { vendorData: partner.id, person: { firstName, lastName } } }),
+});
+// → 201 { status: 'success', verification: { id, url, host, status, sessionToken, endUserId, vendorData } }
+```
+
+The twin's default credentials are fixtures, not secrets: `VERIFF_API_KEY` =
+`11111111-2222-4333-8444-555555555555` and `VERIFF_SHARED_SECRET` =
+`abcdef12-abcd-abcd-abcd-abcdef012345` (the secret from Veriff's own published mock vector). Pass
+`--shared-secret` / `createVeriffTwinServer({ apiKey, sharedSecret })` to use your own.
+
+### Driving the decision lifecycle
+
+Real Veriff decides a session with OCR, face matching, liveness and sometimes a human reviewer.
+What the twin models faithfully is the
+**lifecycle** those decisions move through, driven deterministically by the caller through a
+**twin-only** control route (namespaced out of the vendor's surface, and deliberately absent from the
+capability manifest — it is test scaffolding, not coverage):
+
+```
+POST   /v1/sessions                              → created
+PATCH  /v1/sessions/{id} {status:'submitted'}    → submitted   (+ the 7002 event webhook)
+POST   /v1/_twin/sessions/{id}/decision          → approved | declined | resubmission_requested
+                                                   | review | expired | abandoned  (+ the decision webhook)
+POST   /v1/_twin/sessions/{id}/event {started}   → started     (+ the 7001 event webhook)
+GET    /v1/_twin/deliveries[?sessionId=]         → every webhook the twin would have PUSHED, signed
+```
+
+Webhook deliveries are **recorded, signed exactly as they would go on the wire, and never put on a
+socket** — so a consumer can read one back and run its real verification code against it offline,
+with no receiver to stand up.
+
+## Coverage
+
+Coverage is measured against the **real Veriff surface** as the denominator (see
+`src/veriff-capabilities.ts`) — it reads partial-but-honest and grows toward 100%. Run
+`bun scripts/manifest-baseline-one.ts veriff` for the live numbers.
+
+The denominator was enumerated top-down from `devdocs.veriff.com/llms.txt` (Veriff's own
+machine-readable index of all 140 doc pages, whose `/apidocs/*` pages embed the real OpenAPI 3.0.0
+documents) — the 18 documented Public API v1 operations, the three Feedback/Fraud API operations, the
+sync-api registry operation, and the per-solution pages (Document+Selfie, Document-only, Biometric
+Authentication/Liveness, Selfie2Selfie, Age Estimation, Unstructured Docs, Proof of Address, AML
+screening, NFC/ePassport, UK DIATF, and the nine database verifications).
+
+**Modeled (done, with failable offline verifies):**
+
+- **Sessions** — create (`201`, all seven required `verification` fields, `url = host + '/v/' +
+  sessionToken`), `PATCH … {status:'submitted'}` (the only value the vendor accepts), delete;
+  the documented negative paths: missing `verification` (`400`/`1101`), non-string / over-1,000-char
+  `vendorData` (`1501` / `1500`), non-HTTPS `callback` (`1302`), re-submit (`Session has already been
+  submitted`), delete-while-submitted (`1306` `Session in progress.`) and delete-in-review (`1305`
+  `Session is not in a completed status.`).
+- **Decisions** — `verification: null` before a decision (including while `submitted`), then
+  approved `9001` / declined `9102` + granular reason & reasonCode / resubmission `9103` (which
+  re-opens the session for capture) / expired `9104` / abandoned `9121` / review with a **null**
+  code (Veriff publishes none — see below); extracted
+  `person` + `document` kept distinct from the hints supplied at creation; `riskLabels`; the
+  state-machine guard (`1304`) in both directions — no jump straight from `created`, and no second
+  decision over a terminal one.
+- **Attempts** — the `verifications[]` array with `id`/`status`/`userDefinedData`/`createdTime`,
+  reverse-chronological across a resubmission cycle, empty (not `404`) before the first attempt.
+- **Person** — `GET /v1/sessions/{id}/person`, `null` until a decision exists.
+- **Media** — upload (`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 — with the documented
+  image object; `name` mirrors `context`; `timestamp` is
+  deprecated and always `null`; `size` is the *decoded* byte count), context-enum (`1402`) and
+  base64 (`1401`) rejection, the `409` on upload-after-submit, per-session and per-attempt listing
+  (`images`/`videos`/`nfcDocuments`), and download as **real bytes under the object's own mimetype**.
+- **Auth** — missing `X-AUTH-CLIENT` (`401`, the vendor's verbatim message); missing/wrong
+  `X-HMAC-SIGNATURE` (`401`/`1812`); the `POST /v1/sessions` signing exemption *and* that every other
+  endpoint still requires one; body-vs-path-resource-id signing; the published mock vector; and the
+  documented response sender headers.
+- **Webhooks** — the decision delivery carrying byte-identical content to the decision endpoint; a
+  real consumer's verification passing over the raw body; rejection of a tampered body, a wrong
+  `x-auth-client`, a missing signature and a wrong secret — each by its own reason; the 7002
+  `submitted` and 7001 `started` event payloads (no `verification` key, which is the discriminator a
+  real receiver routes on); and no delivery at all when no callback was configured.
+- **Errors + platform** — the `{status:'fail', code, message}` envelope with `code` as a **string**
+  (the schema's declared type, despite every value looking numeric); unmodeled routes failing like
+  the vendor (`404`); `readOnly` refusing every write with `405`; and two deliberate **dirty-state**
+  verifies (ids never reused across delete→recreate; a decision after a resubmission cycle reports
+  the *latest* attempt).
+- **Connector** — pull decisions/attempts/media over an injected client, idempotent re-pull
+  (`deltasAppended` → 0), no id collision in **either** direction (local mint after a pull, pull
+  after a local mint), push create/submit/delete with confirmation **only** on `status:'success'`,
+  the pure action→request and signing-payload rules, mappers that rename the kernel's reserved META
+  keys, and the client-side rate budget refusing past the ceiling with the injected fake's call count
+  **unchanged**.
+
+A **fidelity test** (`src/veriff-fetch.integration.test.ts`) drives the twin over **real-transport
+`fetch`** with a client rebuilt from the reference consumer's own source — same headers, same signing
+payload, same shape checks. Veriff publishes **no server-side SDK** (its npm org ships browser and
+mobile packages only), so a real server integration hand-rolls exactly this, and
+[Adding a twin](../../../docs/contributing/adding-a-twin.md) §10 sanctions it for precisely this case. The same
+file additionally pins **`@veriff/js-sdk` v2.0.0's wire contract**, read from the published bundle.
+
+**`todo` (real surface enumerated but not yet modeled):** watchlist screening / AML (`GET`+`PATCH`,
+hits, `202` in-progress, `402` not-enabled, its webhook family, `pepSanctionMatch`); collected-data
+/ device intelligence and `technicalData`; bulk face import; `validate-registry` (both the Public API
+and the synchronous `sync-api.veriff.me` variant) and the three legacy registry decisions; the ten
+database verifications; the ten IDV solutions and their decision-payload objects (`riskScore`,
+`additionalVerifiedData`, `biometricAuthentication`, `udocs`, `comments`, `submissionTime`, `tag`);
+the full granular decline/resubmission reason-code tables; the complete `person`/`document` field
+sets; Proof of Address (validation, matching, fraud check); PDF/NFC/video media and the documented
+size limits; the web-flow event actions 7007-7011 and the `context` object; the user-defined-statuses,
+Full Auto and registry webhook families; delivery retries; multiple shared secrets with a master
+signing key; the Feedback/Fraud API on its own host with the `VRF-*` header scheme; 7-day session
+expiry; the 9-resubmission cap; the served `429`; the precise credential (1801-1819) and
+troubleshooting (1001-2104) code taxonomies; and five connector gaps (media bytes, watchlist, person,
+media push, mid-batch back-off) filed in `pull-audit.json`.
+
+### The twin refuses to invent a `GET /v1/sessions/{id}`
+
+Veriff **has no such endpoint** — its API reference index lists only `POST`/`PATCH`/`DELETE` on that
+path, and GETs on the sub-resources (`/decision`, `/person`, `/attempts`, `/media`,
+`/watchlist-screening`). An integration learns a session's state from the webhooks and the decision
+endpoint, which is exactly why the reference consumer stores its own `veriffSessionId` and status.
+Serving a convenient read here would be the mirror image of the "unmodeled ops fail like the vendor"
+rule — an *invented* op — so a `GET` on that path answers the vendor's `404`, and
+`veriff.sessions.no_get_endpoint` pins it while asserting the sub-resources still answer for the
+same live session. Verifies that need to read a session's status back use the twin-only
+`GET /v1/_twin/sessions/{id}`, which is scaffolding and is not in the manifest.
+
+### Where Veriff's own docs contradict themselves
+
+Recorded rather than papered over, because a twin that silently picks a side teaches the wrong thing:
+
+1. **`POST /v1/sessions` — 200 or 201?** The embedded OpenAPI declares the success response `200`;
+   the vendor's own HTTP-status-codes table says `201` ("returned when session creation was a
+   success"); and `@veriff/js-sdk` v2.0.0 hard-checks `201 === xhr.status`. **This twin answers 201**,
+   because answering 200 would break the shipped SDK.
+2. **`review` has no published code.** The decision endpoint's `code` enum is exactly
+   `[9001, 9102, 9103, 9104, 9121]` and its `status` enum is
+   `[approved, declined, resubmission_requested, expired, abandoned]` — yet the decision **webhook**
+   page lists `review` among the statuses it sends (it is opt-in: "Only if previously agreed with
+   Veriff"). So `review` is a real status with no number of its own. **This twin emits `code: null`
+   for it** rather than borrowing 9121, which belongs to `abandoned` (the endpoint's prose says so,
+   and its `session_abandoned_generic` example pairs them explicitly, as
+   `session_expired_generic` pairs `expired` with 9104). Borrowing would tell a consumer branching
+   on `code` that a manual-review case was abandoned. `veriff.decisions.review_code` and
+   `veriff.decisions.code_numbering` are the filed todos. Note the reference consumer keys off
+   `status`, never `code` — which is the behaviour a twin should encourage.
+
+Two smaller ones, both recorded in the code where they bite. The DELETE endpoint's prose lists seven
+deletable statuses (`created`, `started`, `approved`, `declined`, `resubmission_requested`, `expired`,
+`abandoned`) while its own `1305` example says the session "must be in a completed state (`approved`,
+`declined`, `expired`, `abandoned`)" — the twin follows the prose list, because the same page also
+describes a decision webhook firing when a `created`/`started`/`resubmission_requested` session is
+deleted, which only makes sense if those are deletable. And the attempts endpoint's published `status`
+enum omits `approved` while its own examples show it — the twin follows the examples
+(`veriff.attempts.status_enum` is filed to pin it). The decision schema declares `code` and
+`reasonCode` as integers and the decision *webhook* sample agrees (`"code": 9001`), while the
+decision *endpoint*'s own examples quote them (`"code": "9121"`) — the twin emits numbers and files
+`veriff.decisions.code_wire_type`. And the DELETE page publishes both a blanket
+`1305` refusal for every non-deletable status *and* a `1306` "Session in progress." whose stated
+trigger (`started`) is on the deletable list — so routing `submitted` → `1306` is this twin's
+disambiguation, said plainly as such in the code and filed as `veriff.sessions.delete_refusal_codes`.
+
+A third: the HMAC doc's Python sample emits a `sha256=` prefix that contradicts the same
+page's mock vector and every other sample on it. The twin follows the vector — bare lowercase hex.
+
+### No UI mirror
+
+**The API is the product here.** When someone does Veriff's core job *the way the party integrating
+it does* — POST a session, embed the hosted flow, receive the decision webhook, read the decision —
+they write code. The only screen in that loop is Veriff's **own hosted capture flow** (camera,
+document framing, retries, localisation) served from the session `url`, which is Veriff's first-party
+product surface rather than a customer-operated console. The twin returns a real session `url`, so
+an integration's redirect/embed path is exercised end to end. Coverage is API + connector, and the
+manifest has zero `ui` capabilities that claim a mirror.
+
+The counter-argument is real and is recorded in `ui-scope.json` rather than dismissed: **Veriff
+Station** *is* a dashboard where a compliance team reviews sessions, decisions and captured media,
+and [Adding a twin](../../../docs/contributing/adding-a-twin.md) warns that a thin REST API is evidence *for* a
+mirror, not against it. What settles it here is that the UI in question is the *end user's* one-time
+capture flow rather than the customer's workspace — and that reproducing the review console would
+mean rendering document photographs a local twin never has. The reference consumer agrees in
+practice: dub embeds `@veriff/incontext-sdk` and then built its **own** admin identity-verification
+screen rather than working in Veriff Station. Re-opening this is legitimate.
+
+## Architecture
+
+State uses the shared kernel; see [the model](../../../docs/concepts/the-model.md) for log,
+checkpoint and branch semantics. There is no parallel mutable truth store.
+There is **no vendor devDependency** — Veriff publishes no server-side SDK, so fidelity is proven
+over real-transport `fetch`. The pack **`peerDepends`** on `@volter/world-core`, and conformance tooling
+(`@volter/world-tooling`) is dev-only and imported lazily by the CLI.
+
+Ids are **UUID v4**, because that is what Veriff's ids are (`"format": "uuid"` on every id in the
+published schemas) — and because entropy, never a row count, is what makes a local mint and a pulled
+vendor id incapable of colliding in either direction. Veriff's payloads are full of `id` fields, and
+the kernel's projection RESERVES `type`/`id`/`updatedAt` as META (a resource field with one of those
+names is silently dropped), so every vendor id is stored under a renamed key (`sessionId`,
+`attemptId`, `mediaId`) and mapped back at the boundary — on the local-mint path and the connector's
+pull path alike.
+
+**Pull is handle-driven, and that is the vendor's doing:** Veriff publishes no account-wide list
+endpoint — there is no `GET /v1/sessions`, and every documented read is scoped to an id the caller
+already holds — so `syncVeriffFromReal` takes the session ids to pull, exactly as a real integration
+does. `pull-audit.json` records this rather than filing an enumeration gap for surface the API does
+not expose.
+
+Every live call goes through **one guarded client** (`liveVeriffExecute`) with a persistent,
+token-keyed spend ledger that throws instead of calling past the ceiling — see `src/veriff-budget.ts`
+for how Veriff's two published limits (600/min enterprise, 30/min self-serve session creation;
+10-per-24h + 5-per-1h on delete) were turned into numbers, and for what the guard honestly does not
+enforce.

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,30 @@
+#!/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.js";
+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.js");
+    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/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+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.js';
+export type { VeriffRequest, VeriffResponse, VeriffSessionStatus, VeriffDecisionStatus } from './veriff-twin.js';
+export { createVeriffTwinFetch, createVeriffTwinServer, veriffResponseHeaders, type VeriffTwinFetchOptions } from './veriff-server.js';
+export { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, signaturesMatch, veriffSignature, veriffSignatureBytes, verifyVeriffSignature, } from './veriff-signature.js';
+export { buildSignedDelivery, emitVeriffWebhook, VERIFF_EVENT_ACTIONS, verifyWebhook, VeriffWebhookVerificationError, } from './veriff-events.js';
+export type { VeriffDecisionPayload, VeriffEventAction, VeriffEventPayload, VeriffWebhookDelivery, VeriffWebhookPayload } from './veriff-events.js';
+export { liveVeriffExecute, mapSessionDecision, mapSessionAttempt, mapSessionMedia, pullVeriffAttempts, pullVeriffDecisions, pullVeriffMedia, pushPendingVeriffActions, signaturePayloadFor, syncVeriffFromReal, veriffRequestForAction, } from './veriff-connector.js';
+export type { LiveVeriffOptions, VeriffExecute } from './veriff-connector.js';
+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.js';
+export type { VeriffBudgetErrorKind, VeriffBudgetOptions, VeriffBudgetReservation, VeriffBudgetSnapshot } from './veriff-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,119 @@
+// @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.js";
+export { createVeriffTwinFetch, createVeriffTwinServer, veriffResponseHeaders } from "./veriff-server.js";
+export { AUTH_CLIENT_HEADER, HMAC_SIGNATURE_HEADER, signaturesMatch, veriffSignature, veriffSignatureBytes, verifyVeriffSignature, } from "./veriff-signature.js";
+export { buildSignedDelivery, emitVeriffWebhook, VERIFF_EVENT_ACTIONS, verifyWebhook, VeriffWebhookVerificationError, } from "./veriff-events.js";
+export { liveVeriffExecute, mapSessionDecision, mapSessionAttempt, mapSessionMedia, pullVeriffAttempts, pullVeriffDecisions, pullVeriffMedia, pushPendingVeriffActions, signaturePayloadFor, syncVeriffFromReal, veriffRequestForAction, } from "./veriff-connector.js";
+// 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.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { signaturePayloadFor } from "./veriff-connector.js";
+import { HMAC_SIGNATURE_HEADER } from "./veriff-signature.js";
+import { performVeriffAction, syncVeriffFromRemote } from "./veriff-connector.js";
+import { VERIFF_RATE_BUDGET as RATE_BUDGET } from "./veriff-budget.js";
+export const pack = {
+    // 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);