@zudojs/http 1.1.0 → 1.3.0

package/dist/httpQuery/querySerialize/query.util.d.ts

@@ -0,0 +1,21 @@
+import type { QueryObject } from "../queryTypes/index.js";
+/**
+ * Deep-copies a parsed query object.
+ *
+ * Structural rather than a `JSON.parse(JSON.stringify(…))` round-trip. That
+ * round-trip rebuilt every level with `Object.prototype`, so the clone of a
+ * hardened, null-prototype query silently regained `toString`, `constructor`
+ * and every other inherited member — the exact property the parser exists to
+ * guarantee. It also violated the repo rule against calling `JSON` directly.
+ */
+export declare function cloneQuery(query: QueryObject): QueryObject;
+/**
+ * Merges query objects left to right into a fresh null-prototype object.
+ *
+ * Every value is deep-copied on the way in. Assigning the source's own
+ * nested object by reference made the result alias its inputs, so mutating
+ * `merged.a.b` also changed the source query the caller had already handed
+ * to something else.
+ */
+export declare function mergeQuery(...queries: QueryObject[]): QueryObject;
+//# sourceMappingURL=query.util.d.ts.map

package/dist/httpQuery/querySerialize/query.util.js

@@ -0,0 +1,67 @@
+import { createQueryContainer, DEFAULT_QUERY_MAX_DEPTH, HTTPQueryLimitError, isForbiddenQueryKey, isQueryObject, ownValue, } from "../queryTypes/index.js";
+/**
+ * Deep-copies a parsed query object.
+ *
+ * Structural rather than a `JSON.parse(JSON.stringify(…))` round-trip. That
+ * round-trip rebuilt every level with `Object.prototype`, so the clone of a
+ * hardened, null-prototype query silently regained `toString`, `constructor`
+ * and every other inherited member — the exact property the parser exists to
+ * guarantee. It also violated the repo rule against calling `JSON` directly.
+ */
+export function cloneQuery(query) {
+    return cloneQueryObject(query, DEFAULT_QUERY_MAX_DEPTH);
+}
+function cloneQueryObject(source, depth) {
+    if (depth <= 0) {
+        throw new HTTPQueryLimitError("Query object nesting exceeds the maximum allowed depth.");
+    }
+    const result = createQueryContainer();
+    for (const [key, value] of Object.entries(source)) {
+        if (isForbiddenQueryKey(key)) {
+            continue;
+        }
+        result[key] = cloneQueryValue(value, depth);
+    }
+    return result;
+}
+function cloneQueryValue(value, depth) {
+    if (Array.isArray(value)) {
+        return value.map((item) => cloneQueryValue(item, depth - 1));
+    }
+    if (isQueryObject(value)) {
+        return cloneQueryObject(value, depth - 1);
+    }
+    return value;
+}
+/**
+ * Merges query objects left to right into a fresh null-prototype object.
+ *
+ * Every value is deep-copied on the way in. Assigning the source's own
+ * nested object by reference made the result alias its inputs, so mutating
+ * `merged.a.b` also changed the source query the caller had already handed
+ * to something else.
+ */
+export function mergeQuery(...queries) {
+    const result = createQueryContainer();
+    for (const query of queries) {
+        mergeQueryObject(result, query, DEFAULT_QUERY_MAX_DEPTH);
+    }
+    return result;
+}
+function mergeQueryObject(target, source, depth) {
+    if (depth <= 0) {
+        throw new HTTPQueryLimitError("Query object nesting exceeds the maximum allowed depth.");
+    }
+    for (const [key, value] of Object.entries(source)) {
+        if (isForbiddenQueryKey(key)) {
+            continue;
+        }
+        const existing = ownValue(target, key);
+        if (isQueryObject(existing) && isQueryObject(value)) {
+            mergeQueryObject(existing, value, depth - 1);
+            continue;
+        }
+        target[key] = cloneQueryValue(value, depth);
+    }
+}
+//# sourceMappingURL=query.util.js.map

package/dist/httpQuery/querySerialize/querySerialize.core.d.ts

@@ -0,0 +1,12 @@
+import type { QueryObject, QueryStringifyOptions } 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 declare function stringifyQuery(query: QueryObject | Record<string, unknown>, options?: QueryStringifyOptions): string;
+export declare function buildQueryString(query: QueryObject | Record<string, unknown>, options?: QueryStringifyOptions): string;
+//# sourceMappingURL=querySerialize.core.d.ts.map

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[];