hono-webhooks 0.5.1 → 0.6.0

package/dist/otel.js

@@ -49,9 +49,10 @@ function otelWebhooks(options = {}) {
       });
     },
     onEvent: (event) => {
-      const summary = summarizeEvent(event);
+      const summary = summarizeEvent(event, options.summary);
       const success = summary.status < 400;
       const call = {
+        ignored: summary.route !== null && ignored.has(summary.route),
         ...summary,
         level: summary.status >= 500 ? "error" : success ? "info" : "warn",
         outcome: summary.validation ? "validation_failed" : success ? "success" : "failed"
@@ -71,8 +72,7 @@ function otelWebhooks(options = {}) {
       span?.setStatus({
         code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
       });
-      const isIgnored = call.route !== null && ignored.has(call.route);
-      if (!isIgnored) {
+      if (!call.ignored) {
         instruments ??= createInstruments(options.meter ?? metrics.getMeter("webhooks"));
         const attributes = {
           route: call.route ?? UNMATCHED_ROUTE,
@@ -81,7 +81,7 @@ function otelWebhooks(options = {}) {
         instruments.total.add(1, attributes);
         instruments.duration.record(event.durationMs, attributes);
       }
-      if (span && options.logger && call.route !== null && !isIgnored) {
+      if (span && options.logger && call.route !== null && !call.ignored) {
         options.logger(span)[call.level]("webhook.completed", {
           event: "webhook.completed",
           route: call.route,
@@ -89,7 +89,10 @@ function otelWebhooks(options = {}) {
           status_code: call.status,
           duration_ms: call.durationMs,
           status: call.outcome,
-          ...call.error && { error_type: call.error.name }
+          ...call.error && {
+            error_type: call.error.name,
+            error_message: call.error.message
+          }
         });
       }
       return options.onWebhookCall?.(call, event);

package/dist/signatures.d.ts

@@ -17,6 +17,17 @@ export interface HmacOptions {
     /** @default 'SHA-256' */
     hash?: 'SHA-1' | 'SHA-256' | 'SHA-512';
 }
+/**
+ * The URL a provider signed. Behind a proxy `c.req.url` is the internal URL,
+ * so return the public one; return several and any match passes.
+ * @default (c) => c.req.url
+ */
+export type SignedUrl = (c: Context<any>) => string | readonly string[] | Promise<string | readonly string[]>;
+/**
+ * Why a built-in scheme rejected a request, passed to `fail` and so to
+ * `onEvent` as `validation.issues[0].message`.
+ */
+export type VerifyFailureReason = 'missing-header' | 'malformed' | 'timestamp-out-of-tolerance' | 'mismatch';
 /**
  * A scheme where one header carries an HMAC of the raw body. Covers most
  * providers; `github` and `shopify` are built with it.
@@ -27,6 +38,8 @@ export interface HmacOptions {
 export declare function hmac(options: HmacOptions): SignatureScheme;
 /** GitHub: `x-hub-signature-256: sha256=<hex>`. */
 export declare const github: SignatureScheme<void, void>;
+/** Meta (WhatsApp, Messenger, Instagram): signs like GitHub, with the app secret. */
+export declare const meta: SignatureScheme<void, void>;
 /** Shopify: `x-shopify-hmac-sha256: <base64>`. */
 export declare const shopify: SignatureScheme<void, void>;
 /**
@@ -51,3 +64,54 @@ export declare const svix: SignatureScheme<{
     id?: string;
     timestamp?: number;
 }>;
+export interface SharedSecretOptions {
+    /** Header carrying the secret, e.g. `x-gitlab-token` or `authorization`. */
+    header: string;
+    /** Text before the secret in the header, e.g. `Bearer `. */
+    prefix?: string;
+}
+/**
+ * A secret sent as is in a header (GitLab's `x-gitlab-token`, Telegram's
+ * `x-telegram-bot-api-secret-token`, `authorization: Bearer <token>`),
+ * compared in constant time. An empty secret throws (a 500).
+ *
+ * @example
+ * verify: sharedSecret({ header: 'x-gitlab-token' }).verify((c) => c.env.GITLAB_TOKEN)
+ */
+export declare function sharedSecret(options: SharedSecretOptions): SignatureScheme;
+/**
+ * Infisical: `x-infisical-signature: t=<ms>;<hex>`, an HMAC-SHA256 of the
+ * JSON body. The body's own `timestamp` (milliseconds) is what is signed, so
+ * that is what must be within `toleranceSeconds` (default 300).
+ */
+export declare const infisical: SignatureScheme<{
+    toleranceSeconds?: number;
+}>;
+/**
+ * Twilio: `x-twilio-signature: <base64>`, an HMAC-SHA1 with the auth token
+ * over the full public URL and the sorted form fields (`bodyType: 'form'`).
+ * Pass `url` when `c.req.url` is not the URL Twilio called.
+ *
+ * @example
+ * verify: twilio.verify((c) => c.env.TWILIO_AUTH_TOKEN, { url: (c) => publicUrl(c) })
+ */
+export declare const twilio: SignatureScheme<{
+    url?: SignedUrl;
+}, {
+    url: string;
+}>;
+/**
+ * HubSpot v3: `x-hubspot-signature-v3: <base64>`, an HMAC-SHA256 with the
+ * app's client secret over `<METHOD><url><body><timestamp>`, and
+ * `x-hubspot-request-timestamp` in milliseconds, rejected when more than
+ * `toleranceSeconds` (default 300) away. Pass `url` when `c.req.url` is not
+ * the URL HubSpot called.
+ */
+export declare const hubspot: SignatureScheme<{
+    url?: SignedUrl;
+    toleranceSeconds?: number;
+}, {
+    url: string;
+    method?: string;
+    timestamp?: number;
+}>;

package/dist/signatures.js

@@ -1,5 +1,6 @@
 // src/signatures.ts
 var encoder = new TextEncoder;
+var reject = (input, reason) => input.fail?.(reason) ?? false;
 function hmacKey(secret, hash) {
   if (!secret.length) {
     throw new Error("hono-webhooks: the signing secret is empty");
@@ -29,19 +30,23 @@ function fromBase64(base64) {
   }
 }
 var resolveSecret = async (secret, c) => typeof secret === "function" ? secret(c) : secret;
+var signedUrls = async (url, c) => [await url?.(c) ?? c.req.url].flat();
+var outsideTolerance = (seconds, toleranceSeconds) => Math.abs(Date.now() / 1000 - seconds) > toleranceSeconds;
 function hmac(options) {
   const { header, encoding, prefix = "", hash = "SHA-256" } = options;
   const name = header.toLowerCase();
   return {
-    verify: (secret) => async ({ c, rawBody, headers }) => {
-      const value = headers[name];
-      if (!value?.startsWith(prefix))
-        return false;
+    verify: (secret) => async (input) => {
+      const value = input.headers[name];
+      if (!value)
+        return reject(input, "missing-header");
+      if (!value.startsWith(prefix))
+        return reject(input, "malformed");
       const encoded = value.slice(prefix.length);
       const signature = encoding === "hex" ? fromHex(encoded) : fromBase64(encoded);
       if (!signature)
-        return false;
-      return hmacVerify(await resolveSecret(secret, c), rawBody, signature, hash);
+        return reject(input, "malformed");
+      return await hmacVerify(await resolveSecret(secret, input.c), input.rawBody, signature, hash) || reject(input, "mismatch");
     },
     async sign(rawBody, secret) {
       const signature = await hmacSign(secret, rawBody, hash);
@@ -56,27 +61,31 @@ var github = hmac({
   encoding: "hex",
   prefix: "sha256="
 });
+var meta = github;
 var shopify = hmac({
   header: "x-shopify-hmac-sha256",
   encoding: "base64"
 });
 var stripe = {
-  verify: (secret, { toleranceSeconds = 300 } = {}) => async ({ c, rawBody, headers }) => {
-    const parts = (headers["stripe-signature"] ?? "").split(",").map((part) => part.split("="));
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async (input) => {
+    const header = input.headers["stripe-signature"];
+    if (!header)
+      return reject(input, "missing-header");
+    const parts = header.split(",").map((part) => part.split("="));
     const timestamp = parts.find(([k]) => k === "t")?.[1] ?? "";
     if (!/^\d+$/.test(timestamp))
-      return false;
-    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
-      return false;
+      return reject(input, "malformed");
+    if (outsideTolerance(Number(timestamp), toleranceSeconds)) {
+      return reject(input, "timestamp-out-of-tolerance");
     }
-    const key = await resolveSecret(secret, c);
+    const key = await resolveSecret(secret, input.c);
     for (const [k, v] of parts) {
       const signature = k === "v1" && v ? fromHex(v) : undefined;
-      if (signature && await hmacVerify(key, `${timestamp}.${rawBody}`, signature)) {
+      if (signature && await hmacVerify(key, `${timestamp}.${input.rawBody}`, signature)) {
         return true;
       }
     }
-    return false;
+    return reject(input, "mismatch");
   },
   async sign(rawBody, secret, { timestamp } = {}) {
     const t = timestamp ?? Math.floor(Date.now() / 1000);
@@ -92,25 +101,29 @@ function svixKey(secret) {
   return key;
 }
 var svix = {
-  verify: (secret, { toleranceSeconds = 300 } = {}) => async ({ c, rawBody, headers }) => {
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async (input) => {
+    const { headers } = input;
     const prefix = headers["svix-id"] ? "svix" : "webhook";
     const id = headers[`${prefix}-id`];
-    const timestamp = headers[`${prefix}-timestamp`] ?? "";
+    const timestamp = headers[`${prefix}-timestamp`];
     const signatures = headers[`${prefix}-signature`];
-    if (!id || !signatures || !/^\d+$/.test(timestamp))
-      return false;
-    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
-      return false;
+    if (!id || !signatures || !timestamp) {
+      return reject(input, "missing-header");
     }
-    const key = svixKey(await resolveSecret(secret, c));
+    if (!/^\d+$/.test(timestamp))
+      return reject(input, "malformed");
+    if (outsideTolerance(Number(timestamp), toleranceSeconds)) {
+      return reject(input, "timestamp-out-of-tolerance");
+    }
+    const key = svixKey(await resolveSecret(secret, input.c));
     for (const entry of signatures.split(" ")) {
       const [version, encoded] = entry.split(",");
       const signature = version === "v1" && encoded ? fromBase64(encoded) : undefined;
-      if (signature && await hmacVerify(key, `${id}.${timestamp}.${rawBody}`, signature)) {
+      if (signature && await hmacVerify(key, `${id}.${timestamp}.${input.rawBody}`, signature)) {
         return true;
       }
     }
-    return false;
+    return reject(input, "mismatch");
   },
   async sign(rawBody, secret, { id, timestamp } = {}) {
     const msgId = id ?? `msg_${crypto.randomUUID().replaceAll("-", "")}`;
@@ -123,10 +136,144 @@ var svix = {
     };
   }
 };
+var compareKey;
+async function secretsEqual(given, expected) {
+  if (!expected)
+    throw new Error("hono-webhooks: the shared secret is empty");
+  compareKey ??= crypto.subtle.generateKey({ name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+  const key = await compareKey;
+  const mac = await crypto.subtle.sign("HMAC", key, encoder.encode(expected));
+  return crypto.subtle.verify("HMAC", key, mac, encoder.encode(given));
+}
+function sharedSecret(options) {
+  const { prefix = "" } = options;
+  const name = options.header.toLowerCase();
+  return {
+    verify: (secret) => async (input) => {
+      const value = input.headers[name];
+      if (!value)
+        return reject(input, "missing-header");
+      if (!value.startsWith(prefix))
+        return reject(input, "malformed");
+      return await secretsEqual(value.slice(prefix.length), await resolveSecret(secret, input.c)) || reject(input, "mismatch");
+    },
+    async sign(_rawBody, secret) {
+      return { [name]: `${prefix}${secret}` };
+    }
+  };
+}
+var infisical = {
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async (input) => {
+    const header = input.headers["x-infisical-signature"];
+    if (!header)
+      return reject(input, "missing-header");
+    const signature = fromHex(header.split(";")[1] ?? "");
+    if (!signature?.length)
+      return reject(input, "malformed");
+    let timestamp;
+    try {
+      timestamp = JSON.parse(input.rawBody)?.timestamp;
+    } catch {}
+    if (typeof timestamp !== "number")
+      return reject(input, "malformed");
+    if (!await hmacVerify(await resolveSecret(secret, input.c), input.rawBody, signature)) {
+      return reject(input, "mismatch");
+    }
+    return !outsideTolerance(timestamp / 1000, toleranceSeconds) || reject(input, "timestamp-out-of-tolerance");
+  },
+  async sign(rawBody, secret) {
+    let t;
+    try {
+      t = JSON.parse(rawBody)?.timestamp;
+    } catch {}
+    const signature = toHex(await hmacSign(secret, rawBody));
+    return { "x-infisical-signature": `t=${t ?? Date.now()};${signature}` };
+  }
+};
+function twilioPayload(url, rawBody) {
+  const fields = [...new URLSearchParams(rawBody)].sort(([a, x], [b, y]) => a === b ? x < y ? -1 : 1 : a < b ? -1 : 1);
+  return url + fields.map(([k, v]) => k + v).join("");
+}
+var twilio = {
+  verify: (secret, { url } = {}) => async (input) => {
+    const signature = input.headers["x-twilio-signature"];
+    if (!signature)
+      return reject(input, "missing-header");
+    const bytes = fromBase64(signature);
+    if (!bytes)
+      return reject(input, "malformed");
+    const key = await resolveSecret(secret, input.c);
+    for (const candidate of await signedUrls(url, input.c)) {
+      const payload = twilioPayload(candidate, input.rawBody);
+      if (await hmacVerify(key, payload, bytes, "SHA-1"))
+        return true;
+    }
+    return reject(input, "mismatch");
+  },
+  async sign(rawBody, secret, options) {
+    if (!options?.url)
+      throw new Error("hono-webhooks: twilio.sign needs a url");
+    const signature = await hmacSign(secret, twilioPayload(options.url, rawBody), "SHA-1");
+    return { "x-twilio-signature": toBase64(signature) };
+  }
+};
+var HUBSPOT_DECODE = {
+  "%3A": ":",
+  "%2F": "/",
+  "%3F": "?",
+  "%40": "@",
+  "%21": "!",
+  "%24": "$",
+  "%27": "'",
+  "%28": "(",
+  "%29": ")",
+  "%2A": "*",
+  "%2C": ",",
+  "%3B": ";"
+};
+var hubspotUrl = (url) => url.replace(/%(3A|2F|3F|40|21|24|27|28|29|2A|2C|3B)/gi, (match) => HUBSPOT_DECODE[match.toUpperCase()] ?? match);
+var hubspot = {
+  verify: (secret, { url, toleranceSeconds = 300 } = {}) => async (input) => {
+    const signature = input.headers["x-hubspot-signature-v3"];
+    const timestamp = input.headers["x-hubspot-request-timestamp"];
+    if (!signature || !timestamp)
+      return reject(input, "missing-header");
+    const bytes = fromBase64(signature);
+    if (!bytes || !/^\d+$/.test(timestamp))
+      return reject(input, "malformed");
+    if (outsideTolerance(Number(timestamp) / 1000, toleranceSeconds)) {
+      return reject(input, "timestamp-out-of-tolerance");
+    }
+    const key = await resolveSecret(secret, input.c);
+    const method = input.c.req.method.toUpperCase();
+    for (const candidate of await signedUrls(url, input.c)) {
+      const payload = `${method}${hubspotUrl(candidate)}${input.rawBody}${timestamp}`;
+      if (await hmacVerify(key, payload, bytes))
+        return true;
+    }
+    return reject(input, "mismatch");
+  },
+  async sign(rawBody, secret, options) {
+    if (!options?.url)
+      throw new Error("hono-webhooks: hubspot.sign needs a url");
+    const t = options.timestamp ?? Date.now();
+    const method = (options.method ?? "POST").toUpperCase();
+    const signature = await hmacSign(secret, `${method}${hubspotUrl(options.url)}${rawBody}${t}`);
+    return {
+      "x-hubspot-signature-v3": toBase64(signature),
+      "x-hubspot-request-timestamp": String(t)
+    };
+  }
+};
 export {
   github,
   hmac,
+  hubspot,
+  infisical,
+  meta,
+  sharedSecret,
   shopify,
   stripe,
-  svix
+  svix,
+  twilio
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -88,7 +88,7 @@
     "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@types/bun": "^1.4.2",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "hanzio": "^3.3.0",
+    "hanzio": "^3.4.0",
     "hono": "^4.13.10",
     "husky": "^9.1.7",
     "typescript": "^7.0.2",

package/src/cli-commands.ts

@@ -18,19 +18,30 @@ import {
 } from './index'
 import {
 	github,
+	hubspot,
+	infisical,
+	meta,
 	type SignatureScheme,
 	shopify,
 	stripe,
-	svix
+	svix,
+	twilio
 } from './signatures'
 
 const schemes: Record<string, SignatureScheme<any, any>> = {
 	github,
+	hubspot,
+	infisical,
+	meta,
 	shopify,
 	stripe,
-	svix
+	svix,
+	twilio
 }
 
+/** `request()` with a bare path runs at this origin, so URL-signing schemes sign it. */
+const ORIGIN = 'http://localhost'
+
 /** A file path relative to the cwd, or a package name. */
 const importModule = (specifier: string) =>
 	import(
@@ -119,6 +130,7 @@ const list = defineCommand({
 				`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
 			)
 			if (validates) print(ctx, `        validates ${validates}`)
+			if (config.verify === false) print(ctx, '        public (verify: false)')
 		}
 	}
 })
@@ -213,6 +225,7 @@ const testCommand = defineCommand({
 				headers.set('content-type', 'text/plain')
 			}
 		}
+		const url = `${path.startsWith('/') ? path : `/${path}`}${input.query ? `?${input.query}` : ''}`
 		if (input.sign) {
 			const scheme = schemes[input.sign]
 			if (!scheme) {
@@ -225,13 +238,15 @@ const testCommand = defineCommand({
 			const secret = ctx.env[name]
 			if (secret === undefined) throw new CliError(`${name} is not set`)
 			for (const [key, value] of Object.entries(
-				await scheme.sign(input.body ?? '', secret)
+				await scheme.sign(input.body ?? '', secret, {
+					url: ORIGIN + url,
+					method: method.toUpperCase()
+				})
 			)) {
 				headers.set(key, value)
 			}
 		}
 
-		const url = `${path.startsWith('/') ? path : `/${path}`}${input.query ? `?${input.query}` : ''}`
 		const start = performance.now()
 		const res = await ctx.context.request(url, {
 			method: method.toUpperCase(),