@heyatom/bastion-client 0.2.0 → 0.3.1

package/dist/esm/webhooks/index.js

@@ -0,0 +1,68 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** Headers Bastion sends with every delivery. Lower-case, as Node exposes them. */
+export const BASTION_SIGNATURE_HEADER = 'x-bastion-signature';
+export const BASTION_SIGNATURE_V2_HEADER = 'x-bastion-signature-v2';
+export const BASTION_EVENT_HEADER = 'x-bastion-event';
+export const BASTION_DELIVERY_ID_HEADER = 'x-bastion-delivery-id';
+/** Sent to every app with a webhook URL, whether or not the user has a role in it. */
+export const BASTION_LIFECYCLE_EVENTS = ['user.deleted', 'user.expired_unverified', 'user.deactivated'];
+function header(headers, name) {
+    const direct = headers[name] ?? headers[name.toLowerCase()];
+    if (direct !== undefined)
+        return Array.isArray(direct) ? direct[0] : direct;
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
+    const v = key ? headers[key] : undefined;
+    return Array.isArray(v) ? v[0] : v;
+}
+function macEquals(hexA, hexB) {
+    const a = Buffer.from(hexA, 'hex');
+    const b = Buffer.from(hexB, 'hex');
+    return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
+/**
+ * Verifies a Bastion delivery. Prefers `X-Bastion-Signature-V2`
+ * (`t=<unix>,id=<deliveryId>,v1=<hex>[,v1=<hex>]`, MAC over `"<t>.<id>.<body>"`),
+ * which binds the timestamp and the delivery id so a stale or replayed
+ * delivery is rejected without trusting any unsigned header; falls back to
+ * the legacy `X-Bastion-Signature: sha256=<hex>` over the body alone only when
+ * v2 is absent. Any of the caller's `secrets` matching any `v1=` accepts:
+ * that is how a secret rotation stays zero-downtime on both sides.
+ */
+export function verifyWebhookSignature(options) {
+    const body = typeof options.rawBody === 'string' ? Buffer.from(options.rawBody, 'utf8') : options.rawBody;
+    const secrets = (Array.isArray(options.secrets) ? options.secrets : [options.secrets]).filter(Boolean);
+    if (secrets.length === 0)
+        return { ok: false, reason: 'missing' };
+    const v2 = header(options.headers, BASTION_SIGNATURE_V2_HEADER);
+    if (v2) {
+        const parts = v2.split(',').map((p) => p.trim());
+        const t = parts.find((p) => p.startsWith('t='))?.slice(2);
+        const id = parts.find((p) => p.startsWith('id='))?.slice(3);
+        const macs = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
+        const timestamp = Number(t);
+        if (!t || !id || macs.length === 0 || !Number.isFinite(timestamp))
+            return { ok: false, reason: 'malformed' };
+        const now = Math.floor((options.now ?? Date.now)() / 1000);
+        if (Math.abs(now - timestamp) > (options.toleranceSeconds ?? 300))
+            return { ok: false, reason: 'stale' };
+        const signed = Buffer.concat([Buffer.from(`${timestamp}.${id}.`, 'utf8'), body]);
+        for (const secret of secrets) {
+            const expected = createHmac('sha256', secret).update(signed).digest('hex');
+            if (macs.some((mac) => macEquals(mac, expected)))
+                return { ok: true, version: 'v2', timestamp, deliveryId: id };
+        }
+        return { ok: false, reason: 'mismatch' };
+    }
+    const legacy = header(options.headers, BASTION_SIGNATURE_HEADER);
+    if (!legacy)
+        return { ok: false, reason: 'missing' };
+    if (!legacy.startsWith('sha256='))
+        return { ok: false, reason: 'malformed' };
+    const provided = legacy.slice('sha256='.length).trim();
+    for (const secret of secrets) {
+        const expected = createHmac('sha256', secret).update(body).digest('hex');
+        if (macEquals(provided, expected))
+            return { ok: true, version: 'legacy' };
+    }
+    return { ok: false, reason: 'mismatch' };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyatom/bastion-client",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Consumer SDK for the Bastion identity provider: JWKS verification, service-client auth, audit writes, NestJS guards",
   "license": "MIT",
   "author": "Andrea Tombolato <hey@heyatom.dev> (https://heyatom.dev)",
@@ -35,6 +35,16 @@
         "types": "./dist/cjs/nest/index.d.ts",
         "default": "./dist/cjs/nest/index.js"
       }
+    },
+    "./webhooks": {
+      "import": {
+        "types": "./dist/esm/webhooks/index.d.ts",
+        "default": "./dist/esm/webhooks/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/webhooks/index.d.ts",
+        "default": "./dist/cjs/webhooks/index.js"
+      }
     }
   },
   "scripts": {
@@ -85,6 +95,9 @@
       ],
       "*": [
         "./dist/cjs/core/index.d.ts"
+      ],
+      "webhooks": [
+        "./dist/cjs/webhooks/index.d.ts"
       ]
     }
   }