@zudojs/http 0.1.0 → 1.1.0

package/dist/httpTrustProxy/httpTrustProxy.ip.d.ts

@@ -0,0 +1,49 @@
+/**
+ * IP address and CIDR primitives for trust-proxy evaluation.
+ *
+ * `trustProxy` decides whether a socket peer may dictate the client's identity
+ * via `X-Forwarded-*`. That decision has to be made by comparing real
+ * addresses, so this module parses IPv4, IPv6 and IPv4-mapped IPv6 into bytes
+ * and performs prefix matching. String equality is not sufficient: `10.0.0.1`,
+ * `::ffff:10.0.0.1` and `[::ffff:10.0.0.1]%eth0` are the same peer.
+ *
+ * @module httpTrustProxy/ip
+ */
+export type IpFamily = 4 | 6;
+export interface ParsedIp {
+    readonly family: IpFamily;
+    readonly bytes: Uint8Array;
+}
+export interface ParsedCidr {
+    readonly family: IpFamily;
+    readonly bytes: Uint8Array;
+    readonly prefix: number;
+}
+/**
+ * Strips the decorations Node and proxies add to an address literal:
+ * surrounding brackets, an IPv6 zone identifier, and surrounding whitespace.
+ */
+export declare function normalizeIpAddress(value: string): string;
+/**
+ * Parses an address literal. IPv4-mapped IPv6 addresses collapse to IPv4 so
+ * that `::ffff:127.0.0.1` matches a `127.0.0.0/8` rule.
+ */
+export declare function parseIpAddress(value: string): ParsedIp | undefined;
+export declare function isIpAddress(value: string): boolean;
+/**
+ * Parses `address/prefix`. Returns `undefined` when the value is not CIDR
+ * notation or the prefix is out of range for the address family.
+ */
+export declare function parseCidr(value: string): ParsedCidr | undefined;
+export declare function ipMatchesCidr(address: ParsedIp, cidr: ParsedCidr): boolean;
+export declare function ipEquals(left: ParsedIp, right: ParsedIp): boolean;
+export declare const LOOPBACK_RANGES: readonly string[];
+export declare const LINK_LOCAL_RANGES: readonly string[];
+export declare const UNIQUE_LOCAL_RANGES: readonly string[];
+/** `127.0.0.0/8` and `::1/128` — exact, not `startsWith("::1")`. */
+export declare function isLoopbackAddress(value: string): boolean;
+/** `169.254.0.0/16` and `fe80::/10` — the actual link-local ranges. */
+export declare function isLinkLocalAddress(value: string): boolean;
+/** RFC 1918 plus `fc00::/7`. */
+export declare function isUniqueLocalAddress(value: string): boolean;
+//# sourceMappingURL=httpTrustProxy.ip.d.ts.map

package/dist/httpTrustProxy/httpTrustProxy.ip.js

@@ -0,0 +1,238 @@
+/**
+ * IP address and CIDR primitives for trust-proxy evaluation.
+ *
+ * `trustProxy` decides whether a socket peer may dictate the client's identity
+ * via `X-Forwarded-*`. That decision has to be made by comparing real
+ * addresses, so this module parses IPv4, IPv6 and IPv4-mapped IPv6 into bytes
+ * and performs prefix matching. String equality is not sufficient: `10.0.0.1`,
+ * `::ffff:10.0.0.1` and `[::ffff:10.0.0.1]%eth0` are the same peer.
+ *
+ * @module httpTrustProxy/ip
+ */
+/**
+ * Strips the decorations Node and proxies add to an address literal:
+ * surrounding brackets, an IPv6 zone identifier, and surrounding whitespace.
+ */
+export function normalizeIpAddress(value) {
+    let result = value.trim();
+    if (result.startsWith("[")) {
+        const end = result.indexOf("]");
+        if (end !== -1) {
+            result = result.slice(1, end);
+        }
+    }
+    const zone = result.indexOf("%");
+    if (zone !== -1) {
+        result = result.slice(0, zone);
+    }
+    return result.toLowerCase();
+}
+function parseIPv4Bytes(value) {
+    const parts = value.split(".");
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    const bytes = new Uint8Array(4);
+    let index = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part)) {
+            return undefined;
+        }
+        const octet = Number(part);
+        if (octet > 255) {
+            return undefined;
+        }
+        bytes[index] = octet;
+        index += 1;
+    }
+    return bytes;
+}
+function expandIPv6Groups(groups, out) {
+    const last = groups.length - 1;
+    let index = 0;
+    for (const group of groups) {
+        if (index === last && group.includes(".")) {
+            const embedded = parseIPv4Bytes(group);
+            if (!embedded) {
+                return false;
+            }
+            out.push(embedded[0] ?? 0, embedded[1] ?? 0, embedded[2] ?? 0, embedded[3] ?? 0);
+            index += 1;
+            continue;
+        }
+        if (!/^[0-9a-f]{1,4}$/.test(group)) {
+            return false;
+        }
+        const word = Number.parseInt(group, 16);
+        out.push((word >> 8) & 0xff, word & 0xff);
+        index += 1;
+    }
+    return true;
+}
+function parseIPv6Bytes(value) {
+    if (!value.includes(":")) {
+        return undefined;
+    }
+    const compression = value.indexOf("::");
+    if (compression !== value.lastIndexOf("::")) {
+        return undefined;
+    }
+    const headText = compression === -1 ? value : value.slice(0, compression);
+    const tailText = compression === -1 ? "" : value.slice(compression + 2);
+    const head = [];
+    const tail = [];
+    if (!expandIPv6Groups(headText.length > 0 ? headText.split(":") : [], head) ||
+        !expandIPv6Groups(tailText.length > 0 ? tailText.split(":") : [], tail)) {
+        return undefined;
+    }
+    const bytes = new Uint8Array(16);
+    if (compression === -1) {
+        if (head.length !== 16) {
+            return undefined;
+        }
+        bytes.set(head);
+        return bytes;
+    }
+    /* `::` stands for at least one all-zero group. */
+    if (head.length + tail.length > 14) {
+        return undefined;
+    }
+    bytes.set(head, 0);
+    bytes.set(tail, 16 - tail.length);
+    return bytes;
+}
+function unmapIPv4(bytes) {
+    for (let index = 0; index < 10; index += 1) {
+        if (bytes[index] !== 0) {
+            return undefined;
+        }
+    }
+    if (bytes[10] !== 0xff || bytes[11] !== 0xff) {
+        return undefined;
+    }
+    return bytes.slice(12);
+}
+/**
+ * Parses an address literal. IPv4-mapped IPv6 addresses collapse to IPv4 so
+ * that `::ffff:127.0.0.1` matches a `127.0.0.0/8` rule.
+ */
+export function parseIpAddress(value) {
+    const normalized = normalizeIpAddress(value);
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    const v4 = parseIPv4Bytes(normalized);
+    if (v4) {
+        return { family: 4, bytes: v4 };
+    }
+    const v6 = parseIPv6Bytes(normalized);
+    if (!v6) {
+        return undefined;
+    }
+    const mapped = unmapIPv4(v6);
+    if (mapped) {
+        return { family: 4, bytes: mapped };
+    }
+    return { family: 6, bytes: v6 };
+}
+export function isIpAddress(value) {
+    return parseIpAddress(value) !== undefined;
+}
+/**
+ * Parses `address/prefix`. Returns `undefined` when the value is not CIDR
+ * notation or the prefix is out of range for the address family.
+ */
+export function parseCidr(value) {
+    const slash = value.lastIndexOf("/");
+    if (slash === -1) {
+        return undefined;
+    }
+    const address = parseIpAddress(value.slice(0, slash));
+    const prefixText = value.slice(slash + 1).trim();
+    if (!address || !/^\d{1,3}$/.test(prefixText)) {
+        return undefined;
+    }
+    const prefix = Number(prefixText);
+    if (prefix > (address.family === 4 ? 32 : 128)) {
+        return undefined;
+    }
+    return { family: address.family, bytes: address.bytes, prefix };
+}
+export function ipMatchesCidr(address, cidr) {
+    if (address.family !== cidr.family) {
+        return false;
+    }
+    let remaining = cidr.prefix;
+    let index = 0;
+    while (remaining >= 8) {
+        if (address.bytes[index] !== cidr.bytes[index]) {
+            return false;
+        }
+        remaining -= 8;
+        index += 1;
+    }
+    if (remaining === 0) {
+        return true;
+    }
+    const mask = (0xff << (8 - remaining)) & 0xff;
+    return (((address.bytes[index] ?? 0) & mask) === ((cidr.bytes[index] ?? 0) & mask));
+}
+export function ipEquals(left, right) {
+    if (left.family !== right.family ||
+        left.bytes.length !== right.bytes.length) {
+        return false;
+    }
+    for (let index = 0; index < left.bytes.length; index += 1) {
+        if (left.bytes[index] !== right.bytes[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+function compileRanges(ranges) {
+    const result = [];
+    for (const range of ranges) {
+        const parsed = parseCidr(range);
+        if (parsed) {
+            result.push(parsed);
+        }
+    }
+    return result;
+}
+export const LOOPBACK_RANGES = Object.freeze([
+    "127.0.0.0/8",
+    "::1/128",
+]);
+export const LINK_LOCAL_RANGES = Object.freeze([
+    "169.254.0.0/16",
+    "fe80::/10",
+]);
+export const UNIQUE_LOCAL_RANGES = Object.freeze([
+    "10.0.0.0/8",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+    "fc00::/7",
+]);
+const LOOPBACK_CIDRS = compileRanges(LOOPBACK_RANGES);
+const LINK_LOCAL_CIDRS = compileRanges(LINK_LOCAL_RANGES);
+const UNIQUE_LOCAL_CIDRS = compileRanges(UNIQUE_LOCAL_RANGES);
+function matchesAny(value, cidrs) {
+    const address = parseIpAddress(value);
+    if (!address) {
+        return false;
+    }
+    return cidrs.some((cidr) => ipMatchesCidr(address, cidr));
+}
+/** `127.0.0.0/8` and `::1/128` — exact, not `startsWith("::1")`. */
+export function isLoopbackAddress(value) {
+    return matchesAny(value, LOOPBACK_CIDRS);
+}
+/** `169.254.0.0/16` and `fe80::/10` — the actual link-local ranges. */
+export function isLinkLocalAddress(value) {
+    return matchesAny(value, LINK_LOCAL_CIDRS);
+}
+/** RFC 1918 plus `fc00::/7`. */
+export function isUniqueLocalAddress(value) {
+    return matchesAny(value, UNIQUE_LOCAL_CIDRS);
+}
+//# sourceMappingURL=httpTrustProxy.ip.js.map

package/dist/httpTrustProxy/httpTrustProxy.parsing.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Forwarded header parsing.
+ *
+ * @module httpTrustProxy/parsing
+ */
+import type { ProxyRequest, ForwardedAddress } from "./httpTrustProxy.type.js";
+/**
+ * Splits an address literal into address and port.
+ *
+ * Handles `1.2.3.4`, `1.2.3.4:8080`, `[::1]`, `[::1]:8080` and bare `::1`.
+ * A bare IPv6 literal is never split on `:` — that is what turned `[::1]:8080`
+ * into `[` in the previous host parsing.
+ */
+export declare function splitAddressAndPort(value: string): {
+    readonly address: string;
+    readonly port: number | undefined;
+};
+/**
+ * Parses the X-Forwarded-For header into individual addresses, left to right
+ * (client first, nearest proxy last).
+ */
+export declare function parseForwardedFor(request: ProxyRequest): readonly ForwardedAddress[];
+/**
+ * Parses the Forwarded header (RFC 7239).
+ */
+export declare function parseForwarded(request: ProxyRequest): readonly ForwardedAddress[];
+/**
+ * Gets all forwarded client addresses from the request, ordered left to right
+ * (originating client first, nearest proxy last).
+ */
+export declare function getForwardedClientAddresses(request: ProxyRequest): readonly ForwardedAddress[];
+//# sourceMappingURL=httpTrustProxy.parsing.d.ts.map

package/dist/httpTrustProxy/httpTrustProxy.parsing.js

@@ -0,0 +1,133 @@
+/**
+ * Forwarded header parsing.
+ *
+ * @module httpTrustProxy/parsing
+ */
+import { X_FORWARDED_FOR, FORWARDED_HEADER } from "./httpTrustProxy.type.js";
+import { isIpAddress, normalizeIpAddress } from "./httpTrustProxy.ip.js";
+function headerValue(header) {
+    /*
+     * Node collapses repeated `X-Forwarded-For` headers into an array. The full
+     * chain is every entry in order, not just the first — taking `[0]` would
+     * drop the hops an attacker most wants dropped.
+     */
+    if (Array.isArray(header)) {
+        return header.join(", ");
+    }
+    return header;
+}
+/**
+ * Splits an address literal into address and port.
+ *
+ * Handles `1.2.3.4`, `1.2.3.4:8080`, `[::1]`, `[::1]:8080` and bare `::1`.
+ * A bare IPv6 literal is never split on `:` — that is what turned `[::1]:8080`
+ * into `[` in the previous host parsing.
+ */
+export function splitAddressAndPort(value) {
+    const trimmed = value.trim().replace(/^"|"$/g, "");
+    if (trimmed.startsWith("[")) {
+        const end = trimmed.indexOf("]");
+        if (end !== -1) {
+            const address = trimmed.slice(1, end);
+            const rest = trimmed.slice(end + 1);
+            if (rest.startsWith(":")) {
+                const port = Number.parseInt(rest.slice(1), 10);
+                return {
+                    address,
+                    port: Number.isInteger(port) ? port : undefined,
+                };
+            }
+            return { address, port: undefined };
+        }
+    }
+    const colon = trimmed.indexOf(":");
+    /* More than one colon means a bare IPv6 literal, which carries no port. */
+    if (colon === -1 || trimmed.indexOf(":", colon + 1) !== -1) {
+        return { address: trimmed, port: undefined };
+    }
+    const port = Number.parseInt(trimmed.slice(colon + 1), 10);
+    return {
+        address: trimmed.slice(0, colon),
+        port: Number.isInteger(port) ? port : undefined,
+    };
+}
+/**
+ * Parses the X-Forwarded-For header into individual addresses, left to right
+ * (client first, nearest proxy last).
+ */
+export function parseForwardedFor(request) {
+    const value = headerValue(request.headers[X_FORWARDED_FOR]);
+    if (!value) {
+        return [];
+    }
+    const result = [];
+    for (const entry of value.split(",")) {
+        const { address, port } = splitAddressAndPort(entry);
+        if (address.length === 0) {
+            continue;
+        }
+        result.push({
+            address: isIpAddress(address) ? normalizeIpAddress(address) : address,
+            port,
+            source: X_FORWARDED_FOR,
+        });
+    }
+    return result;
+}
+/**
+ * Parses the Forwarded header (RFC 7239).
+ */
+export function parseForwarded(request) {
+    const value = headerValue(request.headers[FORWARDED_HEADER]);
+    if (!value) {
+        return [];
+    }
+    const result = [];
+    for (const entry of value.split(",")) {
+        let rawFor = "";
+        let protocol;
+        let host;
+        for (const part of entry.split(";")) {
+            const separator = part.indexOf("=");
+            if (separator === -1) {
+                continue;
+            }
+            const key = part.slice(0, separator).trim().toLowerCase();
+            const raw = part
+                .slice(separator + 1)
+                .trim()
+                .replace(/^"|"$/g, "");
+            if (key === "for" && raw) {
+                rawFor = raw;
+                continue;
+            }
+            if (key === "proto" && raw) {
+                protocol = raw.toLowerCase();
+                continue;
+            }
+            if (key === "host" && raw) {
+                host = raw;
+            }
+        }
+        if (rawFor.length === 0 && protocol === undefined && host === undefined) {
+            continue;
+        }
+        const { address, port } = splitAddressAndPort(rawFor);
+        result.push({
+            address: isIpAddress(address) ? normalizeIpAddress(address) : address,
+            port,
+            protocol,
+            host,
+            source: FORWARDED_HEADER,
+        });
+    }
+    return result;
+}
+/**
+ * Gets all forwarded client addresses from the request, ordered left to right
+ * (originating client first, nearest proxy last).
+ */
+export function getForwardedClientAddresses(request) {
+    return [...parseForwarded(request), ...parseForwardedFor(request)].filter((entry) => entry.address.length > 0);
+}
+//# sourceMappingURL=httpTrustProxy.parsing.js.map

package/dist/httpTrustProxy/httpTrustProxy.type.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Trust proxy types and constants.
+ *
+ * @module httpTrustProxy/types
+ */
+export type TrustProxy = boolean | "all" | "linklocal" | "loopback" | string | readonly string[] | ((value: string, index: number) => boolean);
+export interface TrustProxyOptions {
+    readonly trustProxy?: TrustProxy;
+    readonly maxDepth?: number;
+    readonly strict?: boolean;
+}
+export interface ProxyRequest {
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    readonly socket?: {
+        readonly remoteAddress?: string;
+    };
+}
+export interface ForwardedAddress {
+    readonly address: string;
+    readonly port: number | undefined;
+    /** RFC 7239 `proto=` parameter, when present. */
+    readonly protocol?: string;
+    /** RFC 7239 `host=` parameter, when present. */
+    readonly host?: string;
+    readonly source: string;
+}
+export interface ProxyInfo {
+    readonly clientIp: string | undefined;
+    readonly clientPort: number | undefined;
+    readonly protocol: string | undefined;
+    readonly hostname: string | undefined;
+    readonly port: number | undefined;
+    readonly chain: readonly string[];
+}
+export declare const X_FORWARDED_FOR: "x-forwarded-for";
+export declare const X_FORWARDED_PROTO: "x-forwarded-proto";
+export declare const X_FORWARDED_HOST: "x-forwarded-host";
+export declare const X_FORWARDED_PORT: "x-forwarded-port";
+export declare const X_FORWARDED_PREFIX: "x-forwarded-prefix";
+export declare const FORWARDED_HEADER: "forwarded";
+//# sourceMappingURL=httpTrustProxy.type.d.ts.map

package/dist/httpTrustProxy/httpTrustProxy.type.js

@@ -0,0 +1,12 @@
+/**
+ * Trust proxy types and constants.
+ *
+ * @module httpTrustProxy/types
+ */
+export const X_FORWARDED_FOR = "x-forwarded-for";
+export const X_FORWARDED_PROTO = "x-forwarded-proto";
+export const X_FORWARDED_HOST = "x-forwarded-host";
+export const X_FORWARDED_PORT = "x-forwarded-port";
+export const X_FORWARDED_PREFIX = "x-forwarded-prefix";
+export const FORWARDED_HEADER = "forwarded";
+//# sourceMappingURL=httpTrustProxy.type.js.map

package/dist/httpUrl/http.url.d.ts

@@ -0,0 +1,143 @@
+/**
+ * HTTP URL utilities.
+ *
+ * Provides URL normalization, query parameter handling, path joining and
+ * origin helpers for the HTTP package.
+ *
+ * @remarks
+ * These helpers perform **no scheme validation**. `parseURL`, `toURL`,
+ * `resolveURL` and `resolveURLString` accept `javascript:`, `data:`, `file:`
+ * and any custom scheme, and `new URL(path, base)` discards the base entirely
+ * when `path` carries its own scheme. Any caller that builds a link, a
+ * redirect target or a fetch target from untrusted input must gate the result
+ * with {@link isHTTPOrHTTPSURL} first.
+ */
+export type URLInput = string | URL;
+export type QueryValue = string | number | boolean | bigint | null | undefined;
+export type QueryInput = URLSearchParams | Record<string, QueryValue | readonly QueryValue[]>;
+export interface ParsedURL {
+    readonly url: URL;
+    readonly protocol: string;
+    readonly hostname: string;
+    readonly port: string;
+    readonly pathname: string;
+    readonly search: string;
+    readonly hash: string;
+    readonly origin: string;
+}
+export declare const HTTP_PROTOCOL = "http:";
+export declare const HTTPS_PROTOCOL = "https:";
+export declare const DEFAULT_HTTP_PORT = 80;
+export declare const DEFAULT_HTTPS_PORT = 443;
+export declare function parseURL(input: URLInput, base?: URLInput): URL;
+export declare function tryParseURL(input: URLInput | undefined | null, base?: URLInput): URL | undefined;
+export declare function toURL(input: URLInput, base?: URLInput): URL;
+export declare function stringifyURL(input: URLInput): string;
+export declare function getOrigin(input: URLInput): string;
+export declare function getProtocol(input: URLInput): string;
+export declare function getHostname(input: URLInput): string;
+export declare function getPort(input: URLInput): number | undefined;
+export declare function getPathname(input: URLInput): string;
+export declare function getSearch(input: URLInput): string;
+export declare function getHash(input: URLInput): string;
+export declare function isHTTPURL(input: URLInput): boolean;
+export declare function isHTTPSURL(input: URLInput): boolean;
+export declare function isHTTPOrHTTPSURL(input: URLInput): boolean;
+export declare function isSecureURL(input: URLInput): boolean;
+/**
+ * Reports whether two URLs share a tuple origin.
+ *
+ * The WHATWG `origin` getter returns the literal string `"null"` for every
+ * non-special scheme (`data:`, `file:`, opaque `blob:`, custom schemes). That
+ * value means "opaque origin, equal to nothing, not even itself", so two
+ * `"null"` origins are reported as **not** same-origin rather than as a
+ * universal match.
+ */
+export declare function sameOrigin(left: URLInput, right: URLInput): boolean;
+export declare function sameHost(left: URLInput, right: URLInput): boolean;
+/**
+ * Reports whether two URLs have the identical hostname.
+ *
+ * @remarks
+ * This is host equality, **not** the web platform's "same site". Same-site
+ * compares registrable domains (eTLD+1), so `a.example.com` and
+ * `b.example.com` are same-site while this function reports `false`; and
+ * schemeful same-site also compares the scheme, which this function ignores.
+ * Do not use it for `SameSite` cookie, CSRF or cross-site navigation
+ * decisions.
+ */
+export declare function sameHostname(left: URLInput, right: URLInput): boolean;
+export declare function joinURLPath(...parts: string[]): string;
+/**
+ * Collapses `.` and `..` segments, clamping at the root.
+ *
+ * Each segment is percent-decoded before it is compared, so the encoded forms
+ * of a traversal (`%2e%2e`, `%2E%2e`) are collapsed exactly like the literal
+ * `..` instead of surviving normalisation for a later decoding stage to
+ * re-expand. A backslash is treated as a separator so Windows-style
+ * traversals normalise too. The emitted segments are the original, still
+ * encoded ones.
+ */
+export declare function normalizePath(path: string): string;
+export declare function ensureLeadingSlash(path: string): string;
+export declare function ensureTrailingSlash(path: string): string;
+export declare function removeTrailingSlash(path: string): string;
+export declare function removeLeadingSlash(path: string): string;
+export declare function resolveURL(base: URLInput, path: string): URL;
+export declare function resolveURLString(base: URLInput, path: string): string;
+export declare function appendPath(base: URLInput, ...paths: string[]): URL;
+export declare function getQuery(input: URLInput): URLSearchParams;
+export declare function getQueryParam(input: URLInput, name: string): string | null;
+export declare function getQueryParams(input: URLInput, name: string): string[];
+export declare function hasQueryParam(input: URLInput, name: string): boolean;
+export declare function setQueryParam(input: URLInput, name: string, value: QueryValue): URL;
+export declare function appendQueryParam(input: URLInput, name: string, value: QueryValue): URL;
+export declare function deleteQueryParam(input: URLInput, name: string): URL;
+export declare function setQueryParams(input: URLInput, query: QueryInput): URL;
+export declare function appendQueryParams(input: URLInput, query: QueryInput): URL;
+export declare function clearQuery(input: URLInput): URL;
+export declare function queryToString(query: QueryInput): string;
+export declare function queryToObject(input: URLInput | URLSearchParams): Record<string, string | string[]>;
+export declare function createURL(base: URLInput, options?: {
+    readonly path?: string;
+    readonly query?: QueryInput;
+    readonly hash?: string;
+}): URL;
+export declare function stripHash(input: URLInput): URL;
+export declare function stripQuery(input: URLInput): URL;
+export declare function stripCredentials(input: URLInput): URL;
+export declare function stripQueryAndHash(input: URLInput): URL;
+export declare function getURLUsername(input: URLInput): string;
+export declare function getURLPassword(input: URLInput): string;
+export declare function hasURLCredentials(input: URLInput): boolean;
+/**
+ * Reports whether a URL's host resolves to the local machine by literal form.
+ *
+ * Covers the whole `127.0.0.0/8` block, `0.0.0.0`, the IPv6 loopback in both
+ * bracketed and bare form, IPv4-mapped loopback, the non-canonical numeric
+ * forms (`2130706433`, `0177.0.0.1`, `0x7f.0.0.1`, `127.1`) and the
+ * trailing-dot FQDN.
+ *
+ * @remarks
+ * This inspects the literal host only. It cannot see a DNS name that
+ * *resolves* to loopback, and it does not cover the other private ranges. It
+ * is therefore **not** a complete SSRF control on its own — use
+ * {@link isPrivateHostLiteral} for the private ranges and resolve the name
+ * before connecting.
+ */
+export declare function isLocalhost(input: URLInput): boolean;
+/**
+ * Reports whether a URL's host literal is in a loopback, link-local or
+ * private range, including the non-canonical numeric IPv4 forms.
+ */
+export declare function isPrivateHostLiteral(input: URLInput): boolean;
+/**
+ * Reports whether a URL's host is an IP literal rather than a DNS name.
+ *
+ * Validates the address rather than pattern-matching it, so `999.999.999.999`
+ * and a bare hostname containing a colon are correctly rejected.
+ */
+export declare function isIPLiteral(input: URLInput): boolean;
+export declare function urlsEqual(left: URLInput, right: URLInput): boolean;
+export declare function urlsEquivalent(left: URLInput, right: URLInput): boolean;
+//# sourceMappingURL=http.url.d.ts.map