@zudojs/http 1.2.0 → 1.4.0

package/dist/httpQuery/querySerialize/querySerialize.core.js

@@ -0,0 +1,97 @@
+import { DEFAULT_QUERY_MAX_DEPTH, HTTPQueryLimitError, } from "../queryTypes/index.js";
+/**
+ * Serializes an object into a query string.
+ *
+ * Bounded in the same two ways the parser is. Nesting deeper than `maxDepth`
+ * and any cycle both throw {@link HTTPQueryLimitError}; previously either one
+ * produced a bare `RangeError: Maximum call stack size exceeded` from inside
+ * the walk, which no caller could distinguish from an internal fault.
+ */
+export function stringifyQuery(query, options = {}) {
+    const params = new URLSearchParams();
+    appendObjectToSearchParams(params, query, undefined, options.maxDepth ?? DEFAULT_QUERY_MAX_DEPTH, new Set());
+    return params.toString();
+}
+export function buildQueryString(query, options = {}) {
+    const value = stringifyQuery(query, options);
+    return value ? `?${value}` : "";
+}
+/**
+ * Walks one object level.
+ *
+ * `seen` is scoped to the current path — marked on descent, deleted on
+ * ascent — so a value that legitimately appears twice in a DAG serializes
+ * twice, while a value that contains itself is rejected. A set that is never
+ * unmarked would reject the DAG instead.
+ */
+function appendObjectToSearchParams(params, object, prefix, remainingDepth, seen) {
+    if (remainingDepth <= 0) {
+        throw new HTTPQueryLimitError("Query object nesting exceeds the maximum allowed depth.");
+    }
+    if (seen.has(object)) {
+        throw new HTTPQueryLimitError("Query object contains a circular reference.");
+    }
+    seen.add(object);
+    for (const [key, value] of Object.entries(object)) {
+        const path = prefix ? `${prefix}[${key}]` : key;
+        appendValue(params, value, path, remainingDepth, seen);
+    }
+    seen.delete(object);
+}
+function appendValue(params, value, path, remainingDepth, seen) {
+    if (value === undefined) {
+        return;
+    }
+    if (value === null) {
+        params.append(path, "null");
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (remainingDepth <= 0) {
+            throw new HTTPQueryLimitError("Query object nesting exceeds the maximum allowed depth.");
+        }
+        if (seen.has(value)) {
+            throw new HTTPQueryLimitError("Query object contains a circular reference.");
+        }
+        seen.add(value);
+        for (const item of value) {
+            appendValue(params, item, path, remainingDepth - 1, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    if (isPlainObject(value)) {
+        appendObjectToSearchParams(params, value, path, remainingDepth - 1, seen);
+        return;
+    }
+    params.append(path, serializeQueryPrimitive(value));
+}
+function serializeQueryPrimitive(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+        return String(value);
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=querySerialize.core.js.map

package/dist/httpQuery/queryTypes/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @zudojs/http/httpQuery/queryTypes
+ *
+ * Query value types, parser limits, and the prototype-safe container
+ * primitives every other query module builds on.
+ */
+export type { QueryLimitOptions, QueryObject, QueryParseOptions, QueryPrimitive, QueryStringParseOptions, QueryStringPrimitive, QueryStringifyOptions, QueryStringValue, QueryValue, } from "./query.type.js";
+export { DEFAULT_QUERY_MAX_DEPTH, DEFAULT_QUERY_MAX_KEY_LENGTH, DEFAULT_QUERY_MAX_KEYS, DEFAULT_QUERY_MAX_TOTAL_LENGTH, DEFAULT_QUERY_MAX_VALUE_LENGTH, HTTPQueryLimitError, resolveLimits, } from "./query.limit.js";
+export type { QueryLimits } from "./query.limit.js";
+export { createQueryContainer, isForbiddenQueryKey, isQueryObject, ownValue, queryValueToString, } from "./query.container.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/queryTypes/index.js

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/http/httpQuery/queryTypes
+ *
+ * Query value types, parser limits, and the prototype-safe container
+ * primitives every other query module builds on.
+ */
+export { DEFAULT_QUERY_MAX_DEPTH, DEFAULT_QUERY_MAX_KEY_LENGTH, DEFAULT_QUERY_MAX_KEYS, DEFAULT_QUERY_MAX_TOTAL_LENGTH, DEFAULT_QUERY_MAX_VALUE_LENGTH, HTTPQueryLimitError, resolveLimits, } from "./query.limit.js";
+export { createQueryContainer, isForbiddenQueryKey, isQueryObject, ownValue, queryValueToString, } from "./query.container.js";
+//# sourceMappingURL=index.js.map

package/dist/httpQuery/queryTypes/query.container.d.ts

@@ -0,0 +1,16 @@
+import type { QueryObject, QueryValue } from "./query.type.js";
+export declare function isForbiddenQueryKey(key: string): boolean;
+export declare function createQueryContainer(): Record<string, QueryValue>;
+export declare function ownValue<T>(target: Record<string, T>, key: string): T | undefined;
+export declare function isQueryObject(value: QueryValue | undefined): value is QueryObject;
+/**
+ * Stringifies a parsed query value without invoking `String()` on it.
+ *
+ * Every container this module builds has a `null` prototype, so it inherits
+ * neither `toString` nor `valueOf`; `String(container)` throws
+ * `TypeError: Cannot convert object to primitive value`. Because the shape of
+ * a parsed value is attacker-chosen (`?a[b]=1&a=2` yields an array holding an
+ * object), that throw was reachable from any request.
+ */
+export declare function queryValueToString(value: QueryValue): string;
+//# sourceMappingURL=query.container.d.ts.map

package/dist/httpQuery/queryTypes/query.container.js

@@ -0,0 +1,51 @@
+/**
+ * Key names that would mutate a prototype chain if assigned to an object.
+ *
+ * `__proto__` is the direct pollution vector. `constructor` and `prototype`
+ * are blocked as defence in depth so no future container type re-opens the
+ * hole.
+ */
+const FORBIDDEN_QUERY_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+export function isForbiddenQueryKey(key) {
+    return FORBIDDEN_QUERY_KEYS.has(key);
+}
+export function createQueryContainer() {
+    return Object.create(null);
+}
+export function ownValue(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key)
+        ? target[key]
+        : undefined;
+}
+export function isQueryObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Stringifies a parsed query value without invoking `String()` on it.
+ *
+ * Every container this module builds has a `null` prototype, so it inherits
+ * neither `toString` nor `valueOf`; `String(container)` throws
+ * `TypeError: Cannot convert object to primitive value`. Because the shape of
+ * a parsed value is attacker-chosen (`?a[b]=1&a=2` yields an array holding an
+ * object), that throw was reachable from any request.
+ */
+export function queryValueToString(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(queryValueToString).join(",");
+    }
+    return `[object Object]`;
+}
+//# sourceMappingURL=query.container.js.map

package/dist/httpQuery/queryTypes/query.limit.d.ts

@@ -0,0 +1,25 @@
+import { HttpError } from "@zudojs/errors";
+import type { QueryLimitOptions } from "./query.type.js";
+export declare const DEFAULT_QUERY_MAX_KEYS = 1000;
+export declare const DEFAULT_QUERY_MAX_KEY_LENGTH = 4096;
+export declare const DEFAULT_QUERY_MAX_VALUE_LENGTH = 16384;
+export declare const DEFAULT_QUERY_MAX_TOTAL_LENGTH: number;
+export declare const DEFAULT_QUERY_MAX_DEPTH = 10;
+/**
+ * Thrown when a query string exceeds one of the parser's limits.
+ *
+ * Carries `statusCode: 414` so an error handler can answer with
+ * `414 URI Too Long` rather than treating the rejection as an internal fault.
+ */
+export declare class HTTPQueryLimitError extends HttpError {
+    constructor(message: string);
+}
+/** Resolved form of {@link QueryLimitOptions}, with every default applied. */
+export interface QueryLimits {
+    readonly maxKeys: number;
+    readonly maxKeyLength: number;
+    readonly maxValueLength: number;
+    readonly maxTotalLength: number;
+}
+export declare function resolveLimits(options: QueryLimitOptions): QueryLimits;
+//# sourceMappingURL=query.limit.d.ts.map

package/dist/httpQuery/queryTypes/query.limit.js

@@ -0,0 +1,32 @@
+import { HttpError } from "@zudojs/errors";
+export const DEFAULT_QUERY_MAX_KEYS = 1000;
+export const DEFAULT_QUERY_MAX_KEY_LENGTH = 4096;
+export const DEFAULT_QUERY_MAX_VALUE_LENGTH = 16384;
+export const DEFAULT_QUERY_MAX_TOTAL_LENGTH = 1024 * 1024;
+export const DEFAULT_QUERY_MAX_DEPTH = 10;
+/**
+ * Thrown when a query string exceeds one of the parser's limits.
+ *
+ * Carries `statusCode: 414` so an error handler can answer with
+ * `414 URI Too Long` rather than treating the rejection as an internal fault.
+ */
+export class HTTPQueryLimitError extends HttpError {
+    constructor(message) {
+        super(message, {
+            statusCode: 414,
+            code: "HTTP_QUERY_LIMIT",
+            expose: true,
+            isOperational: true,
+        });
+        this.name = "HTTPQueryLimitError";
+    }
+}
+export function resolveLimits(options) {
+    return {
+        maxKeys: options.maxKeys ?? DEFAULT_QUERY_MAX_KEYS,
+        maxKeyLength: options.maxKeyLength ?? DEFAULT_QUERY_MAX_KEY_LENGTH,
+        maxValueLength: options.maxValueLength ?? DEFAULT_QUERY_MAX_VALUE_LENGTH,
+        maxTotalLength: options.maxTotalLength ?? DEFAULT_QUERY_MAX_TOTAL_LENGTH,
+    };
+}
+//# sourceMappingURL=query.limit.js.map

package/dist/httpQuery/queryTypes/query.type.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Query value shapes produced by {@link parseQuery}.
+ *
+ * `QueryValue` is recursive on purpose. A query string may address the same
+ * name both as a scalar and as a bracket path (`?a[b]=1&a=2`), so an array
+ * element can itself be an object. Typing the array as `QueryPrimitive[]`
+ * described a shape the parser could not actually produce, and callers that
+ * trusted it crashed on the mixed array.
+ */
+export type QueryPrimitive = string | number | boolean | null;
+export type QueryValue = QueryPrimitive | QueryValue[] | QueryObject;
+export interface QueryObject {
+    readonly [key: string]: QueryValue;
+}
+/**
+ * Limits applied to every query string this module parses.
+ *
+ * All limits are enforced, on both the string and the `URLSearchParams` entry
+ * points. Exceeding one throws {@link HTTPQueryLimitError}, which carries a
+ * 414 status code so a server layer can map it to a response instead of a 500.
+ */
+export interface QueryLimitOptions {
+    /** Maximum number of parameters, counted after comma expansion. Default 1000. */
+    readonly maxKeys?: number;
+    /** Maximum decoded length of a parameter name. Default 4096. */
+    readonly maxKeyLength?: number;
+    /** Maximum decoded length of a parameter value. Default 16384. */
+    readonly maxValueLength?: number;
+    /** Maximum length of the whole query string. Default 1 MiB. */
+    readonly maxTotalLength?: number;
+}
+export interface QueryParseOptions extends QueryLimitOptions {
+    /** Split values on `,` into an array. Default `false`. */
+    readonly commaSeparated?: boolean;
+    /** Decode `+` as a space. Default `true`. */
+    readonly plusAsSpace?: boolean;
+    /** Percent-decode names and values. Default `true`. */
+    readonly decode?: boolean;
+    /** Maximum bracket-path nesting depth. Default 10. */
+    readonly maxDepth?: number;
+}
+export type QueryStringPrimitive = string | number | boolean | null | undefined;
+export type QueryStringValue = QueryStringPrimitive | readonly QueryStringPrimitive[];
+export interface QueryStringParseOptions extends QueryLimitOptions {
+    /** Decode `+` as a space. Default `true`. */
+    readonly decodePlusAsSpace?: boolean;
+    /** Keep parameters whose name decodes to the empty string. Default `true`. */
+    readonly allowEmptyKeys?: boolean;
+}
+/**
+ * Bounds applied when serializing an object back into a query string.
+ *
+ * The parser is iterative and depth-capped, so it cannot be made to overflow
+ * the stack. The serializer walks the same shapes and needs the same bounds:
+ * without them a cyclic or deeply nested object threw a bare `RangeError`
+ * instead of a typed, catchable failure.
+ */
+export interface QueryStringifyOptions {
+    /** Maximum nesting depth of the object being serialized. Default 10. */
+    readonly maxDepth?: number;
+}
+//# sourceMappingURL=query.type.d.ts.map

package/dist/httpQuery/queryTypes/query.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=query.type.js.map

package/dist/httpRedirect/http.redirect.d.ts

@@ -60,6 +60,12 @@ export declare function getRedirectMethod(statusCode: number, method: string): s
 export declare function createRedirectPolicy(options?: Partial<RedirectPolicy> | undefined): RedirectPolicy;
 export declare function canFollowRedirect(fromURL: string | URL, toURL: string | URL, policy: RedirectPolicy): boolean;
 export declare function resolveRedirectChain(initialURL: string | URL, locations: readonly (string | URL)[], policy?: Partial<RedirectPolicy> | undefined): URL[];
+/**
+ * Whether the same location appears twice in a redirect chain.
+ *
+ * Relative locations are accepted: they are resolved against a fixed base, so
+ * `["/a", "/a"]` reports a loop instead of throwing `Invalid URL`.
+ */
 export declare function hasRedirectLoop(locations: readonly (string | URL)[]): boolean;
 export declare function assertNoRedirectLoop(locations: readonly (string | URL)[]): void;
 export declare function isSameOrigin(left: string | URL, right: string | URL): boolean;

package/dist/httpRedirect/http.redirect.js

@@ -202,10 +202,16 @@ export function resolveRedirectChain(initialURL, locations, policy = {}) {
 /* -------------------------------------------------------------------------- */
 /* Redirect Loop Detection                                                    */
 /* -------------------------------------------------------------------------- */
+/**
+ * Whether the same location appears twice in a redirect chain.
+ *
+ * Relative locations are accepted: they are resolved against a fixed base, so
+ * `["/a", "/a"]` reports a loop instead of throwing `Invalid URL`.
+ */
 export function hasRedirectLoop(locations) {
     const seen = new Set();
     for (const location of locations) {
-        const normalized = normalizeURL(location).href;
+        const normalized = redirectIdentity(location);
         if (seen.has(normalized)) {
             return true;
         }
@@ -421,11 +427,56 @@ export function getLocationHeader(headers) {
 /* -------------------------------------------------------------------------- */
 /* URL Normalization                                                          */
 /* -------------------------------------------------------------------------- */
+/**
+ * The origin a relative `Location` is resolved against.
+ *
+ * A relative reference is legal under RFC 9110 and is what this module's own
+ * `createRedirect` / `formatLocation` emit by default, so the predicates
+ * below must answer for one rather than throw `Invalid URL`. `.invalid` is
+ * reserved by RFC 6761, so this can never collide with a real origin.
+ */
+const RELATIVE_BASE = "http://redirect.invalid";
 function normalizeURL(value) {
     if (value instanceof URL) {
         return new URL(value.href);
     }
-    return new URL(value);
+    try {
+        return new URL(value);
+    }
+    catch {
+        /* Not absolute — resolve it as the relative reference it is. */
+    }
+    try {
+        return new URL(value, RELATIVE_BASE);
+    }
+    catch {
+        return new URL(RELATIVE_BASE);
+    }
+}
+/**
+ * The identity a location is compared under when detecting a loop.
+ *
+ * An unparseable value keeps its literal form rather than collapsing onto the
+ * base origin, so two different malformed locations are never reported as a
+ * loop.
+ */
+function redirectIdentity(location) {
+    if (location instanceof URL) {
+        return location.href;
+    }
+    const trimmed = location.trim();
+    try {
+        return new URL(trimmed).href;
+    }
+    catch {
+        /* Fall through to the relative resolution. */
+    }
+    try {
+        return new URL(trimmed, RELATIVE_BASE).href;
+    }
+    catch {
+        return trimmed;
+    }
 }
 function getEffectivePort(url) {
     if (url.port) {

package/dist/httpRequest/http.request.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingHttpHeaders, IncomingMessage } from "node:http";
+import type { TrustProxy } from "../httpTrustProxy/httpTrustProxy.type.js";
 import type { HTTPHeaders, HTTPMethod, HTTPParams, HTTPQuery, HTTPRequest } from "../httpTypes/http.types.js";
 export declare class NodeHTTPHeaders implements HTTPHeaders {
     private readonly headers;
@@ -20,6 +21,15 @@ export interface HTTPRequestOptions {
     readonly ip?: string;
     readonly ips?: readonly string[];
     readonly signal?: AbortSignal;
+    /**
+     * Which socket peers may speak for a client through `X-Forwarded-*`.
+     *
+     * Defaults to `false`: every forwarded header is ignored and the socket
+     * peer decides `ip`, `protocol` and `secure`. Set it to the address, CIDR
+     * range, preset or predicate matching the proxy in front of this process
+     * before `req.ip` may report a forwarded address.
+     */
+    readonly trustProxy?: TrustProxy;
 }
 export declare class NodeHTTPRequest implements HTTPRequest {
     readonly method: HTTPMethod;
@@ -62,8 +72,57 @@ export declare function createHTTPRequest(request: IncomingMessage, options?: HT
 export declare function getRequestPath(request: IncomingMessage): string;
 export declare function getRequestHost(request: IncomingMessage): string;
 export declare function getHostname(host: string): string;
-export declare function getRequestProtocol(request: IncomingMessage): string;
-export declare function getRequestIP(request: IncomingMessage): string | undefined;
+/**
+ * Resolves the scheme the client used.
+ *
+ * `X-Forwarded-Proto` is written by whoever opened the socket, so it is read
+ * only when that peer is a configured trusted proxy, and only when it names
+ * `http` or `https` — a value such as `wss` is discarded rather than
+ * propagated. With the default `trustProxy` of `false` the socket's own TLS
+ * state is the only input.
+ *
+ * @param request - The incoming Node request.
+ * @param trustProxy - Which peers may speak through `X-Forwarded-Proto`.
+ * @returns `"https"` or `"http"`.
+ */
+export declare function getRequestProtocol(request: IncomingMessage, trustProxy?: TrustProxy): string;
+/**
+ * Resolves the client address.
+ *
+ * The socket peer is authoritative. `X-Forwarded-For` is consulted only when
+ * that peer is a configured trusted proxy, and the chain walk is delegated to
+ * `getClientIp` so there is a single implementation of the hop logic. With
+ * the default `trustProxy` of `false` the peer address is returned unchanged,
+ * which is what an allowlist, per-IP rate limit or audit trail keyed on
+ * `req.ip` needs.
+ *
+ * @param request - The incoming Node request.
+ * @param trustProxy - Which peers may speak through `X-Forwarded-For`.
+ * @returns The client address, or `undefined` when the socket has none.
+ */
+export declare function getRequestIP(request: IncomingMessage, trustProxy?: TrustProxy): string | undefined;
+/**
+ * Parses the query component of a request-target into a flat record.
+ *
+ * Delegates to the hardened `httpQuery` parser, the same one behind the Node
+ * adapter's `request.query` and the router's `ctx.query`. This function used
+ * to carry its own loop that accumulated into an object literal and read
+ * `result[key]` without an own-property check, which had two consequences on
+ * fully attacker-controlled input:
+ *
+ * - `?__proto__=a&__proto__=b` assigned an array through the `__proto__`
+ *   setter, so the returned query object's prototype became that array. The
+ *   parameter vanished from its own keys while the object silently gained
+ *   `length`, `map` and the rest of `Array.prototype`.
+ * - `?constructor=x` read the inherited `Object` constructor as the "existing"
+ *   value and stored it in the result, handing a handler
+ *   `query.constructor === [Function: Object], "x"]`.
+ *
+ * It also applied none of the four documented query limits, so a request with
+ * 50,000 parameters was parsed in full. Delegating fixes all three, and makes
+ * a limit breach throw {@link HTTPQueryLimitError} (414) as it already did on
+ * every other request path.
+ */
 export declare function parseQueryString(url: string): HTTPQuery;
 export declare function normalizeHTTPMethod(method: string | undefined): HTTPMethod;
 export declare function parseAcceptHeader(value: string): string[];

package/dist/httpRequest/http.request.js

@@ -1,5 +1,7 @@
 import { HTTP_HEADERS } from "../httpConstants/http.constants.js";
 import { InvalidJSONError } from "../httpErrors/httpError.helper.js";
+import { parseQueryString as parseHardenedQueryString } from "../httpQuery/queryParse/index.js";
+import { getClientIp, isTrustedPeer, } from "../httpTrustProxy/httpTrustProxy.helper.js";
 /* -------------------------------------------------------------------------- */
 /* Request Headers                                                            */
 /* -------------------------------------------------------------------------- */
@@ -72,7 +74,8 @@ export class NodeHTTPRequest {
     cachedJSON;
     jsonParsed = false;
     constructor(request, options = {}) {
-        const protocol = getRequestProtocol(request);
+        const trustProxy = options.trustProxy ?? false;
+        const protocol = getRequestProtocol(request, trustProxy);
         const host = getRequestHost(request);
         const path = getRequestPath(request);
         this.method = normalizeHTTPMethod(request.method);
@@ -84,9 +87,9 @@ export class NodeHTTPRequest {
         this.params = options.params ?? {};
         this.protocol = protocol;
         this.hostname = getHostname(host);
-        this.ip = options.ip ?? getRequestIP(request);
+        this.ip = options.ip ?? getRequestIP(request, trustProxy);
         this.ips = options.ips;
-        this.secure = protocol === "https" || protocol === "wss";
+        this.secure = protocol === "https";
         this.rawBody = options.rawBody;
         this.body = options.body;
         this.signal = options.signal;
@@ -229,10 +232,41 @@ export function getHostname(host) {
 /* -------------------------------------------------------------------------- */
 /* Protocol                                                                   */
 /* -------------------------------------------------------------------------- */
-export function getRequestProtocol(request) {
-    const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_PROTO];
-    if (typeof forwarded === "string") {
-        return (forwarded.split(",", 1)[0] ?? "").trim().toLowerCase();
+/** The only schemes a forwarded proto may name. */
+const FORWARDED_PROTOCOLS = Object.freeze(["http", "https"]);
+/**
+ * Presents an `IncomingMessage` in the shape `httpTrustProxy` works on, so
+ * this path and the Node adapter share one implementation of the hop logic.
+ */
+function toProxyRequest(request) {
+    return {
+        headers: request.headers,
+        socket: { remoteAddress: request.socket?.remoteAddress },
+    };
+}
+/**
+ * Resolves the scheme the client used.
+ *
+ * `X-Forwarded-Proto` is written by whoever opened the socket, so it is read
+ * only when that peer is a configured trusted proxy, and only when it names
+ * `http` or `https` — a value such as `wss` is discarded rather than
+ * propagated. With the default `trustProxy` of `false` the socket's own TLS
+ * state is the only input.
+ *
+ * @param request - The incoming Node request.
+ * @param trustProxy - Which peers may speak through `X-Forwarded-Proto`.
+ * @returns `"https"` or `"http"`.
+ */
+export function getRequestProtocol(request, trustProxy = false) {
+    if (isTrustedPeer(toProxyRequest(request), trustProxy)) {
+        const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_PROTO];
+        const value = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+        if (typeof value === "string") {
+            const proto = (value.split(",", 1)[0] ?? "").trim().toLowerCase();
+            if (FORWARDED_PROTOCOLS.includes(proto)) {
+                return proto;
+            }
+        }
     }
     if ("encrypted" in request.socket &&
         request.socket.encrypted) {
@@ -243,43 +277,60 @@ export function getRequestProtocol(request) {
 /* -------------------------------------------------------------------------- */
 /* IP                                                                         */
 /* -------------------------------------------------------------------------- */
-export function getRequestIP(request) {
-    const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_FOR];
-    if (typeof forwarded === "string") {
-        const first = forwarded.split(",", 1)[0]?.trim();
-        if (first) {
-            return first;
-        }
+/**
+ * Resolves the client address.
+ *
+ * The socket peer is authoritative. `X-Forwarded-For` is consulted only when
+ * that peer is a configured trusted proxy, and the chain walk is delegated to
+ * `getClientIp` so there is a single implementation of the hop logic. With
+ * the default `trustProxy` of `false` the peer address is returned unchanged,
+ * which is what an allowlist, per-IP rate limit or audit trail keyed on
+ * `req.ip` needs.
+ *
+ * @param request - The incoming Node request.
+ * @param trustProxy - Which peers may speak through `X-Forwarded-For`.
+ * @returns The client address, or `undefined` when the socket has none.
+ */
+export function getRequestIP(request, trustProxy = false) {
+    const proxyRequest = toProxyRequest(request);
+    const peer = proxyRequest.socket?.remoteAddress;
+    if (!isTrustedPeer(proxyRequest, trustProxy)) {
+        return peer ?? undefined;
     }
-    return request.socket.remoteAddress ?? undefined;
+    return getClientIp(proxyRequest, trustProxy) ?? peer ?? undefined;
 }
 /* -------------------------------------------------------------------------- */
 /* Query                                                                      */
 /* -------------------------------------------------------------------------- */
+/**
+ * Parses the query component of a request-target into a flat record.
+ *
+ * Delegates to the hardened `httpQuery` parser, the same one behind the Node
+ * adapter's `request.query` and the router's `ctx.query`. This function used
+ * to carry its own loop that accumulated into an object literal and read
+ * `result[key]` without an own-property check, which had two consequences on
+ * fully attacker-controlled input:
+ *
+ * - `?__proto__=a&__proto__=b` assigned an array through the `__proto__`
+ *   setter, so the returned query object's prototype became that array. The
+ *   parameter vanished from its own keys while the object silently gained
+ *   `length`, `map` and the rest of `Array.prototype`.
+ * - `?constructor=x` read the inherited `Object` constructor as the "existing"
+ *   value and stored it in the result, handing a handler
+ *   `query.constructor === [Function: Object], "x"]`.
+ *
+ * It also applied none of the four documented query limits, so a request with
+ * 50,000 parameters was parsed in full. Delegating fixes all three, and makes
+ * a limit breach throw {@link HTTPQueryLimitError} (414) as it already did on
+ * every other request path.
+ */
 export function parseQueryString(url) {
     const queryIndex = url.indexOf("?");
     if (queryIndex < 0) {
-        return {};
-    }
-    const queryString = url.slice(queryIndex + 1);
-    if (!queryString) {
-        return {};
-    }
-    const searchParams = new URLSearchParams(queryString);
-    const result = {};
-    for (const [key, value] of searchParams.entries()) {
-        const existing = result[key];
-        if (existing === undefined) {
-            result[key] = value;
-            continue;
-        }
-        if (Array.isArray(existing)) {
-            result[key] = [...existing, value];
-            continue;
-        }
-        result[key] = [existing, value];
+        return parseHardenedQueryString(undefined);
     }
-    return result;
+    const hashIndex = url.indexOf("#", queryIndex + 1);
+    return parseHardenedQueryString(url.slice(queryIndex + 1, hashIndex === -1 ? undefined : hashIndex));
 }
 /* -------------------------------------------------------------------------- */
 /* Method                                                                     */

package/dist/httpRequest/httpRequest.context.d.ts

@@ -66,7 +66,15 @@ export declare class HttpRequestContext {
     private protocolValue;
     private hostnameValue;
     private portValue;
+    private readonly signalValue;
     constructor(init: RequestContextInit);
+    /**
+     * Aborts when the request is abandoned — for the Node adapter, when the
+     * client disconnects before the response finished. `RequestContextInit`
+     * always accepted a `signal`, but the constructor dropped it, so the
+     * router handed every handler a signal that could never fire.
+     */
+    get signal(): AbortSignal | undefined;
     get headers(): RequestHeaders;
     hasHeader(name: string): boolean;
     getHeader(name: string): string | undefined;