@rotorsoft/act-http 1.0.0 → 1.1.0

package/dist/@types/receiver/check.d.ts

@@ -0,0 +1,66 @@
+import type { IdempotencyStore } from "@rotorsoft/act-ops/idempotency";
+import { type VerifyOptions } from "./verify.js";
+/**
+ * Failure reasons returned by {@link checkWebhook}. The shape splits
+ * `missing-key` (a client error, mapped to HTTP 400) from the five
+ * verification failures (authentication errors, HTTP 401) so each
+ * maps to its own telemetry bucket.
+ */
+export type CheckFailureReason = "missing-key" | "missing-signature" | "missing-timestamp" | "stale" | "future" | "bad-signature";
+/**
+ * Outcome of {@link checkWebhook}. Either the request passed every
+ * configured check and carries a usable idempotency key, or it
+ * failed one of them and the framework adapter should reply with the
+ * corresponding HTTP status.
+ */
+export type CheckResult = {
+    ok: false;
+    status: 400 | 401;
+    reason: CheckFailureReason;
+} | {
+    ok: true;
+    key: string;
+    deduped: boolean;
+};
+/** Options for {@link checkWebhook}. */
+export type CheckWebhookOptions = {
+    /** Idempotency store the framework-agnostic core claims the key on. */
+    store: IdempotencyStore;
+    /**
+     * Optional HMAC-SHA256 secret. When set, the request's
+     * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are
+     * verified before the dedup claim. When omitted, signature
+     * verification is skipped (unsigned receivers).
+     */
+    secret?: string;
+    /**
+     * Verification options forwarded to {@link verifyWebhook}. Only
+     * meaningful when `secret` is set. Defaults to a ±300-second
+     * timestamp window.
+     */
+    verify?: VerifyOptions;
+};
+/**
+ * Framework-agnostic receiver check: verify the signature (when a
+ * secret is configured), extract the `Idempotency-Key`, and claim
+ * it on the store. Returns the request's fate as a discriminated
+ * union the per-framework adapter translates into the framework's
+ * idiomatic 4xx response or context injection.
+ *
+ * **Order of checks** (matters):
+ *
+ * 1. Verify signature + timestamp window (when `secret` is set).
+ *    Rejecting bad signatures *before* extracting and claiming the
+ *    key keeps attacker-supplied keys out of the dedup store —
+ *    otherwise a flood of spoofed POSTs would pollute the LRU.
+ * 2. Extract the `Idempotency-Key`. Missing → reject with 400.
+ * 3. Claim the key on the store. If already seen, return
+ *    `{ ok: true; deduped: true }` so the framework adapter can
+ *    short-circuit the handler without re-running side effects.
+ *
+ * The dedup store may be sync (`InMemoryIdempotencyStore`) or async
+ * (durable adapters like a future `PostgresIdempotencyStore`); the
+ * core awaits unconditionally so both shapes compose cleanly.
+ */
+export declare function checkWebhook(headers: Record<string, string | string[] | undefined>, body: string, options: CheckWebhookOptions): Promise<CheckResult>;
+//# sourceMappingURL=check.d.ts.map

package/dist/@types/receiver/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/receiver/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,aAAa,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,mBAAmB,GACnB,mBAAmB,GACnB,OAAO,GACP,QAAQ,GACR,eAAe,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC5D;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,wCAAwC;AACxC,MAAM,MAAM,mBAAmB,GAAG;IAChC,uEAAuE;IACvE,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAkBtB"}

package/dist/@types/receiver/express/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @packageDocumentation
+ * @module act-http/receiver/express
+ *
+ * Express adapter for the receiver-side webhook check.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import express from "express";
+ * import { webhookMiddleware } from "@rotorsoft/act-http/receiver/express";
+ * import { InMemoryIdempotencyStore } from "@rotorsoft/act-ops/idempotency";
+ *
+ * const app = express();
+ * const dedup = new InMemoryIdempotencyStore();
+ *
+ * // Raw body capture required when signing is enabled.
+ * app.use(express.raw({ type: "application/json" }));
+ *
+ * app.post(
+ *   "/webhooks/orders",
+ *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),
+ *   (req, res) => {
+ *     const { key, deduped } = (req as any).idempotency;
+ *     if (deduped) return res.json({ status: "dedup-skipped", key });
+ *     // ... process the inbound event ...
+ *     res.json({ status: "processed", key });
+ *   }
+ * );
+ * ```
+ *
+ * On failure: responds with the framework-idiomatic JSON shape
+ * `{ error: <reason> }` at status 400 (missing-key) or 401
+ * (verification failures), and does not call `next()`. On success:
+ * attaches `req.idempotency = { key, deduped }` and calls `next()`.
+ *
+ * **Raw body requirement**: when `secret` is configured, mount
+ * `express.raw({ type: "application/json" })` (or whatever
+ * content-type your webhooks use) ahead of the receiver middleware.
+ * The middleware reads `req.body` as a `Buffer | string` and converts
+ * to a UTF-8 string for hashing. Skip when unsigned.
+ */
+import type { RequestHandler } from "express";
+import { type CheckWebhookOptions } from "../check.js";
+/**
+ * Build an Express middleware that verifies the request signature
+ * (when `secret` is set), enforces `Idempotency-Key`, and claims the
+ * key on the configured store. See the module-level docs for usage.
+ */
+export declare function webhookMiddleware(options: CheckWebhookOptions): RequestHandler;
+//# sourceMappingURL=index.d.ts.map

package/dist/@types/receiver/express/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/receiver/express/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,aAAa,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,GAC3B,cAAc,CAwBhB"}

package/dist/@types/receiver/extract.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pull the `Idempotency-Key` header from a Node-style headers bag,
+ * case-insensitive. Returns `undefined` when any of the following
+ * carries no usable key:
+ *
+ * - the header is missing
+ * - its value is an array (ambiguous — can't pick one without a
+ *   policy the receiver hasn't declared)
+ * - its value is the empty string (carries no idempotency
+ *   information; structurally equivalent to "no header at all")
+ *
+ * Pair with `IdempotencyStore.claim` from
+ * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound
+ * request, claim it on the store, return a `deduped` marker when the
+ * claim fails. The framework-agnostic middleware that wires these
+ * together lands in #744.
+ *
+ * Validation beyond "is there a usable key?" (length bounds, format
+ * checks, normalization) is intentionally out of scope. Receivers
+ * picking a policy can layer it on top — or, when #744 ships, opt
+ * into the middleware's opinionated defaults.
+ */
+export declare function extractIdempotencyKey(headers: Record<string, string | string[] | undefined>): string | undefined;
+//# sourceMappingURL=extract.d.ts.map

package/dist/@types/receiver/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../../src/receiver/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,MAAM,GAAG,SAAS,CAQpB"}

package/dist/@types/receiver/fastify/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @packageDocumentation
+ * @module act-http/receiver/fastify
+ *
+ * Fastify adapter for the receiver-side webhook check.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import Fastify from "fastify";
+ * import { webhookMiddleware } from "@rotorsoft/act-http/receiver/fastify";
+ * import { InMemoryIdempotencyStore } from "@rotorsoft/act-ops/idempotency";
+ *
+ * const app = Fastify();
+ * const dedup = new InMemoryIdempotencyStore();
+ *
+ * app.post(
+ *   "/webhooks/orders",
+ *   {
+ *     preHandler: webhookMiddleware({
+ *       store: dedup,
+ *       secret: process.env.WEBHOOK_SECRET,
+ *     }),
+ *   },
+ *   async (request, reply) => {
+ *     const { key, deduped } = (request as any).idempotency;
+ *     if (deduped) return { status: "dedup-skipped", key };
+ *     // ... process the inbound event ...
+ *     return { status: "processed", key };
+ *   }
+ * );
+ * ```
+ *
+ * On failure: replies with `{ error: <reason> }` at status 400
+ * (missing-key) or 401 (verification failures). On success: attaches
+ * `request.idempotency = { key, deduped }` and lets the route handler
+ * run.
+ *
+ * **Raw body requirement**: when `secret` is configured, register a
+ * content-type parser that preserves the raw body string. Fastify's
+ * default JSON parser eats the bytes — register a custom parser via
+ * `app.addContentTypeParser("application/json", { parseAs: "string" }, …)`
+ * and stash the string on `request.rawBody` (Fastify pattern). The
+ * middleware reads `request.rawBody` for hashing. Skip when unsigned.
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { type CheckWebhookOptions } from "../check.js";
+/**
+ * Build a Fastify `preHandler` hook that verifies the request
+ * signature (when `secret` is set), enforces `Idempotency-Key`, and
+ * claims the key on the configured store. See the module-level docs
+ * for usage.
+ */
+export declare function webhookMiddleware(options: CheckWebhookOptions): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/@types/receiver/fastify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/receiver/fastify/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,aAAa,CAAC;AAOrE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,GAC3B,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAkBjE"}

package/dist/@types/receiver/hono/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @packageDocumentation
+ * @module act-http/receiver/hono
+ *
+ * Hono adapter for the receiver-side webhook check.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { Hono } from "hono";
+ * import { webhookMiddleware } from "@rotorsoft/act-http/receiver/hono";
+ * import { InMemoryIdempotencyStore } from "@rotorsoft/act-ops/idempotency";
+ *
+ * const app = new Hono();
+ * const dedup = new InMemoryIdempotencyStore();
+ *
+ * app.post(
+ *   "/webhooks/orders",
+ *   webhookMiddleware({ store: dedup, secret: process.env.WEBHOOK_SECRET }),
+ *   async (c) => {
+ *     const idem = c.get("idempotency") as { key: string; deduped: boolean };
+ *     if (idem.deduped) return c.json({ status: "dedup-skipped", key: idem.key });
+ *     // ... process the inbound event ...
+ *     return c.json({ status: "processed", key: idem.key });
+ *   }
+ * );
+ * ```
+ *
+ * On failure: returns `c.json({ error: <reason> }, status)` directly
+ * (Hono short-circuits when middleware returns a Response). On
+ * success: stashes `c.set("idempotency", { key, deduped })` and
+ * continues with `await next()`.
+ *
+ * **Raw body**: Hono exposes `await c.req.text()` natively, which
+ * the middleware reads when `secret` is configured. No extra setup
+ * needed.
+ */
+import type { MiddlewareHandler } from "hono";
+import { type CheckWebhookOptions } from "../check.js";
+/**
+ * Variables this middleware contributes to the Hono context. The
+ * generic on the returned {@link MiddlewareHandler} threads it
+ * through so route handlers downstream of `app.post(..., webhookMiddleware(...), handler)`
+ * see `c.get("idempotency")` typed without a manual cast.
+ */
+export type WebhookVariables = {
+    idempotency: {
+        key: string;
+        deduped: boolean;
+    };
+};
+/**
+ * Build a Hono middleware that verifies the request signature (when
+ * `secret` is set), enforces `Idempotency-Key`, and claims the key
+ * on the configured store. See the module-level docs for usage.
+ */
+export declare function webhookMiddleware(options: CheckWebhookOptions): MiddlewareHandler<{
+    Variables: WebhookVariables;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/@types/receiver/hono/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/receiver/hono/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,aAAa,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAChD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,GAC3B,iBAAiB,CAAC;IAAE,SAAS,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAWpD"}

package/dist/@types/receiver/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @packageDocumentation
+ * @module act-http/receiver
+ *
+ * Server-side helpers for the inbound HTTP role — the receiver that
+ * sits on the other end of an `@rotorsoft/act-http/webhook` POST.
+ *
+ * The subpath hosts two primitives today:
+ *
+ * - {@link extractIdempotencyKey} — case-insensitive
+ *   `Idempotency-Key` parser; pair with `IdempotencyStore.claim`
+ *   from `@rotorsoft/act-ops/idempotency` for dedup.
+ * - {@link verifyWebhook} — HMAC-SHA256 signature + timestamp
+ *   verifier; pair with `webhook({ secret })` from
+ *   `@rotorsoft/act-http/webhook` for authenticated, replay-resistant
+ *   delivery.
+ *
+ * The framework-agnostic middleware that wires these into request
+ * handlers, plus per-framework adapters (tRPC / Express / Fastify /
+ * Hono), lands in #744 (ACT-1116).
+ *
+ * Sibling subpaths in the same package:
+ *
+ * - `@rotorsoft/act-http/webhook` — the sender side: outbound POSTs,
+ *   automatic `Idempotency-Key`, status-classified retries, optional
+ *   HMAC signing.
+ * - `@rotorsoft/act-http/sse` — incremental state broadcast over
+ *   Server-Sent Events.
+ *
+ * The receiver subpath ships from the same package as `/webhook` so
+ * a service that both sends and receives webhooks installs one
+ * dependency. The dedup contract that links them lives in
+ * `@rotorsoft/act-ops/idempotency`.
+ */
+export { type CheckFailureReason, type CheckResult, type CheckWebhookOptions, checkWebhook, } from "./check.js";
+export { extractIdempotencyKey } from "./extract.js";
+export { receiver } from "./start.js";
+export { type VerifyOptions, type VerifyResult, verifyWebhook, } from "./verify.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/@types/receiver/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/receiver/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/@types/receiver/start.d.ts

@@ -0,0 +1,48 @@
+import type { ReceiverBuilder, ReceiverOptions } from "@rotorsoft/act-ops/receiver";
+/**
+ * Recommended factory for "I want to receive webhooks." Returns a
+ * {@link ReceiverBuilder} the operator configures fluently:
+ *
+ * ```ts
+ * import { receiver } from "@rotorsoft/act-http/receiver";
+ * import { InMemoryIdempotencyStore } from "@rotorsoft/act-ops/idempotency";
+ * import { z } from "zod";
+ *
+ * const r = receiver({
+ *   port: 4001,
+ *   store: new InMemoryIdempotencyStore(),
+ *   secret: process.env.WEBHOOK_SECRET,
+ * })
+ *   .on("OrderConfirmed", z.object({
+ *     orderId: z.string(),
+ *     total: z.number(),
+ *   }), async (event, ctx) => {
+ *     // event.orderId and event.total are typed
+ *     // ctx.key is the deduplicated Idempotency-Key
+ *     await processOrder(event.orderId, event.total);
+ *   })
+ *   .build();
+ *
+ * await r.listen();
+ * ```
+ *
+ * Matches Act's builder pattern: `receiver(...)` is the factory,
+ * `.on()` registers handlers fluently, `.build()` finalizes and
+ * produces an immutable {@link Receiver} — at which point the type
+ * loses `.on()` and gains the runtime methods (`listen` / `close` /
+ * `fetch`). The lifecycle phases are split at the type level.
+ *
+ * Internally uses Hono for routing — the universal-runtime choice
+ * that gives one code path coverage across Node, AWS Lambda,
+ * Cloudflare Workers, Vercel Edge, Bun, and Deno. For operators
+ * with an existing tRPC / Express / Fastify / Hono app who need to
+ * compose the receiver with their own middleware stack, the
+ * lower-level `webhookMiddleware` from
+ * `@rotorsoft/act-http/receiver/<framework>` is the escape hatch.
+ *
+ * `@hono/node-server` is imported lazily inside `.listen()` so
+ * Lambda / edge consumers (who never call `.listen()`) don't need
+ * it installed.
+ */
+export declare function receiver(options: ReceiverOptions): ReceiverBuilder;
+//# sourceMappingURL=start.d.ts.map

package/dist/@types/receiver/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/receiver/start.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,eAAe,EAEf,eAAe,EAEhB,MAAM,6BAA6B,CAAC;AAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CA2FlE"}

package/dist/@types/receiver/trpc/index.d.ts

@@ -0,0 +1,16 @@
+import { type CheckWebhookOptions } from "../check.js";
+/**
+ * Build a tRPC middleware that verifies the request signature (when
+ * `secret` is set), enforces `Idempotency-Key`, and claims the key on
+ * the configured store. See the module-level docs for usage.
+ *
+ * The returned function uses permissive `any` typing because tRPC's
+ * `MiddlewareFunction` type lives in `unstable-core-do-not-import`
+ * (internal namespace, not for external import). Type-safety at the
+ * call site comes from `t.procedure.use(...)` validating the
+ * middleware shape against the procedure's context — the operator's
+ * tRPC context must include `headers` and `rawBody`, and downstream
+ * handlers see `ctx.idempotency = { key, deduped }`.
+ */
+export declare function webhookMiddleware(options: CheckWebhookOptions): any;
+//# sourceMappingURL=index.d.ts.map

package/dist/@types/receiver/trpc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/receiver/trpc/index.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;GAYG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,GAAG,CA2BnE"}

package/dist/@types/receiver/verify.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Outcome of {@link verifyWebhook}. Either the request signature
+ * checks out, or one of five distinct failure reasons applies. Each
+ * reason maps to an operator-meaningful telemetry bucket — separated
+ * deliberately so dashboards can distinguish "client lost its secret"
+ * from "client clock is wrong" from "this is a replay attack."
+ */
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "missing-signature" | "missing-timestamp" | "stale" | "future" | "bad-signature";
+};
+/** Options for {@link verifyWebhook}. */
+export type VerifyOptions = {
+    /**
+     * Maximum acceptable timestamp drift in either direction, in
+     * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /
+     * Slack conventions. Tightening narrows the replay window;
+     * loosening accommodates clients with worse clock sync.
+     */
+    maxAgeSeconds?: number;
+    /**
+     * Current Unix-seconds time. Exposed for tests; production
+     * callers should leave it undefined so wall-clock is used.
+     */
+    now?: number;
+};
+/**
+ * Verify an inbound webhook's signature and timestamp against the
+ * shared secret. Pair with the sender side: configure
+ * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.
+ *
+ * Returns `{ ok: true }` on success or `{ ok: false; reason }` on
+ * failure. The reasons are:
+ *
+ * - `missing-signature` — no `X-Webhook-Signature` header, value
+ *   was an array, or value was empty.
+ * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value
+ *   was empty, or value isn't a parseable integer.
+ * - `stale` — timestamp older than `maxAgeSeconds` from `now`.
+ * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.
+ * - `bad-signature` — signature header didn't start with `sha256=`,
+ *   wasn't 64 hex chars, or the recomputed HMAC didn't match
+ *   (constant-time compare).
+ *
+ * The signed payload is `${timestamp}.${body}`, so `body` must be
+ * the **raw request body bytes**. Any pre-parse normalization
+ * (whitespace trimming, JSON re-stringification) would change the
+ * hash and reject every otherwise-valid request. Framework adapters
+ * in #744 will provide the raw body alongside the parsed one.
+ *
+ * Uses Node's `crypto.timingSafeEqual` for the final comparison to
+ * avoid signature-equality timing attacks.
+ */
+export declare function verifyWebhook(headers: Record<string, string | string[] | undefined>, body: string, secret: string, options?: VerifyOptions): VerifyResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/@types/receiver/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/receiver/verify.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACF,mBAAmB,GACnB,mBAAmB,GACnB,OAAO,GACP,QAAQ,GACR,eAAe,CAAC;CACrB,CAAC;AAEN,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CAqCd"}

package/dist/@types/webhook/classify.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Three buckets for an HTTP response from an outbound delivery:
+ *
+ * - `ok` — the receiver accepted the delivery (2xx). Stop and return.
+ * - `retry` — the receiver had a transient problem (5xx). Throw a
+ *   retryable error; drain will pace the next attempt per `backoff`.
+ * - `block` — the receiver rejected the delivery permanently (3xx
+ *   or 4xx). Throw a non-retryable error; drain blocks the stream
+ *   on the first failed attempt (when `blockOnError` is true) and
+ *   surfaces it via the `"blocked"` lifecycle event.
+ *
+ * The 3xx → `block` mapping is intentional: a redirect at the
+ * delivery layer means the configured URL is wrong, and retrying
+ * the same URL won't fix that. Manual operator review is the right
+ * next step, which is what the block path produces.
+ */
+export type HttpDisposition = "ok" | "retry" | "block";
+/**
+ * Classify an HTTP response as `ok` (2xx), `retry` (5xx), or
+ * `block` (3xx, 4xx). The classification {@link webhook} uses
+ * internally, lifted here so custom integrations (gRPC bridges,
+ * SDK-based reactions, etc.) can apply the same retry semantics
+ * without inventing a parallel rule.
+ */
+export declare function classifyHttpResponse(response: Response): HttpDisposition;
+/** Options for {@link tryOk}. */
+export type TryOkOptions = {
+    /** The endpoint that received the request. Surfaced on the thrown error and in its message. */
+    url: string;
+    /**
+     * Label prefixed onto the error message — typically the
+     * integration's identity (`"webhook"`, `"mySdk"`, `"grpc"`).
+     * Default: `"request"`.
+     */
+    label?: string;
+};
+/**
+ * If `response` is 2xx, return. Otherwise, capture the response body
+ * (best-effort) and throw a {@link RetryableHttpError} (for 5xx) or
+ * {@link NonRetryableHttpError} (for 3xx/4xx). Collapses the
+ * classify-and-throw boilerplate every custom HTTP-like reaction
+ * would otherwise write into one line:
+ *
+ * ```ts
+ * .on("OrderConfirmed").do(async (event) => {
+ *   const response = await mySdk.deliver(event);
+ *   await tryOk(response, { url: mySdk.url, label: "mySdk" });
+ *   // ...response was 2xx; continue with downstream work...
+ * });
+ * ```
+ *
+ * The {@link webhook} helper throws webhook-specific subclasses
+ * ({@link WebhookError} / {@link NonRetryableWebhookError}) for
+ * backward compatibility — both extend the generic classes thrown
+ * here, so `instanceof RetryableHttpError` matches both webhook and
+ * custom-integration errors uniformly.
+ */
+export declare function tryOk(response: Response, options: TryOkOptions): Promise<void>;
+//# sourceMappingURL=classify.d.ts.map

package/dist/@types/webhook/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../../src/webhook/classify.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,eAAe,CAIxE;AAED,iCAAiC;AACjC,MAAM,MAAM,YAAY,GAAG;IACzB,+FAA+F;IAC/F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,KAAK,CACzB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/@types/webhook/index.d.ts

@@ -26,8 +26,9 @@
  */
 import type { ReactionHandler, Schemas } from "@rotorsoft/act";
 import { type WebhookConfig } from "./types.js";
-export type { WebhookBody, WebhookConfig, WebhookResolver } from "./types.js";
-export { NonRetryableWebhookError, WebhookError } from "./types.js";
+export { classifyHttpResponse, type HttpDisposition, type TryOkOptions, tryOk, } from "./classify.js";
+export type { HttpDeliveryErrorInit, WebhookBody, WebhookConfig, WebhookResolver, } from "./types.js";
+export { NonRetryableHttpError, NonRetryableWebhookError, RetryableHttpError, WebhookError, } from "./types.js";
 /**
  * Build a reaction handler that POSTs each event to an external URL.
  *

package/dist/@types/webhook/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/webhook/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAa,eAAe,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsBpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,OAAO,SAAS,OAAO,GAAG,OAAO,EACvD,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAC7B,eAAe,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAsEzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/webhook/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAa,eAAe,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAC;AAsBpB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,OAAO,SAAS,OAAO,GAAG,OAAO,EACvD,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAC7B,eAAe,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CA+EzC"}

package/dist/@types/webhook/sign.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Compute the HMAC-SHA256 signature for an outbound webhook request.
+ *
+ * The signed payload is `${timestamp}.${body}` — Stripe-style. The
+ * timestamp is included so the receiver can reject replays via a
+ * window check, and the dot separator prevents `timestamp + body`
+ * ambiguity (12 + 345 vs 123 + 45).
+ *
+ * Returns `{ signature, timestamp }` so the webhook helper can attach
+ * both as headers — `X-Webhook-Signature: sha256=<hex>` and
+ * `X-Webhook-Timestamp: <unix-seconds>` — for the receiver to verify
+ * via `verifyWebhook` from `@rotorsoft/act-http/receiver`.
+ *
+ * `now` is exposed for tests; production callers should leave it
+ * undefined so wall-clock is used.
+ *
+ * @internal Reachable from tests via the source path. Not re-exported
+ *   from the package's `./webhook` entry — the webhook helper calls
+ *   it internally, and operators don't need it directly.
+ */
+export declare function signRequest(body: string, secret: string, now?: number): {
+    signature: string;
+    timestamp: string;
+};
+//# sourceMappingURL=sign.d.ts.map

package/dist/@types/webhook/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../../src/webhook/sign.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAsC,GAC1C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAK1C"}