whisp-js 0.0.0-stage → 0.3.0

package/dist/esm/webhook.js

@@ -0,0 +1,123 @@
+/**
+ * `verifyWebhook` (phase2-design 7.3, 12.5): checks `X-Whisp-Signature` on a
+ * webhook request and returns the event.
+ *
+ * The header is `t=<unix seconds>,v1=<hex>[,v1=<hex>]`: one `v1` per secret
+ * the endpoint signs with (two during a rotation's 24 h grace, 7.7). Each `v1`
+ * is the lowercase hex HMAC-SHA256, keyed with the whole `wsp_whs_…` secret
+ * as UTF-8, over `<t>.<raw body>`. A request passes when the header parses,
+ * `|now - t|` is within the tolerance (300 s by default) and any `v1` matches.
+ *
+ * Web Crypto's `subtle.verify` compares in constant time. It is async, so
+ * this is. Core's synchronous `verifySignatureHeader` signs the same way for
+ * the server; packages/sdk/test/webhook.test.ts holds the two together.
+ */
+import { SIGNATURE_TOLERANCE_SECONDS, WEBHOOK_SECRET_PATTERN } from './constants.js';
+import { localError, WhispSignatureError } from './errors.js';
+const encoder = new TextEncoder();
+const TIMESTAMP = /^\d{1,12}$/;
+const HEX_SIGNATURE = /^[0-9a-f]{64}$/;
+/** `t` and every `v1`; other keys (a later `v2`) are ignored. Null when malformed, or without `t` or `v1`. */
+export const parseSignatureHeader = (header) => {
+    let timestamp = null;
+    const signatures = [];
+    for (const part of header.split(',')) {
+        const separator = part.indexOf('=');
+        if (separator < 1)
+            return null;
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (key === 't') {
+            if (timestamp !== null || !TIMESTAMP.test(value))
+                return null;
+            timestamp = Number(value);
+        }
+        else if (key === 'v1') {
+            const lower = value.toLowerCase();
+            if (!HEX_SIGNATURE.test(lower))
+                return null;
+            signatures.push(lower);
+        }
+    }
+    return timestamp === null || signatures.length === 0 ? null : { timestamp, signatures };
+};
+const hexToBytes = (hex) => {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+};
+const toBytes = (body) => typeof body === 'string' ? encoder.encode(body) : body instanceof Uint8Array ? body : new Uint8Array(body);
+const secretsOf = (secret) => {
+    const list = (typeof secret === 'string' ? [secret] : (secret ?? [])).map(value => typeof value === 'string' ? value.trim() : '');
+    if (list.length === 0 || list.every(value => value === '')) {
+        throw localError('SECRET_MISSING', "verifyWebhook needs the endpoint's signing secret (wsp_whs_…); is its environment variable set?");
+    }
+    for (const value of list) {
+        if (!WEBHOOK_SECRET_PATTERN.test(value)) {
+            throw localError('SECRET_INVALID', "The secret is not a webhook signing secret (wsp_whs_…). Copy it again from the project's Webhooks tab.");
+        }
+    }
+    return list;
+};
+/**
+ * The event the request carries, typed by `type` (`webhook.test` included),
+ * or throws WhispSignatureError with `reason` 'missing', 'malformed',
+ * 'timestamp' or 'mismatch'. A missing or mistyped secret throws a WhispError
+ * (SECRET_MISSING, SECRET_INVALID), which is a setup problem, not a bad request.
+ */
+export const verifyWebhook = async (input) => {
+    const secrets = secretsOf(input.secret);
+    const tolerance = input.toleranceSeconds ?? SIGNATURE_TOLERANCE_SECONDS;
+    if (!Number.isFinite(tolerance) || tolerance < 0) {
+        throw localError('OPTIONS_INVALID', 'toleranceSeconds must be a number of seconds, 0 or more');
+    }
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle)
+        throw localError('CRYPTO_UNAVAILABLE', 'verifyWebhook needs Web Crypto (crypto.subtle)');
+    const header = typeof input.signature === 'string' ? input.signature : '';
+    if (header.trim() === '')
+        throw new WhispSignatureError('missing');
+    const parsed = parseSignatureHeader(header);
+    if (!parsed)
+        throw new WhispSignatureError('malformed');
+    const nowSec = Math.floor((input.now ?? Date.now()) / 1_000);
+    if (Math.abs(nowSec - parsed.timestamp) > tolerance)
+        throw new WhispSignatureError('timestamp');
+    const body = toBytes(input.body);
+    const prefix = encoder.encode(`${parsed.timestamp}.`);
+    const message = new Uint8Array(prefix.length + body.length);
+    message.set(prefix);
+    message.set(body, prefix.length);
+    let matched = false;
+    for (const secret of secrets) {
+        const key = await subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [
+            'verify',
+        ]);
+        for (const signature of parsed.signatures) {
+            if (await subtle.verify('HMAC', key, hexToBytes(signature), message)) {
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            break;
+    }
+    if (!matched)
+        throw new WhispSignatureError('mismatch');
+    let event;
+    try {
+        event = JSON.parse(typeof input.body === 'string' ? input.body : new TextDecoder().decode(body));
+    }
+    catch {
+        event = undefined;
+    }
+    const record = event;
+    if (typeof record !== 'object' ||
+        record === null ||
+        typeof record.id !== 'string' ||
+        typeof record.type !== 'string') {
+        throw new WhispSignatureError('malformed', 'The body is signed but is not a Whisp event');
+    }
+    return event;
+};

package/package.json

@@ -1,6 +1,38 @@
 {
-  "name": "whisp-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "whisp-js",
+	"version": "0.3.0",
+	"description": "Send WhatsApp messages from your numbers and listen to their events",
+	"license": "MIT",
+	"type": "module",
+	"sideEffects": false,
+	"keywords": [
+		"whatsapp",
+		"messages",
+		"webhooks",
+		"sdk"
+	],
+	"main": "./dist/cjs/index.js",
+	"types": "./dist/esm/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/esm/index.d.ts",
+				"default": "./dist/esm/index.js"
+			},
+			"require": {
+				"types": "./dist/cjs/index.d.ts",
+				"default": "./dist/cjs/index.js"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=22.12"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}