@faable/auth-sdk 2.7.107 → 2.8.0

package/dist/webhooks.js

@@ -0,0 +1,170 @@
+export const WEBHOOK_HEADERS = {
+    signature: "x-faable-signature",
+    timestamp: "x-faable-timestamp",
+    delivery: "x-faable-delivery",
+    event: "x-faable-event",
+};
+/** How far a delivery's timestamp may be from now before it is a replay. */
+export const DEFAULT_WEBHOOK_TOLERANCE_MS = 5 * 60 * 1000;
+/**
+ * Thrown by {@link verifyWebhookSignature} and {@link constructWebhookEvent}.
+ * Answer the delivery with a 400/401 and do nothing else: it was not sent by
+ * Faable Auth with your secret, or it was tampered with or replayed.
+ */
+export class WebhookVerificationError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+        this.reason = reason;
+    }
+}
+const readHeader = (headers, name) => {
+    if (typeof headers.get === "function") {
+        return (headers.get(name) ?? undefined);
+    }
+    const record = headers;
+    const value = record[name] ??
+        Object.entries(record).find(([k]) => k.toLowerCase() === name)?.[1];
+    return Array.isArray(value) ? value[0] : value;
+};
+// Web Crypto and TextEncoder, not `node:crypto` / `Buffer`: this package also
+// loads in browser bundles (the hosted login pages), and the same code then
+// runs on Node ≥ 19, Deno, Bun and edge runtimes.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const bodyText = (body) => typeof body === "string" ? body : decoder.decode(body);
+const fromHex = (hex) => {
+    if (hex.length % 2 !== 0 || !/^[0-9a-f]*$/i.test(hex))
+        return null;
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+};
+// Constant time for equal lengths: the comparison does not stop at the first
+// differing byte, so its timing does not leak how much of a guess was right.
+const sameBytes = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+};
+const hmacSha256 = async (secret, data) => {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("Web Crypto (globalThis.crypto.subtle) is not available: verifying webhooks needs Node ≥ 19 or a runtime with Web Crypto.");
+    }
+    const key = await subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(data)));
+};
+/**
+ * Checks that a delivery was signed by Faable Auth with your secret, recently.
+ * Throws {@link WebhookVerificationError}; returns nothing when it is valid.
+ *
+ * Prefer {@link constructWebhookEvent}, which also parses and types the body.
+ */
+export async function verifyWebhookSignature(options) {
+    const secrets = (Array.isArray(options.secret) ? options.secret : [options.secret]).filter((s) => typeof s === "string" && s.length > 0);
+    if (secrets.length === 0) {
+        throw new WebhookVerificationError("missing_secret", "No webhook secret configured: refusing every delivery.");
+    }
+    const { signature, timestamp } = options;
+    if (!signature || !timestamp) {
+        throw new WebhookVerificationError("missing_headers", `Missing ${WEBHOOK_HEADERS.signature} or ${WEBHOOK_HEADERS.timestamp}.`);
+    }
+    const sent = Number(timestamp);
+    const tolerance = options.toleranceMs ?? DEFAULT_WEBHOOK_TOLERANCE_MS;
+    const now = options.now ?? Date.now();
+    if (!Number.isFinite(sent) || Math.abs(now - sent) > tolerance) {
+        throw new WebhookVerificationError("timestamp_out_of_tolerance", "The delivery timestamp is outside the tolerance: a replay, or a clock far off.");
+    }
+    const signed = `${timestamp}.${bodyText(options.body)}`;
+    const received = signature
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith("sha256="))
+        .map((part) => fromHex(part.slice("sha256=".length)))
+        .filter((r) => r !== null);
+    let matches = false;
+    for (const secret of secrets) {
+        const expected = await hmacSha256(secret, signed);
+        if (received.some((r) => sameBytes(r, expected)))
+            matches = true;
+    }
+    if (!matches) {
+        throw new WebhookVerificationError("signature_mismatch", "The signature does not match: wrong secret, or the body was changed (verify the RAW body, not re-serialised JSON).");
+    }
+}
+/**
+ * Verifies a delivery and returns its typed event.
+ *
+ * @example Next.js (pages router)
+ * ```ts
+ * import { constructWebhookEvent, readRawBody } from "@faable/auth-sdk";
+ *
+ * export const config = { api: { bodyParser: false } };
+ *
+ * export default async function handler(req, res) {
+ *   let event;
+ *   try {
+ *     event = await constructWebhookEvent(
+ *       await readRawBody(req),
+ *       req.headers,
+ *       process.env.FAABLEAUTH_WEBHOOK_SECRET!,
+ *     );
+ *   } catch {
+ *     return res.status(401).end();
+ *   }
+ *   if (event.type === "user.created") {
+ *     event.payload.email; // typed: the User
+ *   }
+ *   res.status(200).end();
+ * }
+ * ```
+ */
+export async function constructWebhookEvent(body, headers, secret, options = {}) {
+    await verifyWebhookSignature({
+        body,
+        signature: readHeader(headers, WEBHOOK_HEADERS.signature),
+        timestamp: readHeader(headers, WEBHOOK_HEADERS.timestamp),
+        secret,
+        ...options,
+    });
+    let event;
+    try {
+        event = JSON.parse(bodyText(body));
+    }
+    catch {
+        throw new WebhookVerificationError("invalid_body", "The body is not JSON.");
+    }
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+        throw new WebhookVerificationError("invalid_body", "The body is not a webhook event.");
+    }
+    return {
+        ...event,
+        delivery_id: readHeader(headers, WEBHOOK_HEADERS.delivery) ?? event.id,
+    };
+}
+/**
+ * The raw body of a Node request (`IncomingMessage`, Next.js pages API with
+ * `bodyParser: false`, Express without `express.json()` on the route): what
+ * the signature is computed over. With fetch-style handlers (Next.js route
+ * handlers, Hono…) use `await request.text()` instead.
+ */
+export const readRawBody = async (req) => {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(typeof chunk === "string" ? encoder.encode(chunk) : chunk);
+    }
+    const all = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let at = 0;
+    for (const c of chunks) {
+        all.set(c, at);
+        at += c.length;
+    }
+    return decoder.decode(all);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.7.107",
+  "version": "2.8.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",