hono-webhooks 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
 import { type Context, type Env, Hono } from 'hono';
 import { HTTPException } from 'hono/http-exception';
-import type { ParamKeys, ParamKeyToRecord } from 'hono/types';
+import type { ParamKeys } from 'hono/types';
 export type { StandardSchemaV1 };
 /** HEAD is not listed: Hono answers HEAD requests with the matching GET route. */
 export type WebhookMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
@@ -13,17 +13,32 @@ export type WebhookMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIO
  */
 export type BodyType = 'auto' | 'json' | 'form' | 'text';
 /** The part of the request (or the response) a schema validates. */
-export type ValidationTarget = 'params' | 'query' | 'headers' | 'body' | 'response';
+export type ValidationTarget = 'params' | 'query' | 'headers' | 'signature' | 'body' | 'response';
 type Schema = StandardSchemaV1;
 type Out<S, Fallback> = S extends Schema ? StandardSchemaV1.InferOutput<S> : Fallback;
 type MaybePromise<T> = T | Promise<T>;
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type ParamRecord<K extends string> = K extends `${infer Name}?` ? {
+    [N in Name]?: string;
+} : {
+    [N in K]: string;
+};
 /**
  * Params typed from the path string: `/users/:id` gives `{ id: string }`,
- * `/files/:name?` gives `{ name: string | undefined }`.
+ * `/files/:name?` gives `{ name?: string }`.
  */
-export type PathParams<P extends string> = [ParamKeys<P>] extends [never] ? Record<string, never> : UnionToIntersection<ParamKeyToRecord<ParamKeys<P>>>;
-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> {
+export type PathParams<P extends string> = [ParamKeys<P>] extends [never] ? Record<string, never> : UnionToIntersection<ParamRecord<ParamKeys<P>>>;
+/** What a `verify` function gets: the request before its body is parsed. */
+export interface VerifyInput<E extends Env = any> {
+    c: Context<E>;
+    /** The body exactly as received. */
+    rawBody: string;
+    /** All request headers, lower-case names, not schema-validated. */
+    headers: Record<string, string>;
+}
+/** Checks a request's signature. `hono-webhooks/signatures` has ready-made ones. */
+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;
     /** Hono path pattern, relative to where the webhooks are mounted. */
     path: P;
@@ -32,6 +47,13 @@ export interface WebhookConfig<P extends string = string, TParams extends Schema
     /** Header names are lower-case. */
     headers?: THeaders;
     body?: TBody;
+    /**
+     * Checks the signature before the body is parsed or validated. Returning
+     * `false` answers `401 { error: 'Invalid signature' }`.
+     *
+     * @example verify: shopify.verify((c) => c.env.SHOPIFY_SECRET)
+     */
+    verify?: Verify<E>;
     /**
      * Checks what the handler returns. A mismatch is reported on
      * `WebhookEvent.validation` and the response is still sent.
@@ -59,7 +81,7 @@ export interface WebhookInput<E extends Env, P extends string, TParams, TQuery,
  */
 export type WebhookResult<TResponse> = MaybePromise<Response | (TResponse extends Schema ? Out<TResponse, never> : unknown)>;
 export interface Webhook<E extends Env = any, P extends string = string, TParams extends Schema | undefined = any, TQuery extends Schema | undefined = any, THeaders extends Schema | undefined = any, TBody extends Schema | undefined = any, TResponse extends Schema | undefined = any> {
-    config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse>;
+    config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse, E>;
     handler(input: WebhookInput<E, P, TParams, TQuery, THeaders, TBody>): WebhookResult<TResponse>;
 }
 /** Reported once per request that reaches the webhooks, after the response is built. */
@@ -68,14 +90,21 @@ export interface WebhookEvent<E extends Env = any> {
     /** The matched path pattern, e.g. `/users/:id`. `undefined` for a 404. */
     route: string | undefined;
     method: string;
-    /** The requested path. */
+    /**
+     * The requested path relative to the mount point, e.g. `/orders/42`. The
+     * full path is `c.req.path`.
+     */
     path: string;
     status: number;
+    /** Fractional milliseconds from `performance.now()`. */
     durationMs: number;
-    /** Each part is set once it has been validated. */
-    params?: unknown;
-    query?: unknown;
-    headers?: unknown;
+    /**
+     * Each part is set once it has been validated: the schema's output, or
+     * the raw string record when there is no schema.
+     */
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
     body?: unknown;
     rawBody?: string;
     /** What the handler returned, unless it returned a `Response`. */
@@ -88,11 +117,27 @@ export interface WebhookEvent<E extends Env = any> {
         issues: readonly StandardSchemaV1.Issue[];
     };
 }
+/** What `around` knows about a request before it is handled. */
+export interface WebhookRequestInfo<E extends Env = any> {
+    c: Context<E>;
+    /** The matched path pattern, e.g. `/users/:id`. `undefined` for a 404. */
+    route: string | undefined;
+    method: string;
+}
 export interface WebhooksOptions<E extends Env = any> {
     /**
-     * Called after every request: log it, store it, record metrics. Not
-     * awaited; a returned promise is handed to `executionCtx.waitUntil` when
-     * the runtime has one, and its rejection is logged.
+     * Wraps each request, 404s and 405s included, with the route already
+     * known: start a span, set up `AsyncLocalStorage`, time it. Call `next()`
+     * to handle the request (which also runs `onEvent`) and return its
+     * response.
+     */
+    around?: (info: WebhookRequestInfo<E>, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Called after every request: log it, store it, record metrics. Runs
+     * inside the request's async context (and inside `around`), so the active
+     * span and `AsyncLocalStorage` values are available. Not awaited; a
+     * returned promise is handed to `executionCtx.waitUntil` when the runtime
+     * has one, and its rejection is logged.
      */
     onEvent?: (event: WebhookEvent<E>) => MaybePromise<void>;
     /**
@@ -101,12 +146,21 @@ export interface WebhooksOptions<E extends Env = any> {
      * and `500 { error: 'Internal Server Error' }` for anything else.
      */
     onError?: (error: unknown, c: Context<E>) => MaybePromise<Response | void>;
+    /**
+     * Log unexpected errors with `console.error` when the default 500
+     * response is used. Turn off when `onEvent` already logs them.
+     * @default true
+     */
+    logErrors?: boolean;
 }
 export type WebhooksApp<E extends Env = any> = Hono<E> & {
     /** The definitions, in the order they were passed. */
     readonly webhooks: readonly Webhook<E>[];
 };
-/** Thrown when a request part fails its schema. Answers 400 by default. */
+/**
+ * Thrown when a request part fails its schema (400) or the signature check
+ * fails (401).
+ */
 export declare class WebhookValidationError extends HTTPException {
     readonly target: Exclude<ValidationTarget, 'response'>;
     readonly issues: readonly StandardSchemaV1.Issue[];
@@ -122,7 +176,7 @@ export declare class WebhookValidationError extends HTTPException {
  *   async ({ params, body }) => ({ id: params.id, total: body.total })
  * )
  */
-export declare const defineWebhook: <const P extends string, TParams extends Schema | undefined = undefined, TQuery extends Schema | undefined = undefined, THeaders extends Schema | undefined = undefined, TBody extends Schema | undefined = undefined, TResponse extends Schema | undefined = undefined>(config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse>, handler: (input: WebhookInput<any, P, TParams, TQuery, THeaders, TBody>) => WebhookResult<TResponse>) => Webhook<any, P, TParams, TQuery, THeaders, TBody, TResponse>;
+export declare const defineWebhook: <const P extends string, TParams extends Schema | undefined = undefined, TQuery extends Schema | undefined = undefined, THeaders extends Schema | undefined = undefined, TBody extends Schema | undefined = undefined, TResponse extends Schema | undefined = undefined>(config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse, any>, handler: (input: WebhookInput<any, P, TParams, TQuery, THeaders, TBody>) => WebhookResult<TResponse>) => Webhook<any, P, TParams, TQuery, THeaders, TBody, TResponse>;
 /**
  * Builds a Hono app that serves the webhooks. Mount it under a prefix:
  * `app.route('/webhooks', createWebhooks([...]))`. Unknown paths below the
@@ -138,6 +192,105 @@ export declare const createWebhooks: (webhooks: readonly Webhook<any, string, an
  *   createWebhookFactory<{ Bindings: { STRIPE_SECRET: string } }>()
  */
 export declare function createWebhookFactory<E extends Env = any>(): {
-    defineWebhook: <const P extends string, TParams extends Schema | undefined = undefined, TQuery extends Schema | undefined = undefined, THeaders extends Schema | undefined = undefined, TBody extends Schema | undefined = undefined, TResponse extends Schema | undefined = undefined>(config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse>, handler: (input: WebhookInput<E, P, TParams, TQuery, THeaders, TBody>) => WebhookResult<TResponse>) => Webhook<E, P, TParams, TQuery, THeaders, TBody, TResponse>;
+    defineWebhook: <const P extends string, TParams extends Schema | undefined = undefined, TQuery extends Schema | undefined = undefined, THeaders extends Schema | undefined = undefined, TBody extends Schema | undefined = undefined, TResponse extends Schema | undefined = undefined>(config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse, E>, handler: (input: WebhookInput<E, P, TParams, TQuery, THeaders, TBody>) => WebhookResult<TResponse>) => Webhook<E, P, TParams, TQuery, THeaders, TBody, TResponse>;
     createWebhooks: (webhooks: readonly Webhook<E, string, any, any, any, any, any>[], options?: WebhooksOptions<E>) => WebhooksApp<E>;
 };
+/**
+ * Validation issues as one line: `total: Expected number; items.0.id: Required`.
+ */
+export declare function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string;
+/** A flat, JSON-safe record of a `WebhookEvent`, ready to log or store. */
+export interface WebhookEventSummary {
+    route: string | null;
+    method: string;
+    /** Relative to the mount point. */
+    path: string;
+    status: number;
+    /** Rounded to two decimals. */
+    durationMs: number;
+    /** From `x-forwarded-for`, `x-real-ip` or `cf-connecting-ip`; clients can spoof these. */
+    ip: string | null;
+    userAgent: string | null;
+    params: Record<string, unknown> | null;
+    query: Record<string, unknown> | null;
+    body: unknown;
+    response: unknown;
+    error: {
+        name: string;
+        message: string;
+        stack: string | null;
+    } | null;
+    validation: {
+        target: ValidationTarget;
+        /** `formatIssues(issues)` */
+        message: string;
+        issues: {
+            message: string;
+            path: string | null;
+        }[];
+    } | null;
+}
+/**
+ * Flattens an event for logging or storage. Request headers are left out on
+ * purpose: they carry signatures and credentials.
+ *
+ * @example
+ * onEvent: (e) => db.insert(webhookCalls).values(summarizeEvent(e))
+ */
+export declare function summarizeEvent(event: WebhookEvent): WebhookEventSummary;
+export interface WebhookDescription {
+    method: WebhookMethod;
+    path: string;
+    description: string | null;
+    /** Whether the webhook has a `verify` function. */
+    verified: boolean;
+    bodyType: BodyType;
+    /**
+     * JSON Schema per part: the input side for request parts, the output side
+     * for `response`. `null` when the part has no schema or its library
+     * doesn't implement Standard JSON Schema.
+     */
+    jsonSchema: Record<'params' | 'query' | 'headers' | 'body' | 'response', Record<string, unknown> | null>;
+}
+/**
+ * Describes webhooks for docs, admin pages or OpenAPI, with JSON Schemas from
+ * any library that implements Standard JSON Schema (Zod 4.2+, for example).
+ */
+export declare function describeWebhooks(source: WebhooksApp | readonly Webhook[], { target }?: {
+    target?: StandardJSONSchemaV1.Target;
+}): WebhookDescription[];
+type In<S, Fallback> = S extends Schema ? StandardSchemaV1.InferInput<S> : Fallback;
+/** What `testWebhook` sends, typed from the webhook's schemas. */
+export type TestWebhookInput<W> = W extends Webhook<infer E, infer P, infer TParams, any, any, infer TBody> ? {
+    /** Filled into the path pattern. */
+    params?: In<TParams, PathParams<P>>;
+    /** Overrides the path, e.g. for wildcard patterns. */
+    path?: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    /**
+     * A string is sent as is (`text/plain` unless you set a content
+     * type). Anything else is sent as JSON, or url-encoded when the
+     * 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>>;
+    /** Bindings, available as `c.env`. */
+    env?: E extends {
+        Bindings: infer B;
+    } ? B : unknown;
+    /** `onEvent`, `onError` and so on, as for `createWebhooks`. */
+    options?: WebhooksOptions<E>;
+} : never;
+/**
+ * Sends one request through a single webhook, with routing, signature check,
+ * validation and response handling, and returns the `Response`.
+ *
+ * @example
+ * const res = await testWebhook(orderPaid, {
+ *   params: { orderId: '42' },
+ *   body: { amount: 10, currency: 'DKK' }
+ * })
+ */
+export declare function testWebhook<W extends Webhook>(webhook: W, input?: TestWebhookInput<W>): Promise<Response>;

package/dist/index.js

@@ -1,12 +1,15 @@
 // src/index.ts
 import { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { basePath } from "hono/route";
 
 class WebhookValidationError extends HTTPException {
   target;
   issues;
   constructor(target, issues) {
-    super(400, { message: `Invalid ${target}` });
+    super(target === "signature" ? 401 : 400, {
+      message: `Invalid ${target}`
+    });
     this.target = target;
     this.issues = issues;
     this.name = "WebhookValidationError";
@@ -49,7 +52,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 }, 400);
+    return c.json({ error: error.message, issues: error.issues }, error.status);
   }
   if (error instanceof HTTPException) {
     return error.res ?? c.json({ error: error.message }, error.status);
@@ -82,13 +85,14 @@ function makeCreateWebhooks() {
       methodsByPath.set(config.path, methods);
     }
     const handle = (route, run) => {
-      return async (c) => {
+      const execute = async (c) => {
         const start = performance.now();
+        const base = basePath(c);
         const event = {
           c,
           route,
           method: c.req.method,
-          path: c.req.path,
+          path: base === "/" ? c.req.path : c.req.path.slice(base.length) || "/",
           status: 0,
           durationMs: 0
         };
@@ -100,7 +104,7 @@ function makeCreateWebhooks() {
           if (error instanceof WebhookValidationError) {
             event.validation = { target: error.target, issues: error.issues };
           }
-          res = await options.onError?.(error, c) ?? defaultErrorResponse(error, c, !options.onError);
+          res = await options.onError?.(error, c) ?? defaultErrorResponse(error, c, options.logErrors ?? true);
         }
         event.status = res.status;
         event.durationMs = performance.now() - start;
@@ -108,6 +112,8 @@ function makeCreateWebhooks() {
           report(c, options.onEvent(event));
         return res;
       };
+      const { around } = options;
+      return (c) => around ? around({ c, route, method: c.req.method }, () => execute(c)) : execute(c);
     };
     const ordered = [...webhooks].sort((a, b) => Number(isDynamic(a.config.path)) - Number(isDynamic(b.config.path)));
     for (const { config, handler } of ordered) {
@@ -116,6 +122,15 @@ function makeCreateWebhooks() {
         event.query = await parse(config.query, c.req.query(), "query");
         event.headers = await parse(config.headers, c.req.header(), "headers");
         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" }
+          ]);
+        }
         event.body = await parse(config.body, parseBody(event.rawBody, config.bodyType ?? "auto", c.req.header("content-type")), "body");
         const result = await handler({
           c,
@@ -166,9 +181,110 @@ function createWebhookFactory() {
     createWebhooks: makeCreateWebhooks()
   };
 }
+function formatIssues(issues) {
+  return issues.map((issue) => {
+    const path = issuePath(issue);
+    return path ? `${path}: ${issue.message}` : issue.message;
+  }).join("; ");
+}
+function issuePath(issue) {
+  const path = issue.path?.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
+  return path || null;
+}
+function summarizeEvent(event) {
+  const { c, error, validation } = event;
+  return {
+    route: event.route ?? null,
+    method: event.method,
+    path: event.path,
+    status: event.status,
+    durationMs: Math.round(event.durationMs * 100) / 100,
+    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,
+    error: error === undefined ? null : error instanceof Error ? {
+      name: error.name,
+      message: error.message,
+      stack: error.stack ?? null
+    } : { name: "Error", message: String(error), stack: null },
+    validation: validation ? {
+      target: validation.target,
+      message: formatIssues(validation.issues),
+      issues: validation.issues.map((issue) => ({
+        message: issue.message,
+        path: issuePath(issue)
+      }))
+    } : null
+  };
+}
+function toJsonSchema(schema, side, target) {
+  const props = schema?.["~standard"];
+  try {
+    return props?.jsonSchema?.[side]({ target }) ?? null;
+  } catch {
+    return null;
+  }
+}
+function describeWebhooks(source, { target = "draft-2020-12" } = {}) {
+  const webhooks = "webhooks" in source ? source.webhooks : source;
+  return webhooks.map(({ config }) => ({
+    method: config.method,
+    path: config.path,
+    description: config.description ?? null,
+    verified: Boolean(config.verify),
+    bodyType: config.bodyType ?? "auto",
+    jsonSchema: {
+      params: toJsonSchema(config.params, "input", target),
+      query: toJsonSchema(config.query, "input", target),
+      headers: toJsonSchema(config.headers, "input", target),
+      body: toJsonSchema(config.body, "input", target),
+      response: toJsonSchema(config.response, "output", target)
+    }
+  }));
+}
+function fillPath(pattern, params) {
+  return pattern.replace(/\/:(\w+)(?:\{[^}]*\})?\??/g, (_, name) => {
+    const value = params[name];
+    return value === undefined ? "" : `/${encodeURIComponent(String(value))}`;
+  });
+}
+async function testWebhook(webhook, input = {}) {
+  const { config } = webhook;
+  const { body, sign, env, options } = input;
+  const headers = new Headers(input.headers);
+  let rawBody;
+  if (typeof body === "string") {
+    rawBody = body;
+    if (!headers.has("content-type"))
+      headers.set("content-type", "text/plain");
+  } else if (body !== undefined && config.bodyType === "form") {
+    rawBody = new URLSearchParams(body).toString();
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/x-www-form-urlencoded");
+    }
+  } else if (body !== undefined) {
+    rawBody = JSON.stringify(body);
+    if (!headers.has("content-type")) {
+      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);
+}
 export {
   WebhookValidationError,
   createWebhookFactory,
   createWebhooks,
-  defineWebhook
+  defineWebhook,
+  describeWebhooks,
+  formatIssues,
+  summarizeEvent,
+  testWebhook
 };

package/dist/signatures.d.ts

@@ -0,0 +1,40 @@
+import type { Context } from 'hono';
+import type { Verify } from './index';
+/** A signing secret, or a function reading it per request (e.g. from `c.env`). */
+export type Secret = string | ((c: Context<any>) => string | Promise<string>);
+export interface SignatureScheme<VerifyOptions = void, SignOptions = void> {
+    /** A `verify` function for `defineWebhook`. */
+    verify(secret: Secret, options?: VerifyOptions): Verify;
+    /** The headers a provider would send with `rawBody`. For tests and the CLI. */
+    sign(rawBody: string, secret: string, options?: SignOptions): Promise<Record<string, string>>;
+}
+export interface HmacOptions {
+    /** Header carrying the signature, e.g. `x-hub-signature-256`. */
+    header: string;
+    encoding: 'hex' | 'base64';
+    /** Text before the signature in the header, e.g. `sha256=`. */
+    prefix?: string;
+    /** @default 'SHA-256' */
+    hash?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+}
+/**
+ * A scheme where one header carries an HMAC of the raw body. Covers most
+ * providers; `github` and `shopify` are built with it.
+ *
+ * @example
+ * const linear = hmac({ header: 'linear-signature', encoding: 'hex' })
+ */
+export declare function hmac(options: HmacOptions): SignatureScheme;
+/** GitHub: `x-hub-signature-256: sha256=<hex>`. */
+export declare const github: SignatureScheme<void, void>;
+/** Shopify: `x-shopify-hmac-sha256: <base64>`. */
+export declare const shopify: SignatureScheme<void, void>;
+/**
+ * Stripe: `stripe-signature: t=<unix>,v1=<hex>`, signed over `<t>.<body>`.
+ * Rejects timestamps more than `toleranceSeconds` (default 300) away.
+ */
+export declare const stripe: SignatureScheme<{
+    toleranceSeconds?: number;
+}, {
+    timestamp?: number;
+}>;

package/dist/signatures.js

@@ -0,0 +1,91 @@
+// src/signatures.ts
+var encoder = new TextEncoder;
+function hmacKey(secret, hash) {
+  if (!secret)
+    throw new Error("hono-webhooks: the signing secret is empty");
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash }, false, ["sign", "verify"]);
+}
+async function hmacSign(secret, payload, hash = "SHA-256") {
+  const key = await hmacKey(secret, hash);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(payload)));
+}
+async function hmacVerify(secret, payload, signature, hash = "SHA-256") {
+  const key = await hmacKey(secret, hash);
+  return crypto.subtle.verify("HMAC", key, signature, encoder.encode(payload));
+}
+var toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+var toBase64 = (bytes) => btoa(String.fromCharCode(...bytes));
+function fromHex(hex) {
+  if (hex.length % 2 || /[^0-9a-f]/i.test(hex))
+    return;
+  return Uint8Array.from(hex.match(/../g) ?? [], (h) => Number.parseInt(h, 16));
+}
+function fromBase64(base64) {
+  try {
+    return Uint8Array.from(atob(base64), (ch) => ch.charCodeAt(0));
+  } catch {
+    return;
+  }
+}
+var resolveSecret = async (secret, c) => typeof secret === "function" ? secret(c) : secret;
+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;
+      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);
+    },
+    async sign(rawBody, secret) {
+      const signature = await hmacSign(secret, rawBody, hash);
+      return {
+        [name]: `${prefix}${encoding === "hex" ? toHex(signature) : toBase64(signature)}`
+      };
+    }
+  };
+}
+var github = hmac({
+  header: "x-hub-signature-256",
+  encoding: "hex",
+  prefix: "sha256="
+});
+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("="));
+    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;
+    }
+    const key = await resolveSecret(secret, c);
+    for (const [k, v] of parts) {
+      const signature = k === "v1" && v ? fromHex(v) : undefined;
+      if (signature && await hmacVerify(key, `${timestamp}.${rawBody}`, signature)) {
+        return true;
+      }
+    }
+    return false;
+  },
+  async sign(rawBody, secret, { timestamp } = {}) {
+    const t = timestamp ?? Math.floor(Date.now() / 1000);
+    const signature = await hmacSign(secret, `${t}.${rawBody}`);
+    return { "stripe-signature": `t=${t},v1=${toHex(signature)}` };
+  }
+};
+export {
+  github,
+  hmac,
+  shopify,
+  stripe
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,11 +42,17 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./signatures": {
+      "types": "./dist/signatures.d.ts",
+      "bun": "./src/signatures.ts",
+      "import": "./dist/signatures.js",
+      "default": "./dist/signatures.js"
     }
   },
   "scripts": {
     "build": "rm -rf dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/cli.ts --outdir ./dist --target node --packages external",
+    "build:js": "bun build ./src/index.ts ./src/signatures.ts ./src/cli.ts --outdir ./dist --target node --packages external",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
@@ -59,7 +65,7 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "peerDependencies": {
-    "hono": "^4.6.0"
+    "hono": "^4.8.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",