@zudojs/http 1.1.0 → 1.3.0

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/httpMiddleware/builtin/static/httpMiddleware.static.js

@@ -7,6 +7,8 @@ import { readFile, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { extname, join, resolve, sep } from "node:path";
 import { applyHeadersToResponse } from "../helpers/index.js";
+import { parseRequestTarget } from "../../../httpRequest/target/httpRequest.target.js";
+import { evaluateConditionalRequest } from "../../../httpConditional/httpConditional.core.js";
 const DEFAULT_INDEX = "index.html";
 const DEFAULT_MAX_AGE = 3600;
 const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
@@ -141,7 +143,7 @@ export function createStaticMiddleware(options) {
          */
         let url;
         try {
-            url = new URL(context.request.url, "http://zudojs.invalid");
+            url = parseRequestTarget(context.request.url);
         }
         catch {
             return next();
@@ -200,9 +202,21 @@ export function createStaticMiddleware(options) {
          * returns the whole body and has no 206 path, so advertising range
          * support makes range-aware clients misbehave.
          */
-        const ifNoneMatch = context.request.headers["if-none-match"];
-        if (ifNoneMatch === etag) {
-            return applyHeadersToResponse(context.response, responseHeaders).setStatus(304);
+        /*
+         * RFC 9110 section 13.2.2 evaluation: `If-None-Match` lists, weak tags
+         * and `*`, then `If-Modified-Since`, plus `If-Match` /
+         * `If-Unmodified-Since` (412). An exact string compare missed all of
+         * those and re-sent the whole file.
+         */
+        const headers = context.request.headers;
+        const conditional = evaluateConditionalRequest(context.request.method, {
+            ifMatch: headers["if-match"],
+            ifNoneMatch: headers["if-none-match"],
+            ifModifiedSince: headers["if-modified-since"],
+            ifUnmodifiedSince: headers["if-unmodified-since"],
+        }, { etag, lastModified });
+        if (conditional.statusCode !== undefined) {
+            return applyHeadersToResponse(context.response, responseHeaders).setStatus(conditional.statusCode);
         }
         return applyHeadersToResponse(context.response, responseHeaders).setBody(fileData);
     };

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

@@ -3,14 +3,17 @@
  *
  * @module httpMiddleware/builtin/video
  *
- * Requires: npm install fluent-ffmpeg
+ * Requires: npm install fluent-ffmpeg (and an ffmpeg binary)
  */
 import type { HttpMiddleware } from "../../httpMiddleware.type.js";
+import { type MediaCompressionErrorHandler } from "../helpers/index.js";
 export interface VideoCompressionOptions {
     readonly bitrate?: string;
     readonly preset?: "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "slower" | "veryslow";
     readonly crf?: number;
     readonly format?: "mp4" | "webm" | "mov";
+    /** Input container; defaults to `mp4`. */
+    readonly inputFormat?: string;
     readonly scale?: {
         readonly width?: number;
         readonly height?: number;
@@ -20,7 +23,22 @@ export interface VideoCompressionMiddlewareOptions {
     readonly enabled?: boolean;
     readonly contentTypeMap?: Record<string, VideoCompressionOptions>;
     readonly tempDir?: string;
+    /**
+     * Called when compression fails. The original response is still served.
+     */
+    readonly onError?: MediaCompressionErrorHandler;
 }
+/**
+ * Transcodes a video held in memory.
+ *
+ * `fluent-ffmpeg`'s export is a factory: `input()` exists only on the
+ * command it returns. Calling it on the module (as this did) threw
+ * `ffmpegInstance.input is not a function` on every call.
+ */
 export declare function compressVideo(inputBuffer: Buffer, options?: VideoCompressionOptions): Promise<Buffer>;
+/**
+ * Compresses `video/*` responses, reading status, headers and body from the
+ * response returned by `next()`.
+ */
 export declare function createVideoCompressionMiddleware(options?: VideoCompressionMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.video.d.ts.map

package/dist/httpMiddleware/builtin/video/httpMiddleware.video.js

@@ -3,79 +3,58 @@
  *
  * @module httpMiddleware/builtin/video
  *
- * Requires: npm install fluent-ffmpeg
+ * Requires: npm install fluent-ffmpeg (and an ffmpeg binary)
+ */
+import { Readable } from "node:stream";
+import { applyCompressedBody, getResponseBytes, getResponseMediaType, loadOptionalModule, } from "../helpers/index.js";
+import { CONTAINER_TYPES, DEFAULT_VIDEO_FORMAT as DEFAULT_FORMAT, buildOutputOptions, } from "./httpMiddleware.video.options.js";
+/**
+ * Transcodes a video held in memory.
+ *
+ * `fluent-ffmpeg`'s export is a factory: `input()` exists only on the
+ * command it returns. Calling it on the module (as this did) threw
+ * `ffmpegInstance.input is not a function` on every call.
  */
-import { applyHeadersToResponse } from "../helpers/index.js";
-const DEFAULT_CRF = 28;
-const DEFAULT_PRESET = "medium";
-const DEFAULT_FORMAT = "mp4";
-async function getFfmpeg() {
-    try {
-        const mod = await import("fluent-ffmpeg");
-        return mod.default ?? mod;
-    }
-    catch {
-        throw new Error("fluent-ffmpeg is not installed. Run: npm install fluent-ffmpeg");
-    }
-}
 export async function compressVideo(inputBuffer, options = {}) {
-    const ffmpegInstance = await getFfmpeg();
-    const crf = options.crf ?? DEFAULT_CRF;
-    const preset = options.preset ?? DEFAULT_PRESET;
-    const format = options.format ?? DEFAULT_FORMAT;
+    const ffmpeg = await loadOptionalModule("fluent-ffmpeg", "npm install fluent-ffmpeg");
     return new Promise((resolve, reject) => {
-        const outputBuffer = [];
-        ffmpegInstance
-            .input(inputBuffer)
-            .inputFormat("mp4")
-            .outputOptions([
-            `-crf ${crf}`,
-            `-preset ${preset}`,
-            "-movflags +faststart",
-        ])
-            .format(format)
-            .on("end", () => {
-            resolve(Buffer.concat(outputBuffer));
-        })
-            .on("error", (err) => {
-            reject(err);
-        })
-            .pipe((err, stdout) => {
-            if (err) {
-                reject(err);
-                return;
-            }
-            stdout.on("data", (chunk) => {
-                outputBuffer.push(chunk);
-            });
-        });
+        const chunks = [];
+        const output = ffmpeg()
+            .input(Readable.from([inputBuffer]))
+            .inputFormat(options.inputFormat ?? "mp4")
+            .outputOptions(buildOutputOptions(options))
+            .format(options.format ?? DEFAULT_FORMAT)
+            .on("error", reject)
+            .pipe();
+        output.on("data", (chunk) => chunks.push(chunk));
+        output.on("end", () => resolve(Buffer.concat(chunks)));
+        output.on("error", reject);
     });
 }
+/**
+ * Compresses `video/*` responses, reading status, headers and body from the
+ * response returned by `next()`.
+ */
 export function createVideoCompressionMiddleware(options = {}) {
     const enabled = options.enabled ?? true;
-    return async (context, next) => {
-        if (!enabled) {
-            return next();
-        }
+    return async (_context, next) => {
         const response = await next();
-        const contentType = context.response.headers["content-type"];
-        if (!contentType || !contentType.startsWith("video/")) {
+        const mediaType = getResponseMediaType(response);
+        if (!enabled || !mediaType?.startsWith("video/")) {
             return response;
         }
-        const body = context.response.body;
-        if (!Buffer.isBuffer(body)) {
+        const body = getResponseBytes(response);
+        if (!body || body.length === 0) {
             return response;
         }
-        const compressionOptions = options.contentTypeMap?.[contentType] ?? {};
+        const compression = options.contentTypeMap?.[mediaType] ?? {};
+        const format = compression.format ?? DEFAULT_FORMAT;
         try {
-            const compressed = await compressVideo(body, compressionOptions);
-            const newContentType = "video/mp4";
-            const headers = new Headers(response.headers);
-            headers.set("content-type", newContentType);
-            headers.set("cache-control", headers.get("cache-control") ?? "public, max-age=86400");
-            return applyHeadersToResponse(response, headers).setBody(compressed);
+            const compressed = await compressVideo(body, compression);
+            return applyCompressedBody(response, compressed, CONTAINER_TYPES[format] ?? "video/mp4");
         }
-        catch {
+        catch (error) {
+            options.onError?.(error, response);
             return response;
         }
     };

package/dist/httpMiddleware/builtin/video/httpMiddleware.video.options.d.ts

@@ -0,0 +1,12 @@
+/**
+ * FFmpeg argument building for the video compression middleware.
+ *
+ * @module httpMiddleware/builtin/video/options
+ */
+import type { VideoCompressionOptions } from "./httpMiddleware.video.js";
+export declare const DEFAULT_VIDEO_FORMAT = "mp4";
+/** Media type per output container. */
+export declare const CONTAINER_TYPES: Readonly<Record<string, string>>;
+/** Builds the ffmpeg output options for a compression request. */
+export declare function buildOutputOptions(options: VideoCompressionOptions): string[];
+//# sourceMappingURL=httpMiddleware.video.options.d.ts.map

package/dist/httpMiddleware/builtin/video/httpMiddleware.video.options.js

@@ -0,0 +1,31 @@
+/**
+ * FFmpeg argument building for the video compression middleware.
+ *
+ * @module httpMiddleware/builtin/video/options
+ */
+const DEFAULT_CRF = 28;
+const DEFAULT_PRESET = "medium";
+export const DEFAULT_VIDEO_FORMAT = "mp4";
+/** Media type per output container. */
+export const CONTAINER_TYPES = Object.freeze({
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+});
+/** Builds the ffmpeg output options for a compression request. */
+export function buildOutputOptions(options) {
+    const output = [
+        `-crf ${options.crf ?? DEFAULT_CRF}`,
+        `-preset ${options.preset ?? DEFAULT_PRESET}`,
+        /* A pipe is not seekable, so the moov atom must be fragmented. */
+        "-movflags frag_keyframe+empty_moov",
+    ];
+    if (options.bitrate) {
+        output.push(`-b:v ${options.bitrate}`);
+    }
+    if (options.scale?.width || options.scale?.height) {
+        output.push(`-vf scale=${options.scale.width ?? -2}:${options.scale.height ?? -2}`);
+    }
+    return output;
+}
+//# sourceMappingURL=httpMiddleware.video.options.js.map

package/dist/httpMiddleware/httpMiddleware.error.d.ts

@@ -1,38 +1,12 @@
 /**
  * HTTP middleware error types.
  *
- * Extends the shared MiddlewareError from @zudojs/errors with
- * HTTP-specific middleware error information.
+ * `HttpMiddlewareError` and `HttpMiddlewarePipelineError` live in
+ * `@zudojs/errors` (both `BaseError`s, 500, not exposed, codes
+ * `HTTP_MIDDLEWARE_ERROR` / `MIDDLEWARE_PIPELINE_ERROR`); they are
+ * re-exported here so existing imports keep working.
  *
  * @module httpMiddleware/errors
  */
-import { BaseError } from "@zudojs/errors";
-/**
- * Error raised by an HTTP middleware function.
- */
-export declare class HttpMiddlewareError extends BaseError {
-    /**
-     * The unique identifier of the middleware.
-     */
-    readonly middlewareId: string | undefined;
-    /**
-     * The name of the middleware.
-     */
-    readonly middlewareName: string | undefined;
-    constructor(message: string, options?: {
-        readonly middlewareId?: string;
-        readonly middlewareName?: string;
-        readonly cause?: unknown;
-    });
-}
-/**
- * Error raised when the HTTP middleware pipeline fails.
- */
-export declare class HttpMiddlewarePipelineError extends BaseError {
-    /**
-     * The errors that occurred during pipeline execution.
-     */
-    readonly errors: readonly HttpMiddlewareError[];
-    constructor(errors: readonly HttpMiddlewareError[]);
-}
+export { HttpMiddlewareError, HttpMiddlewarePipelineError, type HttpMiddlewareErrorOptions, } from "@zudojs/errors";
 //# sourceMappingURL=httpMiddleware.error.d.ts.map

package/dist/httpMiddleware/httpMiddleware.error.js

@@ -1,60 +1,12 @@
 /**
  * HTTP middleware error types.
  *
- * Extends the shared MiddlewareError from @zudojs/errors with
- * HTTP-specific middleware error information.
+ * `HttpMiddlewareError` and `HttpMiddlewarePipelineError` live in
+ * `@zudojs/errors` (both `BaseError`s, 500, not exposed, codes
+ * `HTTP_MIDDLEWARE_ERROR` / `MIDDLEWARE_PIPELINE_ERROR`); they are
+ * re-exported here so existing imports keep working.
  *
  * @module httpMiddleware/errors
  */
-import { BaseError } from "@zudojs/errors";
-/* -------------------------------------------------------------------------- */
-/* Errors                                                                     */
-/* -------------------------------------------------------------------------- */
-/**
- * Error raised by an HTTP middleware function.
- */
-export class HttpMiddlewareError extends BaseError {
-    /**
-     * The unique identifier of the middleware.
-     */
-    middlewareId;
-    /**
-     * The name of the middleware.
-     */
-    middlewareName;
-    constructor(message, options = {}) {
-        super(message, {
-            code: "HTTP_MIDDLEWARE_ERROR",
-            statusCode: 500,
-            expose: false,
-            cause: options.cause,
-        });
-        this.name = "HttpMiddlewareError";
-        this.middlewareId = options.middlewareId;
-        this.middlewareName = options.middlewareName;
-    }
-}
-/**
- * Error raised when the HTTP middleware pipeline fails.
- */
-export class HttpMiddlewarePipelineError extends BaseError {
-    /**
-     * The errors that occurred during pipeline execution.
-     */
-    errors;
-    constructor(errors) {
-        const message = errors.length === 1
-            ? `HTTP middleware pipeline failed: ${errors[0]?.message ?? "Unknown error"}`
-            : `HTTP middleware pipeline failed with ${errors.length} errors: ${errors
-                .map((e) => e.message)
-                .join(", ")}`;
-        super(message, {
-            code: "MIDDLEWARE_PIPELINE_ERROR",
-            statusCode: 500,
-            expose: false,
-        });
-        this.name = "HttpMiddlewarePipelineError";
-        this.errors = Object.freeze([...errors]);
-    }
-}
+export { HttpMiddlewareError, HttpMiddlewarePipelineError, } from "@zudojs/errors";
 //# sourceMappingURL=httpMiddleware.error.js.map

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

@@ -128,6 +128,13 @@ export declare function assertSafeProxyTarget(target: string | URL, options?: Pr
 export declare function assertSafeProxyRedirect(location: string | URL, currentURL: string | URL, options?: ProxySecurityOptions): URL;
 export declare function resolveProxyTarget(target: string | URL, options?: ProxySecurityOptions): ProxyTarget;
 export declare function isValidProxyTarget(target: string | URL | undefined | null): boolean;
+/**
+ * Joins a request path onto a proxy base path.
+ *
+ * @throws {HttpError} 400 when `requestPath` contains a `.` / `..` segment
+ *   (plain or percent-encoded), which an upstream would resolve outside
+ *   `basePath`.
+ */
 export declare function joinProxyPath(basePath: string, requestPath: string): string;
 export declare function rewriteProxyPath(path: string, options?: ProxyRewriteOptions): string;
 export declare function normalizeProxyPath(path: string): string;
@@ -160,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[];
 /**

package/dist/httpProxy/http.proxy.js

@@ -10,7 +10,8 @@
 import { appendHeader, deleteHeader, getHeader, setHeader, } from "../httpProtocol/http.protocol.js";
 import { isValidHTTPURL, isValidHeaderValue } from "../httpValidation/index.js";
 import { isLinkLocalAddress, isLoopbackAddress, isUniqueLocalAddress, parseIpAddress, } from "../httpTrustProxy/httpTrustProxy.ip.js";
-import { assertSafeHeaderValue } from "../httpHeaders/security/index.js";
+import { assertSafeHeaderValue, escapeHeaderQuotedString, } from "../httpHeaders/security/index.js";
+import { assertProxyPathContained } from "./httpProxy.pathGuard.js";
 /* -------------------------------------------------------------------------- */
 /* Target                                                                     */
 /* -------------------------------------------------------------------------- */
@@ -71,6 +72,16 @@ function isBlockedLiteralAddress(hostname) {
             (address.bytes[1] ?? 0) <= 127) {
             return true;
         }
+        /* 192.0.0.0/24 IETF protocol assignments (192.0.0.8, 192.0.0.170, …). */
+        if (first === 192 &&
+            (address.bytes[1] ?? 0) === 0 &&
+            (address.bytes[2] ?? 0) === 0) {
+            return true;
+        }
+        /* 198.18.0.0/15 benchmarking. */
+        if (first === 198 && ((address.bytes[1] ?? 0) & 0xfe) === 18) {
+            return true;
+        }
         return false;
     }
     const first = address.bytes[0] ?? 0;
@@ -204,7 +215,15 @@ function parseProxyURL(target) {
 /* -------------------------------------------------------------------------- */
 /* Path Handling                                                              */
 /* -------------------------------------------------------------------------- */
+/**
+ * Joins a request path onto a proxy base path.
+ *
+ * @throws {HttpError} 400 when `requestPath` contains a `.` / `..` segment
+ *   (plain or percent-encoded), which an upstream would resolve outside
+ *   `basePath`.
+ */
 export function joinProxyPath(basePath, requestPath) {
+    assertProxyPathContained(requestPath);
     const base = normalizeProxyPath(basePath);
     const request = requestPath.startsWith("/") ? requestPath : `/${requestPath}`;
     if (base === "/") {
@@ -352,6 +371,15 @@ function appendForwardedValue(headers, name, value) {
 /* -------------------------------------------------------------------------- */
 /* Standard Forwarded Header                                                  */
 /* -------------------------------------------------------------------------- */
+/**
+ * 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 function createForwardedHeader(address) {
     const parts = [];
     if (address.for) {
@@ -366,7 +394,9 @@ export function createForwardedHeader(address) {
     if (address.protocol) {
         parts.push(`proto=${formatForwardedValue(address.protocol)}`);
     }
-    return parts.join("; ");
+    const value = parts.join("; ");
+    assertSafeHeaderValue(value);
+    return value;
 }
 export function parseForwardedHeader(value) {
     if (!value || value.trim().length === 0) {
@@ -525,11 +555,22 @@ function formatForwardedIdentifier(value) {
     }
     return formatForwardedValue(value);
 }
+/**
+ * Emits an RFC 7239 parameter value.
+ *
+ * Wrapping a value in quotes does not neutralise a CR or LF — the control
+ * character survives into the field value and an attacker-chosen header
+ * follows it on the wire. `escapeHeaderQuotedString` rejects those characters
+ * rather than escaping them, which is what every other quoted-parameter
+ * emitter in this package already uses.
+ *
+ * @throws {TypeError} If the value contains a forbidden control character.
+ */
 function formatForwardedValue(value) {
     if (/^[A-Za-z0-9._:-]+$/.test(value)) {
         return value;
     }
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    return `"${escapeHeaderQuotedString(value)}"`;
 }
 function unquoteForwardedValue(value) {
     if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {