@volter/twin-veriff 0.1.0

package/src/veriff-signature.ts

@@ -0,0 +1,86 @@
+import { nodeBuiltin } from '@volter/world-core';
+// Veriff's HMAC request/webhook signing — REAL crypto, reproduced byte-for-byte.
+//
+// Veriff authenticates two directions with the SAME primitive and two different payloads:
+//
+//   1. OUTBOUND (you → Veriff). `X-AUTH-CLIENT` carries the public API key. Endpoints that require
+//      signing add `X-HMAC-SIGNATURE` = lowercase-hex HMAC-SHA256 over the **payload**, keyed by
+//      the account's shared secret. The payload is the raw JSON request BODY for a request that has
+//      one, and the **path parameter itself** (the session id / attempt id / media id) for a GET,
+//      which has no body. The real consumer does exactly this — dub's
+//      `apps/web/lib/veriff/client.ts` signs `fetchSessionDecision` with
+//      `createHmac('sha256', VERIFF_SHARED_SECRET).update(sessionId).digest('hex')` and sends it as
+//      `X-HMAC-SIGNATURE`.
+//
+//   2. INBOUND (Veriff → you). Every webhook delivery carries `x-auth-client` (the same public API
+//      key, so a receiver can tell WHICH account) and `x-hmac-signature` = lowercase-hex
+//      HMAC-SHA256 over the **raw delivered body**, keyed by the same shared secret. dub's
+//      `app/api/veriff/webhook/route.ts` verifies exactly this, timing-safe, over `req.text()`.
+//
+// Both are pure local computations over a secret, so a twin can hold the scheme HONESTLY rather
+// than faking it: a consumer that signs wrongly gets the vendor's rejection here too, and a
+// consumer verifying a twin-delivered webhook with the real `crypto` code path passes unchanged.
+//
+// `node:crypto` is required LAZILY (server-only) so this module is safe to import anywhere.
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+/** 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: string, sharedSecret: string): string {
+  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: Uint8Array, sharedSecret: string): string {
+  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: string, b: string): boolean {
+  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: string,
+  presented: string | undefined | null,
+  sharedSecret: string,
+): 'missing' | 'mismatch' | null {
+  if (presented === undefined || presented === null || presented === '') return 'missing';
+  return signaturesMatch(veriffSignature(payload, sharedSecret), presented) ? null : 'mismatch';
+}