@daloyjs/core 1.0.0-rc.4 → 1.0.0-rc.6

package/dist/response-cache.d.ts

@@ -32,6 +32,31 @@
  *   the rate-limit store, with an in-memory {@link MemoryResponseCacheStore}
  *   default; supply a shared backend (e.g. Redis) for multi-instance fleets.
  *
+ * ## Cross-principal isolation (CWE-524)
+ *
+ * A shared response cache is only as safe as its key. Anything that varies the
+ * response but not the key becomes a cross-principal disclosure: the next caller
+ * of the same URL receives the previous caller's private body. This module is
+ * fail-closed on every principal dimension the framework can see:
+ *
+ * - **Authority.** The key is built from the *effective request URI* (scheme +
+ *   authority + path + query) per RFC 9111 §4, so one process serving several
+ *   hostnames (vanity domains, subdomain-per-customer) never shares an entry
+ *   across them.
+ * - **Credentials.** Requests carrying `Authorization` **or** `Cookie` bypass
+ *   the shared cache entirely unless the caller is identified (see
+ *   {@link ResponseCacheOptions.principal}) or the header is explicitly declared
+ *   shareable (see {@link ResponseCacheOptions.cacheAuthenticatedRequests}).
+ * - **Tenant.** When `tenancy()` has resolved a tenant for the request, that
+ *   tenant is folded into the key automatically — no `keyGenerator` wiring
+ *   required, and it applies to a custom `keyGenerator` too.
+ * - **Declared variants.** A response's own `Vary` header is honoured as a
+ *   secondary key (RFC 9111 §4.1): an entry is replayed only to a request whose
+ *   values for those fields match the ones it was stored with. `cors()` emits
+ *   `Vary: Origin` and `compression()` emits `Vary: Accept-Encoding`, so
+ *   without this one caller's `Access-Control-Allow-Origin` — or their gzipped
+ *   body — would be served to the next. `Vary: *` is never stored.
+ *
  * 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.
@@ -40,6 +65,15 @@
  * @since 0.37.0
  */
 import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Marker stamped on the `Hooks` object returned by {@link responseCache}, so the
+ * `App` boot guard can detect a cache mounted *ahead of* `tenancy()` — an order
+ * in which the tenant is not yet in `ctx.state` when the cache key is built, and
+ * automatic tenant partitioning therefore cannot protect the entry.
+ *
+ * @since 1.0.0
+ */
+export declare const RESPONSE_CACHE_HOOK_MARKER: unique symbol;
 /**
  * Test-only helper that clears the process-wide shared stores used by
  * `responseCache({ groupId })`. Not part of the documented public API.
@@ -64,6 +98,22 @@ export interface CachedResponse {
     freshUntil: number;
     /** End of the stale-while-revalidate window as ms since epoch. */
     staleUntil: number;
+    /**
+     * Lower-cased request-header names from the stored response's `Vary` header —
+     * the secondary cache key per RFC 9111 §4.1. Absent when the response
+     * declared no `Vary`.
+     *
+     * @since 1.0.0
+     */
+    vary?: string[];
+    /**
+     * The values {@link vary}'s fields had on the request that produced this
+     * entry, length-prefix encoded. A stored entry is only reusable for a request
+     * whose values re-encode identically.
+     *
+     * @since 1.0.0
+     */
+    varyKey?: string;
 }
 /**
  * Pluggable persistence backend for {@link responseCache}. All methods may be
@@ -118,13 +168,62 @@ export interface ResponseCacheOptions {
      * Request header names whose values partition the cache (e.g.
      * `["accept-language"]`). Their values are folded into the cache key.
      * Default: none.
+     *
+     * @remarks This is the *proactive* dimension list, applied to every request
+     * before the handler runs. It is independent of — and additive to — the
+     * `Vary` header a response declares for itself, which the cache always
+     * honours as a secondary key (see {@link responseCache}).
      */
     varyHeaders?: string[];
     /**
-     * Derive the cache key from the request. Default: method + URL +
+     * Extra response headers to drop before an entry is stored, on top of the
+     * built-in hop-by-hop / per-request set (`Age`, `Connection`,
+     * `Transfer-Encoding`, `X-Request-Id`, …).
+     *
+     * Supply the name of a custom correlation or tracing header so it is not
+     * frozen into the entry and replayed to every later caller — for example
+     * `requestId({ header: "x-correlation-id" })` pairs with
+     * `excludeHeaders: ["x-correlation-id"]`.
+     *
+     * @since 1.0.0
+     */
+    excludeHeaders?: readonly string[];
+    /**
+     * Derive the cache key **body** from the request. Default: method + the
+     * effective request URI (scheme + authority + path + query) +
      * {@link varyHeaders} values. Return `null` to skip caching for this request.
+     *
+     * The resolved tenant and {@link principal} partition is applied *around*
+     * whatever this returns, so a custom generator does not have to (and should
+     * not bother to) fold them in itself — it cannot accidentally widen the
+     * partition below what the framework knows about the caller.
      */
     keyGenerator?: (ctx: BaseContext<any, any>) => string | null;
+    /**
+     * Identify the caller, so responses to credentialed requests can be cached
+     * *per principal* instead of bypassing the cache.
+     *
+     * Return a stable id for the calling principal (user id, tenant id, API-key
+     * fingerprint — never the raw credential), or `null` / `undefined` when the
+     * request is anonymous. The returned id is folded into the cache key.
+     *
+     * This is what makes cookie-authenticated caching safe: a session cookie
+     * identifies a user that the cache key would otherwise ignore, so without a
+     * `principal` such a request is not cached at all.
+     *
+     * ```ts
+     * responseCache({
+     *   ttlSeconds: 30,
+     *   principal: (ctx) => ctx.state.session?.get<string>("userId") ?? null,
+     * });
+     * ```
+     *
+     * @remarks Returning `null` for a request that *does* carry credentials is
+     * treated as "cannot identify this caller", and the request bypasses the cache
+     * rather than sharing an anonymous entry.
+     * @since 1.0.0
+     */
+    principal?: (ctx: BaseContext<any, any>) => string | null | undefined;
     /**
      * Maximum response body size (bytes) the middleware will buffer and store.
      * Larger responses pass through uncached. Default: `1048576` (1 MiB).
@@ -142,33 +241,79 @@ export interface ResponseCacheOptions {
      */
     groupId?: string;
     /**
-     * Whether to cache responses to requests that carry an `Authorization`
-     * header. Default: `false`.
+     * Whether to cache responses to requests that carry credentials — an
+     * `Authorization` header or a `Cookie` header. Default: `false` for both.
+     *
+     * A shared response cache keyed on the request URI does not include the
+     * credential, so caching a credentialed response would serve one user's
+     * private data to the next caller of the same URL (CWE-524 — cross-principal
+     * cached-response disclosure). Per RFC 9111 §3.5 a shared cache MUST NOT
+     * reuse a response to an `Authorization`-bearing request unless explicitly
+     * permitted; `Cookie` is treated the same way because a session cookie is the
+     * single most common way a response is made private.
      *
-     * A shared response cache keyed on method + URL (the default) does not
-     * include the credential, so caching an authenticated response would serve
-     * one user's private data to the next user requesting the same URL
-     * (CWE-524 — cross-tenant cached-response disclosure). For that reason, and
-     * per RFC 9111 §3.5 (a shared cache MUST NOT reuse a response to an
-     * `Authorization`-bearing request unless explicitly permitted), such
-     * requests bypass the cache entirely by default.
+     * Pass a boolean to set both, or an object to control them independently —
+     * useful when a public endpoint receives unrelated analytics cookies but must
+     * never cache bearer-authenticated responses:
      *
-     * Set this to `true` only when the response is genuinely shareable across
-     * principals (e.g. public reference data served behind a bearer gate) — and
-     * then also add the credential to {@link varyHeaders} or a custom
-     * {@link keyGenerator} so distinct callers cannot collide.
+     * ```ts
+     * responseCache({ cacheAuthenticatedRequests: { cookie: true } });
+     * ```
      *
-     * @since 0.40.0
+     * Enable a dimension only when the response is genuinely shareable across
+     * principals (e.g. public reference data behind a bearer gate). Otherwise
+     * prefer {@link principal}, which keeps caching *and* keeps callers apart.
+     *
+     * @remarks Declaring the credential header in {@link varyHeaders} also counts
+     * as handling it, since its value then partitions the key.
+     * @since 0.40.0 — extended to `Cookie` and per-header control in 1.0.0.
      */
-    cacheAuthenticatedRequests?: boolean;
+    cacheAuthenticatedRequests?: boolean | {
+        authorization?: boolean;
+        cookie?: boolean;
+    };
+}
+/** Options for {@link MemoryResponseCacheStore}. */
+export interface MemoryResponseCacheStoreOptions {
+    /**
+     * Hard ceiling on retained entries. Default: `10_000`. Once reached, the
+     * oldest-inserted entries are evicted — expired ones first.
+     */
+    maxEntries?: number;
+    /**
+     * Hard ceiling on retained body bytes. Default: `64 * 1024 * 1024` (64 MiB).
+     *
+     * An entry count alone does not bound memory: with the module's default
+     * `maxBodyBytes` of 1 MiB, ten thousand entries is ten gigabytes. This is the
+     * limit that actually caps the store's footprint.
+     */
+    maxBytes?: number;
 }
 /**
  * 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.
+ * deployments.
+ *
+ * Expired entries are dropped on access. The map is bounded on **both** entry
+ * count and retained body bytes ({@link MemoryResponseCacheStoreOptions}):
+ * pruning expired entries alone cannot bound it, because every entry in a burst
+ * of requests for distinct URLs is unexpired for the whole TTL. An attacker
+ * rotating a query string would otherwise grow the map without limit until the
+ * process runs out of memory.
+ *
+ * Eviction is FIFO over insertion order (expired entries first), which `Map`
+ * gives in O(1) per eviction.
  */
 export declare class MemoryResponseCacheStore implements ResponseCacheStore {
     private readonly map;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    /** Running sum of `entry.body.length` over `map`, kept in step with writes. */
+    private bytes;
+    /**
+     * @param opts - Capacity limits; see {@link MemoryResponseCacheStoreOptions}.
+     * @throws TypeError if either limit is not a positive integer.
+     */
+    constructor(opts?: MemoryResponseCacheStoreOptions);
     /** @inheritDoc */
     get(key: string): CachedResponse | null;
     /**
@@ -179,7 +324,13 @@ export declare class MemoryResponseCacheStore implements ResponseCacheStore {
     set(key: string, entry: CachedResponse, _ttlMs?: number): void;
     /** @inheritDoc */
     delete(key: string): void;
-    private prune;
+    /** Remove one entry, keeping the byte counter in step. */
+    private drop;
+    /**
+     * Bring the map back under both limits: expired entries first, then
+     * oldest-inserted, since `Map` iterates in insertion order.
+     */
+    private evict;
     /** Test helper. Remove every entry. */
     clear(): void;
     /** Test helper. Number of stored entries (including expired). */
@@ -201,10 +352,17 @@ export declare class MemoryResponseCacheStore implements ResponseCacheStore {
  *
  * 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
+ * `no-store` / `private` / `no-cache`, carrying `Set-Cookie` or `Vary: *`,
+ * failing {@link ResponseCacheOptions.cacheableStatus}, or larger than
  * {@link ResponseCacheOptions.maxBodyBytes} are never cached.
  *
+ * A response that declares `Vary` is stored as a **variant**: the request's
+ * values for those fields are recorded alongside it, and the entry is replayed
+ * only to a request whose values match. A mismatch is a miss, so the handler
+ * runs and the entry is re-stored for that variant. This applies to `Vary`
+ * written by any middleware in the chain — notably `cors()` (`Origin`) and
+ * `compression()` (`Accept-Encoding`) — with no configuration.
+ *
  * @example
  * ```ts
  * import { App, responseCache } from "@daloyjs/core";