@daloyjs/core 1.0.0-rc.5 → 1.0.0-rc.7

package/dist/middleware.d.ts

@@ -470,8 +470,22 @@ export interface RateLimitOptions {
      * Trust x-forwarded-for / x-real-ip when deriving the default key.
      * Off by default because those headers are client-spoofable unless your
      * reverse proxy strips and rewrites them.
+     *
+     * When enabled, the key is the **rightmost** `X-Forwarded-For` entry — the
+     * one your immediate proxy appended — never the attacker-influenceable
+     * leftmost one, so rotating spoofed left entries cannot evade the limit.
+     * Behind more than one proxy hop, set {@link trustedHops} instead.
      */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet. Implies proxy-header trust and derives the default key that
+     * many entries from the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}. Must be an integer in
+     * [1, 64]; validated at construction. Ignored when a custom `keyGenerator`
+     * is supplied.
+     */
+    trustedHops?: number;
     /** When true, set Retry-After header on 429. Default: true. */
     retryAfter?: boolean;
     /**
@@ -546,8 +560,24 @@ export interface LoginThrottleOptions {
     keyGenerator?: (ctx: RateLimitContext) => string;
     /** Shared store for the hard limit. Uses rateLimit()'s in-memory group bucket by default. */
     store?: RateLimitStore;
-    /** Trust x-forwarded-for / x-real-ip when deriving the default key. Default: false. */
+    /** Trust x-forwarded-for / x-real-ip when deriving the default key. Default: false.
+     *
+     * When enabled, the key is the **rightmost** `X-Forwarded-For` entry — the
+     * one your immediate proxy appended — never the attacker-influenceable
+     * leftmost one. Behind more than one proxy hop, set {@link trustedHops}
+     * instead.
+     */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet. Implies proxy-header trust and derives the default key that
+     * many entries from the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}, so rotating spoofed
+     * left entries cannot evade the throttle. Must be an integer in [1, 64];
+     * validated at construction. Ignored when a custom `keyGenerator` is
+     * supplied.
+     */
+    trustedHops?: number;
     /** When true, set Retry-After header on 429. Default: true. */
     retryAfter?: boolean;
     /** Start slowing responses after this many attempts in the same window. Default: 2. */

package/dist/middleware.js

@@ -7,6 +7,7 @@
 import { assertCookieAttributes, readRequestCookie, serializeCookie } from "./cookie.js";
 import { TooManyRequestsError, ForbiddenError } from "./errors.js";
 import { randomId, sanitizeHeaderName, timingSafeEqual } from "./security.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 /**
  * Generate or accept a stable `X-Request-ID` for every request. The id is
  * stamped on `ctx.state.requestId`, mirrored on outgoing response headers,
@@ -775,15 +776,8 @@ export function rateLimit(opts) {
         store = new MemoryStore();
     }
     const groupPrefix = opts.groupId ? `${opts.groupId}:` : "";
-    const keyOf = opts.keyGenerator ??
-        ((ctx) => {
-            if (opts.trustProxyHeaders) {
-                const xff = ctx.request.headers.get("x-forwarded-for");
-                const first = xff ? xff.split(",")[0].trim() : "";
-                return first || ctx.request.headers.get("x-real-ip") || "global";
-            }
-            return "global";
-        });
+    const hops = resolveForwardedTrust("rateLimit()", opts);
+    const keyOf = opts.keyGenerator ?? defaultForwardedRateLimitKey(hops);
     const enforce = async (ctx) => {
         const key = `${groupPrefix}${keyOf(ctx)}`;
         const { count, resetMs } = await store.hit(key, opts.windowMs);
@@ -811,15 +805,22 @@ function assertPositiveInteger(name, value) {
         throw new Error(`loginThrottle(): ${name} must be a positive integer.`);
     }
 }
-function defaultLoginThrottleKey(trustProxyHeaders) {
-    return (ctx) => {
-        if (trustProxyHeaders) {
-            const forwardedFor = ctx.request.headers.get("x-forwarded-for");
-            const firstForwarded = forwardedFor ? forwardedFor.split(",")[0].trim() : "";
-            return firstForwarded || ctx.request.headers.get("x-real-ip") || "global";
-        }
-        return "global";
-    };
+/**
+ * Default rate-limit / login-throttle key: the spoof-resistant forwarded client
+ * IP, or the shared `"global"` bucket when proxy-header trust is off or the
+ * request carries no trustworthy forwarded identity.
+ *
+ * @param hops - Trusted proxy hop count from
+ *   {@link "./conn-info.js".resolveForwardedTrust}, or `undefined` when
+ *   forwarded-header trust is disabled.
+ * @returns A key generator suitable for {@link rateLimit} and
+ *   {@link loginThrottle}.
+ * @internal
+ */
+function defaultForwardedRateLimitKey(hops) {
+    if (hops === undefined)
+        return () => "global";
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops) ?? "global";
 }
 function wait(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -852,7 +853,8 @@ export function loginThrottle(opts = {}) {
     assertNonNegativeInteger("delayMs", delayMs);
     assertNonNegativeInteger("maxDelayMs", maxDelayMs);
     const groupId = opts.groupId ?? "login";
-    const keyGenerator = opts.keyGenerator ?? defaultLoginThrottleKey(opts.trustProxyHeaders);
+    const hops = resolveForwardedTrust("loginThrottle()", opts);
+    const keyGenerator = opts.keyGenerator ?? defaultForwardedRateLimitKey(hops);
     const limiter = rateLimit({
         windowMs,
         max,

package/dist/multipart.js

@@ -55,9 +55,7 @@ function isBlobLike(v) {
     if (v == null || typeof v !== "object")
         return false;
     const b = v;
-    return (typeof b.size === "number" &&
-        typeof b.type === "string" &&
-        typeof b.arrayBuffer === "function");
+    return (typeof b.size === "number" && typeof b.type === "string" && typeof b.arrayBuffer === "function");
 }
 function mimeMatches(actual, pattern) {
     const a = actual.toLowerCase();
@@ -137,11 +135,7 @@ function normalizeCustomMagicSignature(value) {
             throw new Error("fileField(): magicBytes.bytes entries must be integers in [0, 255].");
         }
     }
-    const mimes = value.mime === undefined
-        ? []
-        : typeof value.mime === "string"
-            ? [value.mime]
-            : [...value.mime];
+    const mimes = value.mime === undefined ? [] : typeof value.mime === "string" ? [value.mime] : [...value.mime];
     return {
         label: value.label ?? bytes.map((byte) => byte.toString(16).padStart(2, "0")).join(" "),
         mimes,
@@ -186,9 +180,10 @@ function asciiPrefix(bytes) {
         const byte = bytes[i];
         // Keep printable ASCII + common whitespace; replace everything else with
         // a space so keyword searches still work across NULs / UTF-16 padding.
-        out += byte === 0x09 || byte === 0x0a || byte === 0x0d || (byte >= 0x20 && byte <= 0x7e)
-            ? String.fromCharCode(byte)
-            : " ";
+        out +=
+            byte === 0x09 || byte === 0x0a || byte === 0x0d || (byte >= 0x20 && byte <= 0x7e)
+                ? String.fromCharCode(byte)
+                : " ";
     }
     return out.toLowerCase();
 }
@@ -200,7 +195,9 @@ function detectScriptableImagePayload(bytes) {
     }
     // ImageMagick MVG / MSL — vector / scripting formats that can shell out
     // through the `url:`, `ephemeral:`, `msl:` coders (ImageTragick).
-    if (prefix.includes("push graphic-context") || prefix.startsWith("<msl>") || prefix.includes("<image ")) {
+    if (prefix.includes("push graphic-context") ||
+        prefix.startsWith("<msl>") ||
+        prefix.includes("<image ")) {
         return "mvg-or-msl";
     }
     // SVG — XML-based and routinely carries `<script>` / external references.

package/dist/openapi.d.ts

@@ -14,7 +14,7 @@ export { httpBearerScheme, httpBasicScheme, apiKeyScheme, oauth2Scheme, openIdCo
 export type { ApiKeyLocation, ApiKeyScheme, ApiKeySchemeOptions, HttpBasicScheme, HttpBasicSchemeOptions, HttpBearerScheme, HttpBearerSchemeOptions, OAuth2AuthorizationCodeFlow, OAuth2ClientCredentialsFlow, OAuth2Flows, OAuth2ImplicitFlow, OAuth2PasswordFlow, OAuth2Scheme, OAuth2SchemeOptions, OpenIdConnectScheme, OpenIdConnectSchemeOptions, SecurityScheme, } from "./security-schemes.js";
 export { discriminator, discriminatedUnion } from "./discriminator.js";
 export type { DiscriminatorObject, DiscriminatedUnion, DiscriminatedUnionOptions, } from "./discriminator.js";
-export type { CallbackDefinition, CallbackMap, CallbackOperation, } from "./types.js";
+export type { CallbackDefinition, CallbackMap, CallbackOperation } from "./types.js";
 /** OpenAPI [Info Object](https://spec.openapis.org/oas/v3.1.0#info-object) header fields. */
 export interface OpenAPIInfo {
     /** Human-readable API title shown by Swagger UI / Scalar. */

package/dist/openapi.js

@@ -102,8 +102,8 @@ function buildOperation(route, path) {
     const mergedTags = mergeTags(route.tags, meta?.tags);
     const op = {
         ...(route.operationId ? { operationId: route.operationId } : {}),
-        ...(route.summary ?? meta?.summary ? { summary: route.summary ?? meta?.summary } : {}),
-        ...(route.description ?? meta?.description
+        ...((route.summary ?? meta?.summary) ? { summary: route.summary ?? meta?.summary } : {}),
+        ...((route.description ?? meta?.description)
             ? { description: route.description ?? meta?.description }
             : {}),
         ...(mergedTags.length ? { tags: mergedTags } : {}),

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

@@ -64,10 +64,10 @@ export interface RedisRateLimitStoreOptions {
      */
     prefix?: string;
     /**
-    * Called when the underlying Redis call throws. The default behavior is
-    * fail-open, which allows the request and reports it as the first hit in a
-    * fresh local window. Override to fail-closed or to wire into your
-    * structured logger.
+     * Called when the underlying Redis call throws. The default behavior is
+     * fail-open, which allows the request and reports it as the first hit in a
+     * fresh local window. Override to fail-closed or to wire into your
+     * structured logger.
      */
     onError?: (err: unknown) => "fail-open" | "fail-closed";
 }

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