@rotorsoft/act-http 1.0.0 → 1.2.0

package/dist/@types/api/actor.d.ts

@@ -0,0 +1,20 @@
+import type { Actor } from "@rotorsoft/act";
+/**
+ * Extractor function the host supplies to resolve an {@link Actor}
+ * from an incoming request. The framework keeps auth out of the
+ * package — JWT vs session vs API key is the host's call — and asks
+ * for this single closure that every transport (tRPC, Hono, OpenAPI
+ * docs) composes against.
+ *
+ * The `request` argument is intentionally generic. Each transport
+ * narrows it at the call site (`IncomingMessage` for Hono, the tRPC
+ * context object for tRPC, etc.) — keeping the contract here
+ * transport-agnostic means one extractor implementation plugs into
+ * every adapter unchanged.
+ *
+ * Async is allowed so the extractor can verify a JWT against a
+ * remote JWKS endpoint without forcing every host to synchronously
+ * cache.
+ */
+export type ActorExtractor = (request: unknown) => Actor | Promise<Actor>;
+//# sourceMappingURL=actor.d.ts.map

package/dist/@types/api/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/api/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC"}

package/dist/@types/api/errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Uniform error envelope shipped over the wire by every act-http
+ * transport. Hosts get the same shape from REST, tRPC, and OpenAPI —
+ * a client that talks to two transports doesn't have to invent two
+ * error parsers.
+ *
+ * - `error` — the framework error name (`"ValidationError"`,
+ *   `"InvariantError"`, …). Stable identifier, safe to switch on.
+ * - `detail` — the framework's message text. Human-readable; not
+ *   parsed by clients.
+ * - `code` — a machine-readable status code from {@link ERROR_MAP}
+ *   for clients that prefer enum-style branching over name strings.
+ */
+export type ApiError = {
+    error: string;
+    detail?: string;
+    code?: string;
+};
+/**
+ * Status + code pair for one known framework error.
+ */
+export type ErrorMapEntry = {
+    status: number;
+    code: string;
+};
+/**
+ * The single table that maps framework error types to HTTP status
+ * codes and machine-readable codes. One table, three consumers
+ * (Hono, tRPC, OpenAPI) — cross-transport consistency by
+ * construction.
+ *
+ * Operators wanting different mappings wrap the generated transport
+ * rather than mutating this — the consistency is the load-bearing
+ * property, not the specific status codes.
+ */
+export declare const ERROR_MAP: {
+    readonly ValidationError: {
+        readonly status: 422;
+        readonly code: "VALIDATION";
+    };
+    readonly InvariantError: {
+        readonly status: 409;
+        readonly code: "INVARIANT";
+    };
+    readonly ConcurrencyError: {
+        readonly status: 412;
+        readonly code: "CONCURRENCY";
+    };
+    readonly StreamClosedError: {
+        readonly status: 410;
+        readonly code: "STREAM_CLOSED";
+    };
+    readonly NonRetryableError: {
+        readonly status: 400;
+        readonly code: "NON_RETRYABLE";
+    };
+};
+/**
+ * Translate an unknown thrown value into the canonical
+ * {@link ApiError} envelope plus HTTP status. Each transport's error
+ * boundary calls this once and forwards the result to the wire.
+ *
+ * Known framework errors map per {@link ERROR_MAP}. Everything else
+ * surfaces as a 500 with `code: "INTERNAL"`; the `detail` field is
+ * populated when the throw was an `Error` instance, omitted
+ * otherwise (a thrown string or object doesn't get to leak its
+ * payload to the client).
+ */
+export declare function toApiError(err: unknown): {
+    status: number;
+    body: ApiError;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/@types/api/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/api/errors.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;CAM4B,CAAC;AAWnD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAuB3E"}

package/dist/@types/api/idempotency.d.ts

@@ -0,0 +1,36 @@
+import type { IdempotencyStore } from "@rotorsoft/act-ops/idempotency";
+/**
+ * Result of a {@link withIdempotency} call.
+ *
+ * - `{ deduped: false, result }` — the claim was fresh; the handler
+ *   ran and produced `result`.
+ * - `{ deduped: true }` — the claim was already taken; the handler
+ *   was *not* invoked. The caller decides how to respond (typically
+ *   a 2xx with no body, matching the receiver-side convention).
+ *
+ * Note: the contract does not cache the previous response. A
+ * duplicate call returns the deduped marker only — replaying the
+ * original handler's output would require a response-caching
+ * adapter, which is out of scope here. The receiver-side convention
+ * (and the convention the generated transports follow) is "ack the
+ * duplicate; do nothing else."
+ */
+export type IdempotencyResult<T> = {
+    deduped: false;
+    result: T;
+} | {
+    deduped: true;
+};
+/**
+ * Wrap an action handler so the framework honors `Idempotency-Key`
+ * dedup. Acquires the key via {@link IdempotencyStore.claim}, runs
+ * the handler exactly when the claim was fresh, and skips the
+ * handler entirely on a duplicate.
+ *
+ * Reuses the contract `@rotorsoft/act-ops/idempotency` already
+ * defines for the receiver-side `Idempotency-Key` story. A single
+ * `IdempotencyStore` implementation covers both halves of the "Act
+ * over the wire" surface — receiver and generated API.
+ */
+export declare function withIdempotency<T>(store: IdempotencyStore, key: string, handler: () => Promise<T>): Promise<IdempotencyResult<T>>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/@types/api/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/api/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAEtB;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAM/B"}

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

@@ -0,0 +1,39 @@
+/**
+ * @packageDocumentation
+ * @module act-http/api
+ *
+ * Shared utilities for the act-http auto-generated API surfaces.
+ * Three concerns that every transport (tRPC, Hono, OpenAPI) has to
+ * address — actor extraction, error envelope mapping,
+ * `Idempotency-Key` wiring — defined once here and composed by each
+ * transport sibling subpath.
+ *
+ * - {@link ActorExtractor} — the host-supplied closure that resolves
+ *   an `Actor` from an incoming request. Auth (JWT, session, API
+ *   key) stays in the host; the package only asks for this one
+ *   function.
+ * - {@link ApiError}, {@link ERROR_MAP}, {@link toApiError} — the
+ *   uniform error envelope and the status/code mapping every
+ *   transport uses. Cross-transport consistency by construction.
+ * - {@link withIdempotency} — the helper that wraps action handlers
+ *   in an `Idempotency-Key` claim. Reuses the
+ *   `@rotorsoft/act-ops/idempotency` contract that
+ *   `@rotorsoft/act-http/receiver` already speaks, so receivers and
+ *   generated APIs share one `IdempotencyStore` implementation.
+ *
+ * Sibling subpaths in the same package consume the utilities here:
+ *
+ * - `@rotorsoft/act-http/trpc` — tRPC adapter (#843).
+ * - `@rotorsoft/act-http/hono` — Hono adapter (#844).
+ * - `@rotorsoft/act-http/openapi` — OpenAPI emitter (#845).
+ *
+ * Existing siblings unrelated to the generated-API work:
+ *
+ * - `@rotorsoft/act-http/webhook` — outbound POST delivery.
+ * - `@rotorsoft/act-http/sse` — incremental state broadcast.
+ * - `@rotorsoft/act-http/receiver` — inbound webhook ingestion.
+ */
+export type { ActorExtractor } from "./actor.js";
+export { type ApiError, ERROR_MAP, type ErrorMapEntry, toApiError, } from "./errors.js";
+export { type IdempotencyResult, withIdempotency } from "./idempotency.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,KAAK,QAAQ,EACb,SAAS,EACT,KAAK,aAAa,EAClB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

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"}