@kirimdev/sdk 2.0.0 → 3.0.0

package/dist/webhooks.js

@@ -1,64 +1,125 @@
 /**
  * Webhook HMAC verification + typed event payloads.
  *
- * The Kirim API signs outbound webhook deliveries with HMAC-SHA256 over the
- * raw request body, encoded as `sha256=<hex>` in the `X-Kirim-Signature`
- * header. This module exposes a constant-time verifier using Web Crypto
- * (`crypto.subtle`) so it runs on Node 18+, Bun, Deno, and edge runtimes.
+ * Kirim signs outbound webhook deliveries using a Stripe-style header
+ * format mirroring `apps/worker/src/jobs/webhook-delivery/sign.ts`:
  *
- * The signing scheme mirrors `apps/api/src/lib/webhook-security.ts`.
+ *   X-Kirim-Signature: t=<unix_seconds>,v1=<hex>[,v1=<hex>...]
  *
- * Usage:
- *   import { verifyWebhookSignature } from '@kirimdev/sdk/webhooks'
+ * - `t` is the time the signature was computed; callers reject when
+ *   |now - t| exceeds `toleranceSeconds` (default 5 minutes).
+ * - Each `v1=` is HMAC-SHA256 of `${t}.${rawBody}` under one ACTIVE
+ *   signing secret. During rotation a subscription may have multiple
+ *   active secrets and the header carries one `v1=` per secret —
+ *   verification passes if ANY caller-supplied secret matches ANY
+ *   `v1=` value.
  *
- *   const ok = await verifyWebhookSignature(
- *     await req.text(),
- *     req.headers.get('x-kirim-signature') ?? '',
- *     process.env.KIRIM_WEBHOOK_SECRET!,
- *   )
- *   if (!ok) return new Response('bad signature', { status: 401 })
- */
-/**
- * Verify a Kirim webhook signature.
+ * Uses Web Crypto (`crypto.subtle`) so this module runs unchanged on
+ * Node 18+, Bun, Deno, and edge runtimes.
  *
- * MUST be called with the raw request body (the same bytes Kirim signed —
- * re-serializing JSON will break the signature). Returns `false` (never
- * throws) when the header is absent / malformed / mismatched. The caller
- * MUST reject the request when this returns `false` (fail-closed).
+ * The error classes in this module (`KirimWebhookError`,
+ * `InvalidSignatureError`, `SignatureExpiredError`,
+ * `MalformedPayloadError`) form a SEPARATE hierarchy from the HTTP
+ * `KirimError` tree in `@kirimdev/sdk` — webhook errors carry no
+ * `requestId` / `status` / `code` because they fire before any HTTP
+ * round-trip. Consumers wanting a single catch surface should branch
+ * on `instanceof KirimWebhookError` separately from `instanceof
+ * KirimError`.
  */
-export async function verifyWebhookSignature(body, signatureHeader, secret) {
-    if (!signatureHeader || !secret)
-        return false;
-    const provided = signatureHeader.startsWith('sha256=')
-        ? signatureHeader.slice('sha256='.length)
-        : signatureHeader;
-    const expected = await hmacSha256Hex(secret, body);
-    // Length comparison short-circuits *before* the timing-safe step. That's
-    // safe because byte length is not a secret (HMAC-SHA256 hex is always 64
-    // chars); leaking it gives the attacker nothing.
-    if (expected.length !== provided.length)
-        return false;
-    return timingSafeEqualHex(expected, provided);
+export class KirimWebhookError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KirimWebhookError';
+    }
+}
+export class InvalidSignatureError extends KirimWebhookError {
+    constructor(message = 'Invalid webhook signature') {
+        super(message);
+        this.name = 'InvalidSignatureError';
+    }
+}
+export class SignatureExpiredError extends KirimWebhookError {
+    constructor(message = 'Webhook signature timestamp outside tolerance window') {
+        super(message);
+        this.name = 'SignatureExpiredError';
+    }
+}
+export class MalformedPayloadError extends KirimWebhookError {
+    constructor(message = 'Webhook payload is not valid JSON') {
+        super(message);
+        this.name = 'MalformedPayloadError';
+    }
+}
+function parseHeader(header) {
+    const parts = header.split(',').map((s) => s.trim()).filter(Boolean);
+    let t = null;
+    const v1 = [];
+    for (const part of parts) {
+        const eq = part.indexOf('=');
+        if (eq <= 0)
+            return null;
+        const k = part.slice(0, eq);
+        const v = part.slice(eq + 1);
+        if (k === 't') {
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0)
+                return null;
+            t = n;
+        }
+        else if (k === 'v1') {
+            if (!/^[0-9a-f]+$/i.test(v))
+                return null;
+            v1.push(v.toLowerCase());
+        }
+        // Unknown scheme tokens (future-proof: e.g. v2=) are ignored.
+    }
+    if (t === null || v1.length === 0)
+        return null;
+    return { t, v1 };
+}
+export async function verifyWebhookSignature(opts) {
+    const tolerance = opts.toleranceSeconds ?? 300;
+    const now = (opts.nowSeconds ?? (() => Math.floor(Date.now() / 1000)))();
+    if (!opts.signatureHeader || opts.secrets.length === 0) {
+        throw new InvalidSignatureError('Missing signature header or secrets');
+    }
+    const parsed = parseHeader(opts.signatureHeader);
+    if (!parsed)
+        throw new InvalidSignatureError('Malformed signature header');
+    if (Math.abs(now - parsed.t) > tolerance) {
+        throw new SignatureExpiredError();
+    }
+    const signedString = `${parsed.t}.${opts.rawBody}`;
+    for (const secret of opts.secrets) {
+        const expected = await hmacSha256Hex(secret, signedString);
+        for (const candidate of parsed.v1) {
+            if (expected.length === candidate.length && timingSafeEqualHex(expected, candidate)) {
+                try {
+                    return JSON.parse(opts.rawBody);
+                }
+                catch {
+                    throw new MalformedPayloadError();
+                }
+            }
+        }
+    }
+    throw new InvalidSignatureError('No v1 signature matched any provided secret');
 }
 async function hmacSha256Hex(secret, body) {
     const enc = new TextEncoder();
     const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
     const buf = await crypto.subtle.sign('HMAC', key, enc.encode(body));
-    return bufferToHex(new Uint8Array(buf));
-}
-function bufferToHex(buf) {
     let out = '';
-    for (let i = 0; i < buf.length; i++) {
-        const byte = buf[i] ?? 0;
-        out += byte.toString(16).padStart(2, '0');
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < view.length; i++) {
+        out += (view[i] ?? 0).toString(16).padStart(2, '0');
     }
     return out;
 }
-/** Constant-time string comparison. Inputs MUST be equal length. */
 function timingSafeEqualHex(a, b) {
     let diff = 0;
     for (let i = 0; i < a.length; i++) {
-        diff |= (a.charCodeAt(i) ^ b.charCodeAt(i));
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
     }
     return diff === 0;
 }

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAY,EACZ,eAA0C,EAC1C,MAAc;IAEd,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC;QACpD,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;QACzC,CAAC,CAAC,eAAe,CAAA;IAEnB,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAClD,yEAAyE;IACzE,yEAAyE;IACzE,iDAAiD;IACjD,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACrD,OAAO,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;AAC/C,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,IAAY;IACvD,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAA;IAC7B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAClB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAA;IACD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACnE,OAAO,WAAW,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AACzC,CAAC;AAED,SAAS,WAAW,CAAC,GAAe;IAClC,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACxB,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC3C,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,oEAAoE;AACpE,SAAS,kBAAkB,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAA;AACnB,CAAC"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}