@zudojs/http 1.2.0 → 1.3.0

package/dist/httpAdapter/http.adapters.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { HTTPContext, HTTPHandler, HTTPMiddleware, HTTPRequest, HTTPResponse, HTTPRouteMatch, HTTPState } from "../httpTypes/http.types.js";
+import type { TrustProxy } from "../httpTrustProxy/httpTrustProxy.type.js";
 export interface HTTPAdapter<State extends HTTPState = HTTPState> {
     readonly name: string;
     createRequest(request: IncomingMessage): HTTPRequest;
@@ -9,9 +10,21 @@ export interface HTTPAdapter<State extends HTTPState = HTTPState> {
         readonly signal?: AbortSignal;
     }): HTTPContext<State>;
 }
+/**
+ * Options every Node request built by this module accepts.
+ *
+ * `trustProxy` defaults to `false`, so `X-Forwarded-For` and
+ * `X-Forwarded-Proto` are ignored and the socket peer decides `request.ip`,
+ * `request.protocol` and `request.secure`.
+ */
+export interface NodeRequestTrustOptions {
+    readonly trustProxy?: TrustProxy;
+}
 export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implements HTTPAdapter<State> {
     readonly name = "node";
-    createRequest(request: IncomingMessage): HTTPRequest;
+    private readonly trustProxy;
+    constructor(options?: NodeRequestTrustOptions);
+    createRequest(request: IncomingMessage, options?: NodeRequestTrustOptions): HTTPRequest;
     createResponse(response: ServerResponse): HTTPResponse;
     createContext(request: HTTPRequest, response: HTTPResponse, options?: {
         readonly state?: State;
@@ -20,12 +33,19 @@ export declare class NodeHTTPAdapter<State extends HTTPState = HTTPState> implem
 }
 export interface HTTPAdapterOptions<State extends HTTPState = HTTPState> {
     readonly adapter?: HTTPAdapter<State>;
+    /**
+     * Which socket peers may speak for a client through `X-Forwarded-*`.
+     * Defaults to `false` — forwarded headers are ignored.
+     */
+    readonly trustProxy?: TrustProxy;
 }
-export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(): NodeHTTPAdapter<State>;
+export declare function createHTTPAdapter<State extends HTTPState = HTTPState>(options?: NodeRequestTrustOptions): NodeHTTPAdapter<State>;
 export interface RequestAdapter {
     toHTTPRequest(request: IncomingMessage): HTTPRequest;
 }
 export declare class NodeRequestAdapter implements RequestAdapter {
+    private readonly trustProxy;
+    constructor(options?: NodeRequestTrustOptions);
     toHTTPRequest(request: IncomingMessage): HTTPRequest;
 }
 export interface ResponseAdapter {
@@ -61,11 +81,12 @@ export declare class DefaultHTTPMiddlewareAdapter<State extends HTTPState = HTTP
 export interface HTTPRouteAdapter<State extends HTTPState = HTTPState> {
     match(method: string, path: string): HTTPRouteMatch<State> | undefined;
 }
-export declare function adaptNodeRequest(request: IncomingMessage): HTTPRequest;
+export declare function adaptNodeRequest(request: IncomingMessage, options?: NodeRequestTrustOptions): HTTPRequest;
 export declare function adaptNodeResponse(response: ServerResponse): HTTPResponse;
 export declare function adaptNodeContext<State extends HTTPState = HTTPState>(request: IncomingMessage, response: ServerResponse, options?: {
     readonly state?: State;
     readonly signal?: AbortSignal;
+    readonly trustProxy?: TrustProxy;
 }): HTTPContext<State>;
 export declare function isHTTPAdapter(value: unknown): value is HTTPAdapter;
 //# sourceMappingURL=http.adapters.d.ts.map

package/dist/httpAdapter/http.adapters.js

@@ -2,13 +2,16 @@ import { createHTTPContext } from "../httpContext/http.context.js";
 import { createHTTPRequest } from "../httpRequest/http.request.js";
 import { createHTTPResponse } from "../httpResponse/http.response.js";
 import { createDefaultContextLogger } from "./httpAdapter.logger.js";
-/* -------------------------------------------------------------------------- */
-/* Node Adapter                                                               */
-/* -------------------------------------------------------------------------- */
 export class NodeHTTPAdapter {
     name = "node";
-    createRequest(request) {
-        return createHTTPRequest(request);
+    trustProxy;
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy ?? false;
+    }
+    createRequest(request, options = {}) {
+        return createHTTPRequest(request, {
+            trustProxy: options.trustProxy ?? this.trustProxy,
+        });
     }
     createResponse(response) {
         return createHTTPResponse(response);
@@ -26,12 +29,16 @@ export class NodeHTTPAdapter {
 /* -------------------------------------------------------------------------- */
 /* Adapter Factory                                                             */
 /* -------------------------------------------------------------------------- */
-export function createHTTPAdapter() {
-    return new NodeHTTPAdapter();
+export function createHTTPAdapter(options = {}) {
+    return new NodeHTTPAdapter(options);
 }
 export class NodeRequestAdapter {
+    trustProxy;
+    constructor(options = {}) {
+        this.trustProxy = options.trustProxy ?? false;
+    }
     toHTTPRequest(request) {
-        return createHTTPRequest(request);
+        return createHTTPRequest(request, { trustProxy: this.trustProxy });
     }
 }
 export class NodeResponseAdapter {
@@ -76,15 +83,17 @@ export class DefaultHTTPMiddlewareAdapter {
 /* -------------------------------------------------------------------------- */
 /* Request Conversion Helpers                                                  */
 /* -------------------------------------------------------------------------- */
-export function adaptNodeRequest(request) {
-    return createHTTPRequest(request);
+export function adaptNodeRequest(request, options = {}) {
+    return createHTTPRequest(request, {
+        trustProxy: options.trustProxy ?? false,
+    });
 }
 export function adaptNodeResponse(response) {
     return createHTTPResponse(response);
 }
 export function adaptNodeContext(request, response, options = {}) {
     return createHTTPContext({
-        request: adaptNodeRequest(request),
+        request: adaptNodeRequest(request, { trustProxy: options.trustProxy }),
         response: adaptNodeResponse(response),
         state: options.state ?? {},
         signal: options.signal,

package/dist/httpAdapter/node/httpNode.request.js

@@ -6,7 +6,7 @@
 import { HttpRequestContext, createRequestContext, } from "../../httpRequest/httpRequest.context.js";
 import { getClientIp, isTrustedProxy, } from "../../httpTrustProxy/httpTrustProxy.core.js";
 import { removePort, extractPort } from "./httpNode.server.js";
-import { parseQueryString } from "../../httpQuery/http.query.js";
+import { parseQueryString } from "../../httpQuery/index.js";
 import { findRequestTargetViolation } from "../../httpRequest/target/httpRequest.target.js";
 /* -------------------------------------------------------------------------- */
 /* Proxy Trust                                                                */

package/dist/httpAgent/http.agent.d.ts

@@ -46,9 +46,28 @@ export interface AgentRegistryKey {
     readonly name?: string;
 }
 export declare function getOrCreateAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): HTTPAgentInstance;
-export declare function getAgent(key: string | AgentRegistryKey): HTTPAgentInstance | undefined;
-export declare function hasAgent(key: string | AgentRegistryKey): boolean;
-export declare function removeAgent(key: string | AgentRegistryKey, destroy?: boolean): boolean;
+/**
+ * Looks up a registered agent.
+ *
+ * `options` must be the same TLS-relevant options `getOrCreateAgent` was
+ * given, because they are part of the key; omitting them looks up the agent
+ * created with no options.
+ */
+export declare function getAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): HTTPAgentInstance | undefined;
+/**
+ * Whether an agent is registered for this key and TLS option set.
+ */
+export declare function hasAgent(key: string | AgentRegistryKey, options?: HTTPAgentConfig | HTTPSAgentConfig): boolean;
+/**
+ * Removes registered agents for a key.
+ *
+ * With `options` the single matching agent is removed; without them every
+ * agent registered for that host is removed, whatever TLS options it was
+ * created with, so a per-host teardown releases all of its sockets.
+ *
+ * @returns Whether anything was removed.
+ */
+export declare function removeAgent(key: string | AgentRegistryKey, destroy?: boolean, options?: HTTPAgentConfig | HTTPSAgentConfig): boolean;
 export declare function clearAgents(destroy?: boolean): void;
 export declare function getRegisteredAgentKeys(): string[];
 export declare function getDefaultHTTPAgent(): HTTPAgent;

package/dist/httpAgent/http.agent.js

@@ -113,7 +113,7 @@ export function getOrCreateAgent(key, options = {}) {
      * passing `rejectUnauthorized: false` would have disabled certificate
      * verification for a caller that had pinned a CA, with no way to detect it.
      */
-    const cacheKey = `${registryKey}|${tlsFingerprint(options)}`;
+    const cacheKey = agentCacheKey(registryKey, options);
     const existing = agentRegistry.get(cacheKey);
     if (existing) {
         return existing;
@@ -127,6 +127,18 @@ export function getOrCreateAgent(key, options = {}) {
     agentRegistry.set(cacheKey, agent);
     return agent;
 }
+/**
+ * Builds the registry key an agent is stored under.
+ *
+ * Every read and write goes through this one helper. `getOrCreateAgent` used
+ * to append the TLS fingerprint while `getAgent`, `hasAgent` and
+ * `removeAgent` looked up the bare registry key, so every lookup missed and
+ * the documented per-host teardown silently leaked the agent and its
+ * keep-alive sockets.
+ */
+function agentCacheKey(registryKey, options) {
+    return `${registryKey}|${tlsFingerprint(options)}`;
+}
 /**
  * Builds a stable fingerprint of the TLS-relevant fields of an agent config.
  */
@@ -156,23 +168,49 @@ function describeCredential(value) {
     }
     return "opaque";
 }
-export function getAgent(key) {
-    return agentRegistry.get(normalizeRegistryKey(key));
+/**
+ * Looks up a registered agent.
+ *
+ * `options` must be the same TLS-relevant options `getOrCreateAgent` was
+ * given, because they are part of the key; omitting them looks up the agent
+ * created with no options.
+ */
+export function getAgent(key, options = {}) {
+    return agentRegistry.get(agentCacheKey(normalizeRegistryKey(key), options));
 }
-export function hasAgent(key) {
-    return agentRegistry.has(normalizeRegistryKey(key));
+/**
+ * Whether an agent is registered for this key and TLS option set.
+ */
+export function hasAgent(key, options = {}) {
+    return agentRegistry.has(agentCacheKey(normalizeRegistryKey(key), options));
 }
-export function removeAgent(key, destroy = true) {
+/**
+ * Removes registered agents for a key.
+ *
+ * With `options` the single matching agent is removed; without them every
+ * agent registered for that host is removed, whatever TLS options it was
+ * created with, so a per-host teardown releases all of its sockets.
+ *
+ * @returns Whether anything was removed.
+ */
+export function removeAgent(key, destroy = true, options) {
     const registryKey = normalizeRegistryKey(key);
-    const agent = agentRegistry.get(registryKey);
-    if (!agent) {
-        return false;
-    }
-    agentRegistry.delete(registryKey);
-    if (destroy) {
-        agent.destroy();
+    const cacheKeys = options === undefined
+        ? Array.from(agentRegistry.keys()).filter((candidate) => candidate.startsWith(`${registryKey}|`))
+        : [agentCacheKey(registryKey, options)];
+    let removed = false;
+    for (const cacheKey of cacheKeys) {
+        const agent = agentRegistry.get(cacheKey);
+        if (!agent) {
+            continue;
+        }
+        agentRegistry.delete(cacheKey);
+        if (destroy) {
+            agent.destroy();
+        }
+        removed = true;
     }
-    return true;
+    return removed;
 }
 export function clearAgents(destroy = true) {
     if (destroy) {

package/dist/httpCacheControl/httpCacheControl.freshness.d.ts

@@ -12,11 +12,17 @@ import type { CacheFreshness } from "./core/httpCacheControl.type.js";
  * the origin marked must-revalidate-before-reuse must never be reported
  * fresh.
  *
+ * The response's current age follows RFC 9111 section 4.2.3: the `Age`
+ * header plus the time elapsed since the response's `Date`. Reading `Age`
+ * alone — as this used to — left every response without that header aged
+ * `0` forever, so `isFresh()` answered `true` for a response of any age.
+ *
  * @param responseHeaders - The cached response's headers.
  * @param responseDate - The response's `Date`, if already parsed.
+ * @param now - The current time, defaulting to `Date.now()`.
  * @returns The freshness calculation.
  */
-export declare function calculateFreshness(responseHeaders: Readonly<Record<string, string>>, responseDate?: Date): CacheFreshness;
+export declare function calculateFreshness(responseHeaders: Readonly<Record<string, string>>, responseDate?: Date, now?: Date): CacheFreshness;
 /**
  * Determines if a cached response is still fresh.
  */

package/dist/httpCacheControl/httpCacheControl.freshness.js

@@ -12,24 +12,37 @@ import { parseCacheControl } from "./core/httpCacheControl.parse.js";
  * the origin marked must-revalidate-before-reuse must never be reported
  * fresh.
  *
+ * The response's current age follows RFC 9111 section 4.2.3: the `Age`
+ * header plus the time elapsed since the response's `Date`. Reading `Age`
+ * alone — as this used to — left every response without that header aged
+ * `0` forever, so `isFresh()` answered `true` for a response of any age.
+ *
  * @param responseHeaders - The cached response's headers.
  * @param responseDate - The response's `Date`, if already parsed.
+ * @param now - The current time, defaulting to `Date.now()`.
  * @returns The freshness calculation.
  */
-export function calculateFreshness(responseHeaders, responseDate) {
+export function calculateFreshness(responseHeaders, responseDate, now = new Date()) {
     const cacheControl = responseHeaders["cache-control"];
     const directives = parseCacheControl(cacheControl);
-    const date = responseDate ?? new Date(responseHeaders["date"] ?? Date.now());
+    const date = responseDate ?? parseDateHeader(responseHeaders["date"], now);
     /*
      * RFC 9111 section 5.1: Age is a non-negative delta-seconds. A negative or
      * suffixed value would otherwise inflate freshness without bound, which
      * pins a poisoned response in cache far past the origin's TTL.
      */
     const rawAge = (responseHeaders["age"] ?? "").trim();
-    const age = /^\d+$/.test(rawAge) ? Number(rawAge) : 0;
+    const ageHeader = /^\d+$/.test(rawAge) ? Number(rawAge) : 0;
+    const residentSeconds = Math.max(0, Math.floor((now.getTime() - date.getTime()) / 1_000));
+    const age = ageHeader + residentSeconds;
     const expiresHeader = responseHeaders["expires"];
     const expires = expiresHeader ? parseExpires(expiresHeader) : undefined;
     const effectiveMaxAge = resolveMaxAge(directives, expires, date);
+    /*
+     * With an `Expires`-derived lifetime this reduces to `expires - now`,
+     * because the lifetime is measured from `Date` and the age is measured to
+     * `now`.
+     */
     const remaining = Math.max(0, effectiveMaxAge - age);
     const stale = remaining <= 0 ||
         directives.noCache === true ||
@@ -43,6 +56,20 @@ export function calculateFreshness(responseHeaders, responseDate) {
         remaining,
     };
 }
+/**
+ * Parses a `Date` header, falling back to the current time.
+ *
+ * @param value - The raw `Date` value.
+ * @param now - The fallback instant.
+ * @returns The parsed date.
+ */
+function parseDateHeader(value, now) {
+    if (value === undefined) {
+        return now;
+    }
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? now : parsed;
+}
 /**
  * Parses an `Expires` header, treating an unparseable value as expired.
  *

package/dist/httpKeepAlive/httpKeepAlive.core.js

@@ -7,6 +7,7 @@
  * Transport-specific socket management belongs to the server/client adapter
  * layer. This module only handles HTTP-level semantics.
  */
+import { assertSafeHeaderValue, escapeHeaderQuotedString, } from "../httpHeaders/security/index.js";
 /* -------------------------------------------------------------------------- */
 /* Constants                                                                  */
 /* -------------------------------------------------------------------------- */
@@ -121,7 +122,9 @@ export function formatKeepAliveHeader(parameters = {}) {
             parts.push(`${key}=${quoteIfNeeded(value)}`);
         }
     }
-    return parts.join(", ");
+    const header = parts.join(", ");
+    assertSafeHeaderValue(header);
+    return header;
 }
 /* -------------------------------------------------------------------------- */
 /* Connection Header                                                          */
@@ -348,10 +351,19 @@ function unquote(value) {
     }
     return trimmed;
 }
+/**
+ * Emits a Keep-Alive parameter value.
+ *
+ * Quoting does not neutralise a CR or LF, so the control character used to
+ * survive into the field value. `escapeHeaderQuotedString` rejects it, the
+ * same helper every other quoted-parameter emitter in this package uses.
+ *
+ * @throws {TypeError} If the value contains a forbidden control character.
+ */
 function quoteIfNeeded(value) {
     if (/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(value)) {
         return value;
     }
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    return `"${escapeHeaderQuotedString(value)}"`;
 }
 //# sourceMappingURL=httpKeepAlive.core.js.map

package/dist/httpMiddleware/builtin/logging/httpMiddleware.logging.d.ts

@@ -11,6 +11,24 @@ export interface RequestLogger {
 export interface LoggingMiddlewareOptions {
     readonly logger?: RequestLogger;
     readonly includeHeaders?: boolean;
+    /**
+     * Extra header names whose value must be replaced with `[REDACTED]`, on top
+     * of the credential-bearing names `@zudojs/logger` already recognises
+     * (`authorization`, `proxy-authorization`, `cookie`, `set-cookie`, …).
+     */
+    readonly redactHeaders?: readonly string[];
 }
+/**
+ * Creates the request/response logging middleware.
+ *
+ * With `includeHeaders` the header record is redacted before it reaches the
+ * logger, using the same matcher `@zudojs/logger` applies to log metadata.
+ * It used to be copied verbatim, so a bearer token and the whole session
+ * cookie landed in the log store on every request.
+ *
+ * @param options - Logger, header inclusion and extra redacted names.
+ * @returns A middleware that logs the start, completion and failure of a
+ *   request.
+ */
 export declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.logging.d.ts.map

package/dist/httpMiddleware/builtin/logging/httpMiddleware.logging.js

@@ -3,8 +3,24 @@
  *
  * @module httpMiddleware/builtin/logging
  */
+import { createSecretMatcher, redactLogValue } from "@zudojs/logger";
 import { getRequestMethod, getRequestUrl, getRequestHeaders, getResponseStatus, } from "../helpers/index.js";
+/**
+ * Creates the request/response logging middleware.
+ *
+ * With `includeHeaders` the header record is redacted before it reaches the
+ * logger, using the same matcher `@zudojs/logger` applies to log metadata.
+ * It used to be copied verbatim, so a bearer token and the whole session
+ * cookie landed in the log store on every request.
+ *
+ * @param options - Logger, header inclusion and extra redacted names.
+ * @returns A middleware that logs the start, completion and failure of a
+ *   request.
+ */
 export function createLoggingMiddleware(options = {}) {
+    const isSecret = createSecretMatcher({
+        keys: options.redactHeaders ? [...options.redactHeaders] : undefined,
+    });
     return async (context, next) => {
         const startedAt = Date.now();
         const request = context.request;
@@ -14,7 +30,7 @@ export function createLoggingMiddleware(options = {}) {
             url: getRequestUrl(request),
             ...(options.includeHeaders
                 ? {
-                    headers: getRequestHeaders(request),
+                    headers: redactLogValue(getRequestHeaders(request), isSecret),
                 }
                 : {}),
         });

package/dist/httpMiddleware/builtin/security/httpMiddleware.security.d.ts

@@ -17,5 +17,16 @@ export interface SecurityMiddlewareOptions {
      */
     readonly useDefaults?: boolean;
 }
+/**
+ * Creates the response-hardening middleware.
+ *
+ * Called with no options it emits the package's default security header set
+ * ({@link createDefaultSecurityHeaderOptions}); the options below layer over
+ * that set, and `useDefaults: false` drops it entirely.
+ *
+ * @param options - Explicit header values, layered over the baseline.
+ * @returns A middleware that adds the headers to the downstream response.
+ * @throws {TypeError} If a configured value contains a control character.
+ */
 export declare function createSecurityMiddleware(options?: SecurityMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.security.d.ts.map

package/dist/httpMiddleware/builtin/security/httpMiddleware.security.js

@@ -4,19 +4,34 @@
  * @module httpMiddleware/builtin/security
  */
 import { isValidHeaderFieldValue } from "../../../httpHeaders/security/index.js";
+import { createSecurityHeaders } from "../../../httpSecurityHeaders/httpSecurityHeader.factory.js";
+import { createDefaultSecurityHeaderOptions } from "../../../httpSecurityHeaders/httpSecurityHeader.recommended.js";
 import { withResponseHeaders } from "../helpers/index.js";
 /**
- * Headers applied when the caller does not override them.
+ * The headers applied when the caller does not override them.
  *
- * `createSecurityMiddleware()` previously defaulted every option to
- * `undefined` and therefore set no headers at all — its presence in a
- * codebase read as evidence that the control existed while shipping nothing.
+ * This is the package's declared safe baseline — the very set
+ * `createDefaultSecurityHeaderOptions` was written for and, until now, was
+ * never called for. The middleware used to re-derive its own three-entry
+ * list, so `pipeline.use(createSecurityMiddleware())` emitted no
+ * `Content-Security-Policy`, no `Strict-Transport-Security`, no
+ * `Permissions-Policy` and none of the cross-origin isolation headers while
+ * reading as evidence that the control was in force.
+ */
+function defaultSecurityHeaders() {
+    return createSecurityHeaders(createDefaultSecurityHeaderOptions());
+}
+/**
+ * Creates the response-hardening middleware.
+ *
+ * Called with no options it emits the package's default security header set
+ * ({@link createDefaultSecurityHeaderOptions}); the options below layer over
+ * that set, and `useDefaults: false` drops it entirely.
+ *
+ * @param options - Explicit header values, layered over the baseline.
+ * @returns A middleware that adds the headers to the downstream response.
+ * @throws {TypeError} If a configured value contains a control character.
  */
-const DEFAULT_SECURITY_HEADERS = Object.freeze({
-    "x-content-type-options": "nosniff",
-    "x-frame-options": "DENY",
-    "referrer-policy": "strict-origin-when-cross-origin",
-});
 export function createSecurityMiddleware(options = {}) {
     const configured = {
         "strict-transport-security": options.strictTransportSecurity,
@@ -26,9 +41,7 @@ export function createSecurityMiddleware(options = {}) {
         "content-security-policy": options.contentSecurityPolicy,
         "referrer-policy": options.referrerPolicy,
     };
-    const resolved = {
-        ...(options.useDefaults === false ? {} : DEFAULT_SECURITY_HEADERS),
-    };
+    const resolved = options.useDefaults === false ? {} : defaultSecurityHeaders();
     for (const [name, value] of Object.entries(configured)) {
         if (value === undefined) {
             continue;

package/dist/httpNegotiation/httpNegotiation.core.d.ts

@@ -99,6 +99,19 @@ export declare function negotiateCharset(header: string | undefined | null, avai
  * @returns The selected alternative, or `undefined` if none is acceptable.
  */
 export declare function negotiate<T>(preferences: readonly NegotiationPreference[], available: readonly T[], matcher: (accepted: string, available: T) => boolean): T | undefined;
+/**
+ * Returns the weight a preference list assigns to one value.
+ *
+ * The **most specific** match wins, and only then the highest weight, per
+ * RFC 9110 section 12.4.2. Ranking by weight first let `*;q=1` override an
+ * explicit `gzip;q=0`, so a coding the client had refused came back with
+ * full quality.
+ *
+ * @param preferences - The parsed preferences.
+ * @param value - The alternative to weigh.
+ * @param matcher - Matches a preference value against an alternative.
+ * @returns The quality in `[0, 1]`, or `0` when nothing matches.
+ */
 export declare function getPreferenceQuality<T>(preferences: readonly NegotiationPreference[], value: T, matcher: (accepted: string, available: T) => boolean): number;
 export declare function normalizeMediaType(value: string): string;
 export declare function splitMediaType(value: string): [string, string] | undefined;

package/dist/httpNegotiation/httpNegotiation.core.js

@@ -214,7 +214,36 @@ export function negotiateEncoding(header, available) {
     if (preferences.length === 0) {
         return available[0];
     }
-    return negotiate(preferences, available, matchesEncoding);
+    const selected = negotiate(preferences, available, matchesEncoding);
+    if (selected !== undefined) {
+        return selected;
+    }
+    /*
+     * RFC 9110 section 12.5.3: a representation with no content coding is
+     * acceptable unless the field explicitly excludes it with `identity;q=0`
+     * or a `*;q=0` that no identity entry overrides. Returning `undefined`
+     * here made `Accept-Encoding: zstd` look like "nothing is acceptable", so
+     * a caller answered 406 for a request it could have served uncompressed.
+     */
+    const identity = available.find((value) => isIdentityEncoding(value));
+    if (identity === undefined || isIdentityRejected(preferences)) {
+        return undefined;
+    }
+    return identity;
+}
+/**
+ * Reports whether an `Accept-Encoding` field rejects the identity coding.
+ *
+ * @param preferences - The parsed preferences.
+ * @returns `true` when identity must not be served.
+ */
+function isIdentityRejected(preferences) {
+    const explicit = preferences.find((preference) => isIdentityEncoding(preference.value));
+    if (explicit) {
+        return !isAcceptableQuality(explicit.quality);
+    }
+    const wildcard = preferences.find((preference) => isWildcardEncoding(preference.value));
+    return wildcard !== undefined && !isAcceptableQuality(wildcard.quality);
 }
 export function getEncodingQuality(header, encoding) {
     const preferences = parseAcceptEncoding(header);
@@ -319,20 +348,43 @@ function isExcluded(candidate, selected, rejections, matcher) {
     return rejections.some((rejection) => rejection.specificity >= selected.specificity &&
         matcher(rejection.value, candidate));
 }
+/**
+ * Returns the weight a preference list assigns to one value.
+ *
+ * The **most specific** match wins, and only then the highest weight, per
+ * RFC 9110 section 12.4.2. Ranking by weight first let `*;q=1` override an
+ * explicit `gzip;q=0`, so a coding the client had refused came back with
+ * full quality.
+ *
+ * @param preferences - The parsed preferences.
+ * @param value - The alternative to weigh.
+ * @param matcher - Matches a preference value against an alternative.
+ * @returns The quality in `[0, 1]`, or `0` when nothing matches.
+ */
 export function getPreferenceQuality(preferences, value, matcher) {
     let best;
     for (const preference of preferences) {
-        if (matcher(preference.value, value)) {
-            if (!best ||
-                preference.quality > best.quality ||
-                (preference.quality === best.quality &&
-                    preference.specificity > best.specificity)) {
-                best = preference;
-            }
+        if (!matcher(preference.value, value)) {
+            continue;
+        }
+        if (!best || isMoreRelevant(preference, best)) {
+            best = preference;
         }
     }
     return best?.quality ?? 0;
 }
+/**
+ * Orders two matching preferences: specificity, then weight, then position.
+ */
+function isMoreRelevant(candidate, best) {
+    if (candidate.specificity !== best.specificity) {
+        return candidate.specificity > best.specificity;
+    }
+    if (candidate.quality !== best.quality) {
+        return candidate.quality > best.quality;
+    }
+    return false;
+}
 /* -------------------------------------------------------------------------- */
 /* Media Type Helpers                                                         */
 /* -------------------------------------------------------------------------- */

package/dist/httpProxy/http.proxy.d.ts

@@ -167,6 +167,15 @@ export declare function applyProxyHeaders(headers: readonly HTTPHeader[], additi
  * with `httpTrustProxy.getClientIp` rather than copying the raw header.
  */
 export declare function setForwardedHeaders(headers: readonly HTTPHeader[], target: ProxyTarget, client?: ProxyClientContext): HTTPHeader[];
+/**
+ * Builds an RFC 7239 `Forwarded` field value.
+ *
+ * Every parameter is escaped as a `quoted-string` when it is not a bare
+ * token, and the finished value is checked the same way `setForwardedHeaders`
+ * checks the values it writes.
+ *
+ * @throws {TypeError} If any parameter contains a control character.
+ */
 export declare function createForwardedHeader(address: ForwardedAddress): string;
 export declare function parseForwardedHeader(value: string | undefined | null): ForwardedAddress[];
 /**