@zap-studio/webhooks 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @zap-studio/webhooks
 
+## 0.2.0
+
+### Minor Changes
+
+- c686862: Switch `createHmacVerifier` to Web Crypto and standardize the verifier around string secrets.
+
+  This change removes the Node `crypto` dependency from the verifier path, keeps `req.rawBody` as `Uint8Array`, simplifies `createHmacVerifier` to take a string secret, and adds public `VerificationError` in `@zap-studio/webhooks/errors` for verifier setup and signature failures.
+
+## 0.1.4
+
+### Patch Changes
+
+- e26293e: Updated dependencies.
+  - @zap-studio/validation@0.3.2
+
 ## 0.1.3
 
 ### Patch Changes

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Alexandre Trotel
+Copyright (c) 2026 Alexandre Trotel
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # @zap-studio/webhooks
 
-Schema-first, type-safe webhook routing with signature verification support.
+Schema-first, type-safe webhook routing with runtime-agnostic signature verification support.
 
 Works with any validation library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), including Zod, Valibot, and ArkType.
 
@@ -90,11 +90,7 @@ const router = createWebhookRouter({
       throw new Error("Missing Stripe signature");
     }
 
-    stripe.webhooks.constructEvent(
-      req.rawBody,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
+    stripe.webhooks.constructEvent(req.rawBody, signature, process.env.STRIPE_WEBHOOK_SECRET!);
   },
 });
 
@@ -138,18 +134,33 @@ const router = createWebhookRouter({
 
 `@zap-studio/webhooks/verify` exports `createHmacVerifier`, a small helper that builds a `verify` function for HMAC-signed webhook providers.
 
+It does not depend on Node APIs. The verifier uses the Web Crypto API, so it works in any runtime that provides `globalThis.crypto.subtle`.
+
 - reads a signature from the header you choose
 - computes an HMAC from `req.rawBody`
 - compares signatures in constant time
+- uses the Web Crypto API instead of Node `crypto`
+- works across runtimes that provide `globalThis.crypto.subtle`
+- expects a string secret
+- throws `VerificationError` on verifier setup or signature failures
 
 ```ts
 import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+import { VerificationError } from "@zap-studio/webhooks/errors";
 
 const verify = createHmacVerifier({
   headerName: "x-hub-signature-256",
   secret: process.env.WEBHOOK_SECRET!,
   algo: "sha256", // optional, defaults to sha256
 });
+
+try {
+  await verify(req);
+} catch (error) {
+  if (error instanceof VerificationError) {
+    console.error("webhook verification failed", error.message);
+  }
+}
 ```
 
 Use this when your provider uses standard HMAC signatures. For providers with custom signing formats, pass your own `verify` function.
@@ -178,15 +189,10 @@ class MyHttpAdapter extends BaseAdapter {
     };
   }
 
-  async toFrameworkResponse(
-    res: any,
-    normalized: NormalizedResponse
-  ): Promise<any> {
+  async toFrameworkResponse(res: any, normalized: NormalizedResponse): Promise<any> {
     res.statusCode = normalized.status;
     res.end(
-      typeof normalized.body === "string"
-        ? normalized.body
-        : JSON.stringify(normalized.body)
+      typeof normalized.body === "string" ? normalized.body : JSON.stringify(normalized.body),
     );
     return res;
   }

package/bin/intent.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+await import("@tanstack/intent/intent-library");

package/dist/adapters/base.d.mts

@@ -1,58 +1,58 @@
 import { NormalizedRequest, NormalizedResponse } from "../types/index.mjs";
 
 //#region src/adapters/base.d.ts
-
 /**
- * Minimal framework adapter contract.
- *
- * Implement this when integrating the webhook router with an HTTP framework.
- */
+* Minimal framework adapter contract.
+*
+* Implement this when integrating the webhook router with an HTTP framework.
+*/
 interface Adapter {
   /**
-   * Creates a framework handler that:
-   * 1. normalizes the incoming framework request
-   * 2. executes the webhook router
-   * 3. writes the normalized response back to the framework response
-   */
+  * Creates a framework handler that:
+  * 1. normalizes the incoming framework request
+  * 2. executes the webhook router
+  * 3. writes the normalized response back to the framework response
+  */
   handleWebhook<TFrameworkReq = unknown, TFrameworkRes = unknown>(router: {
     handle(req: NormalizedRequest): Promise<NormalizedResponse>;
   }): (req: TFrameworkReq, res: TFrameworkRes) => Promise<void>;
   /**
-   * Maps a normalized router response to the framework response object.
-   *
-   * @param frameworkRes - Framework-specific response object (e.g. `res`)
-   * @param res - Normalized response returned by the webhook router
-   */
+  * Maps a normalized router response to the framework response object.
+  *
+  * @param frameworkRes - Framework-specific response object (e.g. `res`)
+  * @param res - Normalized response returned by the webhook router
+  */
   toFrameworkResponse<TFrameworkRes = unknown>(frameworkRes: TFrameworkRes, res: NormalizedResponse): Promise<TFrameworkRes>;
   /**
-   * Maps a framework request into the normalized request contract.
-   *
-   * The returned object must include `rawBody` to support signature verification.
-   *
-   * @param req - Framework-specific request object
-   */
+  * Maps a framework request into the normalized request contract.
+  *
+  * The returned object must include `rawBody` to support signature verification.
+  *
+  * @param req - Framework-specific request object
+  */
   toNormalizedRequest<TReq = unknown>(req: TReq): Promise<NormalizedRequest>;
 }
 /**
- * Base adapter helper.
- *
- * Extend this class in consumers to keep framework integration boilerplate
- * in one place while relying on the package router contract.
- */
+* Base adapter helper.
+*
+* Extend this class in consumers to keep framework integration boilerplate
+* in one place while relying on the package router contract.
+*/
 declare abstract class BaseAdapter implements Adapter {
   /** @inheritdoc */
   abstract toNormalizedRequest<TReq = unknown>(req: TReq): Promise<NormalizedRequest>;
   /** @inheritdoc */
   abstract toFrameworkResponse<TFrameworkRes = unknown>(frameworkRes: TFrameworkRes, res: NormalizedResponse): Promise<TFrameworkRes>;
   /**
-   * Shared adapter pipeline implementation.
-   *
-   * Most consumers only need to implement request/response mapping methods and
-   * can reuse this default orchestration.
-   */
+  * Shared adapter pipeline implementation.
+  *
+  * Most consumers only need to implement request/response mapping methods and
+  * can reuse this default orchestration.
+  */
   handleWebhook<TFrameworkReq = unknown, TFrameworkRes = unknown>(router: {
     handle(req: NormalizedRequest): Promise<NormalizedResponse>;
   }): (req: TFrameworkReq, res: TFrameworkRes) => Promise<void>;
 }
 //#endregion
-export { Adapter, BaseAdapter };
+export { Adapter, BaseAdapter };
+//# sourceMappingURL=base.d.mts.map

package/dist/adapters/base.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.mts","names":[],"sources":["../../src/adapters/base.ts"],"mappings":";;;;;AAOA;;;UAAiB,OAAA;;;;;;;EAOf,aAAA,mDAAgE,MAAA;IAC9D,MAAA,CAAO,GAAA,EAAK,iBAAA,GAAoB,OAAA,CAAQ,kBAAA;EAAA,KACrC,GAAA,EAAK,aAAA,EAAe,GAAA,EAAK,aAAA,KAAkB,OAAA;;;;;;;EAQhD,mBAAA,0BACE,YAAA,EAAc,aAAA,EACd,GAAA,EAAK,kBAAA,GACJ,OAAA,CAAQ,aAAA;;;;;;;;EASX,mBAAA,iBAAoC,GAAA,EAAK,IAAA,GAAO,OAAA,CAAQ,iBAAA;AAAA;;;;;;;uBASpC,WAAA,YAAuB,OAAA;;WAElC,mBAAA,gBAAA,CAAoC,GAAA,EAAK,IAAA,GAAO,OAAA,CAAQ,iBAAA;;WAExD,mBAAA,yBAAA,CACP,YAAA,EAAc,aAAA,EACd,GAAA,EAAK,kBAAA,GACJ,OAAA,CAAQ,aAAA;;;;;;AAPb;EAeE,aAAA,kDAAA,CAAgE,MAAA;IAC9D,MAAA,CAAO,GAAA,EAAK,iBAAA,GAAoB,OAAA,CAAQ,kBAAA;EAAA,KACrC,GAAA,EAAK,aAAA,EAAe,GAAA,EAAK,aAAA,KAAkB,OAAA;AAAA"}

package/dist/adapters/base.mjs

@@ -20,6 +20,7 @@ var BaseAdapter = class {
 		};
 	}
 };
-
 //#endregion
-export { BaseAdapter };
+export { BaseAdapter };
+
+//# sourceMappingURL=base.mjs.map

package/dist/adapters/base.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.mjs","names":[],"sources":["../../src/adapters/base.ts"],"sourcesContent":["import type { NormalizedRequest, NormalizedResponse } from \"../types/index.js\";\n\n/**\n * Minimal framework adapter contract.\n *\n * Implement this when integrating the webhook router with an HTTP framework.\n */\nexport interface Adapter {\n  /**\n   * Creates a framework handler that:\n   * 1. normalizes the incoming framework request\n   * 2. executes the webhook router\n   * 3. writes the normalized response back to the framework response\n   */\n  handleWebhook<TFrameworkReq = unknown, TFrameworkRes = unknown>(router: {\n    handle(req: NormalizedRequest): Promise<NormalizedResponse>;\n  }): (req: TFrameworkReq, res: TFrameworkRes) => Promise<void>;\n\n  /**\n   * Maps a normalized router response to the framework response object.\n   *\n   * @param frameworkRes - Framework-specific response object (e.g. `res`)\n   * @param res - Normalized response returned by the webhook router\n   */\n  toFrameworkResponse<TFrameworkRes = unknown>(\n    frameworkRes: TFrameworkRes,\n    res: NormalizedResponse,\n  ): Promise<TFrameworkRes>;\n\n  /**\n   * Maps a framework request into the normalized request contract.\n   *\n   * The returned object must include `rawBody` to support signature verification.\n   *\n   * @param req - Framework-specific request object\n   */\n  toNormalizedRequest<TReq = unknown>(req: TReq): Promise<NormalizedRequest>;\n}\n\n/**\n * Base adapter helper.\n *\n * Extend this class in consumers to keep framework integration boilerplate\n * in one place while relying on the package router contract.\n */\nexport abstract class BaseAdapter implements Adapter {\n  /** @inheritdoc */\n  abstract toNormalizedRequest<TReq = unknown>(req: TReq): Promise<NormalizedRequest>;\n  /** @inheritdoc */\n  abstract toFrameworkResponse<TFrameworkRes = unknown>(\n    frameworkRes: TFrameworkRes,\n    res: NormalizedResponse,\n  ): Promise<TFrameworkRes>;\n\n  /**\n   * Shared adapter pipeline implementation.\n   *\n   * Most consumers only need to implement request/response mapping methods and\n   * can reuse this default orchestration.\n   */\n  handleWebhook<TFrameworkReq = unknown, TFrameworkRes = unknown>(router: {\n    handle(req: NormalizedRequest): Promise<NormalizedResponse>;\n  }): (req: TFrameworkReq, res: TFrameworkRes) => Promise<void> {\n    return async (req, res) => {\n      const normalizedReq = await this.toNormalizedRequest(req);\n      const normalizedRes = await router.handle(normalizedReq);\n      await this.toFrameworkResponse(res, normalizedRes);\n    };\n  }\n}\n"],"mappings":";;;;;;;AA6CA,IAAsB,cAAtB,MAAqD;;;;;;;CAenD,cAAgE,QAEF;AAC5D,SAAO,OAAO,KAAK,QAAQ;GACzB,MAAM,gBAAgB,MAAM,KAAK,oBAAoB,IAAI;GACzD,MAAM,gBAAgB,MAAM,OAAO,OAAO,cAAc;AACxD,SAAM,KAAK,oBAAoB,KAAK,cAAc"}

package/dist/errors.d.mts

@@ -0,0 +1,13 @@
+//#region src/errors.d.ts
+/**
+* Error thrown when webhook request verification fails.
+*
+* This error is used by verifier helpers such as `createHmacVerifier` so
+* callers can distinguish verification failures from other webhook errors.
+*/
+declare class VerificationError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { VerificationError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"mappings":";;AAMA;;;;;cAAa,iBAAA,SAA0B,KAAA;EACrC,WAAA,CAAY,OAAA;AAAA"}

package/dist/errors.mjs

@@ -0,0 +1,17 @@
+//#region src/errors.ts
+/**
+* Error thrown when webhook request verification fails.
+*
+* This error is used by verifier helpers such as `createHmacVerifier` so
+* callers can distinguish verification failures from other webhook errors.
+*/
+var VerificationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "VerificationError";
+	}
+};
+//#endregion
+export { VerificationError };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error thrown when webhook request verification fails.\n *\n * This error is used by verifier helpers such as `createHmacVerifier` so\n * callers can distinguish verification failures from other webhook errors.\n */\nexport class VerificationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"VerificationError\";\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,SAAiB;AAC3B,QAAM,QAAQ;AACd,OAAK,OAAO"}

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { AfterHook, BeforeHook, ErrorHook, InferSchemaOutput, NormalizedRequest, NormalizedResponse, RegisterOptions, SchemaRouteOptions, WebhookHandler } from "./types/index.mjs";
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import { StandardSchemaV1 } from "@zap-studio/validation";
 
 //#region src/index.d.ts
 interface WebhookRouterOptions {
@@ -15,10 +15,10 @@ interface WebhookRouterOptions {
   verify?: (req: NormalizedRequest) => Promise<void> | void;
 }
 /**
- * Main webhook router class.
- *
- * Register routes with typed schemas and call `handle` with a normalized request.
- */
+* Main webhook router class.
+*
+* Register routes with typed schemas and call `handle` with a normalized request.
+*/
 declare class WebhookRouter<TMap = unknown> {
   private readonly handlers;
   private readonly verify?;
@@ -28,23 +28,23 @@ declare class WebhookRouter<TMap = unknown> {
   private readonly prefix;
   constructor(opts?: WebhookRouterOptions);
   /**
-   * Register a webhook handler for a specific path.
-   *
-   * When a schema is provided, `payload` is inferred from the schema output type.
-   *
-   * @param path - Route path relative to configured prefix.
-   * @param handlerOrOptions - Handler function or schema-based registration options.
-   * @returns The same router instance with an updated internal route type map.
-   */
+  * Register a webhook handler for a specific path.
+  *
+  * When a schema is provided, `payload` is inferred from the schema output type.
+  *
+  * @param path - Route path relative to configured prefix.
+  * @param handlerOrOptions - Handler function or schema-based registration options.
+  * @returns The same router instance with an updated internal route type map.
+  */
   register<Path extends string, TSchema extends StandardSchemaV1<unknown, unknown>>(path: Path, handlerOrOptions: SchemaRouteOptions<TSchema>): WebhookRouter<TMap & Record<Path, InferSchemaOutput<TSchema>>>;
   register<Path extends string, TPayload>(path: Path, handlerOrOptions: RegisterOptions<TPayload>): WebhookRouter<TMap & Record<Path, TPayload>>;
   register<Path extends string>(path: Path, handlerOrOptions: WebhookHandler<unknown>): WebhookRouter<TMap & Record<Path, unknown>>;
   /**
-   * Handles a normalized incoming webhook request.
-   *
-   * @param req - Normalized request object.
-   * @returns Normalized response for the adapter/framework layer.
-   */
+  * Handles a normalized incoming webhook request.
+  *
+  * @param req - Normalized request object.
+  * @returns Normalized response for the adapter/framework layer.
+  */
   handle(req: NormalizedRequest): Promise<NormalizedResponse>;
   private normalizePath;
   private runGlobalBeforeHooks;
@@ -58,11 +58,12 @@ declare class WebhookRouter<TMap = unknown> {
   private handleError;
 }
 /**
- * Factory helper for creating a webhook router instance.
- *
- * @param opts - Optional global router options.
- * @returns A new webhook router.
- */
+* Factory helper for creating a webhook router instance.
+*
+* @param opts - Optional global router options.
+* @returns A new webhook router.
+*/
 declare function createWebhookRouter(opts?: WebhookRouterOptions): WebhookRouter;
 //#endregion
-export { WebhookRouter, WebhookRouterOptions, createWebhookRouter };
+export { WebhookRouter, WebhookRouterOptions, createWebhookRouter };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;UA6BiB,oBAAA;;EAEf,KAAA,GAAQ,SAAA,GAAY,SAAA;EAFL;EAIf,MAAA,GAAS,UAAA,GAAa,UAAA;;EAEtB,OAAA,GAAU,SAAA;;EAEV,MAAA;;EAEA,MAAA,IAAU,GAAA,EAAK,iBAAA,KAAsB,OAAA;AAAA;;;;;;cAQ1B,aAAA;EAAA,iBACM,QAAA;EAAA,iBACA,MAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,gBAAA;EAAA,iBACA,eAAA;EAAA,iBACA,MAAA;EAEjB,WAAA,CAAY,IAAA,GAAO,oBAAA;;;;;AARrB;;;;;EAkCE,QAAA,sCAA8C,gBAAA,mBAAA,CAC5C,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,kBAAA,CAAmB,OAAA,IACpC,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA,EAAM,iBAAA,CAAkB,OAAA;EACvD,QAAA,+BAAA,CACE,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,eAAA,CAAgB,QAAA,IACjC,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA,EAAM,QAAA;EACrC,QAAA,qBAAA,CACE,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,cAAA,YACjB,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA;;;;;;;EAkD/B,MAAA,CAAa,GAAA,EAAK,iBAAA,GAAoB,OAAA,CAAQ,kBAAA;EAAA,QAsCtC,aAAA;EAAA,QA0BM,oBAAA;EAAA,QAMA,mBAAA;EAAA,QAQN,gBAAA;EAAA,QAUA,eAAA;EAAA,QASM,eAAA;EAAA,QA8BA,cAAA;EAAA,QAyBA,kBAAA;EAAA,QAYA,mBAAA;EAAA,QASA,WAAA;AAAA;;;;;;;iBA0BA,mBAAA,CAAoB,IAAA,GAAO,oBAAA,GAAuB,aAAA"}

package/dist/index.mjs

@@ -1,5 +1,4 @@
 import { standardValidate } from "@zap-studio/validation";
-
 //#region src/index.ts
 /**
 * Main webhook router class.
@@ -27,12 +26,11 @@ var WebhookRouter = class {
 			if (handlerOrOptions.before) beforeHooks = Array.isArray(handlerOrOptions.before) ? handlerOrOptions.before : [handlerOrOptions.before];
 			let afterHooks;
 			if (handlerOrOptions.after) afterHooks = Array.isArray(handlerOrOptions.after) ? handlerOrOptions.after : [handlerOrOptions.after];
-			this.handlers[path] = {
-				handler: handlerOrOptions.handler,
-				schema: handlerOrOptions.schema,
-				before: beforeHooks,
-				after: afterHooks
-			};
+			const entry = { handler: handlerOrOptions.handler };
+			if (handlerOrOptions.schema !== void 0) entry.schema = handlerOrOptions.schema;
+			if (beforeHooks !== void 0) entry.before = beforeHooks;
+			if (afterHooks !== void 0) entry.after = afterHooks;
+			this.handlers[path] = entry;
 		}
 		return this;
 	}
@@ -86,7 +84,7 @@ var WebhookRouter = class {
 	}
 	parseRequestBody(req) {
 		try {
-			const parsed = JSON.parse(req.rawBody.toString());
+			const parsed = JSON.parse(new TextDecoder().decode(req.rawBody));
 			req.json = parsed;
 			return parsed;
 		} catch {
@@ -115,11 +113,14 @@ var WebhookRouter = class {
 		return await handler({
 			req,
 			payload: validatedPayload,
-			ack: async (r) => ({
-				status: r?.status ?? 200,
-				body: r?.body ?? "ok",
-				headers: r?.headers
-			})
+			ack: async (r) => {
+				const response = {
+					status: r?.status ?? 200,
+					body: r?.body ?? "ok"
+				};
+				if (r?.headers !== void 0) response.headers = r.headers;
+				return response;
+			}
 		}) ?? {
 			status: 200,
 			body: "ok"
@@ -151,6 +152,7 @@ var WebhookRouter = class {
 function createWebhookRouter(opts) {
 	return new WebhookRouter(opts);
 }
-
 //#endregion
-export { WebhookRouter, createWebhookRouter };
+export { WebhookRouter, createWebhookRouter };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@zap-studio/validation\";\nimport { standardValidate } from \"@zap-studio/validation\";\nimport type {\n  AfterHook,\n  BeforeHook,\n  ErrorHook,\n  InferSchemaOutput,\n  NormalizedRequest,\n  NormalizedResponse,\n  RegisterOptions,\n  SchemaRouteOptions,\n  WebhookHandler,\n} from \"./types/index.js\";\n\n/**\n * Schema-first webhook router with path dispatching, validation, and optional verification.\n *\n * @typeParam TMap - Internal route payload map built incrementally via `register`.\n */\n\ninterface HandlerEntry<TPayload = unknown> {\n  after?: AfterHook[];\n  before?: BeforeHook[];\n  handler: WebhookHandler<TPayload>;\n  schema?: StandardSchemaV1<unknown, TPayload>;\n}\n\ntype HandlerStore = Record<string, HandlerEntry<unknown>>;\n\nexport interface WebhookRouterOptions {\n  /** Global hooks executed after successful route handler completion. */\n  after?: AfterHook | AfterHook[];\n  /** Global hooks executed before route-level hooks and verification. */\n  before?: BeforeHook | BeforeHook[];\n  /** Global error hook used to override the default `500` response. */\n  onError?: ErrorHook;\n  /** Required path prefix for all webhook routes. Defaults to `\"/webhooks/\"`. */\n  prefix?: string;\n  /** Optional request verification function (for signature checks, auth, etc.). */\n  verify?: (req: NormalizedRequest) => Promise<void> | void;\n}\n\n/**\n * Main webhook router class.\n *\n * Register routes with typed schemas and call `handle` with a normalized request.\n */\nexport class WebhookRouter<TMap = unknown> {\n  private readonly handlers: HandlerStore = {};\n  private readonly verify?: (req: NormalizedRequest) => Promise<void> | void;\n  private readonly globalBeforeHooks: BeforeHook[] = [];\n  private readonly globalAfterHooks: AfterHook[] = [];\n  private readonly globalErrorHook?: ErrorHook;\n  private readonly prefix: string;\n\n  constructor(opts?: WebhookRouterOptions) {\n    this.prefix = opts?.prefix ?? \"/webhooks/\";\n\n    if (opts?.verify) {\n      this.verify = opts.verify;\n    }\n    if (opts?.before) {\n      this.globalBeforeHooks = Array.isArray(opts.before) ? opts.before : [opts.before];\n    }\n    if (opts?.after) {\n      this.globalAfterHooks = Array.isArray(opts.after) ? opts.after : [opts.after];\n    }\n    if (opts?.onError) {\n      this.globalErrorHook = opts.onError;\n    }\n  }\n\n  /**\n   * Register a webhook handler for a specific path.\n   *\n   * When a schema is provided, `payload` is inferred from the schema output type.\n   *\n   * @param path - Route path relative to configured prefix.\n   * @param handlerOrOptions - Handler function or schema-based registration options.\n   * @returns The same router instance with an updated internal route type map.\n   */\n  register<Path extends string, TSchema extends StandardSchemaV1<unknown, unknown>>(\n    path: Path,\n    handlerOrOptions: SchemaRouteOptions<TSchema>,\n  ): WebhookRouter<TMap & Record<Path, InferSchemaOutput<TSchema>>>;\n  register<Path extends string, TPayload>(\n    path: Path,\n    handlerOrOptions: RegisterOptions<TPayload>,\n  ): WebhookRouter<TMap & Record<Path, TPayload>>;\n  register<Path extends string>(\n    path: Path,\n    handlerOrOptions: WebhookHandler<unknown>,\n  ): WebhookRouter<TMap & Record<Path, unknown>>;\n  register(\n    path: string,\n    handlerOrOptions: WebhookHandler<unknown> | RegisterOptions<unknown>,\n  ): WebhookRouter<TMap> {\n    if (typeof handlerOrOptions === \"function\") {\n      this.handlers[path] = {\n        handler: handlerOrOptions,\n      };\n    } else {\n      let beforeHooks: BeforeHook[] | undefined;\n      if (handlerOrOptions.before) {\n        beforeHooks = Array.isArray(handlerOrOptions.before)\n          ? handlerOrOptions.before\n          : [handlerOrOptions.before];\n      }\n\n      let afterHooks: AfterHook[] | undefined;\n      if (handlerOrOptions.after) {\n        afterHooks = Array.isArray(handlerOrOptions.after)\n          ? handlerOrOptions.after\n          : [handlerOrOptions.after];\n      }\n\n      const entry: HandlerEntry<unknown> = {\n        handler: handlerOrOptions.handler,\n      };\n\n      if (handlerOrOptions.schema !== undefined) {\n        entry.schema = handlerOrOptions.schema;\n      }\n      if (beforeHooks !== undefined) {\n        entry.before = beforeHooks;\n      }\n      if (afterHooks !== undefined) {\n        entry.after = afterHooks;\n      }\n\n      this.handlers[path] = entry;\n    }\n\n    return this;\n  }\n\n  /**\n   * Handles a normalized incoming webhook request.\n   *\n   * @param req - Normalized request object.\n   * @returns Normalized response for the adapter/framework layer.\n   */\n  async handle(req: NormalizedRequest): Promise<NormalizedResponse> {\n    try {\n      const normalizedPath = this.normalizePath(req);\n\n      if (normalizedPath === null) {\n        return { status: 404, body: { error: \"not found\" } };\n      }\n\n      const handlerEntry = this.handlers[normalizedPath];\n      if (!handlerEntry) {\n        return { status: 404, body: { error: \"not found\" } };\n      }\n\n      await this.runGlobalBeforeHooks(req);\n      await this.runRouteBeforeHooks(req, handlerEntry.before);\n\n      if (this.verify) {\n        await this.verify(req);\n      }\n\n      const parsedJson = this.parseRequestBody(req);\n      const validationResult = await this.validatePayload(parsedJson, handlerEntry.schema);\n\n      if (this.isErrorResponse(validationResult)) {\n        return validationResult;\n      }\n\n      const response = await this.executeHandler(handlerEntry.handler, req, validationResult);\n\n      await this.runRouteAfterHooks(req, response, handlerEntry.after);\n      await this.runGlobalAfterHooks(req, response);\n\n      return response;\n    } catch (error) {\n      return this.handleError(error, req);\n    }\n  }\n\n  private normalizePath(req: NormalizedRequest): string | null {\n    let pathname = req.path;\n    try {\n      // Try to parse as URL (e.g. handles full URLs like https://example.com/webhooks/path -> /webhooks/path)\n      const url = new URL(req.path);\n      pathname = url.pathname;\n    } catch {\n      // Not a full URL, use the path as-is\n    }\n\n    // Require prefix (e.g. /webhooks/path -> /path)\n    if (!pathname.startsWith(this.prefix)) {\n      // Path doesn't start with the required prefix - not a webhook route\n      return null;\n    }\n\n    // Strip prefix and keep the leading slash\n    pathname = pathname.slice(this.prefix.length - 1);\n    req.path = pathname;\n\n    // Normalize path by removing leading slash for handler matching (e.g. /path -> path)\n    const normalizedPath = pathname.startsWith(\"/\") ? pathname.slice(1) : pathname;\n\n    return normalizedPath;\n  }\n\n  private async runGlobalBeforeHooks(req: NormalizedRequest): Promise<void> {\n    for (const hook of this.globalBeforeHooks) {\n      await hook(req);\n    }\n  }\n\n  private async runRouteBeforeHooks(req: NormalizedRequest, before?: BeforeHook[]): Promise<void> {\n    if (before) {\n      for (const hook of before) {\n        await hook(req);\n      }\n    }\n  }\n\n  private parseRequestBody<TParsed = unknown>(req: NormalizedRequest): TParsed | undefined {\n    try {\n      const parsed = JSON.parse(new TextDecoder().decode(req.rawBody));\n      req.json = parsed;\n      return parsed as TParsed;\n    } catch {\n      return;\n    }\n  }\n\n  private isErrorResponse(value: unknown): value is NormalizedResponse {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      \"status\" in value &&\n      typeof value.status === \"number\"\n    );\n  }\n\n  private async validatePayload<TPayload>(\n    parsedJson: unknown,\n    schema?: StandardSchemaV1<unknown, TPayload>,\n  ): Promise<TPayload | NormalizedResponse> {\n    if (!schema) {\n      return parsedJson as TPayload;\n    }\n\n    const result = await standardValidate(schema, parsedJson, {\n      throwOnError: false,\n    });\n\n    if (result.issues) {\n      return {\n        status: 400,\n        body: {\n          error: \"validation failed\",\n          issues: result.issues.map((issue) => ({\n            path: issue.path?.map((p) =>\n              typeof p === \"object\" && \"key\" in p ? String(p.key) : String(p),\n            ),\n            message: issue.message,\n          })),\n        },\n      };\n    }\n\n    return result.value as TPayload;\n  }\n\n  private async executeHandler<TPayload = unknown>(\n    handler: WebhookHandler<TPayload>,\n    req: NormalizedRequest,\n    validatedPayload: TPayload,\n  ): Promise<NormalizedResponse> {\n    const responded = await handler({\n      req,\n      payload: validatedPayload,\n      ack: async (r?: Partial<NormalizedResponse>) => {\n        const response: NormalizedResponse = {\n          status: r?.status ?? 200,\n          body: r?.body ?? \"ok\",\n        };\n\n        if (r?.headers !== undefined) {\n          response.headers = r.headers;\n        }\n\n        return response;\n      },\n    });\n\n    return responded ?? { status: 200, body: \"ok\" };\n  }\n\n  private async runRouteAfterHooks(\n    req: NormalizedRequest,\n    response: NormalizedResponse,\n    after?: AfterHook[],\n  ): Promise<void> {\n    if (after) {\n      for (const hook of after) {\n        await hook(req, response);\n      }\n    }\n  }\n\n  private async runGlobalAfterHooks(\n    req: NormalizedRequest,\n    response: NormalizedResponse,\n  ): Promise<void> {\n    for (const hook of this.globalAfterHooks) {\n      await hook(req, response);\n    }\n  }\n\n  private async handleError<TError = unknown>(\n    error: TError,\n    req: NormalizedRequest,\n  ): Promise<NormalizedResponse> {\n    if (this.globalErrorHook) {\n      const errorResponse = await this.globalErrorHook(error as Error, req);\n      if (errorResponse) {\n        return errorResponse;\n      }\n    }\n\n    return {\n      status: 500,\n      body: {\n        error: error instanceof Error ? error.message : \"Internal server error\",\n      },\n    };\n  }\n}\n\n/**\n * Factory helper for creating a webhook router instance.\n *\n * @param opts - Optional global router options.\n * @returns A new webhook router.\n */\nexport function createWebhookRouter(opts?: WebhookRouterOptions): WebhookRouter {\n  return new WebhookRouter(opts);\n}\n"],"mappings":"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"}

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import { StandardSchemaV1 } from "@zap-studio/validation";
 
 //#region src/types/index.d.ts
 /** Framework-agnostic request shape consumed by the webhook router. */
@@ -16,7 +16,7 @@ interface NormalizedRequest {
   /** The query parameters of the request */
   query?: Record<string, string | string[]>;
   /** The raw body of the request (for signature) */
-  rawBody: Buffer;
+  rawBody: Uint8Array<ArrayBufferLike>;
   /** The parsed text body of the request if applicable */
   text?: string;
 }
@@ -41,16 +41,16 @@ interface RegisterOptions<T> {
   schema?: StandardSchemaV1<unknown, T>;
 }
 /**
- * Infers the output type from a Standard Schema instance.
- *
- * @typeParam TSchema - A Standard Schema type.
- */
+* Infers the output type from a Standard Schema instance.
+*
+* @typeParam TSchema - A Standard Schema type.
+*/
 type InferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1<unknown, infer TOutput> ? TOutput : never;
 /**
- * Route options where schema is required and handler payload is inferred.
- *
- * @typeParam TSchema - Schema used to infer handler payload type.
- */
+* Route options where schema is required and handler payload is inferred.
+*
+* @typeParam TSchema - Schema used to infer handler payload type.
+*/
 type SchemaRouteOptions<TSchema extends StandardSchemaV1<unknown, unknown>> = Omit<RegisterOptions<InferSchemaOutput<TSchema>>, "schema"> & {
   schema: TSchema;
 };
@@ -61,10 +61,10 @@ interface RouteLike {
   schema: StandardSchemaV1<unknown, unknown>;
 }
 /**
- * Applies schema-driven payload inference to each route entry.
- *
- * @typeParam TRoutes - Route dictionary keyed by webhook path.
- */
+* Applies schema-driven payload inference to each route entry.
+*
+* @typeParam TRoutes - Route dictionary keyed by webhook path.
+*/
 type SchemaRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: SchemaRouteOptions<TRoutes[P]["schema"]> };
 /** The webhook handler function, responsible for processing incoming webhook events. */
 type WebhookHandler<TPayload = unknown> = (ctx: {
@@ -75,10 +75,10 @@ type WebhookHandler<TPayload = unknown> = (ctx: {
 /** Maps route keys to their payload-specific webhook handlers. */
 type HandlerMap<TMap extends Record<string, unknown>> = { [P in keyof TMap]: WebhookHandler<TMap[P]> };
 /**
- * Builds a webhook payload map from a schema-based route dictionary.
- *
- * @typeParam TRoutes - Route dictionary keyed by webhook path.
- */
+* Builds a webhook payload map from a schema-based route dictionary.
+*
+* @typeParam TRoutes - Route dictionary keyed by webhook path.
+*/
 type InferWebhookMapFromRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: InferSchemaOutput<TRoutes[P]["schema"]> };
 /** Verification function for incoming requests */
 type VerifyFn = (req: NormalizedRequest) => Promise<void> | void;
@@ -89,4 +89,5 @@ type AfterHook = (req: NormalizedRequest, res: NormalizedResponse) => Promise<vo
 /** Hook function that runs when an error occurs */
 type ErrorHook = (error: Error, req: NormalizedRequest) => Promise<NormalizedResponse | undefined> | NormalizedResponse | undefined;
 //#endregion
-export { AfterHook, BeforeHook, ErrorHook, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, NormalizedRequest, NormalizedResponse, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookHandler };
+export { AfterHook, BeforeHook, ErrorHook, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, NormalizedRequest, NormalizedResponse, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookHandler };
+//# sourceMappingURL=index.d.mts.map

package/dist/types/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types/index.ts"],"mappings":";;;;UAGiB,iBAAA;EAAjB;EAEE,OAAA,EAAS,OAAA;;EAET,IAAA;;EAEA,MAAA,EAAQ,OAAA;;EAER,MAAA,GAAS,MAAA;;EAET,IAAA;EAIS;EAFT,KAAA,GAAQ,MAAA;;EAER,OAAA,EAAS,UAAA,CAAW,eAAA;;EAEpB,IAAA;AAAA;;UAIe,kBAAA;;EAEf,IAAA,GAAO,KAAA;;EAEP,OAAA,GAAU,OAAA;;EAEV,MAAA;AAAA;;UAIe,eAAA;EAVA;EAYf,KAAA,GAAQ,SAAA,GAAY,SAAA;EARV;EAUV,MAAA,GAAS,UAAA,GAAa,UAAA;;EAEtB,OAAA,EAAS,cAAA,CAAe,CAAA;;EAExB,MAAA,GAAS,gBAAA,UAA0B,CAAA;AAAA;;;AARrC;;;KAgBY,iBAAA,YACV,OAAA,SAAgB,gBAAA,2BAA2C,OAAA;;;;;;KAOjD,kBAAA,iBAAmC,gBAAA,sBAAsC,IAAA,CACnF,eAAA,CAAgB,iBAAA,CAAkB,OAAA;EAGlC,MAAA,EAAQ,OAAA;AAAA;AAAA,UAGA,SAAA;EACR,KAAA,GAAQ,SAAA,GAAY,SAAA;EACpB,MAAA,GAAS,UAAA,GAAa,UAAA;EACtB,OAAA,EAAS,cAAA;EACT,MAAA,EAAQ,gBAAA;AAAA;;;;;;KAQE,YAAA,iBAA6B,MAAA,SAAe,SAAA,mBAC1C,OAAA,GAAU,kBAAA,CAAmB,OAAA,CAAQ,CAAA;;KAIvC,cAAA,wBAAsC,GAAA;EAChD,GAAA,EAAK,iBAAA;EACL,OAAA,EAAS,QAAA;EACT,GAAA,GAAM,GAAA,GAAM,OAAA,CAAQ,kBAAA,MAAwB,OAAA,CAAQ,kBAAA;AAAA,MAChD,OAAA,CAAQ,kBAAA,gBAAkC,kBAAA;;KAGpC,UAAA,cAAwB,MAAA,mCACtB,IAAA,GAAO,cAAA,CAAe,IAAA,CAAK,CAAA;;;;;;KAQ7B,yBAAA,iBAA0C,MAAA,SAAe,SAAA,mBACvD,OAAA,GAAU,iBAAA,CAAkB,OAAA,CAAQ,CAAA;;KAItC,QAAA,IAAY,GAAA,EAAK,iBAAA,KAAsB,OAAA;;KAGvC,UAAA,IAAc,GAAA,EAAK,iBAAA,KAAsB,OAAA;;KAGzC,SAAA,IAAa,GAAA,EAAK,iBAAA,EAAmB,GAAA,EAAK,kBAAA,KAAuB,OAAA;;KAGjE,SAAA,IACV,KAAA,EAAO,KAAA,EACP,GAAA,EAAK,iBAAA,KACF,OAAA,CAAQ,kBAAA,gBAAkC,kBAAA"}

package/dist/types/index.mjs

@@ -1 +1 @@
-export {  };
+export {};

package/dist/utils/index.d.mts

@@ -1,12 +1,13 @@
 //#region src/utils/index.d.ts
 /**
- * Compares two strings in constant time to prevent timing attacks.
- *
- * @example
- * ```ts
- * const isEqual = constantTimeEquals("string1", "string2"); // returns false
- * ```
- */
+* Compares two strings in constant time to prevent timing attacks.
+*
+* @example
+* ```ts
+* const isEqual = constantTimeEquals("string1", "string2"); // returns false
+* ```
+*/
 declare function constantTimeEquals(a: string, b: string): boolean;
 //#endregion
-export { constantTimeEquals };
+export { constantTimeEquals };
+//# sourceMappingURL=index.d.mts.map

package/dist/utils/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/utils/index.ts"],"mappings":";;AAQA;;;;;;;iBAAgB,kBAAA,CAAmB,CAAA,UAAW,CAAA"}

package/dist/utils/index.mjs

@@ -13,6 +13,7 @@ function constantTimeEquals(a, b) {
 	for (let i = 0; i < a.length; i += 1) result |= a.charCodeAt(i) ^ b.charCodeAt(i);
 	return result === 0;
 }
-
 //#endregion
-export { constantTimeEquals };
+export { constantTimeEquals };
+
+//# sourceMappingURL=index.mjs.map

package/dist/utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/utils/index.ts"],"sourcesContent":["/**\n * Compares two strings in constant time to prevent timing attacks.\n *\n * @example\n * ```ts\n * const isEqual = constantTimeEquals(\"string1\", \"string2\"); // returns false\n * ```\n */\nexport function constantTimeEquals(a: string, b: string): boolean {\n  if (a.length !== b.length) {\n    return false;\n  }\n\n  let result = 0;\n  for (let i = 0; i < a.length; i += 1) {\n    result |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n\n  return result === 0;\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,mBAAmB,GAAW,GAAoB;AAChE,KAAI,EAAE,WAAW,EAAE,OACjB,QAAO;CAGT,IAAI,SAAS;AACb,MAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK,EACjC,WAAU,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE;AAG7C,QAAO,WAAW"}

package/dist/verify.d.mts

@@ -1,49 +1,54 @@
 import { VerifyFn } from "./types/index.mjs";
-import { BinaryLike, KeyObject } from "node:crypto";
 
 //#region src/verify.d.ts
-
+declare const HMAC_HASH: {
+  readonly sha1: "SHA-1";
+  readonly sha256: "SHA-256";
+  readonly sha384: "SHA-384";
+  readonly sha512: "SHA-512";
+};
+type HmacAlgorithm = keyof typeof HMAC_HASH;
 /**
- * Creates an HMAC-based request verification function.
- *
- * The returned verifier reads the configured signature header, computes the
- * expected HMAC from `req.rawBody`, and compares them in constant time.
- *
- * @note Uses Node.js `crypto` at runtime.
- *
- * @example
- * ```ts
- * import { createWebhookRouter } from "@zap-studio/webhooks";
- * import { createHmacVerifier } from "@zap-studio/webhooks/verify";
- * import { z } from "zod";
- *
- * const router = createWebhookRouter({
- *   verify: createHmacVerifier({
- *     headerName: "x-hub-signature-256",
- *     secret: process.env.GITHUB_WEBHOOK_SECRET!,
- *   }),
- * });
- *
- * router.register("github/push", {
- *   schema: z.object({ ref: z.string() }),
- *   handler: async ({ ack }) => ack(),
- * });
- * ```
- *
- * @param options - HMAC verifier options.
- * @param options.headerName - Header containing provider signature.
- * @param options.secret - HMAC secret key.
- * @param options.algo - Hash algorithm used for HMAC generation.
- * @returns A verifier function compatible with router `verify`.
- */
+* Creates a webhook verifier that validates an HMAC signature from a request header.
+*
+* The verifier imports the provided string secret once, computes an HMAC from
+* `req.rawBody`, normalizes the incoming header value, and compares both
+* signatures in constant time.
+*
+* Header values like `sha256=<hex>` are supported so common provider formats
+* such as GitHub work without extra parsing.
+*
+* @example
+* ```ts
+* import { createWebhookRouter } from "@zap-studio/webhooks";
+* import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+*
+* const router = createWebhookRouter({
+*   verify: createHmacVerifier({
+*     headerName: "x-hub-signature-256",
+*     secret: process.env.GITHUB_WEBHOOK_SECRET!,
+*   }),
+* });
+* ```
+*
+* @param options - Verifier configuration.
+* @param options.headerName - Header containing the provider signature.
+* @param options.secret - Shared HMAC secret as a string.
+* @param options.algo - HMAC hash algorithm. Defaults to `"sha256"`.
+* @returns A router-compatible request verifier.
+*
+* @throws {VerificationError}
+* Thrown when verifier setup fails or request verification does not pass.
+*/
 declare function createHmacVerifier({
   headerName,
   secret,
   algo
 }: {
   headerName: string;
-  secret: BinaryLike | KeyObject;
-  algo?: string;
+  secret: string;
+  algo?: HmacAlgorithm;
 }): VerifyFn;
 //#endregion
-export { createHmacVerifier };
+export { createHmacVerifier };
+//# sourceMappingURL=verify.d.mts.map

package/dist/verify.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.mts","names":[],"sources":["../src/verify.ts"],"mappings":";;;cAIM,SAAA;EAAA,SACJ,IAAA;EAAA,SACA,MAAA;EAAA,SACA,MAAA;EAAA,SACA,MAAA;AAAA;AAAA,KAGG,aAAA,gBAA6B,SAAA;;;;;;AAHhC;;;;;AAqCF;;;;;;;;;;;;;;;;;;;;;;iBAAgB,kBAAA,CAAA;EACd,UAAA;EACA,MAAA;EACA;AAAA;EAEA,UAAA;EACA,MAAA;EACA,IAAA,GAAO,aAAA;AAAA,IACL,QAAA"}

package/dist/verify.mjs

@@ -1,20 +1,26 @@
+import { VerificationError } from "./errors.mjs";
 import { constantTimeEquals } from "./utils/index.mjs";
-
 //#region src/verify.ts
-const SIGNATURE_REGEX = /^sha256=/;
+const HMAC_HASH = {
+	sha1: "SHA-1",
+	sha256: "SHA-256",
+	sha384: "SHA-384",
+	sha512: "SHA-512"
+};
 /**
-* Creates an HMAC-based request verification function.
+* Creates a webhook verifier that validates an HMAC signature from a request header.
 *
-* The returned verifier reads the configured signature header, computes the
-* expected HMAC from `req.rawBody`, and compares them in constant time.
+* The verifier imports the provided string secret once, computes an HMAC from
+* `req.rawBody`, normalizes the incoming header value, and compares both
+* signatures in constant time.
 *
-* @note Uses Node.js `crypto` at runtime.
+* Header values like `sha256=<hex>` are supported so common provider formats
+* such as GitHub work without extra parsing.
 *
 * @example
 * ```ts
 * import { createWebhookRouter } from "@zap-studio/webhooks";
 * import { createHmacVerifier } from "@zap-studio/webhooks/verify";
-* import { z } from "zod";
 *
 * const router = createWebhookRouter({
 *   verify: createHmacVerifier({
@@ -22,26 +28,41 @@ const SIGNATURE_REGEX = /^sha256=/;
 *     secret: process.env.GITHUB_WEBHOOK_SECRET!,
 *   }),
 * });
-*
-* router.register("github/push", {
-*   schema: z.object({ ref: z.string() }),
-*   handler: async ({ ack }) => ack(),
-* });
 * ```
 *
-* @param options - HMAC verifier options.
-* @param options.headerName - Header containing provider signature.
-* @param options.secret - HMAC secret key.
-* @param options.algo - Hash algorithm used for HMAC generation.
-* @returns A verifier function compatible with router `verify`.
+* @param options - Verifier configuration.
+* @param options.headerName - Header containing the provider signature.
+* @param options.secret - Shared HMAC secret as a string.
+* @param options.algo - HMAC hash algorithm. Defaults to `"sha256"`.
+* @returns A router-compatible request verifier.
+*
+* @throws {VerificationError}
+* Thrown when verifier setup fails or request verification does not pass.
 */
 function createHmacVerifier({ headerName, secret, algo = "sha256" }) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new VerificationError("Web Crypto API is unavailable in this runtime");
+	const hash = HMAC_HASH[algo];
+	if (!hash) throw new VerificationError(`Unsupported HMAC algorithm: ${algo}`);
+	const keyPromise = subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash
+	}, false, ["sign"]);
 	return async (req) => {
-		const sig = req.headers.get(headerName.toLowerCase()) || "";
-		if (!sig) throw Object.assign(/* @__PURE__ */ new Error("missing signature"), { name: "SignatureError" });
-		if (!constantTimeEquals((await import("node:crypto")).createHmac(algo, secret).update(req.rawBody).digest("hex"), sig.replace(SIGNATURE_REGEX, ""))) throw Object.assign(/* @__PURE__ */ new Error("invalid signature"), { name: "SignatureError" });
+		const actual = req.headers.get(headerName);
+		if (!actual) throw new VerificationError(`Missing signature header: ${headerName}`);
+		const key = await keyPromise;
+		const signature = await subtle.sign("HMAC", key, req.rawBody);
+		if (!constantTimeEquals(toHex(new Uint8Array(signature)), normalizeSignature(actual))) throw new VerificationError(`Invalid signature for header: ${headerName}`);
 	};
 }
-
+function toHex(bytes) {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function normalizeSignature(signature) {
+	return signature.replace(/^[a-z0-9-]+=/i, "").trim().toLowerCase();
+}
 //#endregion
-export { createHmacVerifier };
+export { createHmacVerifier };
+
+//# sourceMappingURL=verify.mjs.map

package/dist/verify.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.mjs","names":[],"sources":["../src/verify.ts"],"sourcesContent":["import { VerificationError } from \"./errors.js\";\nimport type { VerifyFn } from \"./types/index.js\";\nimport { constantTimeEquals } from \"./utils/index.js\";\n\nconst HMAC_HASH = {\n  sha1: \"SHA-1\",\n  sha256: \"SHA-256\",\n  sha384: \"SHA-384\",\n  sha512: \"SHA-512\",\n} as const;\n\ntype HmacAlgorithm = keyof typeof HMAC_HASH;\n\n/**\n * Creates a webhook verifier that validates an HMAC signature from a request header.\n *\n * The verifier imports the provided string secret once, computes an HMAC from\n * `req.rawBody`, normalizes the incoming header value, and compares both\n * signatures in constant time.\n *\n * Header values like `sha256=<hex>` are supported so common provider formats\n * such as GitHub work without extra parsing.\n *\n * @example\n * ```ts\n * import { createWebhookRouter } from \"@zap-studio/webhooks\";\n * import { createHmacVerifier } from \"@zap-studio/webhooks/verify\";\n *\n * const router = createWebhookRouter({\n *   verify: createHmacVerifier({\n *     headerName: \"x-hub-signature-256\",\n *     secret: process.env.GITHUB_WEBHOOK_SECRET!,\n *   }),\n * });\n * ```\n *\n * @param options - Verifier configuration.\n * @param options.headerName - Header containing the provider signature.\n * @param options.secret - Shared HMAC secret as a string.\n * @param options.algo - HMAC hash algorithm. Defaults to `\"sha256\"`.\n * @returns A router-compatible request verifier.\n *\n * @throws {VerificationError}\n * Thrown when verifier setup fails or request verification does not pass.\n */\nexport function createHmacVerifier({\n  headerName,\n  secret,\n  algo = \"sha256\",\n}: {\n  headerName: string;\n  secret: string;\n  algo?: HmacAlgorithm;\n}): VerifyFn {\n  const subtle = globalThis.crypto?.subtle;\n  if (!subtle) {\n    throw new VerificationError(\"Web Crypto API is unavailable in this runtime\");\n  }\n\n  const hash = HMAC_HASH[algo];\n  if (!hash) {\n    throw new VerificationError(`Unsupported HMAC algorithm: ${algo}`);\n  }\n\n  const keyPromise = subtle.importKey(\n    \"raw\",\n    new TextEncoder().encode(secret),\n    { name: \"HMAC\", hash },\n    false,\n    [\"sign\"],\n  );\n\n  return async (req) => {\n    const actual = req.headers.get(headerName);\n    if (!actual) {\n      throw new VerificationError(`Missing signature header: ${headerName}`);\n    }\n\n    const key = await keyPromise;\n    const signature = await subtle.sign(\"HMAC\", key, req.rawBody as BufferSource);\n    const expected = toHex(new Uint8Array(signature));\n\n    if (!constantTimeEquals(expected, normalizeSignature(actual))) {\n      throw new VerificationError(`Invalid signature for header: ${headerName}`);\n    }\n  };\n}\n\nfunction toHex(bytes: Uint8Array): string {\n  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\nfunction normalizeSignature(signature: string): string {\n  return signature\n    .replace(/^[a-z0-9-]+=/i, \"\")\n    .trim()\n    .toLowerCase();\n}\n"],"mappings":";;;AAIA,MAAM,YAAY;CAChB,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,QAAQ;CACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCD,SAAgB,mBAAmB,EACjC,YACA,QACA,OAAO,YAKI;CACX,MAAM,SAAS,WAAW,QAAQ;AAClC,KAAI,CAAC,OACH,OAAM,IAAI,kBAAkB,gDAAgD;CAG9E,MAAM,OAAO,UAAU;AACvB,KAAI,CAAC,KACH,OAAM,IAAI,kBAAkB,+BAA+B,OAAO;CAGpE,MAAM,aAAa,OAAO,UACxB,OACA,IAAI,aAAa,CAAC,OAAO,OAAO,EAChC;EAAE,MAAM;EAAQ;EAAM,EACtB,OACA,CAAC,OAAO,CACT;AAED,QAAO,OAAO,QAAQ;EACpB,MAAM,SAAS,IAAI,QAAQ,IAAI,WAAW;AAC1C,MAAI,CAAC,OACH,OAAM,IAAI,kBAAkB,6BAA6B,aAAa;EAGxE,MAAM,MAAM,MAAM;EAClB,MAAM,YAAY,MAAM,OAAO,KAAK,QAAQ,KAAK,IAAI,QAAwB;AAG7E,MAAI,CAAC,mBAFY,MAAM,IAAI,WAAW,UAAU,CAAC,EAEf,mBAAmB,OAAO,CAAC,CAC3D,OAAM,IAAI,kBAAkB,iCAAiC,aAAa;;;AAKhF,SAAS,MAAM,OAA2B;AACxC,QAAO,MAAM,KAAK,QAAQ,SAAS,KAAK,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG;;AAGjF,SAAS,mBAAmB,WAA2B;AACrD,QAAO,UACJ,QAAQ,iBAAiB,GAAG,CAC5B,MAAM,CACN,aAAa"}

package/package.json

@@ -1,70 +1,70 @@
 {
   "name": "@zap-studio/webhooks",
-  "version": "0.1.3",
-  "type": "module",
-  "license": "MIT",
+  "version": "0.2.0",
   "private": false,
-  "homepage": "https://www.zapstudio.dev/packages/webhooks",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/zap-studio/monorepo.git",
-    "directory": "packages/webhooks"
-  },
   "description": "A lightweight, type-safe webhook router with Standard Schema validation, signature verification, and lifecycle hooks.",
   "keywords": [
-    "webhooks",
-    "webhook router",
-    "type-safe",
-    "typescript",
-    "validation",
+    "arktype",
+    "lifecycle hooks",
+    "payload validation",
     "schema",
+    "signature verification",
     "standard schema",
-    "zod",
+    "type-safe",
+    "typescript",
     "valibot",
-    "arktype",
-    "signature verification",
-    "lifecycle hooks",
-    "payload validation"
+    "validation",
+    "webhook router",
+    "webhooks",
+    "zod"
   ],
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://www.zapstudio.dev/packages/webhooks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zap-studio/monorepo.git",
+    "directory": "packages/webhooks"
+  },
+  "bin": {
+    "intent": "./bin/intent.js"
   },
   "files": [
     "dist",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
-  "dependencies": {
-    "@standard-schema/spec": "^1.1.0",
-    "@zap-studio/validation": "0.3.1"
-  },
-  "devDependencies": {
-    "@types/node": "^25.0.2",
-    "@vitest/coverage-v8": "^4.0.15",
-    "tsdown": "^0.18.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
-    "zod": "^4.2.0",
-    "@zap-studio/tsdown-config": "0.0.0",
-    "@zap-studio/vitest-config": "0.0.0",
-    "@zap-studio/typescript-config": "0.0.0"
-  },
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
     "./adapters/base": "./dist/adapters/base.mjs",
+    "./errors": "./dist/errors.mjs",
     "./types": "./dist/types/index.mjs",
     "./utils": "./dist/utils/index.mjs",
     "./verify": "./dist/verify.mjs",
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zap-studio/validation": "0.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3",
+    "vite-plus": "latest",
+    "zod": "^4.2.0",
+    "@zap-studio/typescript": "0.0.0"
+  },
   "scripts": {
-    "build": "tsdown --config tsdown.config.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest --watch"
+    "build": "vp pack",
+    "test": "vp test run",
+    "test:watch": "vp test watch"
   }
 }

package/skills/zap-webhooks-routing-and-verification/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: zap-webhooks-routing-and-verification
+description: >
+  Build webhook ingestion with @zap-studio/webhooks using createWebhookRouter,
+  register path keys, prefix normalization, schema validation, lifecycle hooks,
+  createHmacVerifier, and BaseAdapter request/response mapping.
+type: core
+library: "@zap-studio/webhooks"
+library_version: "0.1.3"
+sources:
+  - "zap-studio/monorepo:packages/webhooks/README.md"
+  - "zap-studio/monorepo:packages/webhooks/src/index.ts"
+  - "zap-studio/monorepo:packages/webhooks/src/verify.ts"
+  - "zap-studio/monorepo:packages/webhooks/src/adapters/base.ts"
+---
+
+# @zap-studio/webhooks — Routing and Verification
+
+## Setup
+
+```ts
+import { createWebhookRouter } from "@zap-studio/webhooks";
+import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+import { z } from "zod";
+
+const router = createWebhookRouter({
+  prefix: "/webhooks/",
+  verify: createHmacVerifier({
+    headerName: "x-hub-signature-256",
+    secret: process.env.WEBHOOK_SECRET!,
+  }),
+});
+
+router.register("github/push", {
+  schema: z.object({ ref: z.string() }),
+  handler: async ({ payload, ack }) => {
+    console.log(payload.ref);
+    return ack({ status: 200, body: "ok" });
+  },
+});
+```
+
+## Core Patterns
+
+### Add global hooks for observability and error shaping
+
+```ts
+const router = createWebhookRouter({
+  before: (req) => {
+    console.log("incoming", req.path);
+  },
+  after: (_req, res) => {
+    console.log("status", res.status);
+  },
+  onError: (error) => ({
+    status: 500,
+    body: { error: error.message },
+  }),
+});
+```
+
+### Register route-specific hooks
+
+```ts
+router.register("payments/succeeded", {
+  schema: PaymentSchema,
+  before: (req) => {
+    req.headers.set("x-processed", "1");
+  },
+  after: (_req, res) => {
+    console.log("finished", res.status);
+  },
+  handler: async ({ payload, ack }) => ack({ body: { id: payload.id } }),
+});
+```
+
+### Implement an adapter with `BaseAdapter`
+
+```ts
+import { BaseAdapter } from "@zap-studio/webhooks/adapters/base";
+
+class MyAdapter extends BaseAdapter {
+  async toNormalizedRequest(req: Request) {
+    return {
+      method: req.method,
+      path: req.url,
+      headers: req.headers,
+      rawBody: Buffer.from(await req.text()),
+    };
+  }
+
+  async toFrameworkResponse(res: Response, normalized) {
+    return new Response(JSON.stringify(normalized.body), {
+      status: normalized.status,
+      headers: normalized.headers,
+    }) as unknown as Response;
+  }
+}
+```
+
+## Common Mistakes
+
+### HIGH Registering paths with leading slash
+
+Wrong:
+
+```ts
+router.register("/github/push", {
+  schema: PushSchema,
+  handler,
+});
+```
+
+Correct:
+
+```ts
+router.register("github/push", {
+  schema: PushSchema,
+  handler,
+});
+```
+
+Incoming paths normalize to slashless keys; leading slash route keys do not match and return 404.
+
+Source: zap-studio/monorepo:packages/webhooks/src/index.ts
+
+### CRITICAL Verifying a transformed payload instead of raw body
+
+Wrong:
+
+```ts
+const parsed = JSON.parse(req.rawBody.toString());
+await verifyProvider(JSON.stringify(parsed));
+```
+
+Correct:
+
+```ts
+await verify(req); // uses req.rawBody bytes
+const parsed = JSON.parse(req.rawBody.toString());
+```
+
+Signature checks must run on exact raw bytes; any parse/serialize transformation can invalidate signatures.
+
+Source: zap-studio/monorepo:packages/webhooks/src/verify.ts
+
+### HIGH Assuming `createHmacVerifier` is Node-only
+
+Wrong:
+
+```ts
+const verify = createHmacVerifier({
+  headerName: "x-signature",
+  secret: env.WEBHOOK_SECRET,
+});
+// used in edge runtime
+```
+
+Correct:
+
+```ts
+const verify = createHmacVerifier({
+  headerName: "x-signature",
+  secret: env.WEBHOOK_SECRET,
+});
+```
+
+`createHmacVerifier` uses the Web Crypto API and works across runtimes that expose `globalThis.crypto.subtle`.
+
+Source: zap-studio/monorepo:packages/webhooks/src/verify.ts
+
+See also: zap-validation-standard-schema/SKILL.md — payload validation result handling.