@rotorsoft/act-http 1.2.0 → 1.3.0

package/dist/{chunk-F7VWYZ37.js.map → chunk-K4HAOBRF.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/receiver/hono/index.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/hono\n *\n * Hono adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import { Hono } from \"hono\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/hono\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = new Hono();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   async (c) => {\n *     const idem = c.get(\"idempotency\") as { key: string; deduped: boolean };\n *     if (idem.deduped) return c.json({ status: \"dedup-skipped\", key: idem.key });\n *     // ... process the inbound event ...\n *     return c.json({ status: \"processed\", key: idem.key });\n *   }\n * );\n * ```\n *\n * On failure: returns `c.json({ error: <reason> }, status)` directly\n * (Hono short-circuits when middleware returns a Response). On\n * success: stashes `c.set(\"idempotency\", { key, deduped })` and\n * continues with `await next()`.\n *\n * **Raw body**: Hono exposes `await c.req.text()` natively, which\n * the middleware reads when `secret` is configured. No extra setup\n * needed.\n */\nimport type { MiddlewareHandler } from \"hono\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Variables this middleware contributes to the Hono context. The\n * generic on the returned {@link MiddlewareHandler} threads it\n * through so route handlers downstream of `app.post(..., webhookMiddleware(...), handler)`\n * see `c.get(\"idempotency\")` typed without a manual cast.\n */\nexport type WebhookVariables = {\n  idempotency: { key: string; deduped: boolean };\n};\n\n/**\n * Build a Hono middleware that verifies the request signature (when\n * `secret` is set), enforces `Idempotency-Key`, and claims the key\n * on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): MiddlewareHandler<{ Variables: WebhookVariables }> {\n  return async function check(c, next) {\n    const headers = headersBag(c.req.raw.headers);\n    const rawBody = await c.req.text();\n    const result = await checkWebhook(headers, rawBody, options);\n    if (!result.ok) {\n      return c.json({ error: result.reason }, result.status);\n    }\n    c.set(\"idempotency\", { key: result.key, deduped: result.deduped });\n    await next();\n  };\n}\n\nfunction headersBag(\n  headers: Headers\n): Record<string, string | string[] | undefined> {\n  const out: Record<string, string | string[] | undefined> = {};\n  headers.forEach((value, key) => {\n    out[key] = value;\n  });\n  return out;\n}\n"],"mappings":";;;;;AAuDO,SAAS,kBACd,SACoD;AACpD,SAAO,eAAe,MAAM,GAAG,MAAM;AACnC,UAAM,UAAU,WAAW,EAAE,IAAI,IAAI,OAAO;AAC5C,UAAM,UAAU,MAAM,EAAE,IAAI,KAAK;AACjC,UAAM,SAAS,MAAM,aAAa,SAAS,SAAS,OAAO;AAC3D,QAAI,CAAC,OAAO,IAAI;AACd,aAAO,EAAE,KAAK,EAAE,OAAO,OAAO,OAAO,GAAG,OAAO,MAAM;AAAA,IACvD;AACA,MAAE,IAAI,eAAe,EAAE,KAAK,OAAO,KAAK,SAAS,OAAO,QAAQ,CAAC;AACjE,UAAM,KAAK;AAAA,EACb;AACF;AAEA,SAAS,WACP,SAC+C;AAC/C,QAAM,MAAqD,CAAC;AAC5D,UAAQ,QAAQ,CAAC,OAAO,QAAQ;AAC9B,QAAI,GAAG,IAAI;AAAA,EACb,CAAC;AACD,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/receiver/hono/index.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/hono\n *\n * Hono adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import { Hono } from \"hono\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/hono\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = new Hono();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   async (c) => {\n *     const idem = c.get(\"idempotency\") as { key: string; deduped: boolean };\n *     if (idem.deduped) return c.json({ status: \"dedup-skipped\", key: idem.key });\n *     // ... process the inbound event ...\n *     return c.json({ status: \"processed\", key: idem.key });\n *   }\n * );\n * ```\n *\n * On failure: returns `c.json({ error: <reason> }, status)` directly\n * (Hono short-circuits when middleware returns a Response). On\n * success: stashes `c.set(\"idempotency\", { key, deduped })` and\n * continues with `await next()`.\n *\n * **Raw body**: Hono exposes `await c.req.text()` natively, which\n * the middleware reads when `secret` is configured. No extra setup\n * needed.\n */\nimport type { MiddlewareHandler } from \"hono\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Variables this middleware contributes to the Hono context. The\n * generic on the returned {@link MiddlewareHandler} threads it\n * through so route handlers downstream of `app.post(..., webhookMiddleware(...), handler)`\n * see `c.get(\"idempotency\")` typed without a manual cast.\n */\nexport type WebhookVariables = {\n  idempotency: { key: string; deduped: boolean };\n};\n\n/**\n * Build a Hono middleware that verifies the request signature (when\n * `secret` is set), enforces `Idempotency-Key`, and claims the key\n * on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): MiddlewareHandler<{ Variables: WebhookVariables }> {\n  return async function check(c, next) {\n    const headers = headers_bag(c.req.raw.headers);\n    const rawBody = await c.req.text();\n    const result = await checkWebhook(headers, rawBody, options);\n    if (!result.ok) {\n      return c.json({ error: result.reason }, result.status);\n    }\n    c.set(\"idempotency\", { key: result.key, deduped: result.deduped });\n    await next();\n  };\n}\n\nfunction headers_bag(\n  headers: Headers\n): Record<string, string | string[] | undefined> {\n  const out: Record<string, string | string[] | undefined> = {};\n  headers.forEach((value, key) => {\n    out[key] = value;\n  });\n  return out;\n}\n"],"mappings":";;;;;AAuDO,SAAS,kBACd,SACoD;AACpD,SAAO,eAAe,MAAM,GAAG,MAAM;AACnC,UAAM,UAAU,YAAY,EAAE,IAAI,IAAI,OAAO;AAC7C,UAAM,UAAU,MAAM,EAAE,IAAI,KAAK;AACjC,UAAM,SAAS,MAAM,aAAa,SAAS,SAAS,OAAO;AAC3D,QAAI,CAAC,OAAO,IAAI;AACd,aAAO,EAAE,KAAK,EAAE,OAAO,OAAO,OAAO,GAAG,OAAO,MAAM;AAAA,IACvD;AACA,MAAE,IAAI,eAAe,EAAE,KAAK,OAAO,KAAK,SAAS,OAAO,QAAQ,CAAC;AACjE,UAAM,KAAK;AAAA,EACb;AACF;AAEA,SAAS,YACP,SAC+C;AAC/C,QAAM,MAAqD,CAAC;AAC5D,UAAQ,QAAQ,CAAC,OAAO,QAAQ;AAC9B,QAAI,GAAG,IAAI;AAAA,EACb,CAAC;AACD,SAAO;AACT;","names":[]}

package/dist/chunk-Z6FVXDDU.js

@@ -0,0 +1,63 @@
+// src/api/errors.ts
+import {
+  ConcurrencyError,
+  InvariantError,
+  NonRetryableError,
+  StreamClosedError,
+  ValidationError
+} from "@rotorsoft/act";
+var ERROR_MAP = {
+  ValidationError: { status: 422, code: "VALIDATION" },
+  InvariantError: { status: 409, code: "INVARIANT" },
+  ConcurrencyError: { status: 412, code: "CONCURRENCY" },
+  StreamClosedError: { status: 410, code: "STREAM_CLOSED" },
+  NonRetryableError: { status: 400, code: "NON_RETRYABLE" }
+};
+var lookup_known = (err) => {
+  if (err instanceof ValidationError) return { name: "ValidationError" };
+  if (err instanceof InvariantError) return { name: "InvariantError" };
+  if (err instanceof ConcurrencyError) return { name: "ConcurrencyError" };
+  if (err instanceof StreamClosedError) return { name: "StreamClosedError" };
+  if (err instanceof NonRetryableError) return { name: "NonRetryableError" };
+  return null;
+};
+function toApiError(err) {
+  const known = lookup_known(err);
+  if (known) {
+    const entry = ERROR_MAP[known.name];
+    return {
+      status: entry.status,
+      body: {
+        error: known.name,
+        detail: err.message,
+        code: entry.code
+      }
+    };
+  }
+  if (err instanceof Error) {
+    return {
+      status: 500,
+      body: { error: "InternalError", detail: err.message, code: "INTERNAL" }
+    };
+  }
+  return {
+    status: 500,
+    body: { error: "InternalError", code: "INTERNAL" }
+  };
+}
+
+// src/api/idempotency.ts
+async function withIdempotency(store, key, handler) {
+  const fresh = await store.claim(key);
+  if (!fresh) {
+    return { deduped: true };
+  }
+  return { deduped: false, result: await handler() };
+}
+
+export {
+  ERROR_MAP,
+  toApiError,
+  withIdempotency
+};
+//# sourceMappingURL=chunk-Z6FVXDDU.js.map

package/dist/chunk-Z6FVXDDU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api/errors.ts","../src/api/idempotency.ts"],"sourcesContent":["import {\n  ConcurrencyError,\n  InvariantError,\n  NonRetryableError,\n  StreamClosedError,\n  ValidationError,\n} from \"@rotorsoft/act\";\n\n/**\n * Uniform error envelope shipped over the wire by every act-http\n * transport. Hosts get the same shape from REST, tRPC, and OpenAPI —\n * a client that talks to two transports doesn't have to invent two\n * error parsers.\n *\n * - `error` — the framework error name (`\"ValidationError\"`,\n *   `\"InvariantError\"`, …). Stable identifier, safe to switch on.\n * - `detail` — the framework's message text. Human-readable; not\n *   parsed by clients.\n * - `code` — a machine-readable status code from {@link ERROR_MAP}\n *   for clients that prefer enum-style branching over name strings.\n */\nexport type ApiError = {\n  error: string;\n  detail?: string;\n  code?: string;\n};\n\n/**\n * Status + code pair for one known framework error.\n */\nexport type ErrorMapEntry = {\n  status: number;\n  code: string;\n};\n\n/**\n * The single table that maps framework error types to HTTP status\n * codes and machine-readable codes. One table, three consumers\n * (Hono, tRPC, OpenAPI) — cross-transport consistency by\n * construction.\n *\n * Operators wanting different mappings wrap the generated transport\n * rather than mutating this — the consistency is the load-bearing\n * property, not the specific status codes.\n */\nexport const ERROR_MAP = {\n  ValidationError: { status: 422, code: \"VALIDATION\" },\n  InvariantError: { status: 409, code: \"INVARIANT\" },\n  ConcurrencyError: { status: 412, code: \"CONCURRENCY\" },\n  StreamClosedError: { status: 410, code: \"STREAM_CLOSED\" },\n  NonRetryableError: { status: 400, code: \"NON_RETRYABLE\" },\n} as const satisfies Record<string, ErrorMapEntry>;\n\nconst lookup_known = (\n  err: unknown\n): { name: keyof typeof ERROR_MAP } | null => {\n  if (err instanceof ValidationError) return { name: \"ValidationError\" };\n  if (err instanceof InvariantError) return { name: \"InvariantError\" };\n  if (err instanceof ConcurrencyError) return { name: \"ConcurrencyError\" };\n  if (err instanceof StreamClosedError) return { name: \"StreamClosedError\" };\n  if (err instanceof NonRetryableError) return { name: \"NonRetryableError\" };\n  return null;\n};\n\n/**\n * Translate an unknown thrown value into the canonical\n * {@link ApiError} envelope plus HTTP status. Each transport's error\n * boundary calls this once and forwards the result to the wire.\n *\n * Known framework errors map per {@link ERROR_MAP}. Everything else\n * surfaces as a 500 with `code: \"INTERNAL\"`; the `detail` field is\n * populated when the throw was an `Error` instance, omitted\n * otherwise (a thrown string or object doesn't get to leak its\n * payload to the client).\n */\nexport function toApiError(err: unknown): { status: number; body: ApiError } {\n  const known = lookup_known(err);\n  if (known) {\n    const entry = ERROR_MAP[known.name];\n    return {\n      status: entry.status,\n      body: {\n        error: known.name,\n        detail: (err as Error).message,\n        code: entry.code,\n      },\n    };\n  }\n  if (err instanceof Error) {\n    return {\n      status: 500,\n      body: { error: \"InternalError\", detail: err.message, code: \"INTERNAL\" },\n    };\n  }\n  return {\n    status: 500,\n    body: { error: \"InternalError\", code: \"INTERNAL\" },\n  };\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n\n/**\n * Result of a {@link withIdempotency} call.\n *\n * - `{ deduped: false, result }` — the claim was fresh; the handler\n *   ran and produced `result`.\n * - `{ deduped: true }` — the claim was already taken; the handler\n *   was *not* invoked. The caller decides how to respond (typically\n *   a 2xx with no body, matching the receiver-side convention).\n *\n * Note: the contract does not cache the previous response. A\n * duplicate call returns the deduped marker only — replaying the\n * original handler's output would require a response-caching\n * adapter, which is out of scope here. The receiver-side convention\n * (and the convention the generated transports follow) is \"ack the\n * duplicate; do nothing else.\"\n */\nexport type IdempotencyResult<T> =\n  | { deduped: false; result: T }\n  | { deduped: true };\n\n/**\n * Wrap an action handler so the framework honors `Idempotency-Key`\n * dedup. Acquires the key via {@link IdempotencyStore.claim}, runs\n * the handler exactly when the claim was fresh, and skips the\n * handler entirely on a duplicate.\n *\n * Reuses the contract `@rotorsoft/act-ops/idempotency` already\n * defines for the receiver-side `Idempotency-Key` story. A single\n * `IdempotencyStore` implementation covers both halves of the \"Act\n * over the wire\" surface — receiver and generated API.\n */\nexport async function withIdempotency<T>(\n  store: IdempotencyStore,\n  key: string,\n  handler: () => Promise<T>\n): Promise<IdempotencyResult<T>> {\n  const fresh = await store.claim(key);\n  if (!fresh) {\n    return { deduped: true };\n  }\n  return { deduped: false, result: await handler() };\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAuCA,IAAM,YAAY;AAAA,EACvB,iBAAiB,EAAE,QAAQ,KAAK,MAAM,aAAa;AAAA,EACnD,gBAAgB,EAAE,QAAQ,KAAK,MAAM,YAAY;AAAA,EACjD,kBAAkB,EAAE,QAAQ,KAAK,MAAM,cAAc;AAAA,EACrD,mBAAmB,EAAE,QAAQ,KAAK,MAAM,gBAAgB;AAAA,EACxD,mBAAmB,EAAE,QAAQ,KAAK,MAAM,gBAAgB;AAC1D;AAEA,IAAM,eAAe,CACnB,QAC4C;AAC5C,MAAI,eAAe,gBAAiB,QAAO,EAAE,MAAM,kBAAkB;AACrE,MAAI,eAAe,eAAgB,QAAO,EAAE,MAAM,iBAAiB;AACnE,MAAI,eAAe,iBAAkB,QAAO,EAAE,MAAM,mBAAmB;AACvE,MAAI,eAAe,kBAAmB,QAAO,EAAE,MAAM,oBAAoB;AACzE,MAAI,eAAe,kBAAmB,QAAO,EAAE,MAAM,oBAAoB;AACzE,SAAO;AACT;AAaO,SAAS,WAAW,KAAkD;AAC3E,QAAM,QAAQ,aAAa,GAAG;AAC9B,MAAI,OAAO;AACT,UAAM,QAAQ,UAAU,MAAM,IAAI;AAClC,WAAO;AAAA,MACL,QAAQ,MAAM;AAAA,MACd,MAAM;AAAA,QACJ,OAAO,MAAM;AAAA,QACb,QAAS,IAAc;AAAA,QACvB,MAAM,MAAM;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACA,MAAI,eAAe,OAAO;AACxB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,MAAM,EAAE,OAAO,iBAAiB,QAAQ,IAAI,SAAS,MAAM,WAAW;AAAA,IACxE;AAAA,EACF;AACA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,MAAM,EAAE,OAAO,iBAAiB,MAAM,WAAW;AAAA,EACnD;AACF;;;ACjEA,eAAsB,gBACpB,OACA,KACA,SAC+B;AAC/B,QAAM,QAAQ,MAAM,MAAM,MAAM,GAAG;AACnC,MAAI,CAAC,OAAO;AACV,WAAO,EAAE,SAAS,KAAK;AAAA,EACzB;AACA,SAAO,EAAE,SAAS,OAAO,QAAQ,MAAM,QAAQ,EAAE;AACnD;","names":[]}

package/dist/receiver/express/index.cjs

@@ -40,12 +40,12 @@ var import_node_crypto = require("crypto");
 function verifyWebhook(headers, body, secret, options) {
   const maxAgeSeconds = options?.maxAgeSeconds ?? 300;
   const now = options?.now ?? Math.floor(Date.now() / 1e3);
-  const signature = pickHeader(headers, "x-webhook-signature");
+  const signature = pick_header(headers, "x-webhook-signature");
   if (!signature) return { ok: false, reason: "missing-signature" };
-  const timestampStr = pickHeader(headers, "x-webhook-timestamp");
-  if (!timestampStr) return { ok: false, reason: "missing-timestamp" };
-  const timestamp = Number.parseInt(timestampStr, 10);
-  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {
+  const timestamp_str = pick_header(headers, "x-webhook-timestamp");
+  if (!timestamp_str) return { ok: false, reason: "missing-timestamp" };
+  const timestamp = Number.parseInt(timestamp_str, 10);
+  if (Number.isNaN(timestamp) || String(timestamp) !== timestamp_str) {
     return { ok: false, reason: "missing-timestamp" };
   }
   const delta = now - timestamp;
@@ -54,21 +54,21 @@ function verifyWebhook(headers, body, secret, options) {
   if (!signature.startsWith("sha256=")) {
     return { ok: false, reason: "bad-signature" };
   }
-  const providedHex = signature.slice("sha256=".length);
-  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {
+  const provided_hex = signature.slice("sha256=".length);
+  if (!/^[0-9a-fA-F]{64}$/.test(provided_hex)) {
     return { ok: false, reason: "bad-signature" };
   }
-  const expectedHex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestampStr}.${body}`).digest("hex");
-  const a = Buffer.from(providedHex, "hex");
-  const b = Buffer.from(expectedHex, "hex");
+  const expected_hex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp_str}.${body}`).digest("hex");
+  const a = Buffer.from(provided_hex, "hex");
+  const b = Buffer.from(expected_hex, "hex");
   if (!(0, import_node_crypto.timingSafeEqual)(a, b)) {
     return { ok: false, reason: "bad-signature" };
   }
   return { ok: true };
 }
-function pickHeader(headers, lowerName) {
+function pick_header(headers, lower_name) {
   for (const [name, value] of Object.entries(headers)) {
-    if (name.toLowerCase() !== lowerName) continue;
+    if (name.toLowerCase() !== lower_name) continue;
     if (Array.isArray(value) || value === void 0 || value === "") {
       return void 0;
     }
@@ -99,7 +99,7 @@ async function checkWebhook(headers, body, options) {
 // src/receiver/express/index.ts
 function webhookMiddleware(options) {
   return async function check(req, res, next) {
-    const rawBody = bufferOrString(req.body);
+    const rawBody = buffer_or_string(req.body);
     const result = await checkWebhook(
       req.headers,
       rawBody,
@@ -116,7 +116,7 @@ function webhookMiddleware(options) {
     next();
   };
 }
-function bufferOrString(body) {
+function buffer_or_string(body) {
   if (typeof body === "string") return body;
   if (body instanceof Uint8Array) return Buffer.from(body).toString("utf8");
   return "";

package/dist/receiver/express/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/receiver/express/index.ts","../../../src/receiver/extract.ts","../../../src/receiver/verify.ts","../../../src/receiver/check.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/express\n *\n * Express adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import express from \"express\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/express\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = express();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * // Raw body capture required when signing is enabled.\n * app.use(express.raw({ type: \"application/json\" }));\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   (req, res) => {\n *     const { key, deduped } = (req as any).idempotency;\n *     if (deduped) return res.json({ status: \"dedup-skipped\", key });\n *     // ... process the inbound event ...\n *     res.json({ status: \"processed\", key });\n *   }\n * );\n * ```\n *\n * On failure: responds with the framework-idiomatic JSON shape\n * `{ error: <reason> }` at status 400 (missing-key) or 401\n * (verification failures), and does not call `next()`. On success:\n * attaches `req.idempotency = { key, deduped }` and calls `next()`.\n *\n * **Raw body requirement**: when `secret` is configured, mount\n * `express.raw({ type: \"application/json\" })` (or whatever\n * content-type your webhooks use) ahead of the receiver middleware.\n * The middleware reads `req.body` as a `Buffer | string` and converts\n * to a UTF-8 string for hashing. Skip when unsigned.\n */\nimport type { NextFunction, Request, RequestHandler, Response } from \"express\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Build an Express middleware that verifies the request signature\n * (when `secret` is set), enforces `Idempotency-Key`, and claims the\n * key on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): RequestHandler {\n  return async function check(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    const rawBody = bufferOrString(req.body);\n    const result = await checkWebhook(\n      req.headers as Record<string, string | string[] | undefined>,\n      rawBody,\n      options\n    );\n    if (!result.ok) {\n      res.status(result.status).json({ error: result.reason });\n      return;\n    }\n    (\n      req as Request & { idempotency: { key: string; deduped: boolean } }\n    ).idempotency = {\n      key: result.key,\n      deduped: result.deduped,\n    };\n    next();\n  };\n}\n\nfunction bufferOrString(body: unknown): string {\n  if (typeof body === \"string\") return body;\n  if (body instanceof Uint8Array) return Buffer.from(body).toString(\"utf8\");\n  return \"\";\n}\n","/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pickHeader(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestampStr = pickHeader(headers, \"x-webhook-timestamp\");\n  if (!timestampStr) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestampStr, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const providedHex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expectedHex = createHmac(\"sha256\", secret)\n    .update(`${timestampStr}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(providedHex, \"hex\");\n  const b = Buffer.from(expectedHex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pickHeader(\n  headers: Record<string, string | string[] | undefined>,\n  lowerName: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lowerName) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../src/receiver/express/index.ts","../../../src/receiver/extract.ts","../../../src/receiver/verify.ts","../../../src/receiver/check.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/express\n *\n * Express adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import express from \"express\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/express\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = express();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * // Raw body capture required when signing is enabled.\n * app.use(express.raw({ type: \"application/json\" }));\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   (req, res) => {\n *     const { key, deduped } = (req as any).idempotency;\n *     if (deduped) return res.json({ status: \"dedup-skipped\", key });\n *     // ... process the inbound event ...\n *     res.json({ status: \"processed\", key });\n *   }\n * );\n * ```\n *\n * On failure: responds with the framework-idiomatic JSON shape\n * `{ error: <reason> }` at status 400 (missing-key) or 401\n * (verification failures), and does not call `next()`. On success:\n * attaches `req.idempotency = { key, deduped }` and calls `next()`.\n *\n * **Raw body requirement**: when `secret` is configured, mount\n * `express.raw({ type: \"application/json\" })` (or whatever\n * content-type your webhooks use) ahead of the receiver middleware.\n * The middleware reads `req.body` as a `Buffer | string` and converts\n * to a UTF-8 string for hashing. Skip when unsigned.\n */\nimport type { NextFunction, Request, RequestHandler, Response } from \"express\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Build an Express middleware that verifies the request signature\n * (when `secret` is set), enforces `Idempotency-Key`, and claims the\n * key on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): RequestHandler {\n  return async function check(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    const rawBody = buffer_or_string(req.body);\n    const result = await checkWebhook(\n      req.headers as Record<string, string | string[] | undefined>,\n      rawBody,\n      options\n    );\n    if (!result.ok) {\n      res.status(result.status).json({ error: result.reason });\n      return;\n    }\n    (\n      req as Request & { idempotency: { key: string; deduped: boolean } }\n    ).idempotency = {\n      key: result.key,\n      deduped: result.deduped,\n    };\n    next();\n  };\n}\n\nfunction buffer_or_string(body: unknown): string {\n  if (typeof body === \"string\") return body;\n  if (body instanceof Uint8Array) return Buffer.from(body).toString(\"utf8\");\n  return \"\";\n}\n","/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pick_header(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestamp_str = pick_header(headers, \"x-webhook-timestamp\");\n  if (!timestamp_str) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestamp_str, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestamp_str) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const provided_hex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(provided_hex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expected_hex = createHmac(\"sha256\", secret)\n    .update(`${timestamp_str}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(provided_hex, \"hex\");\n  const b = Buffer.from(expected_hex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pick_header(\n  headers: Record<string, string | string[] | undefined>,\n  lower_name: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lower_name) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":"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","names":[]}

package/dist/receiver/express/index.js

@@ -1,11 +1,11 @@
 import {
   checkWebhook
-} from "../../chunk-NOIXOF2I.js";
+} from "../../chunk-4CGAUB5H.js";
 
 // src/receiver/express/index.ts
 function webhookMiddleware(options) {
   return async function check(req, res, next) {
-    const rawBody = bufferOrString(req.body);
+    const rawBody = buffer_or_string(req.body);
     const result = await checkWebhook(
       req.headers,
       rawBody,
@@ -22,7 +22,7 @@ function webhookMiddleware(options) {
     next();
   };
 }
-function bufferOrString(body) {
+function buffer_or_string(body) {
   if (typeof body === "string") return body;
   if (body instanceof Uint8Array) return Buffer.from(body).toString("utf8");
   return "";

package/dist/receiver/express/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/receiver/express/index.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/express\n *\n * Express adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import express from \"express\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/express\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = express();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * // Raw body capture required when signing is enabled.\n * app.use(express.raw({ type: \"application/json\" }));\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   (req, res) => {\n *     const { key, deduped } = (req as any).idempotency;\n *     if (deduped) return res.json({ status: \"dedup-skipped\", key });\n *     // ... process the inbound event ...\n *     res.json({ status: \"processed\", key });\n *   }\n * );\n * ```\n *\n * On failure: responds with the framework-idiomatic JSON shape\n * `{ error: <reason> }` at status 400 (missing-key) or 401\n * (verification failures), and does not call `next()`. On success:\n * attaches `req.idempotency = { key, deduped }` and calls `next()`.\n *\n * **Raw body requirement**: when `secret` is configured, mount\n * `express.raw({ type: \"application/json\" })` (or whatever\n * content-type your webhooks use) ahead of the receiver middleware.\n * The middleware reads `req.body` as a `Buffer | string` and converts\n * to a UTF-8 string for hashing. Skip when unsigned.\n */\nimport type { NextFunction, Request, RequestHandler, Response } from \"express\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Build an Express middleware that verifies the request signature\n * (when `secret` is set), enforces `Idempotency-Key`, and claims the\n * key on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): RequestHandler {\n  return async function check(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    const rawBody = bufferOrString(req.body);\n    const result = await checkWebhook(\n      req.headers as Record<string, string | string[] | undefined>,\n      rawBody,\n      options\n    );\n    if (!result.ok) {\n      res.status(result.status).json({ error: result.reason });\n      return;\n    }\n    (\n      req as Request & { idempotency: { key: string; deduped: boolean } }\n    ).idempotency = {\n      key: result.key,\n      deduped: result.deduped,\n    };\n    next();\n  };\n}\n\nfunction bufferOrString(body: unknown): string {\n  if (typeof body === \"string\") return body;\n  if (body instanceof Uint8Array) return Buffer.from(body).toString(\"utf8\");\n  return \"\";\n}\n"],"mappings":";;;;;AAkDO,SAAS,kBACd,SACgB;AAChB,SAAO,eAAe,MACpB,KACA,KACA,MACe;AACf,UAAM,UAAU,eAAe,IAAI,IAAI;AACvC,UAAM,SAAS,MAAM;AAAA,MACnB,IAAI;AAAA,MACJ;AAAA,MACA;AAAA,IACF;AACA,QAAI,CAAC,OAAO,IAAI;AACd,UAAI,OAAO,OAAO,MAAM,EAAE,KAAK,EAAE,OAAO,OAAO,OAAO,CAAC;AACvD;AAAA,IACF;AACA,IACE,IACA,cAAc;AAAA,MACd,KAAK,OAAO;AAAA,MACZ,SAAS,OAAO;AAAA,IAClB;AACA,SAAK;AAAA,EACP;AACF;AAEA,SAAS,eAAe,MAAuB;AAC7C,MAAI,OAAO,SAAS,SAAU,QAAO;AACrC,MAAI,gBAAgB,WAAY,QAAO,OAAO,KAAK,IAAI,EAAE,SAAS,MAAM;AACxE,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../../src/receiver/express/index.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/express\n *\n * Express adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import express from \"express\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/express\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = express();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * // Raw body capture required when signing is enabled.\n * app.use(express.raw({ type: \"application/json\" }));\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   (req, res) => {\n *     const { key, deduped } = (req as any).idempotency;\n *     if (deduped) return res.json({ status: \"dedup-skipped\", key });\n *     // ... process the inbound event ...\n *     res.json({ status: \"processed\", key });\n *   }\n * );\n * ```\n *\n * On failure: responds with the framework-idiomatic JSON shape\n * `{ error: <reason> }` at status 400 (missing-key) or 401\n * (verification failures), and does not call `next()`. On success:\n * attaches `req.idempotency = { key, deduped }` and calls `next()`.\n *\n * **Raw body requirement**: when `secret` is configured, mount\n * `express.raw({ type: \"application/json\" })` (or whatever\n * content-type your webhooks use) ahead of the receiver middleware.\n * The middleware reads `req.body` as a `Buffer | string` and converts\n * to a UTF-8 string for hashing. Skip when unsigned.\n */\nimport type { NextFunction, Request, RequestHandler, Response } from \"express\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Build an Express middleware that verifies the request signature\n * (when `secret` is set), enforces `Idempotency-Key`, and claims the\n * key on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): RequestHandler {\n  return async function check(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    const rawBody = buffer_or_string(req.body);\n    const result = await checkWebhook(\n      req.headers as Record<string, string | string[] | undefined>,\n      rawBody,\n      options\n    );\n    if (!result.ok) {\n      res.status(result.status).json({ error: result.reason });\n      return;\n    }\n    (\n      req as Request & { idempotency: { key: string; deduped: boolean } }\n    ).idempotency = {\n      key: result.key,\n      deduped: result.deduped,\n    };\n    next();\n  };\n}\n\nfunction buffer_or_string(body: unknown): string {\n  if (typeof body === \"string\") return body;\n  if (body instanceof Uint8Array) return Buffer.from(body).toString(\"utf8\");\n  return \"\";\n}\n"],"mappings":";;;;;AAkDO,SAAS,kBACd,SACgB;AAChB,SAAO,eAAe,MACpB,KACA,KACA,MACe;AACf,UAAM,UAAU,iBAAiB,IAAI,IAAI;AACzC,UAAM,SAAS,MAAM;AAAA,MACnB,IAAI;AAAA,MACJ;AAAA,MACA;AAAA,IACF;AACA,QAAI,CAAC,OAAO,IAAI;AACd,UAAI,OAAO,OAAO,MAAM,EAAE,KAAK,EAAE,OAAO,OAAO,OAAO,CAAC;AACvD;AAAA,IACF;AACA,IACE,IACA,cAAc;AAAA,MACd,KAAK,OAAO;AAAA,MACZ,SAAS,OAAO;AAAA,IAClB;AACA,SAAK;AAAA,EACP;AACF;AAEA,SAAS,iBAAiB,MAAuB;AAC/C,MAAI,OAAO,SAAS,SAAU,QAAO;AACrC,MAAI,gBAAgB,WAAY,QAAO,OAAO,KAAK,IAAI,EAAE,SAAS,MAAM;AACxE,SAAO;AACT;","names":[]}

package/dist/receiver/fastify/index.cjs

@@ -40,12 +40,12 @@ var import_node_crypto = require("crypto");
 function verifyWebhook(headers, body, secret, options) {
   const maxAgeSeconds = options?.maxAgeSeconds ?? 300;
   const now = options?.now ?? Math.floor(Date.now() / 1e3);
-  const signature = pickHeader(headers, "x-webhook-signature");
+  const signature = pick_header(headers, "x-webhook-signature");
   if (!signature) return { ok: false, reason: "missing-signature" };
-  const timestampStr = pickHeader(headers, "x-webhook-timestamp");
-  if (!timestampStr) return { ok: false, reason: "missing-timestamp" };
-  const timestamp = Number.parseInt(timestampStr, 10);
-  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {
+  const timestamp_str = pick_header(headers, "x-webhook-timestamp");
+  if (!timestamp_str) return { ok: false, reason: "missing-timestamp" };
+  const timestamp = Number.parseInt(timestamp_str, 10);
+  if (Number.isNaN(timestamp) || String(timestamp) !== timestamp_str) {
     return { ok: false, reason: "missing-timestamp" };
   }
   const delta = now - timestamp;
@@ -54,21 +54,21 @@ function verifyWebhook(headers, body, secret, options) {
   if (!signature.startsWith("sha256=")) {
     return { ok: false, reason: "bad-signature" };
   }
-  const providedHex = signature.slice("sha256=".length);
-  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {
+  const provided_hex = signature.slice("sha256=".length);
+  if (!/^[0-9a-fA-F]{64}$/.test(provided_hex)) {
     return { ok: false, reason: "bad-signature" };
   }
-  const expectedHex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestampStr}.${body}`).digest("hex");
-  const a = Buffer.from(providedHex, "hex");
-  const b = Buffer.from(expectedHex, "hex");
+  const expected_hex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp_str}.${body}`).digest("hex");
+  const a = Buffer.from(provided_hex, "hex");
+  const b = Buffer.from(expected_hex, "hex");
   if (!(0, import_node_crypto.timingSafeEqual)(a, b)) {
     return { ok: false, reason: "bad-signature" };
   }
   return { ok: true };
 }
-function pickHeader(headers, lowerName) {
+function pick_header(headers, lower_name) {
   for (const [name, value] of Object.entries(headers)) {
-    if (name.toLowerCase() !== lowerName) continue;
+    if (name.toLowerCase() !== lower_name) continue;
     if (Array.isArray(value) || value === void 0 || value === "") {
       return void 0;
     }

package/dist/receiver/fastify/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/receiver/fastify/index.ts","../../../src/receiver/extract.ts","../../../src/receiver/verify.ts","../../../src/receiver/check.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/fastify\n *\n * Fastify adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import Fastify from \"fastify\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/fastify\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = Fastify();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   {\n *     preHandler: webhookMiddleware({\n *       store: dedup,\n *       secret: process.env.WEBHOOK_SECRET,\n *     }),\n *   },\n *   async (request, reply) => {\n *     const { key, deduped } = (request as any).idempotency;\n *     if (deduped) return { status: \"dedup-skipped\", key };\n *     // ... process the inbound event ...\n *     return { status: \"processed\", key };\n *   }\n * );\n * ```\n *\n * On failure: replies with `{ error: <reason> }` at status 400\n * (missing-key) or 401 (verification failures). On success: attaches\n * `request.idempotency = { key, deduped }` and lets the route handler\n * run.\n *\n * **Raw body requirement**: when `secret` is configured, register a\n * content-type parser that preserves the raw body string. Fastify's\n * default JSON parser eats the bytes — register a custom parser via\n * `app.addContentTypeParser(\"application/json\", { parseAs: \"string\" }, …)`\n * and stash the string on `request.rawBody` (Fastify pattern). The\n * middleware reads `request.rawBody` for hashing. Skip when unsigned.\n */\nimport type { FastifyReply, FastifyRequest } from \"fastify\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\ntype WebhookRequest = FastifyRequest & {\n  rawBody?: string;\n  idempotency?: { key: string; deduped: boolean };\n};\n\n/**\n * Build a Fastify `preHandler` hook that verifies the request\n * signature (when `secret` is set), enforces `Idempotency-Key`, and\n * claims the key on the configured store. See the module-level docs\n * for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {\n  return async function check(\n    request: FastifyRequest,\n    reply: FastifyReply\n  ): Promise<void> {\n    const req = request as WebhookRequest;\n    const rawBody = req.rawBody ?? \"\";\n    const result = await checkWebhook(\n      req.headers as Record<string, string | string[] | undefined>,\n      rawBody,\n      options\n    );\n    if (!result.ok) {\n      await reply.status(result.status).send({ error: result.reason });\n      return;\n    }\n    req.idempotency = { key: result.key, deduped: result.deduped };\n  };\n}\n","/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pickHeader(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestampStr = pickHeader(headers, \"x-webhook-timestamp\");\n  if (!timestampStr) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestampStr, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const providedHex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expectedHex = createHmac(\"sha256\", secret)\n    .update(`${timestampStr}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(providedHex, \"hex\");\n  const b = Buffer.from(expectedHex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pickHeader(\n  headers: Record<string, string | string[] | undefined>,\n  lowerName: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lowerName) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../src/receiver/fastify/index.ts","../../../src/receiver/extract.ts","../../../src/receiver/verify.ts","../../../src/receiver/check.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/fastify\n *\n * Fastify adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import Fastify from \"fastify\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/fastify\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = Fastify();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   {\n *     preHandler: webhookMiddleware({\n *       store: dedup,\n *       secret: process.env.WEBHOOK_SECRET,\n *     }),\n *   },\n *   async (request, reply) => {\n *     const { key, deduped } = (request as any).idempotency;\n *     if (deduped) return { status: \"dedup-skipped\", key };\n *     // ... process the inbound event ...\n *     return { status: \"processed\", key };\n *   }\n * );\n * ```\n *\n * On failure: replies with `{ error: <reason> }` at status 400\n * (missing-key) or 401 (verification failures). On success: attaches\n * `request.idempotency = { key, deduped }` and lets the route handler\n * run.\n *\n * **Raw body requirement**: when `secret` is configured, register a\n * content-type parser that preserves the raw body string. Fastify's\n * default JSON parser eats the bytes — register a custom parser via\n * `app.addContentTypeParser(\"application/json\", { parseAs: \"string\" }, …)`\n * and stash the string on `request.rawBody` (Fastify pattern). The\n * middleware reads `request.rawBody` for hashing. Skip when unsigned.\n */\nimport type { FastifyReply, FastifyRequest } from \"fastify\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\ntype WebhookRequest = FastifyRequest & {\n  rawBody?: string;\n  idempotency?: { key: string; deduped: boolean };\n};\n\n/**\n * Build a Fastify `preHandler` hook that verifies the request\n * signature (when `secret` is set), enforces `Idempotency-Key`, and\n * claims the key on the configured store. See the module-level docs\n * for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {\n  return async function check(\n    request: FastifyRequest,\n    reply: FastifyReply\n  ): Promise<void> {\n    const req = request as WebhookRequest;\n    const rawBody = req.rawBody ?? \"\";\n    const result = await checkWebhook(\n      req.headers as Record<string, string | string[] | undefined>,\n      rawBody,\n      options\n    );\n    if (!result.ok) {\n      await reply.status(result.status).send({ error: result.reason });\n      return;\n    }\n    req.idempotency = { key: result.key, deduped: result.deduped };\n  };\n}\n","/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pick_header(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestamp_str = pick_header(headers, \"x-webhook-timestamp\");\n  if (!timestamp_str) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestamp_str, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestamp_str) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const provided_hex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(provided_hex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expected_hex = createHmac(\"sha256\", secret)\n    .update(`${timestamp_str}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(provided_hex, \"hex\");\n  const b = Buffer.from(expected_hex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pick_header(\n  headers: Record<string, string | string[] | undefined>,\n  lower_name: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lower_name) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":"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","names":[]}

package/dist/receiver/fastify/index.js

@@ -1,6 +1,6 @@
 import {
   checkWebhook
-} from "../../chunk-NOIXOF2I.js";
+} from "../../chunk-4CGAUB5H.js";
 
 // src/receiver/fastify/index.ts
 function webhookMiddleware(options) {

package/dist/receiver/hono/index.cjs

@@ -40,12 +40,12 @@ var import_node_crypto = require("crypto");
 function verifyWebhook(headers, body, secret, options) {
   const maxAgeSeconds = options?.maxAgeSeconds ?? 300;
   const now = options?.now ?? Math.floor(Date.now() / 1e3);
-  const signature = pickHeader(headers, "x-webhook-signature");
+  const signature = pick_header(headers, "x-webhook-signature");
   if (!signature) return { ok: false, reason: "missing-signature" };
-  const timestampStr = pickHeader(headers, "x-webhook-timestamp");
-  if (!timestampStr) return { ok: false, reason: "missing-timestamp" };
-  const timestamp = Number.parseInt(timestampStr, 10);
-  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {
+  const timestamp_str = pick_header(headers, "x-webhook-timestamp");
+  if (!timestamp_str) return { ok: false, reason: "missing-timestamp" };
+  const timestamp = Number.parseInt(timestamp_str, 10);
+  if (Number.isNaN(timestamp) || String(timestamp) !== timestamp_str) {
     return { ok: false, reason: "missing-timestamp" };
   }
   const delta = now - timestamp;
@@ -54,21 +54,21 @@ function verifyWebhook(headers, body, secret, options) {
   if (!signature.startsWith("sha256=")) {
     return { ok: false, reason: "bad-signature" };
   }
-  const providedHex = signature.slice("sha256=".length);
-  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {
+  const provided_hex = signature.slice("sha256=".length);
+  if (!/^[0-9a-fA-F]{64}$/.test(provided_hex)) {
     return { ok: false, reason: "bad-signature" };
   }
-  const expectedHex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestampStr}.${body}`).digest("hex");
-  const a = Buffer.from(providedHex, "hex");
-  const b = Buffer.from(expectedHex, "hex");
+  const expected_hex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp_str}.${body}`).digest("hex");
+  const a = Buffer.from(provided_hex, "hex");
+  const b = Buffer.from(expected_hex, "hex");
   if (!(0, import_node_crypto.timingSafeEqual)(a, b)) {
     return { ok: false, reason: "bad-signature" };
   }
   return { ok: true };
 }
-function pickHeader(headers, lowerName) {
+function pick_header(headers, lower_name) {
   for (const [name, value] of Object.entries(headers)) {
-    if (name.toLowerCase() !== lowerName) continue;
+    if (name.toLowerCase() !== lower_name) continue;
     if (Array.isArray(value) || value === void 0 || value === "") {
       return void 0;
     }
@@ -99,7 +99,7 @@ async function checkWebhook(headers, body, options) {
 // src/receiver/hono/index.ts
 function webhookMiddleware(options) {
   return async function check(c, next) {
-    const headers = headersBag(c.req.raw.headers);
+    const headers = headers_bag(c.req.raw.headers);
     const rawBody = await c.req.text();
     const result = await checkWebhook(headers, rawBody, options);
     if (!result.ok) {
@@ -109,7 +109,7 @@ function webhookMiddleware(options) {
     await next();
   };
 }
-function headersBag(headers) {
+function headers_bag(headers) {
   const out = {};
   headers.forEach((value, key) => {
     out[key] = value;

package/dist/receiver/hono/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/receiver/hono/index.ts","../../../src/receiver/extract.ts","../../../src/receiver/verify.ts","../../../src/receiver/check.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/hono\n *\n * Hono adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import { Hono } from \"hono\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/hono\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = new Hono();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   async (c) => {\n *     const idem = c.get(\"idempotency\") as { key: string; deduped: boolean };\n *     if (idem.deduped) return c.json({ status: \"dedup-skipped\", key: idem.key });\n *     // ... process the inbound event ...\n *     return c.json({ status: \"processed\", key: idem.key });\n *   }\n * );\n * ```\n *\n * On failure: returns `c.json({ error: <reason> }, status)` directly\n * (Hono short-circuits when middleware returns a Response). On\n * success: stashes `c.set(\"idempotency\", { key, deduped })` and\n * continues with `await next()`.\n *\n * **Raw body**: Hono exposes `await c.req.text()` natively, which\n * the middleware reads when `secret` is configured. No extra setup\n * needed.\n */\nimport type { MiddlewareHandler } from \"hono\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Variables this middleware contributes to the Hono context. The\n * generic on the returned {@link MiddlewareHandler} threads it\n * through so route handlers downstream of `app.post(..., webhookMiddleware(...), handler)`\n * see `c.get(\"idempotency\")` typed without a manual cast.\n */\nexport type WebhookVariables = {\n  idempotency: { key: string; deduped: boolean };\n};\n\n/**\n * Build a Hono middleware that verifies the request signature (when\n * `secret` is set), enforces `Idempotency-Key`, and claims the key\n * on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): MiddlewareHandler<{ Variables: WebhookVariables }> {\n  return async function check(c, next) {\n    const headers = headersBag(c.req.raw.headers);\n    const rawBody = await c.req.text();\n    const result = await checkWebhook(headers, rawBody, options);\n    if (!result.ok) {\n      return c.json({ error: result.reason }, result.status);\n    }\n    c.set(\"idempotency\", { key: result.key, deduped: result.deduped });\n    await next();\n  };\n}\n\nfunction headersBag(\n  headers: Headers\n): Record<string, string | string[] | undefined> {\n  const out: Record<string, string | string[] | undefined> = {};\n  headers.forEach((value, key) => {\n    out[key] = value;\n  });\n  return out;\n}\n","/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pickHeader(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestampStr = pickHeader(headers, \"x-webhook-timestamp\");\n  if (!timestampStr) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestampStr, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const providedHex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expectedHex = createHmac(\"sha256\", secret)\n    .update(`${timestampStr}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(providedHex, \"hex\");\n  const b = Buffer.from(expectedHex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pickHeader(\n  headers: Record<string, string | string[] | undefined>,\n  lowerName: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lowerName) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../src/receiver/hono/index.ts","../../../src/receiver/extract.ts","../../../src/receiver/verify.ts","../../../src/receiver/check.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/receiver/hono\n *\n * Hono adapter for the receiver-side webhook check.\n *\n * Usage:\n *\n * ```ts\n * import { Hono } from \"hono\";\n * import { webhookMiddleware } from \"@rotorsoft/act-http/receiver/hono\";\n * import { InMemoryIdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n *\n * const app = new Hono();\n * const dedup = new InMemoryIdempotencyStore();\n *\n * app.post(\n *   \"/webhooks/orders\",\n *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),\n *   async (c) => {\n *     const idem = c.get(\"idempotency\") as { key: string; deduped: boolean };\n *     if (idem.deduped) return c.json({ status: \"dedup-skipped\", key: idem.key });\n *     // ... process the inbound event ...\n *     return c.json({ status: \"processed\", key: idem.key });\n *   }\n * );\n * ```\n *\n * On failure: returns `c.json({ error: <reason> }, status)` directly\n * (Hono short-circuits when middleware returns a Response). On\n * success: stashes `c.set(\"idempotency\", { key, deduped })` and\n * continues with `await next()`.\n *\n * **Raw body**: Hono exposes `await c.req.text()` natively, which\n * the middleware reads when `secret` is configured. No extra setup\n * needed.\n */\nimport type { MiddlewareHandler } from \"hono\";\nimport { type CheckWebhookOptions, checkWebhook } from \"../check.js\";\n\n/**\n * Variables this middleware contributes to the Hono context. The\n * generic on the returned {@link MiddlewareHandler} threads it\n * through so route handlers downstream of `app.post(..., webhookMiddleware(...), handler)`\n * see `c.get(\"idempotency\")` typed without a manual cast.\n */\nexport type WebhookVariables = {\n  idempotency: { key: string; deduped: boolean };\n};\n\n/**\n * Build a Hono middleware that verifies the request signature (when\n * `secret` is set), enforces `Idempotency-Key`, and claims the key\n * on the configured store. See the module-level docs for usage.\n */\nexport function webhookMiddleware(\n  options: CheckWebhookOptions\n): MiddlewareHandler<{ Variables: WebhookVariables }> {\n  return async function check(c, next) {\n    const headers = headers_bag(c.req.raw.headers);\n    const rawBody = await c.req.text();\n    const result = await checkWebhook(headers, rawBody, options);\n    if (!result.ok) {\n      return c.json({ error: result.reason }, result.status);\n    }\n    c.set(\"idempotency\", { key: result.key, deduped: result.deduped });\n    await next();\n  };\n}\n\nfunction headers_bag(\n  headers: Headers\n): Record<string, string | string[] | undefined> {\n  const out: Record<string, string | string[] | undefined> = {};\n  headers.forEach((value, key) => {\n    out[key] = value;\n  });\n  return out;\n}\n","/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pick_header(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestamp_str = pick_header(headers, \"x-webhook-timestamp\");\n  if (!timestamp_str) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestamp_str, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestamp_str) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const provided_hex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(provided_hex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expected_hex = createHmac(\"sha256\", secret)\n    .update(`${timestamp_str}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(provided_hex, \"hex\");\n  const b = Buffer.from(expected_hex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pick_header(\n  headers: Record<string, string | string[] | undefined>,\n  lower_name: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lower_name) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":"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","names":[]}

package/dist/receiver/hono/index.js

@@ -1,7 +1,7 @@
 import {
   webhookMiddleware
-} from "../../chunk-F7VWYZ37.js";
-import "../../chunk-NOIXOF2I.js";
+} from "../../chunk-K4HAOBRF.js";
+import "../../chunk-4CGAUB5H.js";
 export {
   webhookMiddleware
 };