@amirabaris/webhook-kit 0.1.1 → 0.1.2

package/README.md

@@ -525,14 +525,14 @@ try {
 
 All errors inherit from `WebhookKitError` and include machine-readable `code` properties:
 
-| Error Class                   | `code`                          | Root Cause & Mitigation                                                                            |
-| ----------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `SignatureVerificationError`  | `SIGNATURE_VERIFICATION_FAILED` | HMAC digest mismatch or missing signing secret. Check that your webhook signing secret is correct. |
-| `TimestampToleranceError`     | `TIMESTAMP_TOLERANCE_EXCEEDED`  | Payload timestamp exceeds `toleranceSeconds` window. Protects against replay attacks.              |
-| `ReplayAttackError`           | `WEBHOOK_REPLAY_DETECTED`       | Event ID already exists in `store`. Prevents duplicate webhook processing within the TTL window.   |
-| `InvalidSignatureHeaderError` | `INVALID_SIGNATURE_HEADER`      | Header is missing, empty, or lacks required prefix (`sha256=`, `t=...,v1=...`).                    |
-| `PayloadExtractionError`      | `PAYLOAD_EXTRACTION_FAILED`     | Body is an unsupported format or input stream was prematurely closed.                              |
-| `WebhookKitError`             | `WEBHOOK_KIT_ERROR`             | Base class for all webhook-kit errors.                                                             |
+| Error Class                   | `code`                          | Root Cause & Mitigation                                                                          |
+| ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `SignatureVerificationError`  | `SIGNATURE_VERIFICATION_FAILED` | HMAC digest mismatch, missing secret, or invalid format (e.g., non-hex, wrong length).           |
+| `TimestampToleranceError`     | `TIMESTAMP_TOLERANCE_EXCEEDED`  | Payload timestamp is outside `toleranceSeconds` window, or is non-finite (`NaN`/`Infinity`).     |
+| `ReplayAttackError`           | `WEBHOOK_REPLAY_DETECTED`       | Event ID already exists in `store`. Prevents duplicate webhook processing within the TTL window. |
+| `InvalidSignatureHeaderError` | `INVALID_SIGNATURE_HEADER`      | Header is missing, empty, or lacks required prefix (`sha256=`, `t=...,v1=...`).                  |
+| `PayloadExtractionError`      | `PAYLOAD_EXTRACTION_FAILED`     | Body is an unsupported format or input stream was prematurely closed.                            |
+| `WebhookKitError`             | `WEBHOOK_KIT_ERROR`             | Base class for all webhook-kit errors.                                                           |
 
 ### Replay Attack Mitigation & Idempotency Store (`WebhookReplayStore`)
 
@@ -541,15 +541,18 @@ Replay attacks occur when an attacker (or a retry storm) replays a valid webhook
 `webhook-kit` combines two layers of replay protection:
 
 1. **Timestamp Tolerance**:
-   - **Stripe**: Parses `t=...` from `Stripe-Signature` and validates against `toleranceSeconds` (default: 300s).
+   - **Stripe**: Parses `t=...` from `Stripe-Signature` and validates against `toleranceSeconds` (default: 300s). Fractional timestamps are safely floored.
    - **Generic**: Automatically inspects `x-webhook-timestamp` (or explicit `timestamp` option) and validates against `toleranceSeconds`.
-2. **Idempotency / Replay Store (`store: { has(eventId), set(eventId, ttl) }`)**:
-   - Pass any synchronous or asynchronous store implementing `WebhookReplayStore` (`has(eventId)` and `set(eventId, ttlSeconds)`).
-   - `webhook-kit` automatically extracts the event ID from `options.eventId`, standard delivery headers (`X-GitHub-Delivery`, `X-Shopify-Webhook-Id`, `X-Webhook-Id`), or `payload.id` **after** cryptographic HMAC verification succeeds, and rejects duplicates with `ReplayAttackError` (`409 Conflict` in `createWebhookHandler`).
+   - **Strict Numeric Hardening**: Both `timestamp` and `toleranceSeconds` must be positive, finite numbers. Non-finite values (`NaN`, `Infinity`, `-Infinity`) or negative numbers immediately reject with `TimestampToleranceError` to prevent tolerance check bypasses.
+2. **Idempotency / Replay Store (`store: { has(eventId), set(eventId, ttl), setNx?(eventId, ttl) }`)**:
+   - Pass any synchronous or asynchronous store implementing `WebhookReplayStore`.
+   - Supports atomic `setNx` (_set-if-not-exists_) to eliminate race conditions under concurrent deliveries. If `setNx` is omitted, `webhook-kit` automatically serializes in-flight checks.
+   - `webhook-kit` automatically extracts the event ID from `options.eventId`, standard delivery headers (`svix-id`, `webhook-id`, `X-GitHub-Delivery`, `X-Shopify-Webhook-Id`, `X-Webhook-Id`), or `payload.id` **after** cryptographic HMAC verification succeeds, and rejects duplicates with `ReplayAttackError` (`409 Conflict` in `createWebhookHandler`).
+   - Supports both string and numeric event IDs (e.g. Shopify numeric webhook IDs) seamlessly.
 
 #### Default In-Memory TTL Store (`createInMemoryReplayStore`)
 
-For single-instance Node, Bun, or Deno servers, use the built-in zero-dependency TTL store with automatic expiration and LRU capacity bounding:
+For single-instance Node, Bun, or Deno servers, use the built-in zero-dependency TTL store with atomic `setNx`, automatic expiration, and LRU capacity bounding:
 
 ```ts
 import {
@@ -574,22 +577,34 @@ export const POST = createWebhookHandler({
 
 #### Distributed Store Hooks (Redis / Upstash / Cloudflare KV)
 
-For multi-instance or serverless edge deployments, wire a 6-line `WebhookReplayStore` adapter into Redis, Upstash, or Cloudflare Workers KV:
+For multi-instance or serverless edge deployments, wire a lightweight `WebhookReplayStore` adapter into Redis, Upstash, or Cloudflare Workers KV. Provide `setNx` (e.g. Redis `SET key value EX ttl NX`) for hardware-level atomic de-duplication:
 
 ```ts
 import type { WebhookReplayStore } from "@amirabaris/webhook-kit";
 
-// 1. Node / Bun Redis (ioredis or node-redis)
+// 1. Node / Bun Redis (ioredis or node-redis) with atomic setNx
 const redisStore: WebhookReplayStore = {
   has: async (id) => (await redis.exists(`wh:replay:${id}`)) === 1,
   set: async (id, ttl) => await redis.set(`wh:replay:${id}`, "1", "EX", ttl),
+  // Optional atomic set-if-not-exists for distributed lock-free deduplication
+  setNx: async (id, ttl) => {
+    const res = await redis.set(`wh:replay:${id}`, "1", "EX", ttl, "NX");
+    return res === "OK";
+  },
 };
 
-// 2. Upstash Redis (@upstash/redis — Edge & Next.js)
+// 2. Upstash Redis (@upstash/redis — Edge & Next.js) with atomic setNx
 const upstashStore: WebhookReplayStore = {
   has: async (id) => (await upstash.exists(`wh:replay:${id}`)) === 1,
   set: async (id, ttl) =>
     await upstash.set(`wh:replay:${id}`, "1", { ex: ttl }),
+  setNx: async (id, ttl) => {
+    const res = await upstash.set(`wh:replay:${id}`, "1", {
+      ex: ttl,
+      nx: true,
+    });
+    return res !== null;
+  },
 };
 
 // 3. Cloudflare Workers KV ( passed via Hono / Worker env )
@@ -618,10 +633,12 @@ flowchart LR
 
 `webhook-kit` is organized into modular layers:
 
-- **`crypto/`**: Web Cryptography API (`crypto.subtle`) primitives and constant-time buffer comparison.
-- **`utils/`**: Stream and body extraction that preserves raw payload bytes without consuming or mutating input requests.
-- **`providers/`**: Pluggable provider-specific format parsers (Stripe timestamped `t=...,v1=...`, GitHub `sha256=...`, Shopify Base64, etc.).
-- **`errors/`**: Strongly typed error classes (`SignatureVerificationError`, `TimestampToleranceError`, `PayloadExtractionError`).
+- **`crypto/`**: Web Cryptography API (`crypto.subtle`) primitives, key LRU caching, and constant-time buffer comparison (`timingSafeEqual`).
+- **`utils/`**: Stream and header utilities (`extractRawBody`, `extractHeaderValue`) preserving raw bytes without consuming input requests.
+- **`providers/`**: Pluggable provider-specific format parsers and verifiers (Stripe timestamped `t=...,v1=...`, GitHub `sha256=...`, Shopify Base64).
+- **`store/`**: Idempotency and replay attack prevention (`InMemoryReplayStore`, `checkAndRecordReplay`, atomic `setNx`).
+- **`handler/`**: Declarative universal route handler (`createWebhookHandler`) for Next.js, Hono, and WinterCG runtimes.
+- **`errors.ts`**: Strongly typed error class hierarchy (`SignatureVerificationError`, `TimestampToleranceError`, `ReplayAttackError`, `InvalidSignatureHeaderError`, `PayloadExtractionError`).
 
 ---
 

package/bin/webhook-kit.mjs

@@ -28,6 +28,8 @@ const AGENT_RULES_CONTENT = `${START_MARKER}
 - **NEVER parse JSON before verifying signatures**: In frameworks like Next.js, Hono, or Express, parsing JSON reorders keys and strips whitespace, invalidating cryptographic HMAC checks. Always pass the raw \`Request\` or raw text string.
 - **Constant-Time Verification**: Never compare signatures with \`===\` or \`!==\`. Always use \`timingSafeEqual\` or \`verifyWebhookSignature\` from \`@amirabaris/webhook-kit\`.
 - **Zero Node-Only Crypto**: Web standard environments (Cloudflare Workers, Next.js Edge, Bun, Deno) do not support \`node:crypto\`. Rely on \`@amirabaris/webhook-kit\` which uses \`crypto.subtle\`.
+- **Strict Format & Tolerance Hardening**: Validate signature format (e.g. strict 64-char hex or 44-char Base64) before crypto checks. Enforce positive, finite numbers for timestamps and \`toleranceSeconds\` (\`NaN\` and negative tolerance are rejected).
+- **Replay Protection & Store**: Deduplicate retries with \`store: createInMemoryReplayStore()\` or distributed \`WebhookReplayStore\` adapters (\`has\`, \`set\`, optional atomic \`setNx\`), supporting both string and numeric event IDs.
 - **Conventional Commits**: Follow \`type(scope): message\` (e.g. \`feat(stripe): add tolerance check\`).
 ${END_MARKER}`;