@volter/twin-veriff 0.1.0

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

@@ -0,0 +1,36 @@
+/** The header Veriff carries the public API key in (case-insensitive on the wire). */
+export declare const AUTH_CLIENT_HEADER = "x-auth-client";
+/** The header Veriff carries the HMAC in (case-insensitive on the wire). */
+export declare const HMAC_SIGNATURE_HEADER = "x-hmac-signature";
+/**
+ * Compute Veriff's signature for a payload: lowercase-hex HMAC-SHA256(sharedSecret, payload).
+ *
+ * `payload` is the raw request/webhook body for anything with a body, and the bare path parameter
+ * (session id, attempt id, media id) for a GET. Callers pass the exact bytes — this function never
+ * re-serializes, because a re-serialized body signs different bytes than the ones sent.
+ */
+export declare function veriffSignature(payload: string, sharedSecret: string): string;
+/**
+ * The same signature over RAW BYTES rather than a string.
+ *
+ * Needed because one response is not JSON: `GET /v1/media/{id}` answers with the media itself under
+ * its own mimetype, and the documented `X-HMAC-SIGNATURE` header is "Response body signed with the
+ * shared secret key" — the body a receiver actually got. Signing the base64 TEXT the twin happens to
+ * store it as produces a digest that verifies against nothing the consumer holds; a §9 round-two
+ * review measured exactly that mismatch before this existed.
+ */
+export declare function veriffSignatureBytes(payload: Uint8Array, sharedSecret: string): string;
+/**
+ * Constant-time compare of two signature strings.
+ *
+ * Length is compared first and NOT with `timingSafeEqual` — the node primitive THROWS on a length
+ * mismatch rather than returning false, so an unequal-length forgery would crash the handler
+ * instead of being rejected. The real consumer (dub) guards the same way.
+ */
+export declare function signaturesMatch(a: string, b: string): boolean;
+/**
+ * Verify a presented signature against the payload. Returns the reason it failed, or `null` when
+ * it is valid — so a caller can map a MISSING header and a WRONG one to the different statuses
+ * Veriff uses for them.
+ */
+export declare function verifyVeriffSignature(payload: string, presented: string | undefined | null, sharedSecret: string): 'missing' | 'mismatch' | null;

package/dist/src/veriff-signature.js

@@ -0,0 +1,55 @@
+import { nodeBuiltin } from '@volter/world-core';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+/** The header Veriff carries the public API key in (case-insensitive on the wire). */
+export const AUTH_CLIENT_HEADER = 'x-auth-client';
+/** The header Veriff carries the HMAC in (case-insensitive on the wire). */
+export const HMAC_SIGNATURE_HEADER = 'x-hmac-signature';
+/**
+ * Compute Veriff's signature for a payload: lowercase-hex HMAC-SHA256(sharedSecret, payload).
+ *
+ * `payload` is the raw request/webhook body for anything with a body, and the bare path parameter
+ * (session id, attempt id, media id) for a GET. Callers pass the exact bytes — this function never
+ * re-serializes, because a re-serialized body signs different bytes than the ones sent.
+ */
+export function veriffSignature(payload, sharedSecret) {
+    return nodeCrypto().createHmac('sha256', sharedSecret).update(payload, 'utf8').digest('hex');
+}
+/**
+ * The same signature over RAW BYTES rather than a string.
+ *
+ * Needed because one response is not JSON: `GET /v1/media/{id}` answers with the media itself under
+ * its own mimetype, and the documented `X-HMAC-SIGNATURE` header is "Response body signed with the
+ * shared secret key" — the body a receiver actually got. Signing the base64 TEXT the twin happens to
+ * store it as produces a digest that verifies against nothing the consumer holds; a §9 round-two
+ * review measured exactly that mismatch before this existed.
+ */
+export function veriffSignatureBytes(payload, sharedSecret) {
+    return nodeCrypto().createHmac('sha256', sharedSecret).update(payload).digest('hex');
+}
+/**
+ * Constant-time compare of two signature strings.
+ *
+ * Length is compared first and NOT with `timingSafeEqual` — the node primitive THROWS on a length
+ * mismatch rather than returning false, so an unequal-length forgery would crash the handler
+ * instead of being rejected. The real consumer (dub) guards the same way.
+ */
+export function signaturesMatch(a, b) {
+    const ab = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ab.length !== bb.length)
+        return false;
+    return nodeCrypto().timingSafeEqual(Uint8Array.from(ab), Uint8Array.from(bb));
+}
+/**
+ * Verify a presented signature against the payload. Returns the reason it failed, or `null` when
+ * it is valid — so a caller can map a MISSING header and a WRONG one to the different statuses
+ * Veriff uses for them.
+ */
+export function verifyVeriffSignature(payload, presented, sharedSecret) {
+    if (presented === undefined || presented === null || presented === '')
+        return 'missing';
+    return signaturesMatch(veriffSignature(payload, sharedSecret), presented) ? null : 'mismatch';
+}

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

@@ -0,0 +1,104 @@
+export type VeriffRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string | undefined>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The shared secret this twin verifies `X-HMAC-SIGNATURE` against and signs webhooks with. */
+    sharedSecret?: string;
+    /** The API key this twin stamps into `x-auth-client` on outbound webhook deliveries. */
+    apiKey?: string;
+};
+export type VeriffResponse = {
+    status: number;
+    body: unknown;
+};
+/**
+ * The default local credentials. A twin fakes auth, so these are FIXTURES, not secrets: the point
+ * of pinning them is that a consumer's `.env` can point `VERIFF_API_KEY` / `VERIFF_SHARED_SECRET`
+ * at the twin and the HMAC round-trip works end to end with no per-run coordination. Shaped like
+ * the real thing — Veriff's API key and shared secret are both UUIDs.
+ */
+export declare const TWIN_API_KEY = "11111111-2222-4333-8444-555555555555";
+export declare const TWIN_SHARED_SECRET = "abcdef12-abcd-abcd-abcd-abcdef012345";
+/**
+ * The troubleshooting/credential codes this twin actually emits, each with the verbatim message
+ * from the endpoint's own published example. `1101` is heavily overloaded by the vendor — it is the
+ * generic code across 400 (validation), 401 (missing key), 404 (not found) and 500.
+ */
+/**
+ * The verbatim message the vendor's troubleshooting-codes table pairs with each code this twin
+ * emits. Kept as data next to the codes so the two can never drift apart, and so a consumer that
+ * surfaces `message` to a support engineer sees the string Veriff's own docs use.
+ */
+export declare const VERIFF_ERROR_MESSAGES: {
+    readonly '1302': "Only HTTPS return URLs are allowed.";
+    readonly '1401': "Image is not in valid `base64`.";
+    readonly '1402': "Image context is not supported.";
+    readonly '1500': "`vendorData` field cannot be more than 1000 symbols. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer's domain)";
+    readonly '1501': "`vendorData` must be a string. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer's domain)";
+};
+export declare const VERIFF_ERROR_CODES: {
+    readonly generic: "1101";
+    readonly invalidHmac: "1812";
+    readonly notCompleted: "1305";
+    readonly inProgress: "1306";
+    readonly badTransition: "1304";
+    readonly invalidBase64: "1401";
+    readonly unsupportedContext: "1402";
+    readonly httpsOnlyCallback: "1302";
+    readonly vendorDataLength: "1500";
+    readonly vendorDataType: "1501";
+};
+/** Every state a session can be in, across both halves of the lifecycle. */
+export declare const VERIFF_SESSION_STATUSES: readonly ["created", "started", "submitted", "approved", "declined", "resubmission_requested", "review", "expired", "abandoned"];
+export type VeriffSessionStatus = (typeof VERIFF_SESSION_STATUSES)[number];
+/** The terminal decision statuses — the exact set the decision webhook documents, and the exact set
+ *  the reference consumer's zod enum accepts (dub's `veriffDecisionEventSchema`). */
+export declare const VERIFF_DECISION_STATUSES: readonly ["approved", "declined", "resubmission_requested", "review", "expired", "abandoned"];
+export type VeriffDecisionStatus = (typeof VERIFF_DECISION_STATUSES)[number];
+/**
+ * The numeric `code` Veriff carries alongside a decision status.
+ *
+ * Grounded four ways in the decision endpoint's own published document, which is the endpoint this
+ * twin serves: its prose list ("`9104` - Expired", "`9121` - Abandoned"), its
+ * `session_abandoned_generic` example (`"code":"9121"` with `"status":"abandoned"`), its
+ * `session_expired_generic` example (`"code":"9104"` with `"status":"expired"`), and the schema's
+ * `code` enum, which is exactly [9001, 9102, 9103, 9104, 9121].
+ *
+ * `review` therefore gets **null**, not a borrowed code. It is a real status — the decision-webhook
+ * page lists it among `approved|declined|resubmission_requested|review|expired|abandoned`, and it is
+ * opt-in ("Only if previously agreed with Veriff") — but it appears in NEITHER the decision schema's
+ * `status` enum NOR its `code` enum, so no published number belongs to it. Handing it another
+ * status's code would be invention, and a consumer branching on `code` would silently treat a
+ * manual-review case as abandoned. `veriff.decisions.review_code` is the filed todo.
+ *
+ * (An earlier revision of this pack mapped `abandoned: 9104` / `review: 9121` on the strength of a
+ * status-codes table it had not actually read — a §9 review caught it. Recorded because the lesson
+ * generalises: prefer the document you can quote over the one you were told about.)
+ *
+ * Emitted as a NUMBER, matching the decision-webhook sample (`"code": 9001`) and the schema's
+ * declared `"type": "integer"`.
+ */
+export declare const VERIFF_DECISION_CODES: Record<VeriffDecisionStatus, number | null>;
+/** The event-webhook `code` per action. 7001/7002 are the two the event-webhook page documents as
+ *  needing no extra configuration; the 7007-7011 web-flow actions are a filed todo. */
+export declare const VERIFF_EVENT_CODES: Record<'started' | 'submitted', number>;
+/**
+ * The subject types this twin projects.
+ *
+ * `delivery` is the twin's own outbound-webhook log: every decision/event webhook the twin would
+ * have PUSHED is recorded here, signed exactly as it would go on the wire, so a consumer can read
+ * one back and verify it offline instead of standing up a receiver.
+ */
+export declare const VERIFF_RESOURCE_TYPES: readonly ["session", "attempt", "media", "delivery"];
+/**
+ * Every endpoint this twin DISPATCHES, as a `METHOD /path` template. The conformance check drives
+ * one real request per entry and asserts the OUTCOME a live handler produces, so deleting a route —
+ * or a single method branch — from the switchboard below turns it red. Its census is a two-way
+ * bijection with this list, so adding a route here without implementing it is red too.
+ */
+export declare const VERIFF_IMPLEMENTED_ENDPOINTS: readonly ["POST /v1/sessions", "PATCH /v1/sessions/{sessionId}", "DELETE /v1/sessions/{sessionId}", "GET /v1/sessions/{sessionId}/decision", "GET /v1/sessions/{sessionId}/person", "GET /v1/sessions/{sessionId}/attempts", "GET /v1/sessions/{sessionId}/media", "POST /v1/sessions/{sessionId}/media", "GET /v1/attempts/{attemptId}/media", "GET /v1/media/{mediaId}"];
+export declare function handleVeriffTwinRequest(req: VeriffRequest): Promise<VeriffResponse>;