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

package/dist/ip-restriction.js

@@ -40,8 +40,7 @@ export function ipRestriction(opts) {
     }
     const allow = (opts.allow ?? []).map(compileCidrMatcher);
     const deny = (opts.deny ?? []).map(compileCidrMatcher);
-    const resolveIp = opts.resolveIp ??
-        (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
     const message = opts.message ?? "IP address not permitted";
     return {
         beforeHandle(ctx) {
@@ -200,11 +199,7 @@ function parseIPv6(input) {
             return undefined;
         const hi = (v4.bytes[0] << 8) | v4.bytes[1];
         const lo = (v4.bytes[2] << 8) | v4.bytes[3];
-        working =
-            working.slice(0, lastColon + 1) +
-                hi.toString(16) +
-                ":" +
-                lo.toString(16);
+        working = working.slice(0, lastColon + 1) + hi.toString(16) + ":" + lo.toString(16);
     }
     const parts = working.split("::");
     if (parts.length > 2)
@@ -217,11 +212,7 @@ function parseIPv6(input) {
     if (parts.length === 1 && explicit !== 8)
         return undefined;
     const missing = parts.length === 2 ? 8 - explicit : 0;
-    const groups = [
-        ...headGroups,
-        ...Array.from({ length: missing }, () => "0"),
-        ...tailGroups,
-    ];
+    const groups = [...headGroups, ...Array.from({ length: missing }, () => "0"), ...tailGroups];
     if (groups.length !== 8)
         return undefined;
     const bytes = new Uint8Array(16);

package/dist/jwt.js

@@ -18,11 +18,7 @@
  * @since 0.21.0
  */
 import { assertTemporalClaims, TemporalClaimError } from "./time-claims.js";
-const SYMMETRIC = new Set([
-    "HS256",
-    "HS384",
-    "HS512",
-]);
+const SYMMETRIC = new Set(["HS256", "HS384", "HS512"]);
 const ASYMMETRIC = new Set([
     "RS256",
     "RS384",
@@ -254,10 +250,14 @@ export function createJwtSigner(opts) {
         opts.key.byteLength < MIN_HS_KEY_BYTES) {
         throw new JwtError("weak_hs_secret", `jwt(): ${alg} secret must be at least ${MIN_HS_KEY_BYTES} bytes (RFC 7518 §3.2); got ${opts.key.byteLength}.`);
     }
-    if (typeof opts.maxLifetimeSeconds !== "number" || !Number.isFinite(opts.maxLifetimeSeconds) || opts.maxLifetimeSeconds <= 0) {
+    if (typeof opts.maxLifetimeSeconds !== "number" ||
+        !Number.isFinite(opts.maxLifetimeSeconds) ||
+        opts.maxLifetimeSeconds <= 0) {
         throw new JwtError("missing_max_lifetime", "jwt(): maxLifetimeSeconds is required and must be a positive number — a token that never expires is wrong in every threat model.");
     }
-    if (opts.acknowledgeNoExp === true && isProductionEnv(opts.env) && opts.secureDefaults !== false) {
+    if (opts.acknowledgeNoExp === true &&
+        isProductionEnv(opts.env) &&
+        opts.secureDefaults !== false) {
         throw new JwtError("ack_no_exp_refused_in_production", "jwt(): acknowledgeNoExp: true is refused in production under secureDefaults — every issued JWT must carry an exp claim.");
     }
     const resolved = (async () => {
@@ -359,18 +359,16 @@ export function createJwtVerifier(opts) {
         allow.add(alg);
     }
     const hasSym = [...allow].some((a) => SYMMETRIC.has(a));
-    if (hasSym &&
-        opts.key instanceof Uint8Array &&
-        opts.key.byteLength < MIN_HS_KEY_BYTES) {
+    if (hasSym && opts.key instanceof Uint8Array && opts.key.byteLength < MIN_HS_KEY_BYTES) {
         throw new JwtError("weak_hs_secret", `jwt(): HS* secret must be at least ${MIN_HS_KEY_BYTES} bytes (RFC 7518 §3.2); got ${opts.key.byteLength}.`);
     }
-    if (hasSym &&
-        opts.refuseSymmetricWithJwk !== false &&
-        looksLikeJwkSource(opts.key)) {
+    if (hasSym && opts.refuseSymmetricWithJwk !== false && looksLikeJwkSource(opts.key)) {
         throw new JwtError("sym_with_jwk_refused", "jwt(): symmetric algorithms (HS*) mixed with a JWK / JWKS key source are refused — this is the documented JWKS confused-deputy attack. Use asymmetric algorithms (RS/PS/ES/EdDSA), or pass refuseSymmetricWithJwk: false to override (not recommended).");
     }
     if (opts.clockSkewSeconds !== undefined) {
-        if (typeof opts.clockSkewSeconds !== "number" || !Number.isFinite(opts.clockSkewSeconds) || opts.clockSkewSeconds < 0) {
+        if (typeof opts.clockSkewSeconds !== "number" ||
+            !Number.isFinite(opts.clockSkewSeconds) ||
+            opts.clockSkewSeconds < 0) {
             throw new JwtError("invalid_clock_skew", "jwt(): clockSkewSeconds must be a non-negative finite number.");
         }
     }

package/dist/logger.js

@@ -377,9 +377,7 @@ function isSensitiveUrlQueryKey(lowerKey) {
  * @since 1.0.0
  */
 export function sanitizeUrlForLog(url) {
-    if (url.indexOf("?") === -1 &&
-        url.indexOf("#") === -1 &&
-        url.indexOf("@") === -1) {
+    if (url.indexOf("?") === -1 && url.indexOf("#") === -1 && url.indexOf("@") === -1) {
         return url;
     }
     try {

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