@zudojs/http 0.1.0 → 1.0.0

package/dist/httpHeaders/basic/httpHeaders.basicMatch.js

@@ -0,0 +1,45 @@
+/**
+ * Header value comparison utilities.
+ *
+ * @module httpHeaders/basicMatch
+ */
+import { asHTTPHeaders } from "../conversion/httpHeaders.conversion.js";
+/**
+ * Checks if a header equals an expected value.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @param expected - The expected value.
+ * @param options - Matching options (case sensitivity, trimming).
+ * @returns `true` if the header value matches.
+ */
+export function headerEquals(headers, name, expected, options = {}) {
+    const actual = asHTTPHeaders(headers).get(name);
+    if (actual === undefined) {
+        return false;
+    }
+    const left = options.trim === false ? actual : actual.trim();
+    const right = options.trim === false ? expected : expected.trim();
+    if (options.caseSensitive) {
+        return left === right;
+    }
+    return left.toLowerCase() === right.toLowerCase();
+}
+/**
+ * Checks if a header's comma-separated values contain a specific value.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @param value - The value to search for.
+ * @returns `true` if the value is found among the header's values.
+ */
+export function headerContains(headers, name, value) {
+    const actual = asHTTPHeaders(headers).get(name);
+    if (actual === undefined) {
+        return false;
+    }
+    return actual
+        .split(",")
+        .some((item) => item.trim().toLowerCase() === value.trim().toLowerCase());
+}
+//# sourceMappingURL=httpHeaders.basicMatch.js.map

package/dist/httpHeaders/conversion/httpHeaders.conversion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTTP header format conversion utilities.
+ *
+ * @module httpHeaders/conversion
+ */
+import { HTTPHeaders } from "../http.headers.js";
+import type { HTTPHeadersLike } from "../types/httpHeaders.type.js";
+/**
+ * Converts any supported header format into an {@link HTTPHeaders} instance.
+ *
+ * Entries whose name or value is malformed are skipped rather than thrown
+ * on: the input is frequently a raw, attacker-supplied header bag, and a
+ * read-only query such as `headerContains` must not be able to raise from
+ * one bad field.
+ *
+ * @param headers - The headers to convert. If omitted, returns an empty instance.
+ * @returns A new {@link HTTPHeaders} instance.
+ */
+export declare function toHTTPHeaders(headers?: HTTPHeadersLike): HTTPHeaders;
+/**
+ * Returns an {@link HTTPHeaders} view of any supported header format
+ * **without** copying when the input already is one.
+ *
+ * Read-only helpers should use this: `toHTTPHeaders` deep-copies the whole
+ * map on every call, so checking five headers copies it five times.
+ *
+ * @param headers - The headers to view.
+ * @returns The original instance, or a converted one.
+ */
+export declare function asHTTPHeaders(headers?: HTTPHeadersLike): HTTPHeaders;
+//# sourceMappingURL=httpHeaders.conversion.d.ts.map

package/dist/httpHeaders/conversion/httpHeaders.conversion.js

@@ -0,0 +1,103 @@
+/**
+ * HTTP header format conversion utilities.
+ *
+ * @module httpHeaders/conversion
+ */
+import { HTTPHeaders } from "../http.headers.js";
+import { isIterableHeaders } from "../internal/httpHeaders.internal.typeGuards.js";
+/**
+ * Converts any supported header format into an {@link HTTPHeaders} instance.
+ *
+ * Entries whose name or value is malformed are skipped rather than thrown
+ * on: the input is frequently a raw, attacker-supplied header bag, and a
+ * read-only query such as `headerContains` must not be able to raise from
+ * one bad field.
+ *
+ * @param headers - The headers to convert. If omitted, returns an empty instance.
+ * @returns A new {@link HTTPHeaders} instance.
+ */
+export function toHTTPHeaders(headers) {
+    if (headers === undefined) {
+        return new HTTPHeaders();
+    }
+    if (headers instanceof HTTPHeaders) {
+        return headers.clone();
+    }
+    return buildHTTPHeaders(headers);
+}
+/**
+ * Returns an {@link HTTPHeaders} view of any supported header format
+ * **without** copying when the input already is one.
+ *
+ * Read-only helpers should use this: `toHTTPHeaders` deep-copies the whole
+ * map on every call, so checking five headers copies it five times.
+ *
+ * @param headers - The headers to view.
+ * @returns The original instance, or a converted one.
+ */
+export function asHTTPHeaders(headers) {
+    if (headers === undefined) {
+        return new HTTPHeaders();
+    }
+    if (headers instanceof HTTPHeaders) {
+        return headers;
+    }
+    return buildHTTPHeaders(headers);
+}
+/**
+ * Builds a fresh {@link HTTPHeaders} from a non-{@link HTTPHeaders} input.
+ *
+ * @param headers - The headers to convert.
+ * @returns A new instance holding every well-formed entry.
+ */
+function buildHTTPHeaders(headers) {
+    const result = new HTTPHeaders();
+    if (headers instanceof Headers) {
+        headers.forEach((value, name) => {
+            appendSafely(result, name, value);
+        });
+        return result;
+    }
+    if (isIterableHeaders(headers)) {
+        for (const entry of headers) {
+            if (!Array.isArray(entry) || entry.length !== 2) {
+                continue;
+            }
+            appendSafely(result, String(entry[0]), String(entry[1]));
+        }
+        return result;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                appendSafely(result, name, String(item));
+            }
+            continue;
+        }
+        appendSafely(result, name, String(value));
+    }
+    return result;
+}
+/**
+ * Appends one header entry, skipping it if it is malformed.
+ *
+ * @param headers - The target headers.
+ * @param name - The header name.
+ * @param value - The header value.
+ */
+function appendSafely(headers, name, value) {
+    try {
+        headers.append(name, value);
+    }
+    catch {
+        /*
+         * A malformed name or a value carrying CR/LF/NUL is dropped. Throwing
+         * would turn a pure inspection call on attacker-supplied headers into an
+         * unhandled 500.
+         */
+    }
+}
+//# sourceMappingURL=httpHeaders.conversion.js.map

package/dist/httpHeaders/conversion/httpHeaders.conversionObject.d.ts

@@ -0,0 +1,21 @@
+/**
+ * HTTP header format conversion to native and object formats.
+ *
+ * @module httpHeaders/conversionObject
+ */
+import type { HTTPHeadersLike } from "../types/httpHeaders.type.js";
+/**
+ * Converts any supported header format into a native {@link Headers} instance.
+ *
+ * @param headers - The headers to convert. If omitted, returns an empty Headers.
+ * @returns A new {@link Headers} instance.
+ */
+export declare function toHeaders(headers?: HTTPHeadersLike): Headers;
+/**
+ * Converts any supported header format into a plain `Record<string, string>`.
+ *
+ * @param headers - The headers to convert. If omitted, returns an empty object.
+ * @returns A plain object with lowercased header names as keys.
+ */
+export declare function toHeaderObject(headers?: HTTPHeadersLike): Record<string, string>;
+//# sourceMappingURL=httpHeaders.conversionObject.d.ts.map

package/dist/httpHeaders/conversion/httpHeaders.conversionObject.js

@@ -0,0 +1,30 @@
+/**
+ * HTTP header format conversion to native and object formats.
+ *
+ * @module httpHeaders/conversionObject
+ */
+import { toHTTPHeaders } from "../conversion/httpHeaders.conversion.js";
+/**
+ * Converts any supported header format into a native {@link Headers} instance.
+ *
+ * @param headers - The headers to convert. If omitted, returns an empty Headers.
+ * @returns A new {@link Headers} instance.
+ */
+export function toHeaders(headers) {
+    const result = new Headers();
+    const normalized = toHTTPHeaders(headers);
+    normalized.forEach((value, name) => {
+        result.append(name, value);
+    });
+    return result;
+}
+/**
+ * Converts any supported header format into a plain `Record<string, string>`.
+ *
+ * @param headers - The headers to convert. If omitted, returns an empty object.
+ * @returns A plain object with lowercased header names as keys.
+ */
+export function toHeaderObject(headers) {
+    return toHTTPHeaders(headers).toObject();
+}
+//# sourceMappingURL=httpHeaders.conversionObject.js.map

package/dist/httpHeaders/etag/httpHeaders.etag.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ETag header utilities.
+ *
+ * @module httpHeaders/etag
+ */
+/**
+ * Normalizes an ETag value by trimming whitespace.
+ *
+ * @param value - The raw ETag value.
+ * @returns The trimmed ETag, or `undefined` if empty or undefined.
+ */
+export declare function normalizeETag(value: string | undefined): string | undefined;
+/**
+ * Checks if an ETag is a weak validator (prefixed with `W/`).
+ *
+ * @param value - The ETag value.
+ * @returns `true` if the ETag is weak.
+ */
+export declare function isWeakETag(value: string | undefined): boolean;
+/**
+ * Strips the weak validator prefix (`W/`) from an ETag.
+ *
+ * @param value - The ETag value.
+ * @returns The strong ETag, or `undefined` if empty or undefined.
+ */
+export declare function stripWeakETag(value: string | undefined): string | undefined;
+//# sourceMappingURL=httpHeaders.etag.d.ts.map

package/dist/httpHeaders/etag/httpHeaders.etag.js

@@ -0,0 +1,44 @@
+/**
+ * ETag header utilities.
+ *
+ * @module httpHeaders/etag
+ */
+/**
+ * Normalizes an ETag value by trimming whitespace.
+ *
+ * @param value - The raw ETag value.
+ * @returns The trimmed ETag, or `undefined` if empty or undefined.
+ */
+export function normalizeETag(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    return trimmed;
+}
+/**
+ * Checks if an ETag is a weak validator (prefixed with `W/`).
+ *
+ * @param value - The ETag value.
+ * @returns `true` if the ETag is weak.
+ */
+export function isWeakETag(value) {
+    return normalizeETag(value)?.toLowerCase().startsWith("w/") ?? false;
+}
+/**
+ * Strips the weak validator prefix (`W/`) from an ETag.
+ *
+ * @param value - The ETag value.
+ * @returns The strong ETag, or `undefined` if empty or undefined.
+ */
+export function stripWeakETag(value) {
+    const normalized = normalizeETag(value);
+    if (!normalized) {
+        return undefined;
+    }
+    return normalized.replace(/^W\//i, "").trim();
+}
+//# sourceMappingURL=httpHeaders.etag.js.map

package/dist/httpHeaders/etag/httpHeaders.etagMatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ETag comparison and list parsing utilities.
+ *
+ * @module httpHeaders/etagMatch
+ */
+/**
+ * Compares two entity tags.
+ *
+ * @param requested - The validator the client sent (the only side on which
+ *   `*` is meaningful).
+ * @param current - The current representation's validator.
+ * @param allowWeak - `true` (default) performs the weak comparison used by
+ *   `If-None-Match`. `false` performs the strong comparison required by
+ *   `If-Match` and `If-Range`: both validators must be strong *and*
+ *   byte-identical, so two weak tags never match.
+ * @returns `true` if the tags match under the selected comparison.
+ */
+export declare function etagMatches(requested: string | undefined, current: string | undefined, allowWeak?: boolean): boolean;
+/**
+ * Parses a comma-separated list of ETags.
+ *
+ * @param value - The raw ETag list string.
+ * @returns An array of trimmed ETag values.
+ */
+export declare function parseETagList(value: string | undefined): string[];
+//# sourceMappingURL=httpHeaders.etagMatch.d.ts.map

package/dist/httpHeaders/etag/httpHeaders.etagMatch.js

@@ -0,0 +1,53 @@
+/**
+ * ETag comparison and list parsing utilities.
+ *
+ * @module httpHeaders/etagMatch
+ */
+import { splitHeaderValues } from "../list/httpHeaders.list.js";
+import { isWeakETag, normalizeETag, stripWeakETag, } from "./httpHeaders.etag.js";
+/**
+ * Compares two entity tags.
+ *
+ * @param requested - The validator the client sent (the only side on which
+ *   `*` is meaningful).
+ * @param current - The current representation's validator.
+ * @param allowWeak - `true` (default) performs the weak comparison used by
+ *   `If-None-Match`. `false` performs the strong comparison required by
+ *   `If-Match` and `If-Range`: both validators must be strong *and*
+ *   byte-identical, so two weak tags never match.
+ * @returns `true` if the tags match under the selected comparison.
+ */
+export function etagMatches(requested, current, allowWeak = true) {
+    const left = normalizeETag(requested);
+    const right = normalizeETag(current);
+    if (!left || !right) {
+        return false;
+    }
+    /*
+     * The wildcard is only meaningful on the request side; accepting it from
+     * the current representation would make every comparison succeed.
+     */
+    if (left === "*") {
+        return true;
+    }
+    if (allowWeak) {
+        return stripWeakETag(left) === stripWeakETag(right);
+    }
+    if (isWeakETag(left) || isWeakETag(right)) {
+        return false;
+    }
+    return left === right;
+}
+/**
+ * Parses a comma-separated list of ETags.
+ *
+ * @param value - The raw ETag list string.
+ * @returns An array of trimmed ETag values.
+ */
+export function parseETagList(value) {
+    if (!value) {
+        return [];
+    }
+    return splitHeaderValues(value).map((item) => item.trim());
+}
+//# sourceMappingURL=httpHeaders.etagMatch.js.map

package/dist/httpHeaders/forwarded/httpHeaders.forwarded.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Forwarded / proxy header utilities.
+ *
+ * @module httpHeaders/forwarded
+ */
+import type { HTTPHeadersLike } from "../types/httpHeaders.type.js";
+/**
+ * Retrieves all forwarded values for a header, splitting nested comma-separated values.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name (e.g. `"Forwarded"` or `"X-Forwarded-For"`).
+ * @returns An array of all forwarded values.
+ */
+export declare function getForwardedValues(headers: HTTPHeadersLike, name: string): string[];
+/**
+ * Retrieves the leftmost element of a forwarded header.
+ *
+ * @remarks
+ * **The result is fully attacker-controlled.** Every proxy *appends* to the
+ * right of `X-Forwarded-For`, so the leftmost element is whatever the client
+ * wrote — a request carrying `X-Forwarded-For: 127.0.0.1` makes this return
+ * `"127.0.0.1"`. Never use it for a rate limiter, audit log, geo-block or
+ * admin-IP allowlist; select from the right against a trusted-proxy count,
+ * or use `src/httpTrustProxy` instead.
+ *
+ * No IP syntax validation and no RFC 7239 `for=` extraction is performed, so
+ * a real `Forwarded` header yields a whole element such as
+ * `"for=1.2.3.4;proto=https"`.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @returns The untrusted leftmost value, or `undefined` if none exist.
+ */
+export declare function getUntrustedForwardedValue(headers: HTTPHeadersLike, name: string): string | undefined;
+//# sourceMappingURL=httpHeaders.forwarded.d.ts.map

package/dist/httpHeaders/forwarded/httpHeaders.forwarded.js

@@ -0,0 +1,39 @@
+/**
+ * Forwarded / proxy header utilities.
+ *
+ * @module httpHeaders/forwarded
+ */
+import { getHeaderValues, splitHeaderValues, } from "../list/httpHeaders.list.js";
+/**
+ * Retrieves all forwarded values for a header, splitting nested comma-separated values.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name (e.g. `"Forwarded"` or `"X-Forwarded-For"`).
+ * @returns An array of all forwarded values.
+ */
+export function getForwardedValues(headers, name) {
+    return getHeaderValues(headers, name).flatMap((value) => splitHeaderValues(value));
+}
+/**
+ * Retrieves the leftmost element of a forwarded header.
+ *
+ * @remarks
+ * **The result is fully attacker-controlled.** Every proxy *appends* to the
+ * right of `X-Forwarded-For`, so the leftmost element is whatever the client
+ * wrote — a request carrying `X-Forwarded-For: 127.0.0.1` makes this return
+ * `"127.0.0.1"`. Never use it for a rate limiter, audit log, geo-block or
+ * admin-IP allowlist; select from the right against a trusted-proxy count,
+ * or use `src/httpTrustProxy` instead.
+ *
+ * No IP syntax validation and no RFC 7239 `for=` extraction is performed, so
+ * a real `Forwarded` header yields a whole element such as
+ * `"for=1.2.3.4;proto=https"`.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @returns The untrusted leftmost value, or `undefined` if none exist.
+ */
+export function getUntrustedForwardedValue(headers, name) {
+    return getForwardedValues(headers, name)[0];
+}
+//# sourceMappingURL=httpHeaders.forwarded.js.map

package/dist/httpHeaders/forwarded/index.d.ts

@@ -4,5 +4,4 @@
  * HTTP headers forwarded utilities.
  */
 export * from "./httpHeaders.forwarded.js";
-export * from "./index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpHeaders/forwarded/index.js

@@ -4,5 +4,4 @@
  * HTTP headers forwarded utilities.
  */
 export * from "./httpHeaders.forwarded.js";
-export * from "./index.js";
 //# sourceMappingURL=index.js.map

package/dist/httpHeaders/http.headers.d.ts

@@ -0,0 +1,100 @@
+import type { IncomingHttpHeaders } from "node:http";
+export type HTTPHeadersInit = HTTPHeaders | Record<string, string | number | boolean | null | undefined> | Iterable<readonly [string, string | number | boolean]>;
+export type HTTPHeaderValue = string | number | boolean;
+export interface HTTPHeaderEntry {
+    readonly name: string;
+    readonly value: string;
+}
+export declare const HEADER_CONTENT_TYPE = "content-type";
+export declare const HEADER_CONTENT_LENGTH = "content-length";
+export declare const HEADER_ACCEPT = "accept";
+export declare const HEADER_AUTHORIZATION = "authorization";
+export declare const HEADER_USER_AGENT = "user-agent";
+export declare const HEADER_CACHE_CONTROL = "cache-control";
+export declare const HEADER_COOKIE = "cookie";
+export declare const HEADER_SET_COOKIE = "set-cookie";
+export declare const HEADER_LOCATION = "location";
+export declare const HEADER_HOST = "host";
+export declare const HEADER_ORIGIN = "origin";
+export declare const HEADER_REFERER = "referer";
+export declare const HEADER_X_REQUEST_ID = "x-request-id";
+export declare const HEADER_X_FORWARDED_FOR = "x-forwarded-for";
+export declare const HEADER_X_FORWARDED_HOST = "x-forwarded-host";
+export declare const HEADER_X_FORWARDED_PROTO = "x-forwarded-proto";
+export declare class HTTPHeaders implements Iterable<[string, string]> {
+    private readonly values;
+    constructor(init?: HTTPHeadersInit);
+    init(init: HTTPHeadersInit): this;
+    set(name: string, value: HTTPHeaderValue): this;
+    append(name: string, value: HTTPHeaderValue): this;
+    get(name: string): string | undefined;
+    /**
+     * Returns every value stored for a header name.
+     *
+     * Unlike {@link HTTPHeaders.get} this never folds multiple values into a
+     * single comma-joined string, so it is the correct accessor for
+     * `Set-Cookie`.
+     *
+     * @param name - The header name.
+     * @returns All stored values, in insertion order.
+     */
+    getAll(name: string): string[];
+    /**
+     * Returns every `Set-Cookie` value, never folded.
+     *
+     * @returns The stored `Set-Cookie` values in insertion order.
+     */
+    getSetCookie(): string[];
+    has(name: string): boolean;
+    delete(name: string): boolean;
+    clear(): void;
+    keys(): IterableIterator<string>;
+    valuesIterator(): IterableIterator<string>;
+    entries(): IterableIterator<[string, string]>;
+    /**
+     * Materialises the header map as folded `[name, value]` pairs.
+     *
+     * @returns One entry per header name, with the folded value.
+     */
+    private foldedEntries;
+    forEach(callback: (value: string, name: string) => void): void;
+    get size(): number;
+    isEmpty(): boolean;
+    clone(): HTTPHeaders;
+    toObject(): Record<string, string>;
+    /**
+     * Converts to a Node-style outgoing header record.
+     *
+     * Non-foldable headers (`Set-Cookie`) are emitted as arrays so that
+     * multiple values survive the round trip.
+     *
+     * @returns A record suitable for `ServerResponse.writeHead`.
+     */
+    toNodeHeaders(): Record<string, string | string[]>;
+    toJSON(): Record<string, string>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+export declare function createHeaders(init?: HTTPHeadersInit): HTTPHeaders;
+export declare function normalizeHeaders(headers: HTTPHeadersInit | IncomingHttpHeaders | undefined): HTTPHeaders;
+export declare function normalizeHeaderName(name: string): string;
+export declare function setContentType(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function setContentLength(headers: HTTPHeaders, length: number): HTTPHeaders;
+export declare function getAuthorization(headers: HTTPHeadersInit): string | undefined;
+export declare function setAuthorization(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function getUserAgent(headers: HTTPHeadersInit): string | undefined;
+export declare function setUserAgent(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function getAccept(headers: HTTPHeadersInit): string | undefined;
+export declare function setAccept(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function getCacheControl(headers: HTTPHeadersInit): string | undefined;
+export declare function setCacheControl(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function getLocation(headers: HTTPHeadersInit): string | undefined;
+export declare function setLocation(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function getCookieHeader(headers: HTTPHeadersInit): string | undefined;
+export declare function setCookieHeader(headers: HTTPHeaders, value: string): HTTPHeaders;
+export declare function getForwardedFor(headers: HTTPHeadersInit): string | undefined;
+export declare function getForwardedHost(headers: HTTPHeadersInit): string | undefined;
+export declare function getForwardedProto(headers: HTTPHeadersInit): string | undefined;
+export declare function getRequestId(headers: HTTPHeadersInit): string | undefined;
+export declare function setRequestId(headers: HTTPHeaders, requestId: string): HTTPHeaders;
+export declare function hasSecurityHeaders(headers: HTTPHeadersInit): boolean;
+//# sourceMappingURL=http.headers.d.ts.map