@samva/webhooks 0.5.0 → 0.6.0

package/AGENTS.md

@@ -5,7 +5,7 @@ webhook. Verification requires the untouched request body and the endpoint signi
 expose that secret to browser code.
 
 Effect applications can import the typed adapter from `@samva/webhooks/effect` and install the
-optional exact peer `effect@4.0.0-rc.112`.
+optional peer `effect` at the exact version this package's `peerDependencies` names.
 
 Import only package subpaths declared in `package.json`. The delivery, queue, persistence, retry,
 and endpoint-management implementation is not part of this package.

package/README.md

@@ -17,9 +17,13 @@ request body and keep the signing secret on the server.
 Effect applications can use the optional Effect entrypoint:
 
 ```ts
+import { Effect } from "effect";
 import * as Webhooks from "@samva/webhooks/effect";
 
-const verified = yield * Webhooks.verifyRequest(request, secret);
+const program = Effect.gen(function* () {
+  const verified = yield* Webhooks.verifyRequest(request, secret);
+  return verified.event;
+});
 ```
 
-Install the exact optional peer `effect@4.0.0-rc.112` when using that entrypoint.
+Install the `effect` version this package lists in `peerDependencies` when using that entrypoint.

package/dist/effect.d.ts

@@ -1,10 +1,43 @@
 import { Effect } from "effect";
 import type { VerifyOptions } from "./promise.js";
-import { type AnyWebhookVerificationError } from "./protocol.js";
-export declare const verify: (options: VerifyOptions) => Effect.Effect<import("./protocol.js").VerifiedWebhook, AnyWebhookVerificationError, never>;
+import { type AnyWebhookVerificationError, type VerifiedWebhook } from "./protocol.js";
+/**
+ * Effect version of the Promise entrypoint's `verify`: verifies a delivery from its body and
+ * header values and succeeds with its ID and parsed event.
+ *
+ * Reads the current time from Effect's `Clock`, so `TestClock` controls the replay window in
+ * tests. Fails with {@link AnyWebhookVerificationError}; branch with `Effect.catchTag`. Input
+ * that violates the declared types, such as an undefined secret, dies instead.
+ */
+export declare const verify: (options: VerifyOptions) => Effect.Effect<VerifiedWebhook, AnyWebhookVerificationError, never>;
+/**
+ * Effect version of the Promise entrypoint's `verifyRequest`: verifies a delivery received as a
+ * Fetch API `Request` and succeeds with its ID and parsed event. Reads the body from a clone, so
+ * the original request stays readable.
+ *
+ * Reads the current time from Effect's `Clock`. Fails with {@link AnyWebhookVerificationError};
+ * a body that cannot be read fails with {@link WebhookCryptoError}. Input that violates the
+ * declared types dies instead.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import * as Webhooks from "@samva/webhooks/effect";
+ *
+ * const receive = (request: Request, secret: string) =>
+ *   Webhooks.verifyRequest(request, secret).pipe(
+ *     Effect.flatMap(({ id, event }) => Effect.promise(() => handleOnce(id, event))),
+ *     Effect.as(new Response(null, { status: 204 })),
+ *     Effect.catchTags({
+ *       WebhookSignatureError: () => Effect.succeed(new Response(null, { status: 400 })),
+ *       WebhookTimestampError: () => Effect.succeed(new Response(null, { status: 400 })),
+ *     }),
+ *   );
+ * ```
+ */
 export declare const verifyRequest: (request: Request, secret: string, options?: {
     readonly toleranceSeconds?: number | undefined;
-} | undefined) => Effect.Effect<import("./protocol.js").VerifiedWebhook, AnyWebhookVerificationError, never>;
+} | undefined) => Effect.Effect<VerifiedWebhook, AnyWebhookVerificationError, never>;
 export { DEFAULT_TOLERANCE_SECONDS, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, generateWebhookSecret, signWebhook, } from "./protocol.js";
-export type { AnyWebhookVerificationError, SamvaWebhookEvent, VerifiedWebhook, } from "./protocol.js";
+export type { AnyWebhookVerificationError, SamvaWebhookEvent, VerifiedWebhook, WebhookHeaderName, } from "./protocol.js";
 export { InvalidWebhookHeadersError, InvalidWebhookSecretError, MalformedWebhookPayloadError, WebhookCryptoError, WebhookSignatureError, WebhookTimestampError, WebhookVerificationError, } from "./protocol.js";

package/dist/effect.js

@@ -1,38 +1,75 @@
-import { _ as WebhookTimestampError, c as signWebhook, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, s as readWebhookHeaders, t as DEFAULT_TOLERANCE_SECONDS, v as WebhookVerificationError } from "./protocol-M4mOvMtW.js";
+import { _ as WebhookTimestampError, c as signWebhook, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, t as DEFAULT_TOLERANCE_SECONDS, v as WebhookVerificationError } from "./protocol-BGKUmvlI.js";
 import { Clock, Effect } from "effect";
 //#region src/effect.ts
+/**
+* Fails with the verification errors `verifyWebhookAt` rejects with. Any other rejection, such as
+* a `TypeError` from input that violates the declared types, is a defect rather than a failed
+* delivery.
+*/
+const verifyAt = (input) => Effect.flatten(Effect.promise(() => verifyWebhookAt(input).then((verified) => Effect.succeed(verified), (error) => error instanceof WebhookVerificationError ? Effect.fail(error) : Effect.die(error))));
+/**
+* Effect version of the Promise entrypoint's `verify`: verifies a delivery from its body and
+* header values and succeeds with its ID and parsed event.
+*
+* Reads the current time from Effect's `Clock`, so `TestClock` controls the replay window in
+* tests. Fails with {@link AnyWebhookVerificationError}; branch with `Effect.catchTag`. Input
+* that violates the declared types, such as an undefined secret, dies instead.
+*/
 const verify = Effect.fn("Webhooks.verify")(function* (options) {
 	const nowMilliseconds = yield* Clock.currentTimeMillis;
-	return yield* Effect.tryPromise({
-		try: () => verifyWebhookAt({
-			body: options.body,
-			headers: {
-				id: options.id,
-				timestamp: options.timestamp,
-				signature: options.signature
-			},
-			secret: options.secret,
-			toleranceSeconds: options.toleranceSeconds,
-			nowMilliseconds
-		}),
-		catch: (error) => error
+	return yield* verifyAt({
+		body: options.body,
+		headers: {
+			id: options.id,
+			timestamp: options.timestamp,
+			signature: options.signature
+		},
+		secret: options.secret,
+		toleranceSeconds: options.toleranceSeconds,
+		nowMilliseconds
 	});
 });
+/**
+* Effect version of the Promise entrypoint's `verifyRequest`: verifies a delivery received as a
+* Fetch API `Request` and succeeds with its ID and parsed event. Reads the body from a clone, so
+* the original request stays readable.
+*
+* Reads the current time from Effect's `Clock`. Fails with {@link AnyWebhookVerificationError};
+* a body that cannot be read fails with {@link WebhookCryptoError}. Input that violates the
+* declared types dies instead.
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import * as Webhooks from "@samva/webhooks/effect";
+*
+* const receive = (request: Request, secret: string) =>
+*   Webhooks.verifyRequest(request, secret).pipe(
+*     Effect.flatMap(({ id, event }) => Effect.promise(() => handleOnce(id, event))),
+*     Effect.as(new Response(null, { status: 204 })),
+*     Effect.catchTags({
+*       WebhookSignatureError: () => Effect.succeed(new Response(null, { status: 400 })),
+*       WebhookTimestampError: () => Effect.succeed(new Response(null, { status: 400 })),
+*     }),
+*   );
+* ```
+*/
 const verifyRequest = Effect.fn("Webhooks.verifyRequest")(function* (request, secret, options) {
 	const nowMilliseconds = yield* Clock.currentTimeMillis;
 	const body = yield* Effect.tryPromise({
 		try: async () => new Uint8Array(await request.clone().arrayBuffer()),
 		catch: () => new WebhookCryptoError({ detail: "Unable to read webhook request body" })
 	});
-	return yield* Effect.tryPromise({
-		try: () => verifyWebhookAt({
-			body,
-			headers: readWebhookHeaders(request.headers),
-			secret,
-			toleranceSeconds: options?.toleranceSeconds,
-			nowMilliseconds
-		}),
-		catch: (error) => error
+	return yield* verifyAt({
+		body,
+		headers: {
+			id: request.headers.get(WEBHOOK_ID_HEADER),
+			timestamp: request.headers.get(WEBHOOK_TIMESTAMP_HEADER),
+			signature: request.headers.get(WEBHOOK_SIGNATURE_HEADER)
+		},
+		secret,
+		toleranceSeconds: options?.toleranceSeconds,
+		nowMilliseconds
 	});
 });
 //#endregion

package/dist/errors.d.ts

@@ -1,28 +1,77 @@
 interface WebhookVerificationFailureOptions {
     readonly detail: string;
 }
+/** Name of one of the three Standard Webhooks signing headers a delivery carries. */
+export type WebhookHeaderName = "webhook-id" | "webhook-timestamp" | "webhook-signature";
+/**
+ * Base class for every failure this package reports while verifying a webhook delivery.
+ *
+ * Each subclass carries a literal `_tag` (also used as `name`), so you can branch on the failure
+ * with a `switch` or Effect's `catchTag`. `detail` is a human-readable reason for your logs; do not
+ * echo it to the sender, and do not match on its wording.
+ */
 export declare abstract class WebhookVerificationError<Tag extends string = string> extends Error {
+    /** Discriminant naming the concrete failure; equal to the subclass name. */
     readonly _tag: Tag;
+    /** Human-readable reason for logs. The wording is not a stable contract. */
     readonly detail: string;
     protected constructor(tag: Tag, options: WebhookVerificationFailureOptions);
 }
+/**
+ * The signing secret is unusable: it lacks the `whsec_` prefix, the remainder is not Base64, or
+ * the decoded key length is outside the accepted range (`detail` names the range). This is a
+ * configuration error on the receiving side, not a bad delivery; copy the endpoint's signing
+ * secret from Samva again.
+ */
 export declare class InvalidWebhookSecretError extends WebhookVerificationError<"InvalidWebhookSecretError"> {
     constructor(options: WebhookVerificationFailureOptions);
 }
+/**
+ * One of the `webhook-id`, `webhook-timestamp`, or `webhook-signature` headers is missing or
+ * empty; `header` names it. The request is not a Samva delivery, or something between Samva and
+ * your handler stripped the headers.
+ */
 export declare class InvalidWebhookHeadersError extends WebhookVerificationError<"InvalidWebhookHeadersError"> {
-    constructor(options: WebhookVerificationFailureOptions);
+    /** The first signing header, in id, timestamp, signature order, that is missing or empty. */
+    readonly header: WebhookHeaderName;
+    constructor(options: WebhookVerificationFailureOptions & {
+        readonly header: WebhookHeaderName;
+    });
 }
+/**
+ * The `webhook-timestamp` header is not an integer count of Unix seconds, it lies further from the
+ * current time than the replay tolerance, or the tolerance you passed is negative or not finite.
+ * A delivery outside the tolerance is rejected even when its signature is valid; that bounds how
+ * long a captured request can be replayed. Repeated failures on genuine deliveries usually mean
+ * the receiving server's clock is wrong.
+ */
 export declare class WebhookTimestampError extends WebhookVerificationError<"WebhookTimestampError"> {
     constructor(options: WebhookVerificationFailureOptions);
 }
+/**
+ * No signature in the `webhook-signature` header matches the delivery, or no verification key was
+ * supplied. Treat the request as forged and reject it. When genuine deliveries fail, the usual
+ * causes are the wrong endpoint secret or a body that was parsed and re-serialized before
+ * verification instead of passed through as the exact bytes received.
+ */
 export declare class WebhookSignatureError extends WebhookVerificationError<"WebhookSignatureError"> {
     constructor(options: WebhookVerificationFailureOptions);
 }
+/**
+ * The signature is valid, but the body is not UTF-8 JSON holding exactly the `type`,
+ * `timestamp`, and `data` fields of a Samva event envelope.
+ */
 export declare class MalformedWebhookPayloadError extends WebhookVerificationError<"MalformedWebhookPayloadError"> {
     constructor(options: WebhookVerificationFailureOptions);
 }
+/**
+ * The runtime's Web Crypto implementation could not import a key or compute a signature, none of
+ * the supplied public keys could be imported, or the Effect entrypoint could not read the request
+ * body. Points at the runtime or its configuration rather than at the delivery.
+ */
 export declare class WebhookCryptoError extends WebhookVerificationError<"WebhookCryptoError"> {
     constructor(options: WebhookVerificationFailureOptions);
 }
+/** Every concrete failure a verification call can report, discriminated by `_tag`. */
 export type AnyWebhookVerificationError = InvalidWebhookSecretError | InvalidWebhookHeadersError | WebhookTimestampError | WebhookSignatureError | MalformedWebhookPayloadError | WebhookCryptoError;
 export {};

package/dist/promise.d.ts

@@ -1,16 +1,108 @@
 import { type AnyWebhookVerificationError, type VerifiedWebhook } from "./protocol.js";
+/** A delivery's parts, for frameworks that do not expose a Fetch API `Request`. */
 export interface VerifyOptions {
+    /**
+     * The request body exactly as received, as text or bytes. Read it before any JSON body parser
+     * runs: parsing and re-serializing changes the bytes and fails the signature check.
+     */
     readonly body: string | Uint8Array;
-    readonly id: string;
-    readonly timestamp: string;
-    readonly signature: string;
+    /**
+     * Value of the `webhook-id` header (`WEBHOOK_ID_HEADER`). Pass an absent header through as
+     * `null` or `undefined`; verification rejects it with `InvalidWebhookHeadersError`.
+     */
+    readonly id: string | null | undefined;
+    /** Value of the `webhook-timestamp` header (`WEBHOOK_TIMESTAMP_HEADER`), or absent. */
+    readonly timestamp: string | null | undefined;
+    /** Value of the `webhook-signature` header (`WEBHOOK_SIGNATURE_HEADER`), unmodified, or absent. */
+    readonly signature: string | null | undefined;
+    /** The endpoint's signing secret, including its `whsec_` prefix. Keep it on the server. */
     readonly secret: string;
+    /** Replay tolerance in seconds; defaults to `DEFAULT_TOLERANCE_SECONDS`. */
     readonly toleranceSeconds?: number | undefined;
 }
+/**
+ * Verifies a Samva webhook delivery from its body and header values, then returns its ID and
+ * parsed event.
+ *
+ * Verification follows Standard Webhooks: the `webhook-timestamp` must be within the replay
+ * tolerance of the current time, and an HMAC-SHA256 signature over `<id>.<timestamp>.<body>` with
+ * the endpoint secret must match one entry in `webhook-signature`. Only then is the body parsed.
+ * A valid delivery can arrive more than once, so handle each returned `id` once.
+ *
+ * Rejects with a subclass of `WebhookVerificationError`; {@link AnyWebhookVerificationError}
+ * lists them. A missing or empty header rejects with `InvalidWebhookHeadersError`, whose `header`
+ * names it. Use {@link safeVerify} for a result instead of a rejection.
+ *
+ * @example
+ * ```ts
+ * import { verify } from "@samva/webhooks";
+ *
+ * // Express: mount express.raw({ type: "application/json" }) on this route so body is a Buffer.
+ * app.post("/webhooks/samva", async (req, res) => {
+ *   const verified = await verify({
+ *     body: req.body,
+ *     id: req.header("webhook-id"),
+ *     timestamp: req.header("webhook-timestamp"),
+ *     signature: req.header("webhook-signature"),
+ *     secret: process.env.SAMVA_WEBHOOK_SECRET!,
+ *   });
+ *   await handleOnce(verified.id, verified.event);
+ *   res.sendStatus(204);
+ * });
+ * ```
+ */
 export declare const verify: (options: VerifyOptions) => Promise<VerifiedWebhook>;
+/**
+ * Verifies a Samva webhook delivery received as a Fetch API `Request` (Cloudflare Workers, Bun,
+ * Deno, Next.js route handlers, Hono, and similar), then returns its ID and parsed event.
+ *
+ * Reads the body from a clone, so the original request stays readable. Performs the same checks
+ * as {@link verify} and rejects with the same errors; a missing signing header rejects with
+ * `InvalidWebhookHeadersError`, whose `header` names it.
+ *
+ * @example
+ * ```ts
+ * import { verifyRequest, WebhookVerificationError } from "@samva/webhooks";
+ *
+ * export default {
+ *   async fetch(request: Request, env: { SAMVA_WEBHOOK_SECRET: string }) {
+ *     try {
+ *       const { id, event } = await verifyRequest(request, env.SAMVA_WEBHOOK_SECRET);
+ *       await handleOnce(id, event);
+ *       return new Response(null, { status: 204 });
+ *     } catch (error) {
+ *       if (error instanceof WebhookVerificationError) {
+ *         return new Response(null, { status: 400 });
+ *       }
+ *       throw error;
+ *     }
+ *   },
+ * };
+ * ```
+ */
 export declare const verifyRequest: (request: Request, secret: string, options?: {
     readonly toleranceSeconds?: number | undefined;
 }) => Promise<VerifiedWebhook>;
+/**
+ * Runs {@link verify} and resolves to a result instead of rejecting: `{ verified: true, value }`
+ * on success, or `{ verified: false, error }` carrying the verification failure. Any other error,
+ * such as a `TypeError` from input that violates the declared types, rejects.
+ *
+ * @example
+ * ```ts
+ * import { safeVerify, type VerifyOptions } from "@samva/webhooks";
+ *
+ * async function receive(delivery: VerifyOptions): Promise<Response> {
+ *   const result = await safeVerify(delivery);
+ *   if (!result.verified) {
+ *     console.warn("rejected webhook", result.error._tag);
+ *     return new Response(null, { status: 400 });
+ *   }
+ *   await handleOnce(result.value.id, result.value.event);
+ *   return new Response(null, { status: 204 });
+ * }
+ * ```
+ */
 export declare const safeVerify: (options: VerifyOptions) => Promise<{
     readonly verified: true;
     readonly value: VerifiedWebhook;
@@ -19,5 +111,5 @@ export declare const safeVerify: (options: VerifyOptions) => Promise<{
     readonly error: AnyWebhookVerificationError;
 }>;
 export { DEFAULT_TOLERANCE_SECONDS, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, generateWebhookSecret, signWebhook, } from "./protocol.js";
-export type { AnyWebhookVerificationError, SamvaWebhookEvent, VerifiedWebhook, } from "./protocol.js";
+export type { AnyWebhookVerificationError, SamvaWebhookEvent, VerifiedWebhook, WebhookHeaderName, } from "./protocol.js";
 export { InvalidWebhookHeadersError, InvalidWebhookSecretError, MalformedWebhookPayloadError, WebhookCryptoError, WebhookSignatureError, WebhookTimestampError, WebhookVerificationError, } from "./protocol.js";

package/dist/promise.js

@@ -1,5 +1,36 @@
-import { _ as WebhookTimestampError, c as signWebhook, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, s as readWebhookHeaders, t as DEFAULT_TOLERANCE_SECONDS, v as WebhookVerificationError } from "./protocol-M4mOvMtW.js";
+import { _ as WebhookTimestampError, c as signWebhook, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, s as readWebhookHeaders, t as DEFAULT_TOLERANCE_SECONDS, v as WebhookVerificationError } from "./protocol-BGKUmvlI.js";
 //#region src/promise.ts
+/**
+* Verifies a Samva webhook delivery from its body and header values, then returns its ID and
+* parsed event.
+*
+* Verification follows Standard Webhooks: the `webhook-timestamp` must be within the replay
+* tolerance of the current time, and an HMAC-SHA256 signature over `<id>.<timestamp>.<body>` with
+* the endpoint secret must match one entry in `webhook-signature`. Only then is the body parsed.
+* A valid delivery can arrive more than once, so handle each returned `id` once.
+*
+* Rejects with a subclass of `WebhookVerificationError`; {@link AnyWebhookVerificationError}
+* lists them. A missing or empty header rejects with `InvalidWebhookHeadersError`, whose `header`
+* names it. Use {@link safeVerify} for a result instead of a rejection.
+*
+* @example
+* ```ts
+* import { verify } from "@samva/webhooks";
+*
+* // Express: mount express.raw({ type: "application/json" }) on this route so body is a Buffer.
+* app.post("/webhooks/samva", async (req, res) => {
+*   const verified = await verify({
+*     body: req.body,
+*     id: req.header("webhook-id"),
+*     timestamp: req.header("webhook-timestamp"),
+*     signature: req.header("webhook-signature"),
+*     secret: process.env.SAMVA_WEBHOOK_SECRET!,
+*   });
+*   await handleOnce(verified.id, verified.event);
+*   res.sendStatus(204);
+* });
+* ```
+*/
 const verify = (options) => verifyWebhookAt({
 	body: options.body,
 	headers: {
@@ -11,6 +42,34 @@ const verify = (options) => verifyWebhookAt({
 	toleranceSeconds: options.toleranceSeconds,
 	nowMilliseconds: Date.now()
 });
+/**
+* Verifies a Samva webhook delivery received as a Fetch API `Request` (Cloudflare Workers, Bun,
+* Deno, Next.js route handlers, Hono, and similar), then returns its ID and parsed event.
+*
+* Reads the body from a clone, so the original request stays readable. Performs the same checks
+* as {@link verify} and rejects with the same errors; a missing signing header rejects with
+* `InvalidWebhookHeadersError`, whose `header` names it.
+*
+* @example
+* ```ts
+* import { verifyRequest, WebhookVerificationError } from "@samva/webhooks";
+*
+* export default {
+*   async fetch(request: Request, env: { SAMVA_WEBHOOK_SECRET: string }) {
+*     try {
+*       const { id, event } = await verifyRequest(request, env.SAMVA_WEBHOOK_SECRET);
+*       await handleOnce(id, event);
+*       return new Response(null, { status: 204 });
+*     } catch (error) {
+*       if (error instanceof WebhookVerificationError) {
+*         return new Response(null, { status: 400 });
+*       }
+*       throw error;
+*     }
+*   },
+* };
+* ```
+*/
 const verifyRequest = async (request, secret, options) => verifyWebhookAt({
 	body: new Uint8Array(await request.clone().arrayBuffer()),
 	headers: readWebhookHeaders(request.headers),
@@ -18,6 +77,26 @@ const verifyRequest = async (request, secret, options) => verifyWebhookAt({
 	toleranceSeconds: options?.toleranceSeconds,
 	nowMilliseconds: Date.now()
 });
+/**
+* Runs {@link verify} and resolves to a result instead of rejecting: `{ verified: true, value }`
+* on success, or `{ verified: false, error }` carrying the verification failure. Any other error,
+* such as a `TypeError` from input that violates the declared types, rejects.
+*
+* @example
+* ```ts
+* import { safeVerify, type VerifyOptions } from "@samva/webhooks";
+*
+* async function receive(delivery: VerifyOptions): Promise<Response> {
+*   const result = await safeVerify(delivery);
+*   if (!result.verified) {
+*     console.warn("rejected webhook", result.error._tag);
+*     return new Response(null, { status: 400 });
+*   }
+*   await handleOnce(result.value.id, result.value.event);
+*   return new Response(null, { status: 204 });
+* }
+* ```
+*/
 const safeVerify = async (options) => {
 	try {
 		return {
@@ -25,10 +104,11 @@ const safeVerify = async (options) => {
 			value: await verify(options)
 		};
 	} catch (error) {
-		return {
+		if (error instanceof WebhookVerificationError) return {
 			verified: false,
 			error
 		};
+		throw error;
 	}
 };
 //#endregion

package/dist/{protocol-M4mOvMtW.js → protocol-BGKUmvlI.js}

@@ -1,6 +1,15 @@
 //#region src/errors.ts
+/**
+* Base class for every failure this package reports while verifying a webhook delivery.
+*
+* Each subclass carries a literal `_tag` (also used as `name`), so you can branch on the failure
+* with a `switch` or Effect's `catchTag`. `detail` is a human-readable reason for your logs; do not
+* echo it to the sender, and do not match on its wording.
+*/
 var WebhookVerificationError = class extends Error {
+	/** Discriminant naming the concrete failure; equal to the subclass name. */
 	_tag;
+	/** Human-readable reason for logs. The wording is not a stable contract. */
 	detail;
 	constructor(tag, options) {
 		super(options.detail);
@@ -9,31 +18,67 @@ var WebhookVerificationError = class extends Error {
 		this.detail = options.detail;
 	}
 };
+/**
+* The signing secret is unusable: it lacks the `whsec_` prefix, the remainder is not Base64, or
+* the decoded key length is outside the accepted range (`detail` names the range). This is a
+* configuration error on the receiving side, not a bad delivery; copy the endpoint's signing
+* secret from Samva again.
+*/
 var InvalidWebhookSecretError = class extends WebhookVerificationError {
 	constructor(options) {
 		super("InvalidWebhookSecretError", options);
 	}
 };
+/**
+* One of the `webhook-id`, `webhook-timestamp`, or `webhook-signature` headers is missing or
+* empty; `header` names it. The request is not a Samva delivery, or something between Samva and
+* your handler stripped the headers.
+*/
 var InvalidWebhookHeadersError = class extends WebhookVerificationError {
+	/** The first signing header, in id, timestamp, signature order, that is missing or empty. */
+	header;
 	constructor(options) {
 		super("InvalidWebhookHeadersError", options);
+		this.header = options.header;
 	}
 };
+/**
+* The `webhook-timestamp` header is not an integer count of Unix seconds, it lies further from the
+* current time than the replay tolerance, or the tolerance you passed is negative or not finite.
+* A delivery outside the tolerance is rejected even when its signature is valid; that bounds how
+* long a captured request can be replayed. Repeated failures on genuine deliveries usually mean
+* the receiving server's clock is wrong.
+*/
 var WebhookTimestampError = class extends WebhookVerificationError {
 	constructor(options) {
 		super("WebhookTimestampError", options);
 	}
 };
+/**
+* No signature in the `webhook-signature` header matches the delivery, or no verification key was
+* supplied. Treat the request as forged and reject it. When genuine deliveries fail, the usual
+* causes are the wrong endpoint secret or a body that was parsed and re-serialized before
+* verification instead of passed through as the exact bytes received.
+*/
 var WebhookSignatureError = class extends WebhookVerificationError {
 	constructor(options) {
 		super("WebhookSignatureError", options);
 	}
 };
+/**
+* The signature is valid, but the body is not UTF-8 JSON holding exactly the `type`,
+* `timestamp`, and `data` fields of a Samva event envelope.
+*/
 var MalformedWebhookPayloadError = class extends WebhookVerificationError {
 	constructor(options) {
 		super("MalformedWebhookPayloadError", options);
 	}
 };
+/**
+* The runtime's Web Crypto implementation could not import a key or compute a signature, none of
+* the supplied public keys could be imported, or the Effect entrypoint could not read the request
+* body. Points at the runtime or its configuration rather than at the delivery.
+*/
 var WebhookCryptoError = class extends WebhookVerificationError {
 	constructor(options) {
 		super("WebhookCryptoError", options);
@@ -41,9 +86,24 @@ var WebhookCryptoError = class extends WebhookVerificationError {
 };
 //#endregion
 //#region src/protocol.ts
+/**
+* Header carrying the delivery's unique message ID. Retries of the same delivery reuse it, so it
+* is the key for deduplicating deliveries you have already handled.
+*/
 const WEBHOOK_ID_HEADER = "webhook-id";
+/** Header carrying the time Samva signed the delivery, as integer Unix seconds. */
 const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+/**
+* Header carrying one or more space-separated `<version>,<base64 signature>` entries. More than one
+* entry appears while a signing secret is being rotated; a delivery verifies when any entry of the
+* expected version matches.
+*/
 const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+/**
+* Replay tolerance, in seconds, used when a caller passes no `toleranceSeconds`. A delivery whose
+* `webhook-timestamp` differs from the current time by more than this, in either direction, is
+* rejected with {@link WebhookTimestampError}.
+*/
 const DEFAULT_TOLERANCE_SECONDS = 300;
 const SECRET_PREFIX = "whsec_";
 const ASYMMETRIC_ALGORITHM = {
@@ -150,20 +210,54 @@ const parseEvent = (body) => {
 		throw new MalformedWebhookPayloadError({ detail: "Webhook body must be valid UTF-8 JSON containing type, timestamp, and data" });
 	}
 };
+/**
+* Creates a random `whsec_`-prefixed signing secret from the runtime's secure random source.
+* Samva issues each endpoint's secret for you; use this to sign test deliveries with
+* {@link signWebhook}.
+*/
 const generateWebhookSecret = () => {
 	const bytes = crypto.getRandomValues(new Uint8Array(GENERATED_SECRET_BYTES));
 	return `${SECRET_PREFIX}${bytesToBase64(bytes)}`;
 };
+/**
+* Builds the bytes every signature version covers: `<id>.<timestamp>.<body>`. Use it to verify a
+* signature with your own crypto code; {@link verifyWebhookAt} and
+* {@link verifyWebhookAtWithPublicKeys} build it for you.
+*/
 const webhookSignedContent = (input) => signedBytes(input.id, input.timestamp, toBytes(input.body));
+/** Formats raw signature bytes as one `<version>,<base64>` entry of the `webhook-signature` header. */
 const encodeWebhookSignature = (version, signature) => `${version},${bytesToBase64(signature)}`;
+/**
+* Computes the `v1` HMAC-SHA256 signature Samva sends, formatted as one `webhook-signature`
+* entry. Use it to produce signed test deliveries for your handler.
+*
+* `timestamp` is Unix seconds; a number is stringified, and the verifier requires an integer.
+* Rejects with {@link InvalidWebhookSecretError} for an unusable secret and
+* {@link WebhookCryptoError} when Web Crypto fails.
+*/
 const signWebhook = async (input) => {
 	const timestamp = String(input.timestamp);
 	const signature = await hmac(input.secret, input.id, timestamp, toBytes(input.body));
 	return encodeWebhookSignature("v1", signature);
 };
+const requireHeader = (header, value) => {
+	if (value === null || value === void 0) throw new InvalidWebhookHeadersError({
+		header,
+		detail: `${header} header is missing`
+	});
+	if (value.length === 0) throw new InvalidWebhookHeadersError({
+		header,
+		detail: `${header} header is empty`
+	});
+	return value;
+};
+const requireHeaders = (values) => ({
+	id: requireHeader(WEBHOOK_ID_HEADER, values.id),
+	timestamp: requireHeader(WEBHOOK_TIMESTAMP_HEADER, values.timestamp),
+	signature: requireHeader(WEBHOOK_SIGNATURE_HEADER, values.signature)
+});
 const freshHeaders = (input) => {
-	const { id, timestamp, signature } = input.headers;
-	if (id.length === 0 || timestamp.length === 0 || signature.length === 0) throw new InvalidWebhookHeadersError({ detail: "webhook-id, webhook-timestamp, and webhook-signature are required" });
+	const { id, timestamp, signature } = requireHeaders(input.headers);
 	const timestampSeconds = Number(timestamp);
 	if (!Number.isInteger(timestampSeconds)) throw new WebhookTimestampError({ detail: "webhook-timestamp must be Unix seconds" });
 	const toleranceSeconds = input.toleranceSeconds ?? 300;
@@ -175,6 +269,20 @@ const freshHeaders = (input) => {
 		signature
 	};
 };
+/**
+* Verifies a `v1` (HMAC-SHA256) delivery against an explicit current time. The `verify` and
+* `verifyRequest` entry points call this with the current clock; call it directly when your
+* framework owns the clock or a test needs a fixed time.
+*
+* Checks, in order: all three headers are present and non-empty; the timestamp is integer Unix seconds within
+* `toleranceSeconds` of `nowMilliseconds`; some `v1` entry in the signature header matches, using
+* a constant-time comparison; the body is a Samva event envelope. The replay window rejects stale
+* deliveries but does not detect a repeat inside it; deduplicate on the returned `id`.
+*
+* Rejects with {@link InvalidWebhookHeadersError}, {@link WebhookTimestampError},
+* {@link InvalidWebhookSecretError}, {@link WebhookSignatureError},
+* {@link MalformedWebhookPayloadError}, or {@link WebhookCryptoError}.
+*/
 const verifyWebhookAt = async (input) => {
 	const { id, timestamp, signature } = freshHeaders(input);
 	const body = toBytes(input.body);
@@ -185,6 +293,15 @@ const verifyWebhookAt = async (input) => {
 		event: parseEvent(body)
 	};
 };
+/**
+* Verifies a `v2` (RSASSA-PKCS1-v1_5, SHA-256) delivery against one or more public keys, each a
+* Base64-encoded SPKI DER key. Pass several keys during a key rotation; the delivery verifies when
+* any `v2` signature entry matches any key.
+*
+* Header, timestamp, and envelope checks match {@link verifyWebhookAt}. Keys that fail to import
+* are skipped. Rejects with {@link WebhookSignatureError} when `publicKeys` is empty or nothing
+* matches, and {@link WebhookCryptoError} when none of the keys imports.
+*/
 const verifyWebhookAtWithPublicKeys = async (input) => {
 	const { id, timestamp, signature } = freshHeaders(input);
 	if (input.publicKeys.length === 0) throw new WebhookSignatureError({ detail: "No webhook verification key is available" });
@@ -199,12 +316,18 @@ const verifyWebhookAtWithPublicKeys = async (input) => {
 		event: parseEvent(body)
 	};
 };
-const readWebhookHeaders = (headers) => ({
-	id: headers.get("webhook-id") ?? "",
-	timestamp: headers.get("webhook-timestamp") ?? "",
-	signature: headers.get("webhook-signature") ?? ""
+/**
+* Reads the three signing headers from a Fetch API `Headers` object, for code that needs a header
+* value, such as the timestamp, before or beside verification. Throws
+* {@link InvalidWebhookHeadersError}, naming the header, when one is missing or empty; call it
+* inside the same error handling as the verification that follows.
+*/
+const readWebhookHeaders = (headers) => requireHeaders({
+	id: headers.get(WEBHOOK_ID_HEADER),
+	timestamp: headers.get(WEBHOOK_TIMESTAMP_HEADER),
+	signature: headers.get(WEBHOOK_SIGNATURE_HEADER)
 });
 //#endregion
 export { WebhookTimestampError as _, encodeWebhookSignature as a, signWebhook as c, webhookSignedContent as d, InvalidWebhookHeadersError as f, WebhookSignatureError as g, WebhookCryptoError as h, WEBHOOK_TIMESTAMP_HEADER as i, verifyWebhookAt as l, MalformedWebhookPayloadError as m, WEBHOOK_ID_HEADER as n, generateWebhookSecret as o, InvalidWebhookSecretError as p, WEBHOOK_SIGNATURE_HEADER as r, readWebhookHeaders as s, DEFAULT_TOLERANCE_SECONDS as t, verifyWebhookAtWithPublicKeys as u, WebhookVerificationError as v };
 
-//# sourceMappingURL=protocol-M4mOvMtW.js.map
+//# sourceMappingURL=protocol-BGKUmvlI.js.map

package/dist/protocol.d.ts

@@ -1,46 +1,148 @@
+/**
+ * Header carrying the delivery's unique message ID. Retries of the same delivery reuse it, so it
+ * is the key for deduplicating deliveries you have already handled.
+ */
 export declare const WEBHOOK_ID_HEADER = "webhook-id";
+/** Header carrying the time Samva signed the delivery, as integer Unix seconds. */
 export declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+/**
+ * Header carrying one or more space-separated `<version>,<base64 signature>` entries. More than one
+ * entry appears while a signing secret is being rotated; a delivery verifies when any entry of the
+ * expected version matches.
+ */
 export declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+/**
+ * Replay tolerance, in seconds, used when a caller passes no `toleranceSeconds`. A delivery whose
+ * `webhook-timestamp` differs from the current time by more than this, in either direction, is
+ * rejected with {@link WebhookTimestampError}.
+ */
 export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/** The event envelope carried in a verified delivery's body. */
 export interface SamvaWebhookEvent {
+    /** Event type, such as `message.delivered`. Branch on it before reading `data`. */
     readonly type: string;
+    /** When the event occurred, as an ISO 8601 string. Distinct from the delivery's signing time. */
     readonly timestamp: string;
+    /** Event-specific payload. Its shape depends on `type`; validate it before use. */
     readonly data: unknown;
 }
+/** A delivery whose signature, timestamp, and envelope all checked out. */
 export interface VerifiedWebhook {
+    /**
+     * The delivery's `webhook-id` header. Stable across retries of the same delivery; record it to
+     * handle each delivery once, because a valid delivery may arrive more than once within the
+     * replay tolerance.
+     */
     readonly id: string;
     readonly event: SamvaWebhookEvent;
 }
+/** The three signing headers of a delivery, each present and non-empty, read verbatim. */
 export interface WebhookHeaders {
+    /** Value of {@link WEBHOOK_ID_HEADER}. */
     readonly id: string;
+    /** Value of {@link WEBHOOK_TIMESTAMP_HEADER}. */
     readonly timestamp: string;
+    /** Value of {@link WEBHOOK_SIGNATURE_HEADER}. */
     readonly signature: string;
 }
+/**
+ * The three signing header values as your framework reports them. An absent header is `null` (as
+ * Fetch API `Headers.get` returns it) or `undefined` (as Node.js and Express return it); pass it
+ * through as-is and verification rejects it with {@link InvalidWebhookHeadersError}.
+ */
+export interface WebhookHeaderValues {
+    /** Value of {@link WEBHOOK_ID_HEADER}. */
+    readonly id: string | null | undefined;
+    /** Value of {@link WEBHOOK_TIMESTAMP_HEADER}. */
+    readonly timestamp: string | null | undefined;
+    /** Value of {@link WEBHOOK_SIGNATURE_HEADER}. */
+    readonly signature: string | null | undefined;
+}
+/** Input to {@link verifyWebhookAt}, which takes the current time explicitly. */
 export interface VerifyWebhookInput {
+    /**
+     * The request body exactly as received. Pass the raw text or bytes; a body that was parsed and
+     * re-serialized no longer matches its signature.
+     */
     readonly body: string | Uint8Array;
-    readonly headers: WebhookHeaders;
+    readonly headers: WebhookHeaderValues;
+    /** The endpoint's signing secret, including its `whsec_` prefix. Keep it on the server. */
     readonly secret: string;
+    /** Replay tolerance in seconds; defaults to {@link DEFAULT_TOLERANCE_SECONDS}. */
     readonly toleranceSeconds?: number | undefined;
+    /** The current time in Unix milliseconds, as `Date.now()` returns it. */
     readonly nowMilliseconds: number;
 }
+/**
+ * Signature scheme version inside a `webhook-signature` entry: `v1` is HMAC-SHA256 with the
+ * endpoint's shared secret; `v2` is RSASSA-PKCS1-v1_5 with SHA-256, checked against a public key.
+ */
 export type WebhookSignatureVersion = "v1" | "v2";
+/**
+ * Creates a random `whsec_`-prefixed signing secret from the runtime's secure random source.
+ * Samva issues each endpoint's secret for you; use this to sign test deliveries with
+ * {@link signWebhook}.
+ */
 export declare const generateWebhookSecret: () => string;
+/**
+ * Builds the bytes every signature version covers: `<id>.<timestamp>.<body>`. Use it to verify a
+ * signature with your own crypto code; {@link verifyWebhookAt} and
+ * {@link verifyWebhookAtWithPublicKeys} build it for you.
+ */
 export declare const webhookSignedContent: (input: {
     readonly id: string;
     readonly timestamp: string;
     readonly body: string | Uint8Array;
 }) => Uint8Array;
+/** Formats raw signature bytes as one `<version>,<base64>` entry of the `webhook-signature` header. */
 export declare const encodeWebhookSignature: (version: WebhookSignatureVersion, signature: Uint8Array) => string;
+/**
+ * Computes the `v1` HMAC-SHA256 signature Samva sends, formatted as one `webhook-signature`
+ * entry. Use it to produce signed test deliveries for your handler.
+ *
+ * `timestamp` is Unix seconds; a number is stringified, and the verifier requires an integer.
+ * Rejects with {@link InvalidWebhookSecretError} for an unusable secret and
+ * {@link WebhookCryptoError} when Web Crypto fails.
+ */
 export declare const signWebhook: (input: {
     readonly body: string | Uint8Array;
     readonly id: string;
     readonly timestamp: string | number;
     readonly secret: string;
 }) => Promise<string>;
+/**
+ * Verifies a `v1` (HMAC-SHA256) delivery against an explicit current time. The `verify` and
+ * `verifyRequest` entry points call this with the current clock; call it directly when your
+ * framework owns the clock or a test needs a fixed time.
+ *
+ * Checks, in order: all three headers are present and non-empty; the timestamp is integer Unix seconds within
+ * `toleranceSeconds` of `nowMilliseconds`; some `v1` entry in the signature header matches, using
+ * a constant-time comparison; the body is a Samva event envelope. The replay window rejects stale
+ * deliveries but does not detect a repeat inside it; deduplicate on the returned `id`.
+ *
+ * Rejects with {@link InvalidWebhookHeadersError}, {@link WebhookTimestampError},
+ * {@link InvalidWebhookSecretError}, {@link WebhookSignatureError},
+ * {@link MalformedWebhookPayloadError}, or {@link WebhookCryptoError}.
+ */
 export declare const verifyWebhookAt: (input: VerifyWebhookInput) => Promise<VerifiedWebhook>;
+/**
+ * Verifies a `v2` (RSASSA-PKCS1-v1_5, SHA-256) delivery against one or more public keys, each a
+ * Base64-encoded SPKI DER key. Pass several keys during a key rotation; the delivery verifies when
+ * any `v2` signature entry matches any key.
+ *
+ * Header, timestamp, and envelope checks match {@link verifyWebhookAt}. Keys that fail to import
+ * are skipped. Rejects with {@link WebhookSignatureError} when `publicKeys` is empty or nothing
+ * matches, and {@link WebhookCryptoError} when none of the keys imports.
+ */
 export declare const verifyWebhookAtWithPublicKeys: (input: Omit<VerifyWebhookInput, "secret"> & {
     readonly publicKeys: ReadonlyArray<string>;
 }) => Promise<VerifiedWebhook>;
+/**
+ * Reads the three signing headers from a Fetch API `Headers` object, for code that needs a header
+ * value, such as the timestamp, before or beside verification. Throws
+ * {@link InvalidWebhookHeadersError}, naming the header, when one is missing or empty; call it
+ * inside the same error handling as the verification that follows.
+ */
 export declare const readWebhookHeaders: (headers: Headers) => WebhookHeaders;
 export { InvalidWebhookHeadersError, InvalidWebhookSecretError, MalformedWebhookPayloadError, WebhookCryptoError, WebhookSignatureError, WebhookTimestampError, WebhookVerificationError, } from "./errors.js";
-export type { AnyWebhookVerificationError } from "./errors.js";
+export type { AnyWebhookVerificationError, WebhookHeaderName } from "./errors.js";

package/dist/protocol.js

@@ -1,2 +1,2 @@
-import { _ as WebhookTimestampError, a as encodeWebhookSignature, c as signWebhook, d as webhookSignedContent, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, s as readWebhookHeaders, t as DEFAULT_TOLERANCE_SECONDS, u as verifyWebhookAtWithPublicKeys, v as WebhookVerificationError } from "./protocol-M4mOvMtW.js";
+import { _ as WebhookTimestampError, a as encodeWebhookSignature, c as signWebhook, d as webhookSignedContent, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, s as readWebhookHeaders, t as DEFAULT_TOLERANCE_SECONDS, u as verifyWebhookAtWithPublicKeys, v as WebhookVerificationError } from "./protocol-BGKUmvlI.js";
 export { DEFAULT_TOLERANCE_SECONDS, InvalidWebhookHeadersError, InvalidWebhookSecretError, MalformedWebhookPayloadError, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookCryptoError, WebhookSignatureError, WebhookTimestampError, WebhookVerificationError, encodeWebhookSignature, generateWebhookSecret, readWebhookHeaders, signWebhook, verifyWebhookAt, verifyWebhookAtWithPublicKeys, webhookSignedContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samva/webhooks",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Runtime-neutral verification for Samva webhook deliveries",
   "keywords": [
     "samva",
@@ -58,14 +58,14 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.112",
-    "effect": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.117",
+    "effect": "4.0.0-rc.117",
     "tsdown": "^0.22.13",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.112"
+    "effect": "4.0.0-rc.117"
   },
   "peerDependenciesMeta": {
     "effect": {