@daloyjs/core 0.36.0 → 0.38.0

package/dist/waf.js

@@ -0,0 +1,334 @@
+/**
+ * WAF-lite signature/anomaly inbound-inspection middleware (OWASP CRS-lite).
+ *
+ * DaloyJS deliberately leaves a full Web Application Firewall to the operator's
+ * edge (CDN / reverse proxy / ModSecurity CRS). {@link waf} is **not** that — it
+ * is a first-party, opt-in, *defense-in-depth* layer for teams that do not have
+ * an edge WAF, wiring the framework's high-confidence injection signatures
+ * (SQLi, XSS, NoSQL-operator injection, command injection) into a single scored
+ * inbound-inspection pass with per-rule enable/disable and a block-or-log mode.
+ *
+ * Each enabled rule contributes an **anomaly score** when it matches anywhere in
+ * the inspected surface (the decoded URL path, the raw + decoded query string,
+ * an optional header allowlist, and the validated request body). When a
+ * request's total score reaches {@link WafOptions.blockThreshold}, the request is
+ * either rejected with a generic `403` (block mode, the default) or merely
+ * reported to {@link WafOptions.onMatch} (log mode) so operators can tune rules
+ * against real traffic before enforcing.
+ *
+ * Design notes / secure-by-default posture:
+ * - The `403` body is intentionally generic — it never tells the attacker which
+ *   signature fired. Rule detail is delivered server-side via `onMatch` only.
+ * - Body inspection covers the **validated** body (`ctx.body`), so it composes
+ *   with the framework's schema-first contract. Routes without a body schema are
+ *   not body-inspected (their body is never parsed); inspect their inputs with a
+ *   schema to bring them under coverage.
+ * - Header inspection is **opt-in** (off by default) because header values
+ *   (notably `User-Agent` / `Cookie`) carry parentheses and punctuation that can
+ *   trip signatures; enable it with an explicit allowlist.
+ * - Scanning is bounded: per-value length and total node-count caps keep a
+ *   hostile or huge payload from turning inspection into CPU-DoS.
+ * - Signatures are curated for **high confidence / low false-positive rate**;
+ *   this is a complement to, not a replacement for, input schemas and parameter
+ *   binding. Start in `"log"` mode, watch `onMatch`, then switch to `"block"`.
+ *
+ * The middleware is dependency-free and runtime-portable. It inspects the built
+ * context in the {@link "./types.js".Hooks.beforeHandle} phase (so query, params,
+ * headers, and the validated body are all available) and reuses
+ * {@link "./security.js".hasMongoOperatorKeys} for structural NoSQL-operator
+ * detection. Register it with `app.use(waf())`.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { ForbiddenError } from "./errors.js";
+import { hasMongoOperatorKeys } from "./security.js";
+import { readRemoteAddress } from "./conn-info.js";
+/** The four built-in rule categories, in stable order. */
+const ALL_RULE_IDS = Object.freeze([
+    "sqli",
+    "xss",
+    "nosqli",
+    "cmdi",
+]);
+/** Default anomaly score contributed by each rule when it matches. */
+const DEFAULT_RULE_SCORE = 5;
+/** Default total anomaly score at which a request is blocked / reported. */
+const DEFAULT_BLOCK_THRESHOLD = 5;
+/** Default cap on the length of any single string value that is scanned. */
+const DEFAULT_MAX_VALUE_LENGTH = 8192;
+/** Default cap on the number of body nodes walked during inspection. */
+const DEFAULT_MAX_BODY_NODES = 10_000;
+/**
+ * Curated, high-confidence signatures per rule. Patterns are deliberately
+ * conservative (anchored on injection-specific tokens) to keep the
+ * false-positive rate low; this is a defense-in-depth complement to schemas,
+ * not an exhaustive ModSecurity CRS.
+ */
+const SQLI_SIGNATURES = Object.freeze([
+    /\bUNION\b[\s\S]{0,40}?\bSELECT\b/i,
+    /\b(?:OR|AND)\b\s+['"]?\d+['"]?\s*=\s*['"]?\d+/i,
+    /'\s*(?:OR|AND)\s+'?[\w]+'?\s*=\s*'?[\w]+/i,
+    /;\s*(?:DROP|DELETE|INSERT|UPDATE|TRUNCATE|ALTER|CREATE)\b/i,
+    /\b(?:SLEEP|BENCHMARK|PG_SLEEP)\s*\(/i,
+    /\bWAITFOR\s+DELAY\b/i,
+    /\bINFORMATION_SCHEMA\b/i,
+    /\bxp_cmdshell\b/i,
+    /\b(?:LOAD_FILE|OUTFILE|DUMPFILE)\b/i,
+]);
+const XSS_SIGNATURES = Object.freeze([
+    /<script[\s\S]{0,40}?>/i,
+    /<\/script\s*>/i,
+    /javascript:\s*\S/i,
+    /\bon(?:error|load|click|mouseover|focus|submit|toggle|animationstart)\s*=/i,
+    /<iframe[\s>]/i,
+    /<img[\s\S]{0,80}?\bonerror\s*=/i,
+    /<svg[\s\S]{0,40}?\bonload\s*=/i,
+    /<body[\s\S]{0,40}?\bonload\s*=/i,
+    /\bdocument\.cookie\b/i,
+]);
+const NOSQLI_SIGNATURES = Object.freeze([
+    /\$(?:ne|gt|gte|lt|lte|in|nin|where|regex|exists|elemMatch|expr|function|or|and|not)\b/i,
+    /\{\s*"?\$\w+/,
+]);
+const CMDI_SIGNATURES = Object.freeze([
+    /[;&|]\s*(?:cat|ls|rm|zsh|python|perl|ruby|php|powershell|pwsh|whoami|id|uname|chmod|chown|kill|nslookup|ping|nc|ncat|bash|sh|wget|curl)\b/i,
+    /\$\([\s\S]{0,60}?\)/,
+    /`[^`]{1,60}`/,
+    /\|\s*(?:nc|ncat|bash|sh|wget|curl)\b/i,
+    /&&\s*(?:cat|ls|rm|whoami|id|wget|curl)\b/i,
+    /\/(?:etc\/passwd|etc\/shadow|bin\/sh|bin\/bash)\b/i,
+]);
+const SIGNATURES = Object.freeze({
+    sqli: SQLI_SIGNATURES,
+    xss: XSS_SIGNATURES,
+    nosqli: NOSQLI_SIGNATURES,
+    cmdi: CMDI_SIGNATURES,
+});
+function assertPositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new TypeError(`waf(): \`${label}\` must be a positive integer, received ${String(value)}`);
+    }
+}
+/**
+ * Resolve the per-rule config into the active rule set, applying defaults and
+ * overrides and validating any custom scores.
+ */
+function resolveRules(overrides) {
+    const resolved = [];
+    for (const ruleId of ALL_RULE_IDS) {
+        const override = overrides?.[ruleId];
+        let enabled = true;
+        let score = DEFAULT_RULE_SCORE;
+        if (override === false) {
+            enabled = false;
+        }
+        else if (override === true || override === undefined) {
+            // keep defaults
+        }
+        else {
+            enabled = override.enabled ?? true;
+            if (override.score !== undefined) {
+                if (!Number.isFinite(override.score) || override.score <= 0) {
+                    throw new TypeError(`waf(): \`rules.${ruleId}.score\` must be a positive number, received ${String(override.score)}`);
+                }
+                score = override.score;
+            }
+        }
+        if (enabled)
+            resolved.push({ ruleId, score, signatures: SIGNATURES[ruleId] });
+    }
+    return resolved;
+}
+/** Truncate a value to `maxLen` for safe inclusion in a server-side log sample. */
+function sample(value) {
+    const trimmed = value.length > 120 ? `${value.slice(0, 117)}...` : value;
+    // Strip control characters so a log sink can't be tricked by embedded
+    // newlines / escapes carried straight from the attacker's payload.
+    return trimmed.replace(/[\u0000-\u001f\u007f]/g, " ");
+}
+/** Best-effort URL-decode; return the original string if decoding throws. */
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Collect up to `maxNodes` string values from a parsed body value (object /
+ * array / scalar), each truncated to `maxValueLength`. Depth and node count are
+ * bounded so a hostile payload cannot turn inspection into CPU-DoS. Prototype
+ * keys are never followed (only own enumerable properties are walked).
+ */
+function collectBodyStrings(root, maxNodes, maxValueLength) {
+    const out = [];
+    const stack = [root];
+    let visited = 0;
+    while (stack.length > 0 && visited < maxNodes) {
+        const node = stack.pop();
+        visited++;
+        if (typeof node === "string") {
+            out.push(node.length > maxValueLength ? node.slice(0, maxValueLength) : node);
+        }
+        else if (Array.isArray(node)) {
+            for (let i = node.length - 1; i >= 0; i--)
+                stack.push(node[i]);
+        }
+        else if (node && typeof node === "object") {
+            // Also scan own string keys — an injected `$where` can hide in a key.
+            for (const key of Object.keys(node)) {
+                out.push(key.length > maxValueLength ? key.slice(0, maxValueLength) : key);
+                stack.push(node[key]);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Run every enabled rule's signatures against a single value. Records the first
+ * location/sample per rule into `matches` and accumulates the rule's score into
+ * `scored` (so a rule contributes its score at most once per request).
+ */
+function scanValue(value, location, rules, scored) {
+    for (const rule of rules) {
+        if (scored.has(rule.ruleId))
+            continue;
+        for (const signature of rule.signatures) {
+            if (signature.test(value)) {
+                scored.set(rule.ruleId, {
+                    ruleId: rule.ruleId,
+                    score: rule.score,
+                    location,
+                    sample: sample(value),
+                });
+                break;
+            }
+        }
+    }
+}
+/**
+ * Build an opt-in, scored WAF-lite inbound-inspection middleware.
+ *
+ * Inspects the decoded path, query string, an optional header allowlist, and the
+ * validated body for SQLi / XSS / NoSQL-operator / command-injection signatures.
+ * When the summed anomaly score of the rules that fire reaches
+ * {@link WafOptions.blockThreshold}, the request is rejected with a generic `403`
+ * (block mode) or reported to {@link WafOptions.onMatch} (log mode).
+ *
+ * ```ts
+ * import { App, waf } from "@daloyjs/core";
+ *
+ * const app = new App();
+ *
+ * // Start in log mode to tune against real traffic, then switch to block.
+ * app.use(waf({
+ *   mode: "log",
+ *   onMatch: (e) => logger.warn({ waf: e }, "waf detection"),
+ * }));
+ * ```
+ *
+ * @param opts - Mode, per-rule overrides, threshold, inspection surface, and the `onMatch` hook.
+ * @returns A {@link "./types.js".Hooks} bundle exposing only a `beforeHandle` hook.
+ * @throws {TypeError} At construction when an option is invalid.
+ * @throws {ForbiddenError} Per request, in block mode, when a request is flagged.
+ * @since 0.37.0
+ */
+export function waf(opts = {}) {
+    const mode = opts.mode ?? "block";
+    if (mode !== "block" && mode !== "log") {
+        throw new TypeError(`waf(): \`mode\` must be "block" or "log", received ${String(mode)}`);
+    }
+    const blockThreshold = opts.blockThreshold ?? DEFAULT_BLOCK_THRESHOLD;
+    if (!Number.isFinite(blockThreshold) || blockThreshold <= 0) {
+        throw new TypeError(`waf(): \`blockThreshold\` must be a positive number, received ${String(blockThreshold)}`);
+    }
+    const maxValueLength = opts.maxValueLength ?? DEFAULT_MAX_VALUE_LENGTH;
+    assertPositiveInteger(maxValueLength, "maxValueLength");
+    const maxBodyNodes = opts.maxBodyNodes ?? DEFAULT_MAX_BODY_NODES;
+    assertPositiveInteger(maxBodyNodes, "maxBodyNodes");
+    const rules = resolveRules(opts.rules);
+    const nosqliRule = rules.find((r) => r.ruleId === "nosqli");
+    const inspectPath = opts.inspect?.path ?? true;
+    const inspectQuery = opts.inspect?.query ?? true;
+    const inspectBody = opts.inspect?.body ?? true;
+    const headerAllowlist = (opts.inspect?.headers ?? []).map((h) => h.toLowerCase());
+    const onMatch = opts.onMatch;
+    return {
+        beforeHandle(ctx) {
+            // Nothing enabled — pay nothing.
+            if (rules.length === 0)
+                return;
+            const scored = new Map();
+            const url = new URL(ctx.request.url);
+            if (inspectPath) {
+                scanValue(safeDecode(url.pathname), "path", rules, scored);
+            }
+            if (inspectQuery && url.search.length > 1) {
+                // Scan both the raw query string and a best-effort decoded form so an
+                // encoded payload (`%27%20OR%201=1`) is caught after normalization.
+                const raw = url.search.slice(1);
+                scanValue(raw, "query", rules, scored);
+                const decoded = safeDecode(raw);
+                if (decoded !== raw)
+                    scanValue(decoded, "query", rules, scored);
+            }
+            if (headerAllowlist.length > 0) {
+                for (const name of headerAllowlist) {
+                    const value = ctx.request.headers.get(name);
+                    if (value)
+                        scanValue(value, "header", rules, scored);
+                }
+            }
+            if (inspectBody && ctx.body !== undefined && ctx.body !== null) {
+                // Structural NoSQL-operator detection on the parsed body — catches
+                // `{"password": {"$ne": null}}` even though no string value matches.
+                if (nosqliRule &&
+                    !scored.has("nosqli") &&
+                    typeof ctx.body === "object" &&
+                    hasMongoOperatorKeys(ctx.body)) {
+                    scored.set("nosqli", {
+                        ruleId: "nosqli",
+                        score: nosqliRule.score,
+                        location: "body",
+                        sample: "$-prefixed operator key",
+                    });
+                }
+                if (typeof ctx.body === "string") {
+                    scanValue(ctx.body.length > maxValueLength
+                        ? ctx.body.slice(0, maxValueLength)
+                        : ctx.body, "body", rules, scored);
+                }
+                else if (typeof ctx.body === "object") {
+                    const strings = collectBodyStrings(ctx.body, maxBodyNodes, maxValueLength);
+                    for (const value of strings)
+                        scanValue(value, "body", rules, scored);
+                }
+            }
+            if (scored.size === 0)
+                return;
+            let total = 0;
+            for (const match of scored.values())
+                total += match.score;
+            if (total < blockThreshold)
+                return;
+            const matches = Array.from(scored.values());
+            const event = {
+                mode,
+                action: mode === "block" ? "blocked" : "logged",
+                method: ctx.request.method,
+                path: url.pathname,
+                clientIp: readRemoteAddress(ctx),
+                score: total,
+                threshold: blockThreshold,
+                matches,
+            };
+            onMatch?.(event);
+            if (mode === "block") {
+                // Generic detail — never disclose which signature fired to the client.
+                throw new ForbiddenError("Request blocked by security policy");
+            }
+        },
+    };
+}

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Outbound webhook delivery — the sending counterpart to the inbound
+ * {@link verifyWebhookSignature} / {@link signWebhookPayload} helpers.
+ *
+ * Where the inbound helpers answer *“is this webhook I received
+ * authentic?”*, this module answers *“how do I reliably and
+ * securely deliver a webhook to someone else?”* — the three things a
+ * production webhook sender needs:
+ *
+ * - **Signed delivery with timestamped signatures.** Every request carries
+ *   an HMAC signature computed over `"<timestamp>.<body>"` (the Stripe /
+ *   Standard Webhooks convention), plus an idempotency id and a timestamp
+ *   header, so the receiver can authenticate the payload and reject
+ *   replays with {@link verifyWebhookSignature}.
+ * - **Retry with backoff.** Transient failures (network errors, timeouts,
+ *   `408` / `429` / `5xx`) are retried with exponential backoff and full
+ *   jitter, honouring a `Retry-After` header. The signature is computed
+ *   **once** so every retry carries the same id and signature — the
+ *   receiver can dedupe on the id.
+ * - **Dead-letter semantics.** When every attempt is exhausted (or the
+ *   upstream returns a permanent `4xx`), the failed delivery is handed to
+ *   a {@link WebhookDeadLetterSink} for later inspection or replay instead
+ *   of being silently dropped.
+ *
+ * Delivery is **SSRF-hardened by default**: the transport defaults to
+ * {@link fetchGuard}, so a webhook URL that resolves to cloud-metadata or
+ * an internal address is refused before any bytes are sent. Pass your own
+ * `fetch` (e.g. `fetchGuard({ allowPrivate: true })` or a
+ * {@link resilientFetch}) to change that posture deliberately.
+ *
+ * ```ts
+ * import { createWebhookSender, MemoryWebhookDeadLetterSink } from "@daloyjs/core";
+ *
+ * const deadLetters = new MemoryWebhookDeadLetterSink();
+ * const send = createWebhookSender({ secret: process.env.WEBHOOK_SECRET!, deadLetter: deadLetters });
+ *
+ * const result = await send({
+ *   url: "https://example.com/hooks",
+ *   eventType: "invoice.paid",
+ *   payload: { id: "in_123", amount: 4200 },
+ * });
+ * if (!result.ok) {
+ *   // result.deadLettered === true; inspect deadLetters.list()
+ * }
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { type WebhookHmacAlgorithm } from "./security.js";
+/**
+ * A single webhook event to deliver. The `payload` is signed and sent as
+ * the request body; everything else shapes the request and the signature
+ * headers.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookEvent {
+    /** Absolute `http(s)` URL of the receiver. */
+    url: string;
+    /**
+     * The event body. An object or array is JSON-serialised; a `string` is
+     * sent verbatim; a `Uint8Array` is sent as raw bytes. The signature is
+     * always computed over the exact bytes sent.
+     */
+    payload: unknown;
+    /**
+     * Optional event type (e.g. `"invoice.paid"`), emitted as a header and
+     * recorded on the dead letter. Purely informational.
+     */
+    eventType?: string;
+    /**
+     * Stable idempotency id, emitted in the id header so the receiver can
+     * dedupe retries. A random UUID is generated when omitted.
+     */
+    id?: string;
+    /**
+     * Extra request headers merged in **after** the signature headers, so
+     * they cannot overwrite the id / timestamp / signature headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Override the `Content-Type` header. Defaults to `application/json`
+     * for objects / strings and `application/octet-stream` for bytes.
+     */
+    contentType?: string;
+}
+/**
+ * A failed delivery handed to a {@link WebhookDeadLetterSink} after every
+ * attempt is exhausted. Carries enough context to inspect, alert on, or
+ * replay the delivery later.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookDeadLetter {
+    /** The idempotency id used for the delivery. */
+    id: string;
+    /** The receiver URL. */
+    url: string;
+    /** The event type, when one was supplied. */
+    eventType?: string;
+    /** The exact body bytes that were signed and sent. */
+    payload: Uint8Array;
+    /** The `Content-Type` that was sent. */
+    contentType: string;
+    /** Total number of attempts made before giving up. */
+    attempts: number;
+    /** The last HTTP status seen, when the final failure was a response. */
+    lastStatus?: number;
+    /** The last error message, when the final failure was a thrown error. */
+    lastError?: string;
+    /** The Unix-seconds timestamp bound into the signature. */
+    timestamp: number;
+    /** Wall-clock time (ms since epoch) the delivery was dead-lettered. */
+    failedAt: number;
+}
+/**
+ * A sink that receives {@link WebhookDeadLetter}s for permanently-failed
+ * deliveries. Implement this to persist to a queue, database, or alerting
+ * pipeline. `add` may be async; the sender awaits it.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookDeadLetterSink {
+    add(letter: WebhookDeadLetter): void | Promise<void>;
+}
+/**
+ * An in-memory, bounded {@link WebhookDeadLetterSink} suitable for tests
+ * and single-process apps. Holds the most recent `capacity` dead letters
+ * (default `1000`) in a ring buffer; older entries are evicted.
+ *
+ * @since 0.37.0
+ */
+export declare class MemoryWebhookDeadLetterSink implements WebhookDeadLetterSink {
+    #private;
+    constructor(capacity?: number);
+    /** Append a dead letter, evicting the oldest if at capacity. */
+    add(letter: WebhookDeadLetter): void;
+    /** A snapshot of the currently-held dead letters, oldest first. */
+    list(): readonly WebhookDeadLetter[];
+    /** Remove and return every held dead letter (e.g. for a replay sweep). */
+    drain(): WebhookDeadLetter[];
+    /** The number of dead letters currently held. */
+    get size(): number;
+}
+/**
+ * Per-attempt telemetry passed to {@link WebhookSenderOptions.onAttempt}.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookAttempt {
+    /** The idempotency id of the delivery. */
+    id: string;
+    /** 1-based attempt number. */
+    attempt: number;
+    /** The HTTP status, when the attempt produced a response. */
+    status?: number;
+    /** The error, when the attempt threw (network error / timeout). */
+    error?: unknown;
+    /** Whether the sender will retry after this attempt. */
+    willRetry: boolean;
+    /** The backoff delay (ms) before the next attempt, when retrying. */
+    delayMs?: number;
+}
+/**
+ * The outcome of a {@link createWebhookSender} delivery. Never throws for
+ * an ordinary delivery failure — inspect `ok` / `deadLettered` instead.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookDeliveryResult {
+    /** `true` when the receiver returned a 2xx response. */
+    ok: boolean;
+    /** The idempotency id used for the delivery. */
+    id: string;
+    /** The event type, when one was supplied. */
+    eventType?: string;
+    /** Total number of attempts made. */
+    attempts: number;
+    /** The final HTTP status, when the last attempt produced a response. */
+    status?: number;
+    /** The final response object, when the last attempt produced one. */
+    response?: Response;
+    /** The final error, when the last attempt threw. */
+    error?: unknown;
+    /** Whether the failed delivery was handed to the dead-letter sink. */
+    deadLettered: boolean;
+}
+/**
+ * Configuration for {@link createWebhookSender}. Only `secret` is
+ * required; every other field has a production-safe default.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookSenderOptions {
+    /** HMAC secret used to sign every delivery. */
+    secret: string | Uint8Array;
+    /** HMAC digest. Default `"sha256"`. */
+    algorithm?: WebhookHmacAlgorithm;
+    /**
+     * Transport. Defaults to {@link fetchGuard} so webhook URLs that resolve
+     * to internal / cloud-metadata addresses are refused (SSRF defence).
+     * Pass your own to relax or extend that posture.
+     */
+    fetch?: typeof fetch;
+    /** Maximum total attempts (first try + retries). Default `5`. */
+    maxAttempts?: number;
+    /** Base backoff for the first retry, in ms. Default `500`. */
+    retryDelayMs?: number;
+    /** Upper bound on any single backoff delay, in ms. Default `30_000`. */
+    maxRetryDelayMs?: number;
+    /** Exponential backoff multiplier. Default `2`. */
+    backoffFactor?: number;
+    /** Apply full jitter to backoff. Default `true`. */
+    jitter?: boolean;
+    /** Per-attempt timeout, in ms. `0` disables. Default `10_000`. */
+    timeoutMs?: number;
+    /**
+     * Response statuses that trigger a retry. Default
+     * `[408, 429, 500, 502, 503, 504]`. Any other non-2xx status is a
+     * permanent failure (dead-lettered immediately).
+     */
+    retryableStatuses?: readonly number[];
+    /** Honour a `Retry-After` header on a retryable response. Default `true`. */
+    respectRetryAfter?: boolean;
+    /** Header carrying the idempotency id. Default `"webhook-id"`. */
+    idHeader?: string;
+    /** Header carrying the Unix-seconds timestamp. Default `"webhook-timestamp"`. */
+    timestampHeader?: string;
+    /** Header carrying the signature. Default `"webhook-signature"`. */
+    signatureHeader?: string;
+    /** Header carrying the event type. Default `"webhook-event-type"`. */
+    eventTypeHeader?: string;
+    /** `User-Agent` sent with every delivery. Default `"DaloyJS-Webhook/1.0"`. */
+    userAgent?: string;
+    /** Sink for permanently-failed deliveries. */
+    deadLetter?: WebhookDeadLetterSink;
+    /** Clock (ms since epoch). Default {@link Date.now}. Override in tests. */
+    now?: () => number;
+    /**
+     * Abortable sleep, primarily for deterministic tests. Defaults to a
+     * `setTimeout`-based sleep.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /** Per-attempt observer (e.g. to emit a metric). */
+    onAttempt?: (attempt: WebhookAttempt) => void;
+}
+/**
+ * Build a webhook sender bound to a signing secret and delivery policy.
+ * The returned `send(event)` function signs, delivers, retries, and
+ * dead-letters a single {@link WebhookEvent}, resolving to a
+ * {@link WebhookDeliveryResult} (it does not throw on ordinary delivery
+ * failure).
+ *
+ * @example
+ * ```ts
+ * const send = createWebhookSender({ secret: process.env.WEBHOOK_SECRET! });
+ * const result = await send({ url, eventType: "user.created", payload: { id } });
+ * ```
+ *
+ * @since 0.37.0
+ */
+export declare function createWebhookSender(options: WebhookSenderOptions): (event: WebhookEvent) => Promise<WebhookDeliveryResult>;