@daloyjs/core 0.36.0 → 0.37.0

package/dist/request-decompression.js

@@ -0,0 +1,363 @@
+/**
+ * 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, PayloadTooLargeError } from "./errors.js";
+import { readBodyLimited } from "./security.js";
+/**
+ * Internal Symbol (shared via the global registry, same key the adapters and
+ * {@link "./security.js".readBodyLimited} use) under which a pre-resolved
+ * request body is stashed. Setting it lets the framework's body reader skip the
+ * stream and return our inflated bytes directly. Referenced via `Symbol.for`
+ * rather than imported to avoid an `app.ts` import cycle.
+ */
+const REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
+/** Default cap on the compressed request body (bytes) before inflation: 1 MiB. */
+const DEFAULT_MAX_COMPRESSED_BYTES = 1024 * 1024;
+/** Default maximum inflated:compressed expansion ratio. */
+const DEFAULT_MAX_RATIO = 100;
+/**
+ * `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 class DecompressionBombError extends HttpError {
+    /** Structured details about the rejected bomb. */
+    info;
+    constructor(info) {
+        super(413, {
+            type: "https://daloyjs.dev/errors/decompression-bomb",
+            title: "Payload Too Large",
+            detail: info.reason === "ratio"
+                ? `Decompressed body exceeded the allowed expansion ratio for ${info.encoding} content`
+                : `Decompressed body exceeded the maximum allowed size for ${info.encoding} content`,
+        });
+        this.name = "DecompressionBombError";
+        this.info = info;
+    }
+}
+/**
+ * `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 class UnsupportedContentEncodingError extends HttpError {
+    constructor(encoding, allowed) {
+        super(415, {
+            type: "https://daloyjs.dev/errors/unsupported-content-encoding",
+            title: "Unsupported Media Type",
+            detail: `Unsupported request Content-Encoding "${encoding}". Allowed: ${allowed.join(", ")}`,
+        }, { "accept-encoding": allowed.join(", ") });
+        this.name = "UnsupportedContentEncodingError";
+    }
+}
+/**
+ * `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 class MalformedCompressedBodyError extends HttpError {
+    constructor(encoding) {
+        super(400, {
+            type: "https://daloyjs.dev/errors/malformed-compressed-body",
+            title: "Bad Request",
+            detail: `Request body is not a valid ${encoding} stream`,
+        });
+        this.name = "MalformedCompressedBodyError";
+    }
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new TypeError(`requestDecompression(): \`${label}\` must be a positive integer, received ${String(value)}`);
+    }
+}
+let cachedRuntimeSupport = null;
+/**
+ * Probe (once) which encodings the runtime's `DecompressionStream` implements.
+ * Mirrors the `compression()` response-side runtime probe.
+ *
+ * @internal
+ */
+function detectRuntimeSupport() {
+    if (cachedRuntimeSupport)
+        return cachedRuntimeSupport;
+    const Stream = globalThis.DecompressionStream;
+    const supported = new Set();
+    if (Stream) {
+        for (const enc of ["gzip", "deflate"]) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const _probe = new Stream(enc);
+                supported.add(enc);
+            }
+            catch {
+                // not supported on this runtime
+            }
+        }
+    }
+    cachedRuntimeSupport = supported;
+    return supported;
+}
+/**
+ * @internal Reset the cached `DecompressionStream` runtime probe. Test-only.
+ * @since 0.37.0
+ */
+export function _resetRequestDecompressionProbeForTests() {
+    cachedRuntimeSupport = null;
+}
+async function cancelReader(reader) {
+    try {
+        await reader.cancel();
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * 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 async function decompressRequestBody(compressed, encoding, opts) {
+    assertPositiveInteger(opts.maxDecompressedBytes, "maxDecompressedBytes");
+    const maxRatio = opts.maxRatio ?? DEFAULT_MAX_RATIO;
+    if (!Number.isFinite(maxRatio) || maxRatio < 1) {
+        throw new TypeError(`requestDecompression(): \`maxRatio\` must be a finite number >= 1, received ${String(maxRatio)}`);
+    }
+    return inflateGuarded(compressed, encoding, {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxRatio,
+        onBomb: opts.onBomb,
+    });
+}
+async function inflateGuarded(compressed, encoding, caps) {
+    // An empty body has nothing to inflate; treat it as an empty payload rather
+    // than feeding an invalid (zero-byte) stream to DecompressionStream.
+    if (compressed.byteLength === 0)
+        return new Uint8Array(0);
+    const Stream = globalThis.DecompressionStream;
+    if (!Stream || !detectRuntimeSupport().has(encoding)) {
+        throw new UnsupportedContentEncodingError(encoding, [encoding]);
+    }
+    const ds = new Stream(encoding);
+    const writer = ds.writable.getWriter();
+    // Feed the whole compressed payload, then close. Errors on the write/close
+    // side (malformed stream) surface as a rejected close; capture rather than
+    // leak an unhandled rejection.
+    let writeError = false;
+    void writer.write(compressed).catch(() => {
+        writeError = true;
+    });
+    const closePromise = writer.close().catch(() => {
+        writeError = true;
+    });
+    const ratioCapBytes = compressed.byteLength * caps.maxRatio;
+    const reader = ds.readable.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > caps.maxDecompressedBytes) {
+                await cancelReader(reader);
+                const info = {
+                    encoding,
+                    compressedBytes: compressed.byteLength,
+                    decompressedBytes: total,
+                    reason: "absolute",
+                };
+                caps.onBomb?.(info);
+                throw new DecompressionBombError(info);
+            }
+            if (total > ratioCapBytes) {
+                await cancelReader(reader);
+                const info = {
+                    encoding,
+                    compressedBytes: compressed.byteLength,
+                    decompressedBytes: total,
+                    reason: "ratio",
+                };
+                caps.onBomb?.(info);
+                throw new DecompressionBombError(info);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (err) {
+        if (err instanceof DecompressionBombError)
+            throw err;
+        throw new MalformedCompressedBodyError(encoding);
+    }
+    await closePromise;
+    if (writeError)
+        throw new MalformedCompressedBodyError(encoding);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * 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 function requestDecompression(opts) {
+    assertPositiveInteger(opts.maxDecompressedBytes, "maxDecompressedBytes");
+    const maxCompressedBytes = opts.maxCompressedBytes ?? DEFAULT_MAX_COMPRESSED_BYTES;
+    assertPositiveInteger(maxCompressedBytes, "maxCompressedBytes");
+    const maxRatio = opts.maxRatio ?? DEFAULT_MAX_RATIO;
+    if (!Number.isFinite(maxRatio) || maxRatio < 1) {
+        throw new TypeError(`requestDecompression(): \`maxRatio\` must be a finite number >= 1, received ${String(maxRatio)}`);
+    }
+    const allowed = (opts.encodings ?? ["gzip", "deflate"]).map((e) => e.toLowerCase());
+    if (allowed.length === 0) {
+        throw new TypeError("requestDecompression(): `encodings` must contain at least one encoding");
+    }
+    for (const enc of allowed) {
+        if (enc !== "gzip" && enc !== "deflate") {
+            throw new TypeError(`requestDecompression(): unsupported encoding "${enc}"; only "gzip" and "deflate" are supported`);
+        }
+    }
+    const allowedSet = new Set(allowed);
+    const caps = {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxRatio,
+        onBomb: opts.onBomb,
+    };
+    return {
+        async onRequest(request) {
+            const ceRaw = request.headers.get("content-encoding");
+            if (!ceRaw)
+                return;
+            const ce = ceRaw.trim().toLowerCase();
+            if (ce === "" || ce === "identity")
+                return;
+            // Layered encodings (e.g. "gzip, gzip") are a classic nested-bomb vector;
+            // refuse rather than inflate recursively.
+            const parts = ce
+                .split(",")
+                .map((p) => p.trim())
+                .filter((p) => p.length > 0);
+            if (parts.length !== 1) {
+                throw new UnsupportedContentEncodingError(ce, allowed);
+            }
+            const encoding = parts[0];
+            if (!allowedSet.has(encoding) || !detectRuntimeSupport().has(encoding)) {
+                throw new UnsupportedContentEncodingError(parts[0], allowed);
+            }
+            // Bodyless methods carry nothing to inflate.
+            const method = request.method.toUpperCase();
+            if (method === "GET" || method === "HEAD")
+                return;
+            // Read the compressed body under the compressed-size cap (413 if over).
+            const compressed = await readBodyLimited(request, maxCompressedBytes);
+            const target = request;
+            if (compressed.byteLength === 0) {
+                target[REQUEST_RAW_BODY] = compressed;
+                return;
+            }
+            const inflated = await inflateGuarded(compressed, encoding, caps);
+            // Defense in depth: the inflated body must still fit the absolute cap.
+            if (inflated.byteLength > caps.maxDecompressedBytes) {
+                throw new PayloadTooLargeError(caps.maxDecompressedBytes);
+            }
+            // Stash the inflated bytes so the framework's body reader returns them
+            // transparently (schema-validated bodies and raw-body handlers alike).
+            target[REQUEST_RAW_BODY] = inflated;
+        },
+    };
+}

package/dist/response-cache.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Server-side response caching for DaloyJS.
+ *
+ * The {@link responseCache} middleware stores rendered response bodies in a
+ * pluggable backend and replays them for subsequent matching requests, so a
+ * hot read endpoint can skip the handler (and its database / upstream calls)
+ * entirely while a cached representation is fresh. It complements — and does
+ * not overlap with — the two caching-adjacent helpers DaloyJS already ships:
+ *
+ * - `etag()` answers conditional `GET`s with `304 Not Modified` but still runs
+ *   the handler to produce the body it hashes.
+ * - `compression()` shrinks the bytes on the wire but caches nothing.
+ *
+ * `responseCache()` is the missing third piece: it caches the **body** so the
+ * handler is not invoked at all on a fresh hit.
+ *
+ * Highlights:
+ *
+ * - **`Cache-Control` orchestration.** Freshness is derived from the response's
+ *   own `Cache-Control` (`s-maxage` wins over `max-age`) when present, falling
+ *   back to the configured `ttlSeconds`. Responses marked `no-store` /
+ *   `private` / `no-cache`, or carrying `Set-Cookie`, are never cached.
+ * - **Request directives.** `Cache-Control: no-store` on the request bypasses
+ *   the cache completely; `no-cache` bypasses the read but still refreshes the
+ *   stored entry (the same directive the background SWR refresh uses, which
+ *   makes revalidation recursion-safe).
+ * - **stale-while-revalidate.** With `staleWhileRevalidateSeconds` plus a
+ *   `revalidate` callback (typically wired to `app.fetch`), a stale-but-recent
+ *   entry is served immediately (marked `X-Cache: STALE`) while a single,
+ *   de-duplicated background refresh repopulates the cache.
+ * - **Pluggable store.** {@link ResponseCacheStore} mirrors `SessionStore` /
+ *   the rate-limit store, with an in-memory {@link MemoryResponseCacheStore}
+ *   default; supply a shared backend (e.g. Redis) for multi-instance fleets.
+ *
+ * This module is dependency-free and uses only Web Standard
+ * `Request`/`Response` + `Headers`, so it runs unchanged on Node, Bun, Deno,
+ * Cloudflare Workers, and Vercel Edge.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Test-only helper that clears the process-wide shared stores used by
+ * `responseCache({ groupId })`. Not part of the documented public API.
+ *
+ * @internal
+ */
+export declare function _resetSharedResponseCacheStoresForTests(): void;
+/**
+ * A cached HTTP response. The body is stored as standard base64 so arbitrary
+ * binary payloads round-trip safely.
+ */
+export interface CachedResponse {
+    /** HTTP status code of the cached response. */
+    status: number;
+    /** Response headers as `[name, value]` pairs (lower-cased by `Headers`). */
+    headers: Array<[string, string]>;
+    /** Base64-encoded response body (empty string for a bodyless response). */
+    body: string;
+    /** Creation time as ms since epoch (drives the `Age` header). */
+    storedAt: number;
+    /** End of the freshness window as ms since epoch. */
+    freshUntil: number;
+    /** End of the stale-while-revalidate window as ms since epoch. */
+    staleUntil: number;
+}
+/**
+ * Pluggable persistence backend for {@link responseCache}. All methods may be
+ * synchronous or asynchronous. Implementations should treat an entry whose
+ * `staleUntil` is in the past as "missing" and may lazily delete it.
+ */
+export interface ResponseCacheStore {
+    /**
+     * Fetch the cached entry for `key`, or `null` when absent / fully expired.
+     */
+    get(key: string): CachedResponse | null | Promise<CachedResponse | null>;
+    /**
+     * Persist `entry` under `key` with the given total time-to-live (freshness +
+     * stale window) in milliseconds.
+     */
+    set(key: string, entry: CachedResponse, ttlMs: number): void | Promise<void>;
+    /** Remove the cached entry for `key`. */
+    delete(key: string): void | Promise<void>;
+}
+/** Options for the {@link responseCache} middleware. */
+export interface ResponseCacheOptions {
+    /** Pluggable persistence backend. Default: a fresh in-memory store. */
+    store?: ResponseCacheStore;
+    /**
+     * Default freshness lifetime in seconds, used when the response carries no
+     * `s-maxage` / `max-age`. Default: `60`.
+     */
+    ttlSeconds?: number;
+    /**
+     * Extra seconds a stale entry may be served while a background refresh runs.
+     * Requires {@link revalidate}. Default: `0` (no stale serving).
+     */
+    staleWhileRevalidateSeconds?: number;
+    /**
+     * Background refresh callback, typically `(req) => app.fetch(req)`. Invoked
+     * (fire-and-forget, de-duplicated per key) with a clone of the original
+     * request carrying `Cache-Control: no-cache` so it bypasses the cached read
+     * but still repopulates the entry. Required to enable
+     * {@link staleWhileRevalidateSeconds}.
+     */
+    revalidate?: (request: Request) => Promise<Response> | Response;
+    /**
+     * HTTP methods eligible for caching. Default: `["GET", "HEAD"]`.
+     */
+    methods?: string[];
+    /**
+     * Decide whether a produced response is cacheable by status. Default: only
+     * `200 OK`.
+     */
+    cacheableStatus?: (status: number) => boolean;
+    /**
+     * Request header names whose values partition the cache (e.g.
+     * `["accept-language"]`). Their values are folded into the cache key.
+     * Default: none.
+     */
+    varyHeaders?: string[];
+    /**
+     * Derive the cache key from the request. Default: method + URL +
+     * {@link varyHeaders} values. Return `null` to skip caching for this request.
+     */
+    keyGenerator?: (ctx: BaseContext<any, any>) => string | null;
+    /**
+     * Maximum response body size (bytes) the middleware will buffer and store.
+     * Larger responses pass through uncached. Default: `1048576` (1 MiB).
+     */
+    maxBodyBytes?: number;
+    /**
+     * Response header marking cache outcome (`HIT` / `MISS` / `STALE`). Set to
+     * `null` to disable. Default: `"x-cache"`.
+     */
+    statusHeaderName?: string | null;
+    /**
+     * Share a single in-memory store across every `responseCache()` mount that
+     * declares the same `groupId`. Only meaningful for the default in-memory
+     * store.
+     */
+    groupId?: string;
+}
+/**
+ * In-memory {@link ResponseCacheStore}. Suitable for tests and single-process
+ * deployments. Expired entries are dropped on access; the map is
+ * opportunistically pruned so it cannot grow without bound.
+ */
+export declare class MemoryResponseCacheStore implements ResponseCacheStore {
+    private readonly map;
+    /** @inheritDoc */
+    get(key: string): CachedResponse | null;
+    /** @inheritDoc */
+    set(key: string, entry: CachedResponse): void;
+    /** @inheritDoc */
+    delete(key: string): void;
+    private prune;
+    /** Test helper. Remove every entry. */
+    clear(): void;
+    /** Test helper. Number of stored entries (including expired). */
+    size(): number;
+}
+/**
+ * Server-side response cache middleware. Mount it ahead of the read endpoints
+ * whose rendered bodies are safe to reuse for a short window.
+ *
+ * Behavior for an eligible method (see {@link ResponseCacheOptions.methods}):
+ *
+ * - **Fresh hit** → the stored response is served and the handler does not run
+ *   (`X-Cache: HIT`, plus an `Age` header).
+ * - **Stale hit within the SWR window** (requires
+ *   {@link ResponseCacheOptions.revalidate}) → the stale response is served
+ *   immediately (`X-Cache: STALE`) while a single background refresh runs.
+ * - **Miss** → the handler runs; a cacheable response is stored
+ *   (`X-Cache: MISS`).
+ *
+ * Request `Cache-Control: no-store` bypasses the cache entirely; `no-cache`
+ * bypasses the read but still refreshes the stored entry. Responses marked
+ * `no-store` / `private` / `no-cache`, carrying `Set-Cookie`, failing
+ * {@link ResponseCacheOptions.cacheableStatus}, or larger than
+ * {@link ResponseCacheOptions.maxBodyBytes} are never cached.
+ *
+ * @example
+ * ```ts
+ * import { App, responseCache } from "@daloyjs/core";
+ *
+ * const app = new App();
+ * app.use(responseCache({ ttlSeconds: 30 }));
+ *
+ * // stale-while-revalidate, wired to the app itself:
+ * app.use(
+ *   responseCache({
+ *     ttlSeconds: 30,
+ *     staleWhileRevalidateSeconds: 300,
+ *     revalidate: (req) => app.fetch(req),
+ *   }),
+ * );
+ * ```
+ *
+ * @param opts - Response-cache configuration.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @since 0.37.0
+ */
+export declare function responseCache(opts?: ResponseCacheOptions): Hooks;