@daloyjs/core 0.35.2 → 0.37.0

package/dist/pagination.js

@@ -0,0 +1,353 @@
+/**
+ * Cursor pagination helpers for DaloyJS.
+ *
+ * Contract-first list endpoints need three things the framework did not yet
+ * ship: an **opaque cursor** the client can echo back without depending on its
+ * internals, an **RFC 8288 `Link` header** advertising the `next` / `prev` /
+ * `first` pages, and **OpenAPI parameter wiring** so the `cursor` / `limit`
+ * query parameters appear in the generated spec and typed client. This module
+ * provides all three with zero runtime dependencies:
+ *
+ * - {@link encodeCursor} / {@link decodeCursor} — base64url-encode an arbitrary
+ *   JSON-serializable payload (typically the sort key of the last row) into an
+ *   opaque, URL-safe token, and decode it back with prototype-pollution-safe
+ *   parsing and a hard size cap.
+ * - {@link buildLinkHeader} / {@link buildPageLinks} — assemble a Web-standard
+ *   `Link` header, with CRLF / angle-bracket header-injection guards baked in.
+ * - {@link paginationQuery} — a Standard Schema validator for the `cursor` +
+ *   `limit` query parameters that both validates at runtime (clamping `limit`
+ *   to a safe range) **and** advertises itself to the OpenAPI generator via a
+ *   `toJSONSchema()` method, so `request: { query: paginationQuery() }` wires
+ *   the parameters into the contract with no extra code.
+ *
+ * Everything here is built on Web-standard `URL` / `Request` and `btoa` /
+ * `atob`, so it runs unchanged on Node, Bun, Deno, Cloudflare Workers, and
+ * Vercel Edge.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { BadRequestError } from "./errors.js";
+import { isForbiddenObjectKey } from "./security.js";
+/**
+ * Hard cap on the length of an encoded cursor string accepted by
+ * {@link decodeCursor}. Bounds the work an attacker can force by sending a
+ * giant `cursor` query parameter. 4 KiB is far larger than any legitimate
+ * sort-key payload.
+ */
+export const MAX_CURSOR_LENGTH = 4096;
+// ---------- Opaque cursor codec ----------
+/**
+ * Encode an arbitrary JSON-serializable value into an opaque, URL-safe cursor
+ * token (base64url, no padding).
+ *
+ * The token is **opaque, not secret**: it is encoded, not encrypted or signed.
+ * Never trust a decoded cursor for authorization — always re-scope the
+ * underlying query by the authenticated principal on the server. Put only the
+ * data you need to resume a scan (e.g. `{ id, createdAt }`) inside it.
+ *
+ * @param payload - Any JSON-serializable value (object, array, string, …).
+ * @returns A base64url cursor string safe to place in a URL or `Link` header.
+ * @throws {TypeError} If `payload` cannot be JSON-serialized (e.g. a `BigInt`
+ *   or a circular structure).
+ * @since 0.37.0
+ */
+export function encodeCursor(payload) {
+    const json = JSON.stringify(payload);
+    if (json === undefined) {
+        throw new TypeError("encodeCursor(): payload is not JSON-serializable.");
+    }
+    return base64UrlEncode(json);
+}
+/**
+ * Decode an opaque cursor produced by {@link encodeCursor} back into its
+ * original value.
+ *
+ * Parsing is hardened: the input length is capped at {@link MAX_CURSOR_LENGTH},
+ * decoding rejects malformed base64url, and any `__proto__` / `constructor` /
+ * `prototype` keys in the decoded object graph are stripped (prototype-
+ * pollution defense, mirroring the core body parsers).
+ *
+ * @typeParam T - The expected shape of the decoded payload (caller-asserted).
+ * @param cursor - The opaque cursor string from the request.
+ * @returns The decoded payload.
+ * @throws {BadRequestError} If the cursor is missing, over-long, or malformed —
+ *   a `400` so a tampered cursor surfaces as a client error, not a `500`.
+ * @since 0.37.0
+ */
+export function decodeCursor(cursor) {
+    if (typeof cursor !== "string" || cursor.length === 0) {
+        throw new BadRequestError("Invalid pagination cursor.");
+    }
+    if (cursor.length > MAX_CURSOR_LENGTH) {
+        throw new BadRequestError("Pagination cursor is too long.");
+    }
+    let json;
+    try {
+        json = base64UrlDecode(cursor);
+    }
+    catch {
+        throw new BadRequestError("Malformed pagination cursor.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new BadRequestError("Malformed pagination cursor.");
+    }
+    return stripForbiddenKeys(parsed);
+}
+// Reject control characters and the structural delimiters that would let a
+// crafted URL or title break out of the header (CRLF injection, `<`/`>`).
+const LINK_URL_FORBIDDEN = /[\u0000-\u001f\u007f<>]/;
+const LINK_TOKEN_FORBIDDEN = /[\u0000-\u001f\u007f"\\]/;
+/**
+ * Serialize a list of links into a single RFC 8288 `Link` header value.
+ *
+ * Each entry renders as `<url>; rel="rel"` (plus `; title="…"` when present).
+ * URLs containing control characters, `<`, or `>` and rel/title values
+ * containing control characters, `"`, or `\` are rejected — a structural
+ * defense against `Link`-header / response-splitting injection.
+ *
+ * @param links - The links to emit. An empty array yields an empty string.
+ * @returns The comma-joined `Link` header value.
+ * @throws {Error} If any URL or token contains forbidden characters.
+ * @since 0.37.0
+ */
+export function buildLinkHeader(links) {
+    const parts = [];
+    for (const link of links) {
+        if (LINK_URL_FORBIDDEN.test(link.url)) {
+            throw new Error("buildLinkHeader(): link URL contains forbidden characters.");
+        }
+        if (LINK_TOKEN_FORBIDDEN.test(link.rel)) {
+            throw new Error("buildLinkHeader(): link rel contains forbidden characters.");
+        }
+        let part = `<${link.url}>; rel="${link.rel}"`;
+        if (link.title !== undefined) {
+            if (LINK_TOKEN_FORBIDDEN.test(link.title)) {
+                throw new Error("buildLinkHeader(): link title contains forbidden characters.");
+            }
+            part += `; title="${link.title}"`;
+        }
+        parts.push(part);
+    }
+    return parts.join(", ");
+}
+/**
+ * Build the `next` / `prev` / `first` page URLs for a list response by cloning
+ * the current request URL and swapping its cursor query parameter, then
+ * serialize them into an RFC 8288 `Link` header.
+ *
+ * All other query parameters (filters, `limit`, …) are preserved, so the
+ * generated links are drop-in "give me the same query, next page" URLs.
+ *
+ * @example
+ * ```ts
+ * const { linkHeader } = buildPageLinks({
+ *   url: ctx.request.url,
+ *   next: nextCursor,        // from encodeCursor(...)
+ *   prev: prevCursor,
+ *   first: true,
+ * });
+ * set.headers.set("Link", linkHeader);
+ * ```
+ *
+ * @param opts - Current URL plus the cursors to advertise.
+ * @returns The structured links, the `Link` header string, and the page URLs.
+ * @since 0.37.0
+ */
+export function buildPageLinks(opts) {
+    const cursorParam = opts.cursorParam ?? "cursor";
+    const base = new URL(typeof opts.url === "string" ? opts.url : opts.url.href);
+    const self = base.href;
+    const links = [];
+    const urls = { self };
+    if (opts.next !== undefined && opts.next !== null) {
+        const u = new URL(base.href);
+        u.searchParams.set(cursorParam, opts.next);
+        urls.next = u.href;
+        links.push({ url: u.href, rel: "next" });
+    }
+    if (opts.prev !== undefined && opts.prev !== null) {
+        const u = new URL(base.href);
+        u.searchParams.set(cursorParam, opts.prev);
+        urls.prev = u.href;
+        links.push({ url: u.href, rel: "prev" });
+    }
+    if (opts.first === true) {
+        const u = new URL(base.href);
+        u.searchParams.delete(cursorParam);
+        urls.first = u.href;
+        links.push({ url: u.href, rel: "first" });
+    }
+    if (opts.extraLinks)
+        links.push(...opts.extraLinks);
+    return { links, linkHeader: buildLinkHeader(links), urls };
+}
+/**
+ * Build a Standard Schema validator for cursor-pagination query parameters.
+ *
+ * Use it as a route's `request.query`. At runtime it parses and validates
+ * `limit` (coerced from its string query value to an integer and clamped to
+ * `[minLimit, maxLimit]`, defaulting to `defaultLimit` when absent) and passes
+ * `cursor` through as an optional opaque string. Because it also exposes
+ * `toJSONSchema()`, the same call wires both parameters into the generated
+ * OpenAPI document and typed client — no duplicate parameter declarations.
+ *
+ * @example
+ * ```ts
+ * app.route({
+ *   method: "GET",
+ *   path: "/books",
+ *   operationId: "listBooks",
+ *   request: { query: paginationQuery({ defaultLimit: 25, maxLimit: 100 }) },
+ *   responses: { 200: { description: "ok", body: pageSchema } },
+ *   handler: async ({ query }) => {
+ *     const { limit, cursor } = query; // fully typed + validated
+ *     // ...
+ *   },
+ * });
+ * ```
+ *
+ * @param opts - Parameter names and page-size bounds.
+ * @returns A Standard Schema usable as `request.query`.
+ * @throws {Error} If the configured bounds are not positive integers or are
+ *   inconsistent (`minLimit > maxLimit`, `defaultLimit` out of range).
+ * @since 0.37.0
+ */
+export function paginationQuery(opts = {}) {
+    const cursorParam = opts.cursorParam ?? "cursor";
+    const limitParam = opts.limitParam ?? "limit";
+    const minLimit = opts.minLimit ?? 1;
+    const maxLimit = opts.maxLimit ?? 100;
+    const defaultLimit = opts.defaultLimit ?? Math.min(20, maxLimit);
+    for (const [label, n] of [
+        ["minLimit", minLimit],
+        ["maxLimit", maxLimit],
+        ["defaultLimit", defaultLimit],
+    ]) {
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`paginationQuery(): ${label} must be a positive integer.`);
+        }
+    }
+    if (minLimit > maxLimit) {
+        throw new Error("paginationQuery(): minLimit must not exceed maxLimit.");
+    }
+    if (defaultLimit < minLimit || defaultLimit > maxLimit) {
+        throw new Error("paginationQuery(): defaultLimit must be within [minLimit, maxLimit].");
+    }
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "daloyjs",
+            validate(value) {
+                if (value === null || typeof value !== "object") {
+                    return { issues: [{ message: "Expected a query object" }] };
+                }
+                const input = value;
+                const out = { limit: defaultLimit };
+                const rawLimit = input[limitParam];
+                if (rawLimit !== undefined && rawLimit !== "") {
+                    const limitStr = Array.isArray(rawLimit) ? rawLimit[0] : rawLimit;
+                    const n = Number(limitStr);
+                    if (!Number.isInteger(n)) {
+                        return {
+                            issues: [{ message: `${limitParam} must be an integer`, path: [limitParam] }],
+                        };
+                    }
+                    if (n < minLimit || n > maxLimit) {
+                        return {
+                            issues: [
+                                {
+                                    message: `${limitParam} must be between ${minLimit} and ${maxLimit}`,
+                                    path: [limitParam],
+                                },
+                            ],
+                        };
+                    }
+                    out.limit = n;
+                }
+                const rawCursor = input[cursorParam];
+                if (rawCursor !== undefined && rawCursor !== "") {
+                    const cursorStr = Array.isArray(rawCursor) ? rawCursor[0] : rawCursor;
+                    if (typeof cursorStr !== "string") {
+                        return {
+                            issues: [{ message: `${cursorParam} must be a string`, path: [cursorParam] }],
+                        };
+                    }
+                    if (cursorStr.length > MAX_CURSOR_LENGTH) {
+                        return {
+                            issues: [{ message: `${cursorParam} is too long`, path: [cursorParam] }],
+                        };
+                    }
+                    out.cursor = cursorStr;
+                }
+                return { value: out };
+            },
+        },
+        toJSONSchema() {
+            return {
+                type: "object",
+                properties: {
+                    [limitParam]: {
+                        type: "integer",
+                        minimum: minLimit,
+                        maximum: maxLimit,
+                        default: defaultLimit,
+                        description: "Maximum number of items to return.",
+                    },
+                    [cursorParam]: {
+                        type: "string",
+                        maxLength: MAX_CURSOR_LENGTH,
+                        description: "Opaque cursor identifying the page to return.",
+                    },
+                },
+                required: [],
+            };
+        },
+    };
+}
+// ---------- Internal helpers ----------
+/** Encode a UTF-8 string as base64url without padding. */
+function base64UrlEncode(input) {
+    const bytes = new TextEncoder().encode(input);
+    let bin = "";
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decode a base64url (optionally padded) string back to a UTF-8 string. */
+function base64UrlDecode(input) {
+    if (!/^[A-Za-z0-9_-]+$/.test(input)) {
+        throw new Error("invalid base64url");
+    }
+    const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(padded);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+/**
+ * Recursively remove prototype-pollution sink keys (`__proto__`,
+ * `constructor`, `prototype`) from a decoded cursor payload.
+ */
+function stripForbiddenKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map((v) => stripForbiddenKeys(v));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (isForbiddenObjectKey(k))
+                continue;
+            out[k] = stripForbiddenKeys(v);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/rate-limit-redis.d.ts

@@ -75,6 +75,14 @@ export interface RedisRateLimitStoreOptions {
  * The returned store is safe to share between requests and replicas. Errors
  * from Redis are fail-open by default (see {@link RedisRateLimitStoreOptions.onError});
  * pass a custom handler to fail-closed (return `"fail-closed"`).
+ *
+ * @remarks
+ * Security: the default fail-open posture biases toward availability — while
+ * Redis is unreachable the limiter stops enforcing and every request is
+ * allowed (reported as the first hit of a fresh local window). For
+ * abuse-sensitive limiters in front of auth, password-reset, or other
+ * credential endpoints, pass `onError: () => "fail-closed"` so a Redis
+ * outage rejects rather than silently disables the limit.
  */
 export declare function redisRateLimitStore(opts: RedisRateLimitStoreOptions): RateLimitStore;
 /**

package/dist/rate-limit-redis.js

@@ -76,6 +76,14 @@ function toNumber(value) {
  * The returned store is safe to share between requests and replicas. Errors
  * from Redis are fail-open by default (see {@link RedisRateLimitStoreOptions.onError});
  * pass a custom handler to fail-closed (return `"fail-closed"`).
+ *
+ * @remarks
+ * Security: the default fail-open posture biases toward availability — while
+ * Redis is unreachable the limiter stops enforcing and every request is
+ * allowed (reported as the first hit of a fresh local window). For
+ * abuse-sensitive limiters in front of auth, password-reset, or other
+ * credential endpoints, pass `onError: () => "fail-closed"` so a Redis
+ * outage rejects rather than silently disables the limit.
  */
 export function redisRateLimitStore(opts) {
     const prefix = opts.prefix ?? "daloy:rl:";

package/dist/request-decompression.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Inbound request-decompression bomb guard.
+ *
+ * DaloyJS core deliberately does **not** decompress request bodies — it is safe
+ * by omission, so a `Content-Encoding: gzip` request body is read as-is and a
+ * schema parse simply fails on the compressed bytes. Some services, though,
+ * genuinely need to accept compressed uploads (chatty IoT clients, log
+ * shippers, mobile apps on slow links). The moment you inflate attacker-supplied
+ * bytes you inherit the classic **decompression bomb** (a.k.a. "zip bomb"): a
+ * few kilobytes of crafted gzip can expand to gigabytes and blow straight past
+ * {@link "./app.js".AppOptions.bodyLimitBytes}, which only ever sees the small
+ * compressed payload.
+ *
+ * {@link requestDecompression} is the opt-in middleware that adds request
+ * decompression **with the bomb guard baked in**. It inflates the body with two
+ * independent caps enforced *during* inflation (so a bomb is aborted long before
+ * it is fully materialised):
+ *
+ * - an **absolute** cap (`maxDecompressedBytes`) — the inflated body may never
+ *   exceed this many bytes; and
+ * - a **ratio** cap (`maxRatio`) — the inflated size may never exceed
+ *   `compressedBytes * maxRatio`, which catches small-but-explosive payloads
+ *   that stay under the absolute cap in isolation but would amplify wildly.
+ *
+ * The compressed input itself is bounded by `maxCompressedBytes` before a single
+ * byte is inflated. Built on the web-standard `DecompressionStream`, so the same
+ * line works on Node, Bun, Deno, Cloudflare Workers, and Vercel Edge. Zero
+ * runtime dependencies.
+ *
+ * The middleware runs in the {@link "./types.js".Hooks.onRequest} phase — before
+ * the per-request context (and therefore before schema-body validation) is
+ * built — and stashes the inflated bytes on the request so the framework's own
+ * body reader transparently sees the decompressed payload. That means it works
+ * for both schema-validated bodies and handlers that read the raw body
+ * themselves. Register it globally with `app.use(requestDecompression(...))`.
+ *
+ * Secure-by-default posture:
+ * - Only `gzip` and `deflate` are accepted (the encodings `DecompressionStream`
+ *   implements across runtimes). An unknown, unsupported, or **layered**
+ *   (`gzip, gzip`) `Content-Encoding` is refused with `415` — never inflated.
+ * - Malformed compressed input is refused with `400`, never silently treated as
+ *   an empty body.
+ * - The bomb caps are mandatory: there is no "unlimited" mode.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { HttpError } from "./errors.js";
+import type { Hooks } from "./types.js";
+/**
+ * Request `Content-Encoding` values this guard can safely inflate. Limited to
+ * the formats the web-standard `DecompressionStream` implements consistently
+ * across runtimes (brotli is intentionally excluded — it is not part of the
+ * Compression Streams spec and is unavailable on most runtimes).
+ *
+ * @since 0.37.0
+ */
+export type RequestDecompressionEncoding = "gzip" | "deflate";
+/**
+ * Details of a rejected decompression bomb, passed to
+ * {@link RequestDecompressionOptions.onBomb} and carried by
+ * {@link DecompressionBombError}.
+ *
+ * @since 0.37.0
+ */
+export interface DecompressionBombInfo {
+    /** The declared request `Content-Encoding` that was being inflated. */
+    encoding: RequestDecompressionEncoding;
+    /** Size of the compressed input, in bytes. */
+    compressedBytes: number;
+    /** Inflated bytes produced before the guard aborted (always over a cap). */
+    decompressedBytes: number;
+    /** Which cap tripped: the absolute byte cap or the expansion-ratio cap. */
+    reason: "absolute" | "ratio";
+}
+/**
+ * `413 Payload Too Large` raised when an inflating request body crosses either
+ * the absolute (`maxDecompressedBytes`) or ratio (`maxRatio`) cap. Thrown
+ * *during* inflation, so the full bomb is never materialised in memory.
+ *
+ * @since 0.37.0
+ */
+export declare class DecompressionBombError extends HttpError {
+    /** Structured details about the rejected bomb. */
+    readonly info: DecompressionBombInfo;
+    constructor(info: DecompressionBombInfo);
+}
+/**
+ * `415 Unsupported Media Type` raised when a request declares a
+ * `Content-Encoding` this guard cannot safely inflate — an unknown encoding, an
+ * encoding not in the configured allowlist, an encoding the runtime's
+ * `DecompressionStream` does not implement, or a layered encoding such as
+ * `gzip, gzip`. The body is refused, never inflated.
+ *
+ * @since 0.37.0
+ */
+export declare class UnsupportedContentEncodingError extends HttpError {
+    constructor(encoding: string, allowed: readonly string[]);
+}
+/**
+ * `400 Bad Request` raised when the compressed request body is not valid for its
+ * declared `Content-Encoding` (truncated or corrupt stream). Refusing — rather
+ * than treating a malformed body as empty — prevents request-smuggling-style
+ * desync between this guard and any downstream parser.
+ *
+ * @since 0.37.0
+ */
+export declare class MalformedCompressedBodyError extends HttpError {
+    constructor(encoding: RequestDecompressionEncoding);
+}
+/**
+ * Options for {@link requestDecompression} and {@link decompressRequestBody}.
+ *
+ * @since 0.37.0
+ */
+export interface RequestDecompressionOptions {
+    /**
+     * Absolute hard cap (in bytes) on the inflated body. Required — there is no
+     * unlimited mode. Inflation aborts the moment output crosses this value, so a
+     * bomb is never fully materialised. Must be a positive integer.
+     *
+     * Set this at or below your {@link "./app.js".AppOptions.bodyLimitBytes} so the
+     * inflated payload still fits the body the rest of the app expects.
+     */
+    maxDecompressedBytes: number;
+    /**
+     * Cap (in bytes) on the *compressed* input accepted before inflation. The
+     * compressed body is read with this limit, so an oversized upload is rejected
+     * with `413` without inflating anything. Default `1048576` (1 MiB). Must be a
+     * positive integer.
+     */
+    maxCompressedBytes?: number;
+    /**
+     * Maximum allowed inflated:compressed expansion ratio. The inflated body may
+     * not exceed `compressedBytes * maxRatio`; crossing it aborts inflation with
+     * `413`. Default `100`. Must be a finite number `>= 1`.
+     */
+    maxRatio?: number;
+    /**
+     * Allowed request encodings. Defaults to `["gzip", "deflate"]`. Any encoding
+     * outside this set (or unsupported by the runtime) is refused with `415`.
+     */
+    encodings?: readonly RequestDecompressionEncoding[];
+    /**
+     * Optional observability callback invoked when a bomb is rejected, before the
+     * `413` is thrown. Receives the structured {@link DecompressionBombInfo}. Must
+     * not throw.
+     */
+    onBomb?: (info: DecompressionBombInfo) => void;
+}
+/**
+ * @internal Reset the cached `DecompressionStream` runtime probe. Test-only.
+ * @since 0.37.0
+ */
+export declare function _resetRequestDecompressionProbeForTests(): void;
+/**
+ * Inflate `compressed` under `encoding` while enforcing the absolute-size and
+ * expansion-ratio caps *during* decompression. This is the low-level guard used
+ * by {@link requestDecompression}; it is exported so handlers that read raw
+ * bodies (or custom flows) can decompress request bytes with the same
+ * bomb-resistant semantics.
+ *
+ * @param compressed - The compressed request bytes.
+ * @param encoding - The declared `Content-Encoding` (`"gzip"` or `"deflate"`).
+ * @param opts - Caps; only the size/ratio/`onBomb` fields are consulted here.
+ * @returns The inflated body as a `Uint8Array`.
+ * @throws {DecompressionBombError} When an inflating cap is exceeded (`413`).
+ * @throws {MalformedCompressedBodyError} When the input is not a valid stream (`400`).
+ * @throws {UnsupportedContentEncodingError} When the runtime cannot inflate the encoding (`415`).
+ * @since 0.37.0
+ */
+export declare function decompressRequestBody(compressed: Uint8Array, encoding: RequestDecompressionEncoding, opts: RequestDecompressionOptions): Promise<Uint8Array>;
+/**
+ * Opt-in middleware that decompresses inbound request bodies behind a
+ * decompression-bomb guard. Inflates `gzip` / `deflate` request bodies under an
+ * absolute size cap and an expansion-ratio cap, then hands the inflated bytes to
+ * the framework's normal body pipeline so schema validation and raw-body reads
+ * both see the decompressed payload.
+ *
+ * Register it globally so it runs before the per-request context is built:
+ *
+ * ```ts
+ * app.use(requestDecompression({
+ *   maxDecompressedBytes: 1024 * 1024, // inflated body never exceeds 1 MiB
+ *   maxCompressedBytes: 64 * 1024,     // reject compressed uploads over 64 KiB
+ *   maxRatio: 50,                      // and never expand more than 50x
+ * }));
+ * ```
+ *
+ * Requests without a `Content-Encoding` (or `identity`) pass through untouched.
+ * `GET` / `HEAD` requests are never decompressed. Unknown, unsupported, or
+ * layered encodings are refused with `415`; malformed streams with `400`; bombs
+ * with `413` (thrown mid-inflation).
+ *
+ * @param opts - Bomb-guard caps and the encoding allowlist. `maxDecompressedBytes` is required.
+ * @returns A {@link "./types.js".Hooks} bundle exposing only an `onRequest` hook.
+ * @throws {TypeError} At construction when a cap is invalid.
+ * @since 0.37.0
+ */
+export declare function requestDecompression(opts: RequestDecompressionOptions): Hooks;