@zudojs/http 0.1.0 → 1.1.0

package/dist/httpProtocol/http.protocol.js

@@ -0,0 +1,482 @@
+/**
+ * HTTP protocol helpers.
+ *
+ * This module contains the low level HTTP primitives shared by the HTTP
+ * server, client, router, request, and response layers.
+ */
+import { isHTTPMethod, normalizeHTTPMethod, } from "../httpMethods/http.methods.js";
+import { isValidHeaderName, isValidHeaderValue, isValidStatusCode, isValidHTTPURL, isValidRequestTarget, } from "../httpValidation/index.js";
+/* -------------------------------------------------------------------------- */
+/* Constants                                                                  */
+/* -------------------------------------------------------------------------- */
+export const HTTP_1_0 = {
+    major: 1,
+    minor: 0,
+};
+export const HTTP_1_1 = {
+    major: 1,
+    minor: 1,
+};
+export const HTTP_2_0 = {
+    major: 2,
+    minor: 0,
+};
+export const HTTP_3_0 = {
+    major: 3,
+    minor: 0,
+};
+export const DEFAULT_HTTP_VERSION = HTTP_1_1;
+/* -------------------------------------------------------------------------- */
+/* Version Helpers                                                            */
+/* -------------------------------------------------------------------------- */
+export function formatHTTPVersion(version) {
+    return `HTTP/${version.major}.${version.minor}`;
+}
+export function parseHTTPVersion(value) {
+    const match = /^HTTP\/(\d+)\.(\d+)$/.exec(value.trim());
+    if (!match) {
+        throw new TypeError(`Invalid HTTP version: ${value}`);
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+    };
+}
+export function isHTTPVersion(value) {
+    try {
+        parseHTTPVersion(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function compareHTTPVersions(left, right) {
+    if (left.major !== right.major) {
+        return left.major - right.major;
+    }
+    return left.minor - right.minor;
+}
+export function isHTTP11(version) {
+    return version.major === 1 && version.minor === 1;
+}
+export function isHTTP10(version) {
+    return version.major === 1 && version.minor === 0;
+}
+/* -------------------------------------------------------------------------- */
+/* Request Line                                                               */
+/* -------------------------------------------------------------------------- */
+export function formatRequestLine(request) {
+    if (!isHTTPMethod(request.method)) {
+        throw new TypeError(`Invalid HTTP method: ${request.method}`);
+    }
+    if (!isValidRequestTarget(request.target)) {
+        throw new TypeError(`Invalid HTTP request target: ${request.target}`);
+    }
+    return [
+        normalizeHTTPMethod(request.method),
+        request.target,
+        formatHTTPVersion(request.version),
+    ].join(" ");
+}
+export function parseRequestLine(line) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length !== 3) {
+        throw new TypeError("Invalid HTTP request line.");
+    }
+    const [method, target, version] = parts;
+    if (method === undefined || target === undefined || version === undefined) {
+        throw new TypeError("Invalid HTTP request line.");
+    }
+    if (!isHTTPMethod(method)) {
+        throw new TypeError(`Invalid HTTP method: ${method}`);
+    }
+    if (!isValidRequestTarget(target)) {
+        throw new TypeError(`Invalid HTTP request target: ${target}`);
+    }
+    return {
+        method: normalizeHTTPMethod(method),
+        target,
+        version: parseHTTPVersion(version),
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Status Line                                                                */
+/* -------------------------------------------------------------------------- */
+export function formatStatusLine(status) {
+    if (!isValidStatusCode(status.statusCode)) {
+        throw new RangeError(`Invalid HTTP status code: ${status.statusCode}`);
+    }
+    return [
+        formatHTTPVersion(status.version),
+        String(status.statusCode),
+        status.reasonPhrase,
+    ]
+        .filter((part) => part.length > 0)
+        .join(" ");
+}
+export function parseStatusLine(line) {
+    const trimmed = line.trim();
+    const match = /^(HTTP\/\d+\.\d+) (\d{3})(?: (.+))?$/.exec(trimmed);
+    if (!match) {
+        throw new TypeError("Invalid HTTP status line.");
+    }
+    const [, rawVersion, rawStatusCode] = match;
+    if (rawVersion === undefined || rawStatusCode === undefined) {
+        throw new TypeError("Invalid HTTP status line.");
+    }
+    const statusCode = Number(rawStatusCode);
+    if (!isValidStatusCode(statusCode)) {
+        throw new RangeError(`Invalid HTTP status code: ${statusCode}`);
+    }
+    return {
+        version: parseHTTPVersion(rawVersion),
+        statusCode,
+        reasonPhrase: match[3] ?? "",
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Header Formatting                                                          */
+/* -------------------------------------------------------------------------- */
+export function formatHeader(header) {
+    if (!isValidHeaderName(header.name)) {
+        throw new TypeError(`Invalid HTTP header name: ${header.name}`);
+    }
+    if (!isValidHeaderValue(header.value)) {
+        throw new TypeError(`Invalid HTTP header value for ${header.name}`);
+    }
+    return `${header.name}: ${header.value}`;
+}
+export function parseHeader(line) {
+    const separator = line.indexOf(":");
+    if (separator <= 0) {
+        throw new TypeError("Invalid HTTP header line.");
+    }
+    const name = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    if (!isValidHeaderName(name)) {
+        throw new TypeError(`Invalid HTTP header name: ${name}`);
+    }
+    if (!isValidHeaderValue(value)) {
+        throw new TypeError(`Invalid HTTP header value for ${name}`);
+    }
+    return {
+        name,
+        value,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Header Collection                                                          */
+/* -------------------------------------------------------------------------- */
+export function formatHeaders(headers) {
+    return headers.map(formatHeader).join("\r\n");
+}
+export function parseHeaders(value) {
+    if (value.length === 0) {
+        return [];
+    }
+    return value
+        .split(/\r\n/)
+        .filter((line) => line.length > 0)
+        .map(parseHeader);
+}
+export function getHeader(headers, name) {
+    const normalized = name.toLowerCase();
+    const header = headers.find((item) => item.name.toLowerCase() === normalized);
+    return header?.value;
+}
+export function getHeaders(headers, name) {
+    const normalized = name.toLowerCase();
+    return headers
+        .filter((item) => item.name.toLowerCase() === normalized)
+        .map((item) => item.value);
+}
+export function hasHeader(headers, name) {
+    return getHeader(headers, name) !== undefined;
+}
+/* -------------------------------------------------------------------------- */
+/* Header Mutation                                                            */
+/* -------------------------------------------------------------------------- */
+export function setHeader(headers, name, value) {
+    if (!isValidHeaderName(name)) {
+        throw new TypeError(`Invalid HTTP header name: ${name}`);
+    }
+    if (!isValidHeaderValue(value)) {
+        throw new TypeError(`Invalid HTTP header value for ${name}`);
+    }
+    const normalized = name.toLowerCase();
+    const result = [];
+    let replaced = false;
+    for (const header of headers) {
+        if (header.name.toLowerCase() === normalized) {
+            if (!replaced) {
+                result.push({
+                    name,
+                    value,
+                });
+                replaced = true;
+            }
+            continue;
+        }
+        result.push(header);
+    }
+    if (!replaced) {
+        result.push({
+            name,
+            value,
+        });
+    }
+    return result;
+}
+export function appendHeader(headers, name, value) {
+    if (!isValidHeaderName(name)) {
+        throw new TypeError(`Invalid HTTP header name: ${name}`);
+    }
+    if (!isValidHeaderValue(value)) {
+        throw new TypeError(`Invalid HTTP header value for ${name}`);
+    }
+    return [
+        ...headers,
+        {
+            name,
+            value,
+        },
+    ];
+}
+export function deleteHeader(headers, name) {
+    const normalized = name.toLowerCase();
+    return headers.filter((header) => header.name.toLowerCase() !== normalized);
+}
+/* -------------------------------------------------------------------------- */
+/* Request URL Helpers                                                        */
+/* -------------------------------------------------------------------------- */
+export function isAbsoluteHTTPURL(value) {
+    return isValidHTTPURL(value);
+}
+export function isOriginFormTarget(target) {
+    return target.startsWith("/") && target !== "";
+}
+export function isAbsoluteFormTarget(target) {
+    return isValidHTTPURL(target);
+}
+export function isAsteriskFormTarget(target) {
+    return target === "*";
+}
+export function isAuthorityFormTarget(target) {
+    return (!target.startsWith("/") &&
+        !target.startsWith("*") &&
+        !target.includes("://") &&
+        /^[^/\s:]+:\d+$/.test(target));
+}
+/* -------------------------------------------------------------------------- */
+/* Connection Semantics                                                       */
+/* -------------------------------------------------------------------------- */
+export function shouldKeepAlive(version, connectionHeader) {
+    const tokens = connectionHeader?.split(",").map((token) => token.trim().toLowerCase()) ??
+        [];
+    if (tokens.includes("close")) {
+        return false;
+    }
+    if (tokens.includes("keep-alive")) {
+        return true;
+    }
+    return isHTTP11(version);
+}
+export function shouldCloseConnection(version, connectionHeader) {
+    return !shouldKeepAlive(version, connectionHeader);
+}
+/* -------------------------------------------------------------------------- */
+/* Transfer Encoding                                                          */
+/* -------------------------------------------------------------------------- */
+export function parseTransferEncoding(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean);
+}
+export function hasChunkedTransferEncoding(value) {
+    return parseTransferEncoding(value).includes("chunked");
+}
+/* -------------------------------------------------------------------------- */
+/* Connection Header                                                           */
+/* -------------------------------------------------------------------------- */
+export function parseConnectionTokens(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((token) => token.trim().toLowerCase())
+        .filter(Boolean);
+}
+export function hasConnectionToken(value, token) {
+    const normalized = token.trim().toLowerCase();
+    return parseConnectionTokens(value).includes(normalized);
+}
+/* -------------------------------------------------------------------------- */
+/* Content Length                                                             */
+/* -------------------------------------------------------------------------- */
+export function parseContentLength(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new TypeError("Invalid Content-Length header.");
+    }
+    const length = Number(trimmed);
+    if (!Number.isSafeInteger(length)) {
+        throw new RangeError("Content-Length exceeds the safe integer range.");
+    }
+    return length;
+}
+/* -------------------------------------------------------------------------- */
+/* HTTP Message Serialization                                                 */
+/* -------------------------------------------------------------------------- */
+export function serializeRequestHead(request, headers) {
+    return (formatRequestLine(request) + "\r\n" + formatHeaders(headers) + "\r\n\r\n");
+}
+export function serializeResponseHead(status, headers) {
+    return (formatStatusLine(status) + "\r\n" + formatHeaders(headers) + "\r\n\r\n");
+}
+/* -------------------------------------------------------------------------- */
+/* Reason Phrase                                                              */
+/* -------------------------------------------------------------------------- */
+const STANDARD_REASON_PHRASES = {
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+    300: "Multiple Choices",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    305: "Use Proxy",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Content Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Content",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+};
+export function getReasonPhrase(statusCode) {
+    return STANDARD_REASON_PHRASES[statusCode] ?? "";
+}
+export function createStatusLine(statusCode, version = DEFAULT_HTTP_VERSION, reasonPhrase) {
+    if (!isValidStatusCode(statusCode)) {
+        throw new RangeError(`Invalid HTTP status code: ${statusCode}`);
+    }
+    return {
+        version,
+        statusCode,
+        reasonPhrase: reasonPhrase ?? getReasonPhrase(statusCode),
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Status Classification                                                      */
+/* -------------------------------------------------------------------------- */
+export function isInformationalStatus(statusCode) {
+    return statusCode >= 100 && statusCode < 200;
+}
+export function isSuccessfulStatus(statusCode) {
+    return statusCode >= 200 && statusCode < 300;
+}
+export function isRedirectionStatus(statusCode) {
+    return statusCode >= 300 && statusCode < 400;
+}
+export function isClientErrorStatus(statusCode) {
+    return statusCode >= 400 && statusCode < 500;
+}
+export function isServerErrorStatus(statusCode) {
+    return statusCode >= 500 && statusCode < 600;
+}
+export function isErrorStatus(statusCode) {
+    return isClientErrorStatus(statusCode) || isServerErrorStatus(statusCode);
+}
+/* -------------------------------------------------------------------------- */
+/* Utility                                                                    */
+/* -------------------------------------------------------------------------- */
+export function cloneHeaders(headers) {
+    return headers.map((header) => ({
+        name: header.name,
+        value: header.value,
+    }));
+}
+export function headersToRecord(headers) {
+    const result = {};
+    for (const header of headers) {
+        const key = header.name.toLowerCase();
+        const existing = result[key];
+        result[key] =
+            existing === undefined ? header.value : `${existing}, ${header.value}`;
+    }
+    return result;
+}
+export function recordToHeaders(headers) {
+    if (!headers) {
+        return [];
+    }
+    return Object.entries(headers).map(([name, value]) => {
+        if (!isValidHeaderName(name)) {
+            throw new TypeError(`Invalid HTTP header name: ${name}`);
+        }
+        if (!isValidHeaderValue(value)) {
+            throw new TypeError(`Invalid HTTP header value for ${name}`);
+        }
+        return {
+            name,
+            value,
+        };
+    });
+}
+//# sourceMappingURL=http.protocol.js.map

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

@@ -0,0 +1,179 @@
+/**
+ * HTTP proxy utilities.
+ *
+ * Provides framework-agnostic proxy configuration, target resolution,
+ * forwarded-header handling, and proxy request helpers.
+ *
+ * This module does not perform network I/O. Actual proxy transport belongs
+ * to the server/client adapter layer.
+ */
+import type { HTTPHeader } from "../httpProtocol/http.protocol.js";
+export interface ProxyTarget {
+    readonly url: URL;
+    readonly protocol: string;
+    readonly hostname: string;
+    readonly port: number | undefined;
+    readonly pathname: string;
+    readonly search: string;
+}
+/**
+ * Controls which outbound targets this proxy may be pointed at.
+ *
+ * The default posture blocks the internal network. A proxy whose target is
+ * derived from a request is a server-side request forgery primitive: the
+ * classic payload is `http://169.254.169.254/latest/meta-data/iam/`, which
+ * returns cloud credentials to whoever can steer the target.
+ */
+export interface ProxySecurityOptions {
+    /**
+     * Allow loopback, link-local, private/unique-local, multicast and reserved
+     * destinations. Off by default. Turn it on only for a proxy whose target is
+     * fixed configuration, never one influenced by a request.
+     */
+    readonly allowPrivateTargets?: boolean;
+    /**
+     * When present, the target host must appear here (compared case-insensitively
+     * against the hostname). This is the only reliable control for a
+     * request-derived target.
+     */
+    readonly allowedHosts?: readonly string[];
+    /** Extra hostnames to refuse, on top of the built-in blocklist. */
+    readonly blockedHosts?: readonly string[];
+    /** Permit schemes other than http/https. Off by default. */
+    readonly allowInsecureProtocols?: boolean;
+}
+export interface ProxyOptions extends ProxySecurityOptions {
+    readonly target: string | URL;
+    readonly changeOrigin?: boolean;
+    readonly preserveHost?: boolean;
+    readonly xfwd?: boolean;
+    readonly secure?: boolean;
+    readonly timeout?: number;
+    readonly rewritePath?: (path: string, requestURL: URL) => string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * The front-end request a proxied request is being made on behalf of.
+ *
+ * `X-Forwarded-Proto` / `-Host` / `-For` describe the hop the **client** made,
+ * not the hop the proxy is about to make, so these values have to come from
+ * the incoming request.
+ */
+export interface ProxyClientContext {
+    /** Scheme the client used: `http` or `https`. */
+    readonly protocol?: string;
+    /** Host (with optional port) the client addressed. */
+    readonly host?: string;
+    /** Resolved client IP — see `httpTrustProxy.getClientIp`. */
+    readonly clientIp?: string;
+    /** Port the client connected to. */
+    readonly port?: number;
+}
+export interface ProxyRequest {
+    readonly method: string;
+    readonly target: ProxyTarget;
+    readonly path: string;
+    readonly headers: readonly HTTPHeader[];
+}
+export interface ForwardedAddress {
+    readonly protocol?: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly for?: string;
+}
+export interface ProxyRewriteOptions {
+    readonly stripPrefix?: string;
+    readonly prependPrefix?: string;
+}
+/**
+ * Host names that name the local machine or a cloud instance-metadata service.
+ * Compared after lower-casing and stripping a trailing dot.
+ */
+export declare const BLOCKED_PROXY_HOSTS: readonly string[];
+/**
+ * Host suffixes that only ever resolve inside a private network.
+ */
+export declare const BLOCKED_PROXY_HOST_SUFFIXES: readonly string[];
+/**
+ * Explains why a proxy target is refused, or returns `undefined` when it is
+ * acceptable.
+ *
+ * **Limitation, by design:** this module performs no I/O, so a hostname is
+ * checked as a literal only. A name that *resolves* to `169.254.169.254`
+ * passes here. The transport layer must re-apply this check against the
+ * resolved address immediately before connecting (and again on every
+ * redirect), or the DNS-rebinding variant of the same attack still works.
+ * `isBlockedProxyAddress` is exported for exactly that call.
+ */
+export declare function getProxyTargetRejection(target: string | URL, options?: ProxySecurityOptions): string | undefined;
+/**
+ * True when a resolved IP address must not be connected to.
+ *
+ * Call this from the transport layer with the address DNS actually returned.
+ */
+export declare function isBlockedProxyAddress(address: string): boolean;
+export declare function isSafeProxyTarget(target: string | URL, options?: ProxySecurityOptions): boolean;
+/**
+ * Throws unless the target passes {@link getProxyTargetRejection}.
+ */
+export declare function assertSafeProxyTarget(target: string | URL, options?: ProxySecurityOptions): void;
+/**
+ * Validates a redirect the upstream returned before it is followed.
+ *
+ * A redirect re-crosses the trust boundary: the first request may be to an
+ * allowlisted host, and its `302` to `http://169.254.169.254/`. The location is
+ * resolved against the current URL and then subjected to the same guard as the
+ * original target.
+ */
+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;
+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;
+export declare function buildProxyRequestPath(target: ProxyTarget, requestPath: string, rewritePath?: (path: string, requestURL: URL) => string): string;
+/**
+ * Builds the header list for the upstream request.
+ *
+ * Hop-by-hop headers are removed **first**. Forwarding `Transfer-Encoding`
+ * alongside the front end's `Content-Length` is the canonical CL.TE
+ * request-smuggling setup; forwarding `Proxy-Authorization` leaks the proxy's
+ * own credentials upstream; forwarding `Connection: close` destroys upstream
+ * keep-alive pooling.
+ */
+export declare function prepareProxyHeaders(headers: readonly HTTPHeader[], target: ProxyTarget, options?: Pick<ProxyOptions, "changeOrigin" | "preserveHost" | "xfwd">, client?: ProxyClientContext): HTTPHeader[];
+export declare function applyProxyHeaders(headers: readonly HTTPHeader[], additionalHeaders: Readonly<Record<string, string>> | undefined): HTTPHeader[];
+/**
+ * Sets the `X-Forwarded-*` headers on an outbound proxy request.
+ *
+ * `X-Forwarded-Proto` and `X-Forwarded-Host` describe **the scheme and host
+ * the client originally used**, not the upstream this proxy is about to call,
+ * and they are *overwritten* rather than appended to. Appending lets a client
+ * that sends `X-Forwarded-Proto: https` to a plain-HTTP proxy produce
+ * `https, http`, and every consumer in this package reads `[0]` — so the
+ * upstream concludes the request arrived over TLS and issues `Secure` cookies
+ * over cleartext.
+ *
+ * `X-Forwarded-For` is the one header that is appended, because it is a chain:
+ * the client address is added to whatever trusted hops already recorded. It is
+ * only added when `client.clientIp` is supplied — the caller must resolve it
+ * with `httpTrustProxy.getClientIp` rather than copying the raw header.
+ */
+export declare function setForwardedHeaders(headers: readonly HTTPHeader[], target: ProxyTarget, client?: ProxyClientContext): HTTPHeader[];
+export declare function createForwardedHeader(address: ForwardedAddress): string;
+export declare function parseForwardedHeader(value: string | undefined | null): ForwardedAddress[];
+/**
+ * Builds an upstream request description.
+ *
+ * The target passes the SSRF guard, hop-by-hop headers are stripped, and the
+ * `X-Forwarded-*` values come from `client` (the incoming request), not from
+ * the upstream target.
+ */
+export declare function createProxyRequest(method: string, requestPath: string, headers: readonly HTTPHeader[], options: ProxyOptions, client?: ProxyClientContext): ProxyRequest;
+export declare function formatHost(url: URL): string;
+export declare function getProxyHost(target: string | URL): string;
+export declare function removeHopByHopHeaders(headers: readonly HTTPHeader[]): HTTPHeader[];
+export declare function resolveProxyURL(target: string | URL, path: string): URL;
+export declare function isSameOrigin(left: string | URL, right: string | URL): boolean;
+export declare function normalizeProxyOptions(options: ProxyOptions): ProxyOptions;
+//# sourceMappingURL=http.proxy.d.ts.map