@algovoi/webhook-verifier 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+/**
+ * AlgoVoi webhook signature verifier — v1 (HMAC-SHA256) + v2 (HKDF-SHA256 / HMAC-SHA384).
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhook, WebhookVerificationError } from "@algovoi/webhook-verifier";
+ *
+ * try {
+ *   const event = verifyWebhook({
+ *     payload: req.body,           // raw Buffer
+ *     secret: process.env.ALGOVOI_WEBHOOK_SECRET!,
+ *     signatureHeader: req.headers["x-algovoi-signature"] as string,
+ *   });
+ *   console.log(event.type);       // "payment.confirmed"
+ * } catch (err) {
+ *   if (err instanceof WebhookVerificationError) {
+ *     console.error(err.code, err.message);
+ *   }
+ * }
+ * ```
+ */
+type ErrorCode = "MISSING_SIGNATURE" | "MALFORMED_SIGNATURE" | "STALE_SIGNATURE" | "INVALID_SIGNATURE" | "INVALID_PAYLOAD" | "UNKNOWN_EVENT_TYPE";
+declare const ERROR_CODES: ReadonlySet<ErrorCode>;
+interface WebhookEvent {
+    id: string;
+    type: string;
+    created: number;
+    api_version: string;
+    data: Record<string, unknown>;
+}
+interface VerifyOptions {
+    /** Raw request body bytes. */
+    payload: Buffer | Uint8Array | string;
+    /** Tenant webhook signing secret (``algvw_*``). */
+    secret: string;
+    /** Value of the ``X-AlgoVoi-Signature`` header. */
+    signatureHeader: string;
+    /**
+     * Maximum age of a valid signature in seconds. Default: 300.
+     * Pass 0 to disable (test environments only).
+     */
+    tolerance?: number;
+    /**
+     * If true, the v2 signature component must be present and valid.
+     * Default: false (v2 validated when present, accepted when absent).
+     */
+    requireV2?: boolean;
+}
+declare class WebhookVerificationError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+declare const SIGNATURE_HEADER = "X-AlgoVoi-Signature";
+declare const DEFAULT_TOLERANCE = 300;
+declare const KNOWN_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * Verify an AlgoVoi webhook signature and return the parsed event.
+ *
+ * @throws {WebhookVerificationError} on any verification failure.
+ */
+declare function verifyWebhook(options: VerifyOptions): WebhookEvent;
+
+export { DEFAULT_TOLERANCE, ERROR_CODES, type ErrorCode, KNOWN_EVENT_TYPES, SIGNATURE_HEADER, type VerifyOptions, type WebhookEvent, WebhookVerificationError, verifyWebhook };

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * AlgoVoi webhook signature verifier — v1 (HMAC-SHA256) + v2 (HKDF-SHA256 / HMAC-SHA384).
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhook, WebhookVerificationError } from "@algovoi/webhook-verifier";
+ *
+ * try {
+ *   const event = verifyWebhook({
+ *     payload: req.body,           // raw Buffer
+ *     secret: process.env.ALGOVOI_WEBHOOK_SECRET!,
+ *     signatureHeader: req.headers["x-algovoi-signature"] as string,
+ *   });
+ *   console.log(event.type);       // "payment.confirmed"
+ * } catch (err) {
+ *   if (err instanceof WebhookVerificationError) {
+ *     console.error(err.code, err.message);
+ *   }
+ * }
+ * ```
+ */
+type ErrorCode = "MISSING_SIGNATURE" | "MALFORMED_SIGNATURE" | "STALE_SIGNATURE" | "INVALID_SIGNATURE" | "INVALID_PAYLOAD" | "UNKNOWN_EVENT_TYPE";
+declare const ERROR_CODES: ReadonlySet<ErrorCode>;
+interface WebhookEvent {
+    id: string;
+    type: string;
+    created: number;
+    api_version: string;
+    data: Record<string, unknown>;
+}
+interface VerifyOptions {
+    /** Raw request body bytes. */
+    payload: Buffer | Uint8Array | string;
+    /** Tenant webhook signing secret (``algvw_*``). */
+    secret: string;
+    /** Value of the ``X-AlgoVoi-Signature`` header. */
+    signatureHeader: string;
+    /**
+     * Maximum age of a valid signature in seconds. Default: 300.
+     * Pass 0 to disable (test environments only).
+     */
+    tolerance?: number;
+    /**
+     * If true, the v2 signature component must be present and valid.
+     * Default: false (v2 validated when present, accepted when absent).
+     */
+    requireV2?: boolean;
+}
+declare class WebhookVerificationError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+declare const SIGNATURE_HEADER = "X-AlgoVoi-Signature";
+declare const DEFAULT_TOLERANCE = 300;
+declare const KNOWN_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * Verify an AlgoVoi webhook signature and return the parsed event.
+ *
+ * @throws {WebhookVerificationError} on any verification failure.
+ */
+declare function verifyWebhook(options: VerifyOptions): WebhookEvent;
+
+export { DEFAULT_TOLERANCE, ERROR_CODES, type ErrorCode, KNOWN_EVENT_TYPES, SIGNATURE_HEADER, type VerifyOptions, type WebhookEvent, WebhookVerificationError, verifyWebhook };

package/dist/index.js

@@ -0,0 +1,163 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_TOLERANCE: () => DEFAULT_TOLERANCE,
+  ERROR_CODES: () => ERROR_CODES,
+  KNOWN_EVENT_TYPES: () => KNOWN_EVENT_TYPES,
+  SIGNATURE_HEADER: () => SIGNATURE_HEADER,
+  WebhookVerificationError: () => WebhookVerificationError,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+var import_crypto = require("crypto");
+var import_crypto2 = require("crypto");
+var ERROR_CODES = /* @__PURE__ */ new Set([
+  "MISSING_SIGNATURE",
+  "MALFORMED_SIGNATURE",
+  "STALE_SIGNATURE",
+  "INVALID_SIGNATURE",
+  "INVALID_PAYLOAD",
+  "UNKNOWN_EVENT_TYPE"
+]);
+var WebhookVerificationError = class _WebhookVerificationError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+    this.code = code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _WebhookVerificationError);
+    }
+  }
+};
+var SIGNATURE_HEADER = "X-AlgoVoi-Signature";
+var DEFAULT_TOLERANCE = 300;
+var KNOWN_EVENT_TYPES = /* @__PURE__ */ new Set(["payment.confirmed"]);
+var SIG_RE = /^t=(?<ts>\d+),v1=(?<v1>[0-9a-f]{64})(?:,v2=(?<v2>[0-9a-f]{96}))?$/;
+function deriveV2Key(secretBytes) {
+  return Buffer.from(
+    (0, import_crypto2.hkdfSync)(
+      "sha256",
+      secretBytes,
+      Buffer.from("algovoi-webhook-v2-pqc"),
+      Buffer.from("hmac-sha384-outbound"),
+      48
+    )
+  );
+}
+function computeSigs(secret, ts, body) {
+  const secretBytes = Buffer.from(secret, "utf8");
+  const tsPrefix = Buffer.from(`${ts}.`, "utf8");
+  const signedPayload = Buffer.concat([tsPrefix, body]);
+  const v1 = (0, import_crypto.createHmac)("sha256", secretBytes).update(signedPayload).digest("hex");
+  const v2Key = deriveV2Key(secretBytes);
+  const v2 = (0, import_crypto.createHmac)("sha384", v2Key).update(signedPayload).digest("hex");
+  return { v1, v2 };
+}
+function timingSafeCompareHex(a, b) {
+  if (a.length !== b.length) return false;
+  return (0, import_crypto.timingSafeEqual)(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}
+function verifyWebhook(options) {
+  const {
+    payload,
+    secret,
+    signatureHeader,
+    tolerance = DEFAULT_TOLERANCE,
+    requireV2 = false
+  } = options;
+  const trimmedHeader = signatureHeader.trim();
+  if (!trimmedHeader) {
+    throw new WebhookVerificationError(
+      "MISSING_SIGNATURE",
+      "X-AlgoVoi-Signature header is absent"
+    );
+  }
+  const match = SIG_RE.exec(trimmedHeader);
+  if (!match || !match.groups) {
+    throw new WebhookVerificationError(
+      "MALFORMED_SIGNATURE",
+      `Signature header does not match expected format t=<unix>,v1=<sha256hex>[,v2=<sha384hex>]: ${signatureHeader}`
+    );
+  }
+  const ts = parseInt(match.groups.ts, 10);
+  const receivedV1 = match.groups.v1;
+  const receivedV2 = match.groups.v2;
+  if (tolerance > 0) {
+    const age = Math.abs(Math.floor(Date.now() / 1e3) - ts);
+    if (age > tolerance) {
+      throw new WebhookVerificationError(
+        "STALE_SIGNATURE",
+        `Signature timestamp ${ts} is ${age}s old (tolerance ${tolerance}s)`
+      );
+    }
+  }
+  const body = typeof payload === "string" ? Buffer.from(payload, "utf8") : Buffer.from(payload);
+  const { v1: expectedV1, v2: expectedV2 } = computeSigs(secret, ts, body);
+  const v1Ok = timingSafeCompareHex(receivedV1, expectedV1);
+  let v2Ok;
+  if (receivedV2 !== void 0) {
+    v2Ok = timingSafeCompareHex(receivedV2, expectedV2);
+  } else {
+    v2Ok = !requireV2;
+  }
+  if (!v1Ok || !v2Ok) {
+    throw new WebhookVerificationError(
+      "INVALID_SIGNATURE",
+      "One or more signature components did not match"
+    );
+  }
+  let event;
+  try {
+    event = JSON.parse(
+      typeof payload === "string" ? payload : body.toString("utf8")
+    );
+  } catch (err) {
+    throw new WebhookVerificationError(
+      "INVALID_PAYLOAD",
+      `Payload is not valid JSON: ${err.message}`
+    );
+  }
+  if (typeof event !== "object" || event === null || Array.isArray(event)) {
+    throw new WebhookVerificationError(
+      "INVALID_PAYLOAD",
+      "Payload root must be a JSON object"
+    );
+  }
+  const eventType = event.type;
+  if (!KNOWN_EVENT_TYPES.has(eventType)) {
+    throw new WebhookVerificationError(
+      "UNKNOWN_EVENT_TYPE",
+      `Unrecognised event type: ${JSON.stringify(eventType)}`
+    );
+  }
+  return event;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_TOLERANCE,
+  ERROR_CODES,
+  KNOWN_EVENT_TYPES,
+  SIGNATURE_HEADER,
+  WebhookVerificationError,
+  verifyWebhook
+});

package/dist/index.mjs

@@ -0,0 +1,133 @@
+// src/index.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { hkdfSync } from "crypto";
+var ERROR_CODES = /* @__PURE__ */ new Set([
+  "MISSING_SIGNATURE",
+  "MALFORMED_SIGNATURE",
+  "STALE_SIGNATURE",
+  "INVALID_SIGNATURE",
+  "INVALID_PAYLOAD",
+  "UNKNOWN_EVENT_TYPE"
+]);
+var WebhookVerificationError = class _WebhookVerificationError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+    this.code = code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _WebhookVerificationError);
+    }
+  }
+};
+var SIGNATURE_HEADER = "X-AlgoVoi-Signature";
+var DEFAULT_TOLERANCE = 300;
+var KNOWN_EVENT_TYPES = /* @__PURE__ */ new Set(["payment.confirmed"]);
+var SIG_RE = /^t=(?<ts>\d+),v1=(?<v1>[0-9a-f]{64})(?:,v2=(?<v2>[0-9a-f]{96}))?$/;
+function deriveV2Key(secretBytes) {
+  return Buffer.from(
+    hkdfSync(
+      "sha256",
+      secretBytes,
+      Buffer.from("algovoi-webhook-v2-pqc"),
+      Buffer.from("hmac-sha384-outbound"),
+      48
+    )
+  );
+}
+function computeSigs(secret, ts, body) {
+  const secretBytes = Buffer.from(secret, "utf8");
+  const tsPrefix = Buffer.from(`${ts}.`, "utf8");
+  const signedPayload = Buffer.concat([tsPrefix, body]);
+  const v1 = createHmac("sha256", secretBytes).update(signedPayload).digest("hex");
+  const v2Key = deriveV2Key(secretBytes);
+  const v2 = createHmac("sha384", v2Key).update(signedPayload).digest("hex");
+  return { v1, v2 };
+}
+function timingSafeCompareHex(a, b) {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}
+function verifyWebhook(options) {
+  const {
+    payload,
+    secret,
+    signatureHeader,
+    tolerance = DEFAULT_TOLERANCE,
+    requireV2 = false
+  } = options;
+  const trimmedHeader = signatureHeader.trim();
+  if (!trimmedHeader) {
+    throw new WebhookVerificationError(
+      "MISSING_SIGNATURE",
+      "X-AlgoVoi-Signature header is absent"
+    );
+  }
+  const match = SIG_RE.exec(trimmedHeader);
+  if (!match || !match.groups) {
+    throw new WebhookVerificationError(
+      "MALFORMED_SIGNATURE",
+      `Signature header does not match expected format t=<unix>,v1=<sha256hex>[,v2=<sha384hex>]: ${signatureHeader}`
+    );
+  }
+  const ts = parseInt(match.groups.ts, 10);
+  const receivedV1 = match.groups.v1;
+  const receivedV2 = match.groups.v2;
+  if (tolerance > 0) {
+    const age = Math.abs(Math.floor(Date.now() / 1e3) - ts);
+    if (age > tolerance) {
+      throw new WebhookVerificationError(
+        "STALE_SIGNATURE",
+        `Signature timestamp ${ts} is ${age}s old (tolerance ${tolerance}s)`
+      );
+    }
+  }
+  const body = typeof payload === "string" ? Buffer.from(payload, "utf8") : Buffer.from(payload);
+  const { v1: expectedV1, v2: expectedV2 } = computeSigs(secret, ts, body);
+  const v1Ok = timingSafeCompareHex(receivedV1, expectedV1);
+  let v2Ok;
+  if (receivedV2 !== void 0) {
+    v2Ok = timingSafeCompareHex(receivedV2, expectedV2);
+  } else {
+    v2Ok = !requireV2;
+  }
+  if (!v1Ok || !v2Ok) {
+    throw new WebhookVerificationError(
+      "INVALID_SIGNATURE",
+      "One or more signature components did not match"
+    );
+  }
+  let event;
+  try {
+    event = JSON.parse(
+      typeof payload === "string" ? payload : body.toString("utf8")
+    );
+  } catch (err) {
+    throw new WebhookVerificationError(
+      "INVALID_PAYLOAD",
+      `Payload is not valid JSON: ${err.message}`
+    );
+  }
+  if (typeof event !== "object" || event === null || Array.isArray(event)) {
+    throw new WebhookVerificationError(
+      "INVALID_PAYLOAD",
+      "Payload root must be a JSON object"
+    );
+  }
+  const eventType = event.type;
+  if (!KNOWN_EVENT_TYPES.has(eventType)) {
+    throw new WebhookVerificationError(
+      "UNKNOWN_EVENT_TYPE",
+      `Unrecognised event type: ${JSON.stringify(eventType)}`
+    );
+  }
+  return event;
+}
+export {
+  DEFAULT_TOLERANCE,
+  ERROR_CODES,
+  KNOWN_EVENT_TYPES,
+  SIGNATURE_HEADER,
+  WebhookVerificationError,
+  verifyWebhook
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@algovoi/webhook-verifier",
+  "version": "0.1.0",
+  "description": "Cryptographic verifier for AlgoVoi webhook signatures (v1 HMAC-SHA256 + v2 HKDF-SHA256/HMAC-SHA384)",
+  "license": "Apache-2.0",
+  "author": "AlgoVoi <dev@algovoi.co.uk>",
+  "homepage": "https://docs.algovoi.co.uk/webhook-verifier",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chopmob-cloud/algovoi-webhook-verifier"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "webhook",
+    "hmac",
+    "signature",
+    "verification",
+    "algovoi"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}