hono-webhooks 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -35,8 +35,17 @@ export interface VerifyInput<E extends Env = any> {
     rawBody: string;
     /** All request headers, lower-case names, not schema-validated. */
     headers: Record<string, string>;
+    /**
+     * Records why the check failed and returns `false`:
+     * `return fail('timestamp-out-of-tolerance')`. The reason reaches
+     * `onEvent` (`validation.issues[0].message`), never the response.
+     */
+    fail(reason: string): false;
 }
-/** Checks a request's signature. `hono-webhooks/signatures` has ready-made ones. */
+/**
+ * Checks a request's signature. `hono-webhooks/signatures` has ready-made
+ * ones. Only `true` lets the request through.
+ */
 export type Verify<E extends Env = any> = (input: VerifyInput<E>) => MaybePromise<boolean>;
 export interface WebhookConfig<P extends string = string, TParams extends Schema | undefined = Schema | undefined, TQuery extends Schema | undefined = Schema | undefined, THeaders extends Schema | undefined = Schema | undefined, TBody extends Schema | undefined = Schema | undefined, TResponse extends Schema | undefined = Schema | undefined, E extends Env = any> {
     method: WebhookMethod;
@@ -51,9 +60,14 @@ export interface WebhookConfig<P extends string = string, TParams extends Schema
      * Checks the signature right after routing, before anything is validated
      * or parsed. Returning `false` answers `401 { error: 'Invalid signature' }`.
      *
+     * Required for every method but `GET`: pass `false` for a webhook that is
+     * public on purpose, or `createWebhooks` throws.
+     *
      * @example verify: shopify.verify((c) => c.env.SHOPIFY_SECRET)
      */
-    verify?: Verify<E>;
+    verify?: Verify<E> | false;
+    /** Overrides `WebhooksOptions.maxBodyBytes` for this webhook. */
+    maxBodyBytes?: number;
     /**
      * Checks what the handler returns. A mismatch is reported on
      * `WebhookEvent.validation` and the response is still sent.
@@ -152,6 +166,12 @@ export interface WebhooksOptions<E extends Env = any> {
      * @default true
      */
     logErrors?: boolean;
+    /**
+     * Larger bodies answer `413 { error: 'Payload too large' }` before they
+     * are read. `Infinity` turns the limit off. Each webhook can override it.
+     * @default 1_048_576 (1 MiB)
+     */
+    maxBodyBytes?: number;
 }
 export type WebhooksApp<E extends Env = any> = Hono<E> & {
     /** The definitions, in the order they were passed. */
@@ -172,7 +192,12 @@ export declare class WebhookValidationError extends HTTPException {
  *
  * @example
  * defineWebhook(
- *   { method: 'POST', path: '/orders/:id', body: z.object({ total: z.number() }) },
+ *   {
+ *     method: 'POST',
+ *     path: '/orders/:id',
+ *     verify: shopify.verify((c) => c.env.SHOPIFY_SECRET),
+ *     body: z.object({ total: z.number() })
+ *   },
  *   async ({ params, body }) => ({ id: params.id, total: body.total })
  * )
  */
@@ -180,7 +205,8 @@ export declare const defineWebhook: <const P extends string, TParams extends Sch
 /**
  * Builds a Hono app that serves the webhooks. Mount it under a prefix:
  * `app.route('/webhooks', createWebhooks([...]))`. Unknown paths below the
- * prefix answer 404, known paths with the wrong method answer 405.
+ * prefix answer 404, known paths with the wrong method answer 405. Throws
+ * for a duplicate route and for a non-GET webhook without `verify`.
  */
 export declare const createWebhooks: (webhooks: readonly Webhook<any, string, any, any, any, any, any>[], options?: WebhooksOptions<any>) => WebhooksApp<any>;
 /**
@@ -213,6 +239,8 @@ export interface WebhookEventSummary {
     userAgent: string | null;
     params: Record<string, unknown> | null;
     query: Record<string, unknown> | null;
+    /** Only the headers named in `SummaryOptions.headers`; absent without that option. */
+    headers?: Record<string, string>;
     body: unknown;
     response: unknown;
     /** `null` for validation failures, which `validation` describes. */
@@ -231,19 +259,31 @@ export interface WebhookEventSummary {
         }[];
     } | null;
 }
+/** What `summarizeEvent` keeps. Defaults keep everything but headers. */
+export interface SummaryOptions {
+    /** `false` sets `body` and `response` to `null`. @default true */
+    body?: boolean;
+    /** `false` sets `query` to `null`. @default true */
+    query?: boolean;
+    /**
+     * Request headers to keep, lower-case, e.g. a delivery id such as
+     * `x-github-delivery` or `svix-id`. @default []
+     */
+    headers?: readonly string[];
+}
 /**
- * Flattens an event for logging or storage. Request headers are left out on
- * purpose: they carry signatures and credentials.
+ * Flattens an event for logging or storage. Request headers are left out
+ * unless named in `options.headers`: they carry signatures and credentials.
  *
  * @example
- * onEvent: (e) => db.insert(webhookCalls).values(summarizeEvent(e))
+ * onEvent: (e) => db.insert(webhookCalls).values(summarizeEvent(e, { body: false }))
  */
-export declare function summarizeEvent(event: WebhookEvent): WebhookEventSummary;
+export declare function summarizeEvent(event: WebhookEvent, options?: SummaryOptions): WebhookEventSummary;
 export interface WebhookDescription {
     method: WebhookMethod;
     path: string;
     description: string | null;
-    /** Whether the webhook has a `verify` function. */
+    /** Whether the webhook has a `verify` function; `false` for `verify: false`. */
     verified: boolean;
     bodyType: BodyType;
     /**
@@ -275,8 +315,20 @@ export type TestWebhookInput<W> = W extends Webhook<infer E, infer P, infer TPar
      * webhook's `bodyType` is `'form'`.
      */
     body?: In<TBody, unknown> | string;
-    /** Headers computed from the raw body, e.g. `(raw) => shopify.sign(raw, secret)`. */
-    sign?: (rawBody: string) => MaybePromise<Record<string, string>>;
+    /**
+     * Headers computed from the raw body and the request, e.g.
+     * `(raw) => shopify.sign(raw, secret)` or
+     * `(raw, { url }) => twilio.sign(raw, token, { url })`.
+     */
+    sign?: (rawBody: string, request: {
+        url: string;
+        method: string;
+    }) => MaybePromise<Record<string, string>>;
+    /**
+     * Origin the request is sent to, for schemes that sign the URL.
+     * @default 'http://localhost'
+     */
+    baseUrl?: string;
     /** Bindings, available as `c.env`. */
     env?: E extends {
         Bindings: infer B;
@@ -295,3 +347,9 @@ export type TestWebhookInput<W> = W extends Webhook<infer E, infer P, infer TPar
  * })
  */
 export declare function testWebhook<W extends Webhook>(webhook: W, input?: TestWebhookInput<W>): Promise<Response>;
+/**
+ * The webhook's path with `params` filled in, relative to the mount point:
+ * `webhookPath(oauthCallback, { provider: 'gmail' })` gives
+ * `/channels/gmail/callback`. Prepend your origin and mount prefix for a URL.
+ */
+export declare function webhookPath<P extends string>(webhook: Webhook<any, P>, ...[params]: [ParamKeys<P>] extends [never] ? [] : [PathParams<P>]): string;

package/dist/index.js

@@ -1,7 +1,9 @@
 // src/index.ts
 import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
 import { HTTPException } from "hono/http-exception";
 import { basePath } from "hono/route";
+var DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
 class WebhookValidationError extends HTTPException {
   target;
@@ -52,7 +54,7 @@ async function parse(schema, value, target) {
 }
 function defaultErrorResponse(error, c, log) {
   if (error instanceof WebhookValidationError) {
-    return c.json({ error: error.message, issues: error.issues }, error.status);
+    return error.target === "signature" ? c.json({ error: error.message }, error.status) : c.json({ error: error.message, issues: error.issues }, error.status);
   }
   if (error instanceof HTTPException) {
     return error.res ?? c.json({ error: error.message }, error.status);
@@ -77,6 +79,9 @@ function makeCreateWebhooks() {
     const app = new Hono;
     const methodsByPath = new Map;
     for (const { config } of webhooks) {
+      if (config.method !== "GET" && config.verify === undefined) {
+        throw new Error(`hono-webhooks: ${config.method} ${config.path} has no verify. Pass a verify function, or verify: false if it is public on purpose.`);
+      }
       const methods = methodsByPath.get(config.path) ?? [];
       if (methods.includes(config.method)) {
         throw new Error(`hono-webhooks: ${config.method} ${config.path} is defined twice`);
@@ -118,15 +123,32 @@ function makeCreateWebhooks() {
     const ordered = [...webhooks].sort((a, b) => Number(isDynamic(a.config.path)) - Number(isDynamic(b.config.path)));
     for (const { config, handler } of ordered) {
       app.on(config.method, config.path, handle(config.path, async (c, event) => {
+        const maxSize = config.maxBodyBytes ?? options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        if (maxSize !== Infinity) {
+          await bodyLimit({
+            maxSize,
+            onError: () => {
+              throw new HTTPException(413, { message: "Payload too large" });
+            }
+          })(c, async () => {});
+        }
         event.rawBody = await c.req.text();
-        if (config.verify && !await config.verify({
-          c,
-          rawBody: event.rawBody,
-          headers: c.req.header()
-        })) {
-          throw new WebhookValidationError("signature", [
-            { message: "Signature does not match" }
-          ]);
+        if (config.verify) {
+          let reason = "Signature does not match";
+          const ok = await config.verify({
+            c,
+            rawBody: event.rawBody,
+            headers: c.req.header(),
+            fail: (why) => {
+              reason = why;
+              return false;
+            }
+          });
+          if (ok !== true) {
+            throw new WebhookValidationError("signature", [
+              { message: reason }
+            ]);
+          }
         }
         event.params = await parse(config.params, c.req.param(), "params");
         event.query = await parse(config.query, c.req.query(), "query");
@@ -191,8 +213,15 @@ function issuePath(issue) {
   const path = issue.path?.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
   return path || null;
 }
-function summarizeEvent(event) {
+function summarizeEvent(event, options = {}) {
   const { c, error, validation } = event;
+  const keepBody = options.body ?? true;
+  const headers = {};
+  for (const name of options.headers ?? []) {
+    const value = c.req.header(name);
+    if (value !== undefined)
+      headers[name] = value;
+  }
   return {
     route: event.route ?? null,
     method: event.method,
@@ -202,9 +231,10 @@ function summarizeEvent(event) {
     ip: c.req.header("x-forwarded-for")?.split(",")[0]?.trim() || c.req.header("x-real-ip") || c.req.header("cf-connecting-ip") || null,
     userAgent: c.req.header("user-agent") ?? null,
     params: event.params ?? null,
-    query: event.query ?? null,
-    body: event.body ?? null,
-    response: event.response ?? null,
+    query: options.query === false ? null : event.query ?? null,
+    ...options.headers && { headers },
+    body: keepBody ? event.body ?? null : null,
+    response: keepBody ? event.response ?? null : null,
     error: error === undefined || error instanceof WebhookValidationError ? null : error instanceof Error ? {
       name: error.name,
       message: error.message,
@@ -253,7 +283,13 @@ function fillPath(pattern, params) {
 }
 async function testWebhook(webhook, input = {}) {
   const { config } = webhook;
-  const { body, sign, env, options } = input;
+  const {
+    body,
+    sign,
+    env,
+    options,
+    baseUrl = "http://localhost"
+  } = input;
   const headers = new Headers(input.headers);
   let rawBody;
   if (typeof body === "string") {
@@ -271,12 +307,16 @@ async function testWebhook(webhook, input = {}) {
       headers.set("content-type", "application/json");
     }
   }
-  for (const [name, value] of Object.entries(await sign?.(rawBody ?? "") ?? {})) {
-    headers.set(name, value);
-  }
   const path = input.path ?? fillPath(config.path, input.params ?? {});
   const query = new URLSearchParams(input.query).toString();
-  return createWebhooks([webhook], options).request(`${path || "/"}${query ? `?${query}` : ""}`, { method: config.method, headers, body: rawBody }, env);
+  const url = `${baseUrl.replace(/\/$/, "")}${path || "/"}${query ? `?${query}` : ""}`;
+  for (const [name, value] of Object.entries(await sign?.(rawBody ?? "", { url, method: config.method }) ?? {})) {
+    headers.set(name, value);
+  }
+  return createWebhooks([webhook], options).request(url, { method: config.method, headers, body: rawBody }, env);
+}
+function webhookPath(webhook, ...[params]) {
+  return fillPath(webhook.config.path, params ?? {}) || "/";
 }
 export {
   WebhookValidationError,
@@ -286,5 +326,6 @@ export {
   describeWebhooks,
   formatIssues,
   summarizeEvent,
-  testWebhook
+  testWebhook,
+  webhookPath
 };

package/dist/otel.d.ts

@@ -1,6 +1,6 @@
 import { type Meter, type Span, type Tracer } from '@opentelemetry/api';
 import type { Env } from 'hono';
-import { type WebhookEvent, type WebhookEventSummary, type WebhooksOptions } from 'hono-webhooks';
+import { type SummaryOptions, type WebhookEvent, type WebhookEventSummary, type WebhooksOptions } from 'hono-webhooks';
 /** The `route` label for 404s, which match no webhook. */
 export declare const UNMATCHED_ROUTE = "__unmatched__";
 /** A metric `otelWebhooks` records, described for a metric catalog. */
@@ -39,6 +39,8 @@ export interface WebhookCall extends WebhookEventSummary {
     /** `error` for 5xx, `warn` for 4xx, else `info`. */
     level: 'info' | 'warn' | 'error';
     outcome: 'success' | 'failed' | 'validation_failed';
+    /** The route is in `ignoreRoutes`: no metrics or log were recorded. */
+    ignored: boolean;
 }
 /** `console` fits, as does any logger with these three methods. */
 export type WebhookLogger = Record<WebhookCall['level'], (message: string, fields: Record<string, string | number>) => void>;
@@ -49,16 +51,18 @@ export interface OtelWebhooksOptions<E extends Env = any> {
     meter?: Meter;
     /** Routes that get a span but no metrics, e.g. `['/health']`. */
     ignoreRoutes?: readonly string[];
+    /** What `call` keeps of the request, as for `summarizeEvent`. */
+    summary?: SummaryOptions;
     /**
-     * Called after every request, ignored routes included, with the span
-     * still active: log it, store it. A returned promise is handled like
-     * `onEvent`'s.
+     * Called after every request, ignored routes included (`call.ignored`),
+     * with the span still active: log it, store it. A returned promise is
+     * handled like `onEvent`'s.
      */
     onWebhookCall?: (call: WebhookCall, event: WebhookEvent<E>) => void | Promise<void>;
     /**
      * Logs one `webhook.completed` event per request at `call.level`, with
      * `route`, `method`, `status_code`, `duration_ms`, `status` (the outcome)
-     * and `error_type`. 404s and `ignoreRoutes` are skipped. Called with the
+     * `error_type` and `error_message`. 404s and `ignoreRoutes` are skipped. Called with the
      * request's span, so the logger can attach to it.
      *
      * @example

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;
+}>;