hooklatch 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hooklatch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,439 @@
-# Temporary Holding Version
+# Hooklatch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Verify webhooks. Preserve every byte.**
+
+[![CI](https://github.com/Its-amanjha/Hooklatch/actions/workflows/ci.yml/badge.svg)](https://github.com/Its-amanjha/Hooklatch/actions/workflows/ci.yml)
+
+Portable webhook signature verification with a zero-dependency core.
+
+Hooklatch checks incoming webhook signatures over the exact request bytes
+before your code parses or trusts the payload. It supports Stripe, GitHub,
+Shopify, Standard Webhooks, Clerk, Svix, Razorpay, Paddle Billing, Lemon
+Squeezy, Dodo Payments, GitLab signing tokens, Replicate, WorkOS, Sentry App,
+Doppler signed webhooks, Sanity, Grafana, Polar, Linear, Vercel and fal through
+one asynchronous API,
+with optional framework adapters, diagnostics and a local scaffolding CLI.
+
+
+## Requirements
+
+- **Node.js >= 22** (ESM and CommonJS; the 22.0.0 floor, later 22.x and 24.x
+  were qualified — see [module compatibility](docs/compatibility.md))
+- Zero runtime dependencies in the core
+- Optional peers: `express`, `hono` (only needed for those adapters)
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install hooklatch
+```
+
+## Quick start
+
+```ts
+import { verify } from 'hooklatch';
+
+const result = await verify(
+  { rawBody, headers },                       // exact bytes + headers
+  { provider: 'stripe', secrets: [secret] },  // explicit provider
+);
+
+if (!result.ok) {
+  // Request-validation failure: safe to log the reason.
+  console.warn(result.reason, result.message);
+  return;
+}
+
+// Verified. Parse the payload yourself — verification is not parsing.
+const event = JSON.parse(new TextDecoder().decode(result.rawBody));
+```
+
+All examples in this README and under `examples/` use synthetic placeholder
+values. Replace them with your real endpoint secrets and provider payloads.
+
+## Features
+
+- **Exact-byte verification.** Signatures are checked over the raw request
+  bytes captured before any framework parsing or re-serialization.
+- **Explicit provider selection.** You name the provider; there is no
+  auto-detection to misidentify a request.
+- **Credential rotation.** For HMAC providers, pass every active secret; the
+  verifier tries signatures against the accept-set. For fal, configure the
+  trusted public-key accept-set and expected user ID.
+- **Portable core.** Web Crypto HMAC and Ed25519 with no Node-only imports; runs on
+  Node 22+ and in Workers-compatible runtimes.
+- **Framework adapters.** Express, Next.js App Router, Cloudflare Workers,
+  and Hono on isolated subpaths.
+
+## Supported protocols
+
+Verification never parses or validates payload schemas. Algorithms are fixed per
+provider: the first nineteen use HMAC-SHA256, Vercel uses HMAC-SHA1, and fal uses
+Ed25519. Request data cannot select the algorithm.
+
+<!-- hooklatch:provider-table:start -->
+| Provider | Algorithm | Signed content | Credentials | Freshness | Identity |
+|----------|-----------|----------------|-------------|-----------|----------|
+| `stripe` | HMAC-SHA256 | `timestamp.body` | Literal secret string | Signed; inclusive tolerance (default 300s) | Signed timestamp only |
+| `github` | HMAC-SHA256 | Body only | Literal secret string | None signed | Unsigned delivery ID |
+| `shopify` | HMAC-SHA256 | Body only | Literal secret string | None signed | Unsigned webhook/event IDs |
+| `standard-webhooks` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded after `whsec_` strip (24–64 bytes) | Signed; inclusive tolerance (default 300s) | Signed event ID + attempt timestamp |
+| `clerk` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded after `whsec_` strip (24–64 bytes) | Signed; inclusive tolerance (default 300s) | Signed event ID + attempt timestamp |
+| `svix` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded after `whsec_` strip (24–64 bytes) | Signed; inclusive tolerance (default 300s) | Signed event ID + attempt timestamp |
+| `razorpay` | HMAC-SHA256 | Body only | Literal secret string | None signed | Optional unsigned event ID |
+| `paddle` | HMAC-SHA256 | `ts:body` | Literal secret string | Signed; default 5s (symmetric inclusive) | Signed timestamp only |
+| `lemon-squeezy` | HMAC-SHA256 | Body only | Literal secret string | None signed | None extracted |
+| `dodo-payments` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded after optional `whsec_` strip (24–64 bytes) | Signed; default 300s | Signed event ID + timestamp |
+| `gitlab` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded after optional `whsec_` strip (24–64 bytes) | Signed; default 300s | Signed event ID + timestamp |
+| `replicate` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded after optional `whsec_` strip (24–64 bytes) | Signed; default 300s | Signed event ID + timestamp |
+| `workos` | HMAC-SHA256 | `t.body` (millisecond `t`) | Literal secret string | Signed; default 180s | Signed timestamp only |
+| `sentry` | HMAC-SHA256 | Body only | Literal secret string | None signed | None extracted |
+| `doppler` | HMAC-SHA256 | Body only | Literal secret string | None signed | None extracted |
+| `sanity` | HMAC-SHA256 | `t.body` (with `.` separator) | Literal secret string | Signed; default 300s (receiver policy) | Signed timestamp only |
+| `grafana` | HMAC-SHA256 | Body (body mode) or `timestamp:body` (timestamped mode) | Literal secret string | Timestamped mode only; default 300s | Signed timestamp in timestamped mode |
+| `polar` | HMAC-SHA256 | `id.timestamp.body` | Base64-decoded (current) or literal UTF-8 (legacy); one mode per accept-set | Signed; default 300s | Signed event ID + timestamp |
+| `linear` | HMAC-SHA256 | Body only | Literal secret string | Body timestamp not extracted or freshness-checked | None extracted |
+| `vercel` | HMAC-SHA1 | Body only | Literal secret string | None signed | None extracted |
+| `fal` | Ed25519 | `requestId\nuserId\ntimestamp\nsha256hex(body)` | Raw 32-byte public keys (1..16) + required `expectedUserId`; no shared secret | Signed; default 300s | Signed timestamp only |
+<!-- hooklatch:provider-table:end -->
+
+Clerk ignores canonical `webhook-*` headers. Svix accepts either complete header
+family; if both appear they must be complete and equal. Partial families are
+never assembled together. Standard Webhooks, Clerk and Svix require decoded
+signing keys of 24–64 bytes, as do Dodo, GitLab and Replicate; shorter
+reference-library examples are rejected. GitLab requires a signing token;
+legacy `X-Gitlab-Token` alone is not accepted.
+Linear support authenticates the signature over exact body bytes. It does not
+parse `webhookTimestamp` or enforce freshness. The body claims remain covered by
+the MAC, but Hooklatch does not extract them into identity. `Linear-Timestamp`,
+`Linear-Delivery` and `Linear-Event` headers are unsigned and ignored. Applications
+that need replay checks must validate authenticated body claims after success.
+
+See the [provider guide](docs/providers.md) for exact headers, identity fields,
+and protocol-specific limits. Paddle support covers Billing webhooks only.
+
+Use endpoint-specific secrets. Providers sharing a signing protocol can accept
+the same signed request when configured with the same key. The `provider`
+option selects verification rules; it does not add cryptographic vendor binding.
+
+> **Implementation status (documentation reviewed 2026-10-30):** The core,
+> twenty-one provider descriptors, four adapters, CLI and diagnostics helper are
+> implemented. The last measured acceptance was commit `baa8a74` on 2026-10-28:
+> a clean local `npm run verify` passed 87 suites / 4,161 tests plus the
+> package, type and runtime gates, and exact-SHA CI run
+> [40650684406](https://github.com/Its-amanjha/Hooklatch/actions/runs/40650684406)
+> completed successfully (verify on Node.js 22 and 24; node-floor on Node.js
+> 22.0.0; checked 2026-10-29). Tests use reference vectors and synthetic
+> signatures; no live provider or delivery testing has been performed. This
+> documentation review is dated 2026-10-30 and does not re-run or extend that
+> qualification.
+> Run `npm run verify` for the full local checks. See
+> [verification evidence](docs/verification-evidence.md) for the measured scope,
+> provenance and receipt references, and [CONTRIBUTING.md](CONTRIBUTING.md) for
+> the implemented layout.
+
+## Local scaffolding
+
+With a built copy of Hooklatch installed, preview one TypeScript handler
+without writing files:
+
+```sh
+npx --no-install hooklatch init webhook --provider clerk --framework nextjs --dry-run
+```
+
+Remove `--dry-run` to generate it. Existing files are refused. See the
+[CLI reference](docs/cli.md) for paths, environment names and filesystem limits.
+
+## Diagnostics
+
+```ts
+import { diagnose } from 'hooklatch/diagnostics';
+
+if (!result.ok) console.warn(diagnose(result));
+```
+
+The pure helper returns static guidance for a validated reason/provider and
+ignores request messages and payloads. Possible causes are suggestions, not
+proof of a wrong secret or tampering. See [diagnostics](docs/diagnostics.md).
+
+## Core API
+
+### `verify(request, options)`
+
+```ts
+verify(request: WebhookRequest, options: VerifyOptions): Promise<VerificationResult>
+```
+
+- `rawBody` — the exact request bytes. Never a re-serialized object.
+- `headers` — Web `Headers`, a readonly tuple list, or a record with string
+  or string-array values. Lookup is case-insensitive; repeated values are
+  comma-combined. Web `Headers` can normalize surrounding whitespace.
+- `providerOptions` — trusted application configuration, required for Grafana,
+  optional for Polar, and forbidden for other providers. See configured providers below.
+- `secrets` — HMAC providers only: every active secret, including old and new
+  during rotation.
+- `publicKeys` and `expectedUserId` — fal only: trusted raw 32-byte Ed25519
+  public keys (1..16) and the required expected signed user ID. Both fields
+  belong at the top level; fal forbids `secrets` and `providerOptions`.
+- `toleranceSeconds` — signed-timestamp freshness window. Default `5` for
+  Paddle Billing, `180` for WorkOS and `300` for the other timestamped providers.
+  The boundary is inclusive: a timestamp exactly `toleranceSeconds` old is
+  accepted. `0` means a zero-width window (only exact matches), **not** a
+  skip of verification.
+  Paddle uses Hooklatch's symmetric window, including future rejection; this
+  does not promise exact SDK clock or parser parity. Body-only protocols have
+  no authenticated timestamp; signature verification alone does not stop replay.
+- `now` — clock injection for tests; returns epoch seconds and may be fractional.
+  WorkOS and Sanity preserve milliseconds in their default clocks; other default
+  clocks use whole seconds. Sanity's 300-second freshness window is Hooklatch
+  receiver policy, not an established upstream SDK recency default.
+  Request-reading APIs and adapters capture the clock before consuming the body;
+  freshness is measured at ingress, not at business-processing time.
+- `maxBodyBytes` — body size limit. Default `1048576` (1 MiB). Enforced
+  while reading, not just from `Content-Length`.
+
+For fal, supply credentials from trusted application configuration:
+
+```ts
+const result = await verify(
+  { rawBody, headers },
+  {
+    provider: 'fal',
+    publicKeys: trustedPublicKeys, // 1..16 raw 32-byte Uint8Array values
+    expectedUserId: configuredUserId,
+  },
+);
+```
+
+Do not add dummy shared secrets or obtain keys or the expected user ID from
+the incoming request. Signature authentication precedes account matching and
+freshness checks; only the signed timestamp is returned as public identity.
+
+### `verifyRequest(request, options)`
+
+Consumes a Web `Request` once with bounded reading. Already-consumed bodies
+are setup errors (`HooklatchError`). Returns the same `VerificationResult` shape.
+
+### `createVerifier(options)`
+
+Returns a preconfigured asynchronous verifier that takes just the request:
+
+```ts
+const verify = createVerifier({ provider: 'github', secrets: [secret] });
+const result = await verify({ rawBody, headers });
+```
+
+## Configured providers
+
+Grafana requires explicit trusted layout configuration. For example:
+
+```ts
+import { createVerifier } from 'hooklatch';
+
+const verifier = createVerifier({
+  provider: 'grafana',
+  secrets: [secret],
+  providerOptions: { mode: 'timestamped', timestampHeader: 'x-alert-timestamp' },
+});
+```
+
+Body mode signs only the raw body and
+provides no freshness check. Timestamped mode defaults to an inclusive 300-second
+window; neither mode deduplicates requests. Header names are configuration, not
+signed domain separation.
+
+Polar defaults to current Base64-decoded keys. Select
+`providerOptions: { secretMode: 'legacy' }` for full literal UTF-8 keys. One mode
+applies to every active secret; mixed-era rotation is unsupported.
+
+`VerifyOptions` is now a provider-discriminated union. Existing concrete-provider
+calls remain valid; broad provider objects and interface extension may need
+narrowing. See the [provider guide](docs/providers.md) and
+[type migration notes](docs/diagnostics.md#source-typing-migration-impact).
+
+## Result handling
+
+Verification failures are **returned**, not thrown. Setup and runtime
+problems are **thrown** as `HooklatchError`.
+
+```ts
+import { HooklatchError, verify } from 'hooklatch';
+
+// Request failure — an outcome, not an exception.
+const result = await verify(request, options);
+if (!result.ok) {
+  // result.reason is one of:
+  // 'missing-signature' | 'malformed-signature' | 'unsupported-scheme'
+  // | 'invalid-signature' | 'missing-identity' | 'missing-timestamp'
+  // | 'timestamp-expired' | 'timestamp-future' | 'body-too-large'
+}
+
+// Setup failure — thrown, safe to let crash at boot time.
+try {
+  const verify = createVerifier({ provider: 'nope', secrets: [] });
+} catch (err) {
+  if (err instanceof HooklatchError) console.warn(err.code);
+}
+```
+
+| Failure | Meaning |
+|---------|---------|
+| `missing-signature` | Expected signature header absent |
+| `malformed-signature` | Header present but unparseable |
+| `unsupported-scheme` | Only legacy/unknown schemes present |
+| `invalid-signature` | Well-formed, matches no configured secret |
+| `missing-identity` | Required metadata header absent |
+| `missing-timestamp` | Signed-timestamp scheme lacks timestamp |
+| `timestamp-expired` | Older than tolerance window |
+| `timestamp-future` | Newer than tolerance window |
+| `body-too-large` | Exceeds `maxBodyBytes` |
+
+## Verified is not parsed
+
+A successful result says the bytes are authentic. It says nothing about the
+payload's shape. Decode and validate with your own tools:
+
+```ts
+import { z } from 'zod';
+
+const result = await verify(request, options);
+if (!result.ok) return;
+
+const event = StripeEventSchema.parse(
+  JSON.parse(new TextDecoder().decode(result.rawBody)),
+);
+```
+
+## Body size limits
+
+`maxBodyBytes` (default 1 MiB) is enforced while reading streams and before
+copying raw inputs. Exceeding it returns `{ ok: false, reason:
+'body-too-large' }` for request verification, or `HooklatchError` for invalid
+limit configuration. Platform limits (e.g. Workers plan limits) may reject
+earlier.
+
+## Framework adapters
+
+Adapters live on isolated subpaths and import their framework as an optional
+peer dependency:
+
+```ts
+import { createWebhookMiddleware } from 'hooklatch/express';
+import { createWebhookMiddleware } from 'hooklatch/hono';
+import { createWebhookHandler } from 'hooklatch/nextjs';
+import { createWebhookHandler } from 'hooklatch/cloudflare';
+```
+
+Adapter behavior (contract v1):
+
+- Verification failures respond **400**; size violations **413**;
+  setup/runtime failures **500** with a generic response. Core reasons remain
+  available for safe application logging.
+- User handler errors follow the host framework; they are never reported as
+  signature failures.
+- Success runs the handler/next stage without acknowledging work early.
+
+### Express
+
+```ts
+import { createWebhookMiddleware } from 'hooklatch/express';
+
+app.post(
+  '/webhooks/stripe',
+  createWebhookMiddleware({ provider: 'stripe', secrets: [secret] }),
+  (req, res) => {
+    const success = req.webhook;
+    if (!success) return res.sendStatus(500);
+    const event = JSON.parse(new TextDecoder().decode(success.rawBody));
+    res.json({ received: true });
+  },
+);
+```
+
+Mount the middleware **before** any JSON body parser. The adapter reads the
+existing raw `Buffer`/`Uint8Array` or an unconsumed request stream; it never
+reconstructs bytes from a parsed object. Unsupported compressed bodies are
+rejected explicitly.
+
+### Hono
+
+```ts
+import { Hono } from 'hono';
+import { createWebhookMiddleware, type WebhookVariables } from 'hooklatch/hono';
+
+const app = new Hono<{ Variables: WebhookVariables }>();
+
+app.post(
+  '/webhooks/github',
+  createWebhookMiddleware({ provider: 'github', secrets: [secret] }),
+  async (c) => {
+    const success = c.get('webhook');    // VerificationSuccess
+    const event = JSON.parse(new TextDecoder().decode(success.rawBody));
+    return c.json({ received: true });
+  },
+);
+```
+
+### Next.js App Router
+
+```ts
+// app/webhooks/stripe/route.ts
+import { createWebhookHandler } from 'hooklatch/nextjs';
+
+export const POST = createWebhookHandler({
+  provider: 'stripe',
+  secrets: [process.env.STRIPE_SECRET!],
+  handler: async (request, success) => {
+    const event = JSON.parse(new TextDecoder().decode(success.rawBody));
+    return Response.json({ received: true });
+  },
+});
+```
+
+The original request body is consumed during verification; read
+`success.rawBody`, not the request body.
+
+### Cloudflare Workers
+
+```ts
+import { createWebhookHandler } from 'hooklatch/cloudflare';
+
+const fetch = createWebhookHandler<{ GITHUB_SECRET: string }>({
+  options: (env) => ({ provider: 'github', secrets: [env.GITHUB_SECRET] }),
+  handler: async (request, env, ctx, success) => {
+    const event = JSON.parse(new TextDecoder().decode(success.rawBody));
+    return Response.json({ received: true });
+  },
+});
+
+export default { fetch };
+```
+
+`options` receives `env` so bindings are resolved explicitly.
+
+## Roadmap
+
+- Future delivery integrations (queueing, retries, DLQ) are planned but not
+  part of this release. They will be designed separately and will not couple
+  to the verification API.
+
+## Security
+
+See `SECURITY.md` for the vulnerability reporting policy.
+
+## License
+
+MIT — see `LICENSE`.
+
+Reference test vectors come from [GitHub's webhook verification documentation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)
+and the [Standard Webhooks JavaScript test suite at a pinned revision](https://github.com/standard-webhooks/standard-webhooks/blob/7537d2a2d3d52d8f2e0ecd12527af4a9307fd81b/libraries/javascript/src/webhook.test.ts).
+Additional reference tuples come from the [Sanity toolkit tests at a pinned revision](https://github.com/sanity-io/webhook-toolkit/blob/e0c211ed6cd80465a70829e335c9e219f37839ba/test/signature.test.ts).
+The [Paddle Node SDK validator tests](https://github.com/PaddleHQ/paddle-node-sdk/blob/651261beddfc65ba5f861729dca17044cbeffb5f/src/__tests__/notifications/webhooks-validator.node.test.ts)
+also supply two published reference tuples. These are external reference material;
+locally generated cases are separately labelled synthetic.
+The Standard Webhooks repository includes an
+[MIT notice under `libraries/`](https://github.com/standard-webhooks/standard-webhooks/blob/7537d2a2d3d52d8f2e0ecd12527af4a9307fd81b/libraries/LICENSE).
+See [source and history notes](https://github.com/Its-amanjha/Hooklatch/blob/main/CONTRIBUTING.md#source-and-history-notes)
+for attribution and review limits.

package/dist/adapters/cloudflare.d.ts

@@ -0,0 +1,11 @@
+import type { VerificationSuccess, VerifyOptions } from '../types.js';
+export interface ExecutionContextLike {
+    waitUntil?(promise: Promise<unknown>): void;
+    passThroughOnException?(): void;
+}
+export interface WorkerWebhookHandlerOptions<Env = unknown> {
+    readonly options: (env: Env) => VerifyOptions;
+    readonly handler: (request: Request, env: Env, ctx: ExecutionContextLike, success: VerificationSuccess) => Response | Promise<Response>;
+}
+export declare function createWebhookHandler<Env = unknown>(options: WorkerWebhookHandlerOptions<Env>): (request: Request, env: Env, ctx: ExecutionContextLike) => Promise<Response>;
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/adapters/cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,sBAAsB,CAAC,IAAI,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B,CAAC,GAAG,GAAG,OAAO;IACxD,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,aAAa,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,CAChB,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,mBAAmB,KACzB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnC;AAED,wBAAgB,oBAAoB,CAAC,GAAG,GAAG,OAAO,EAChD,OAAO,EAAE,2BAA2B,CAAC,GAAG,CAAC,GACxC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,QAAQ,CAAC,CA8B9E"}

package/dist/adapters/cloudflare.js

@@ -0,0 +1,27 @@
+import { verifyRequest } from '../index.js';
+export function createWebhookHandler(options) {
+    return async (request, env, ctx) => {
+        const encoding = request.headers.get('content-encoding');
+        if (encoding && encoding.toLowerCase() !== 'identity') {
+            return new Response('Bad Request', { status: 400 });
+        }
+        let verification;
+        try {
+            const verifyOptions = options.options(env);
+            const result = await verifyRequest(request, verifyOptions);
+            if (!result.ok) {
+                if (result.reason === 'body-too-large') {
+                    return new Response('Payload Too Large', { status: 413 });
+                }
+                return new Response('Bad Request', { status: 400 });
+            }
+            verification = result;
+        }
+        catch {
+            // This boundary contains setup/verification only, never the user handler.
+            return new Response('Internal Server Error', { status: 500 });
+        }
+        return await options.handler(request, env, ctx, verification);
+    };
+}
+//# sourceMappingURL=cloudflare.js.map

package/dist/adapters/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAkB5C,MAAM,UAAU,oBAAoB,CAClC,OAAyC;IAEzC,OAAO,KAAK,EAAE,OAAgB,EAAE,GAAQ,EAAE,GAAyB,EAAqB,EAAE;QACxF,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAEzD,IAAI,QAAQ,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,UAAU,EAAE,CAAC;YACtD,OAAO,IAAI,QAAQ,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,YAAkC,CAAC;QAEvC,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YAE3D,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,IAAI,MAAM,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;oBACvC,OAAO,IAAI,QAAQ,CAAC,mBAAmB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC5D,CAAC;gBAED,OAAO,IAAI,QAAQ,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YACtD,CAAC;YAED,YAAY,GAAG,MAAM,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;YAC1E,OAAO,IAAI,QAAQ,CAAC,uBAAuB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;IAChE,CAAC,CAAC;AACJ,CAAC"}

package/dist/adapters/express.d.ts

@@ -0,0 +1,9 @@
+import type { RequestHandler } from 'express';
+import type { VerificationSuccess, VerifyOptions } from '../types.js';
+declare module 'express-serve-static-core' {
+    interface Request {
+        webhook?: VerificationSuccess;
+    }
+}
+export declare function createWebhookMiddleware(options: VerifyOptions): RequestHandler;
+//# sourceMappingURL=express.d.ts.map

package/dist/adapters/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAM/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,QAAQ,2BAA2B,CAAC;IACzC,UAAU,OAAO;QACf,OAAO,CAAC,EAAE,mBAAmB,CAAC;KAC/B;CACF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CAwE9E"}

package/dist/adapters/express.js

@@ -0,0 +1,63 @@
+import { HttpError, readNodeStream } from './shared.js';
+import { HooklatchError } from '../errors.js';
+import { prepareVerification } from '../internal/prepare.js';
+import { readClock, verifyPrepared } from '../internal/verification.js';
+import { normalizeHeaders } from '../internal/headers.js';
+export function createWebhookMiddleware(options) {
+    return async (req, res, next) => {
+        try {
+            const prepared = prepareVerification(options);
+            const normalized = prepared.options;
+            const receivedAt = readClock(prepared);
+            const headers = [...normalizeHeaders(req.headers)];
+            const maxBytes = normalized.maxBodyBytes;
+            const encodingHeader = req.headers['content-encoding'];
+            const encoding = Array.isArray(encodingHeader) ? encodingHeader.join(',') : encodingHeader;
+            if (encoding && encoding.toLowerCase() !== 'identity') {
+                res.status(400).send('Bad Request');
+                return;
+            }
+            const body = req.body;
+            let rawBody;
+            if (body instanceof Uint8Array) {
+                if (body.byteLength > maxBytes) {
+                    res.status(413).send('Payload Too Large');
+                    return;
+                }
+                rawBody = new Uint8Array(body);
+            }
+            else if (body !== undefined && body !== null) {
+                res.status(500).send('Internal Server Error');
+                return;
+            }
+            else {
+                if (req.readableEnded || req.readableDidRead || req.destroyed || req.readable === false) {
+                    res.status(500).send('Internal Server Error');
+                    return;
+                }
+                rawBody = await readNodeStream(req, maxBytes);
+            }
+            const result = await verifyPrepared({ rawBody, headers }, prepared, receivedAt);
+            if (!result.ok) {
+                const status = result.reason === 'body-too-large' ? 413 : 400;
+                res.status(status).send(status === 413 ? 'Payload Too Large' : 'Bad Request');
+                return;
+            }
+            req.webhook = result;
+        }
+        catch (err) {
+            if (err instanceof HttpError) {
+                res.status(err.status).send(err.message);
+                return;
+            }
+            if (err instanceof HooklatchError) {
+                res.status(500).send('Internal Server Error');
+                return;
+            }
+            next(err);
+            return;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":"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"}

package/dist/adapters/hono.d.ts

@@ -0,0 +1,12 @@
+import type { MiddlewareHandler } from 'hono';
+import type { VerificationSuccess, VerifyOptions } from '../types.js';
+declare module 'hono' {
+    interface ContextVariableMap {
+        webhook?: VerificationSuccess;
+    }
+}
+export type WebhookVariables = {
+    webhook: VerificationSuccess;
+};
+export declare function createWebhookMiddleware(options: VerifyOptions): MiddlewareHandler;
+//# sourceMappingURL=hono.d.ts.map

package/dist/adapters/hono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/adapters/hono.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAkB;QAC1B,OAAO,CAAC,EAAE,mBAAmB,CAAC;KAC/B;CACF;AAED,MAAM,MAAM,gBAAgB,GAAG;IAAE,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEhE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,iBAAiB,CA8BjF"}

package/dist/adapters/hono.js

@@ -0,0 +1,28 @@
+import { HooklatchError } from '../errors.js';
+import { verifyRequest } from '../index.js';
+export function createWebhookMiddleware(options) {
+    return async (c, next) => {
+        try {
+            const encoding = c.req.raw.headers.get('content-encoding');
+            if (encoding && encoding.toLowerCase() !== 'identity') {
+                return c.text('Bad Request', 400);
+            }
+            const result = await verifyRequest(c.req.raw, options);
+            if (!result.ok) {
+                if (result.reason === 'body-too-large') {
+                    return c.text('Payload Too Large', 413);
+                }
+                return c.text('Bad Request', 400);
+            }
+            c.set('webhook', result);
+        }
+        catch (err) {
+            if (err instanceof HooklatchError) {
+                return c.text('Internal Server Error', 500);
+            }
+            throw err;
+        }
+        await next();
+    };
+}
+//# sourceMappingURL=hono.js.map

package/dist/adapters/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","sourceRoot":"","sources":["../../src/adapters/hono.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAW5C,MAAM,UAAU,uBAAuB,CAAC,OAAsB;IAC5D,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;YAE3D,IAAI,QAAQ,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,UAAU,EAAE,CAAC;gBACtD,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;YACpC,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAEvD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,IAAI,MAAM,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;oBACvC,OAAO,CAAC,CAAC,IAAI,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;gBAC1C,CAAC;gBAED,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;YACpC,CAAC;YAED,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,OAAO,CAAC,CAAC,IAAI,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC;YAED,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/adapters/nextjs.d.ts

@@ -0,0 +1,6 @@
+import type { VerificationSuccess, VerifyOptions } from '../types.js';
+export type NextWebhookHandlerOptions = VerifyOptions & {
+    readonly handler: (request: Request, success: VerificationSuccess) => Response | Promise<Response>;
+};
+export declare function createWebhookHandler(options: NextWebhookHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=nextjs.d.ts.map

package/dist/adapters/nextjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../src/adapters/nextjs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,MAAM,yBAAyB,GAAG,aAAa,GAAG;IACtD,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACpG,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,yBAAyB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA6BhH"}