@zudojs/http 0.1.0 → 1.0.0

package/dist/httpHeaders/http.headers.js

@@ -0,0 +1,324 @@
+import { assertSafeHeaderName, assertSafeHeaderValue, } from "./security/httpHeaders.security.js";
+import { isIterableHeaders } from "./internal/httpHeaders.internal.typeGuards.js";
+/* -------------------------------------------------------------------------- */
+/* Constants                                                                  */
+/* -------------------------------------------------------------------------- */
+export const HEADER_CONTENT_TYPE = "content-type";
+export const HEADER_CONTENT_LENGTH = "content-length";
+export const HEADER_ACCEPT = "accept";
+export const HEADER_AUTHORIZATION = "authorization";
+export const HEADER_USER_AGENT = "user-agent";
+export const HEADER_CACHE_CONTROL = "cache-control";
+export const HEADER_COOKIE = "cookie";
+export const HEADER_SET_COOKIE = "set-cookie";
+export const HEADER_LOCATION = "location";
+export const HEADER_HOST = "host";
+export const HEADER_ORIGIN = "origin";
+export const HEADER_REFERER = "referer";
+export const HEADER_X_REQUEST_ID = "x-request-id";
+export const HEADER_X_FORWARDED_FOR = "x-forwarded-for";
+export const HEADER_X_FORWARDED_HOST = "x-forwarded-host";
+export const HEADER_X_FORWARDED_PROTO = "x-forwarded-proto";
+/* -------------------------------------------------------------------------- */
+/* HTTPHeaders                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Header names that must never be folded into a single comma-joined value.
+ *
+ * RFC 6265 §3 forbids folding `Set-Cookie`: cookie `Expires` attributes
+ * contain commas, so a comma-joined list cannot be split back apart.
+ */
+const NON_FOLDABLE_HEADERS = new Set(["set-cookie"]);
+export class HTTPHeaders {
+    values = new Map();
+    constructor(init) {
+        if (init !== undefined) {
+            this.init(init);
+        }
+    }
+    init(init) {
+        if (init instanceof HTTPHeaders) {
+            for (const name of init.keys()) {
+                for (const value of init.getAll(name)) {
+                    this.append(name, value);
+                }
+            }
+            return this;
+        }
+        if (isIterableHeaders(init)) {
+            for (const entry of init) {
+                if (!Array.isArray(entry) || entry.length !== 2) {
+                    continue;
+                }
+                this.set(String(entry[0]), String(entry[1]));
+            }
+            return this;
+        }
+        for (const [name, value] of Object.entries(init)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            this.set(name, String(value));
+        }
+        return this;
+    }
+    set(name, value) {
+        const normalized = normalizeHeaderName(name);
+        assertSafeHeaderName(normalized);
+        assertSafeHeaderValue(String(value));
+        this.values.set(normalized, [String(value)]);
+        return this;
+    }
+    append(name, value) {
+        const normalized = normalizeHeaderName(name);
+        assertSafeHeaderName(normalized);
+        const stringValue = String(value);
+        assertSafeHeaderValue(stringValue);
+        const existing = this.values.get(normalized);
+        if (existing === undefined) {
+            this.values.set(normalized, [stringValue]);
+        }
+        else {
+            existing.push(stringValue);
+        }
+        return this;
+    }
+    get(name) {
+        const normalized = normalizeHeaderName(name);
+        const stored = this.values.get(normalized);
+        if (stored === undefined || stored.length === 0) {
+            return undefined;
+        }
+        if (stored.length === 1) {
+            return stored[0];
+        }
+        if (NON_FOLDABLE_HEADERS.has(normalized)) {
+            return stored[0];
+        }
+        return stored.join(", ");
+    }
+    /**
+     * 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) {
+        return [...(this.values.get(normalizeHeaderName(name)) ?? [])];
+    }
+    /**
+     * Returns every `Set-Cookie` value, never folded.
+     *
+     * @returns The stored `Set-Cookie` values in insertion order.
+     */
+    getSetCookie() {
+        return this.getAll(HEADER_SET_COOKIE);
+    }
+    has(name) {
+        return this.values.has(normalizeHeaderName(name));
+    }
+    delete(name) {
+        return this.values.delete(normalizeHeaderName(name));
+    }
+    clear() {
+        this.values.clear();
+    }
+    keys() {
+        return this.values.keys();
+    }
+    valuesIterator() {
+        return this.foldedEntries()
+            .map(([, value]) => value)[Symbol.iterator]();
+    }
+    entries() {
+        return this.foldedEntries()[Symbol.iterator]();
+    }
+    /**
+     * Materialises the header map as folded `[name, value]` pairs.
+     *
+     * @returns One entry per header name, with the folded value.
+     */
+    foldedEntries() {
+        const entries = [];
+        for (const name of this.values.keys()) {
+            entries.push([name, this.get(name) ?? ""]);
+        }
+        return entries;
+    }
+    forEach(callback) {
+        for (const [name, value] of this.entries()) {
+            callback(value, name);
+        }
+    }
+    get size() {
+        return this.values.size;
+    }
+    isEmpty() {
+        return this.values.size === 0;
+    }
+    clone() {
+        const copy = new HTTPHeaders();
+        for (const [name, stored] of this.values) {
+            copy.values.set(name, [...stored]);
+        }
+        return copy;
+    }
+    toObject() {
+        return Object.fromEntries(this.entries());
+    }
+    /**
+     * 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() {
+        const result = {};
+        for (const [name, stored] of this.values) {
+            if (NON_FOLDABLE_HEADERS.has(name)) {
+                result[name] = [...stored];
+                continue;
+            }
+            result[name] = stored.join(", ");
+        }
+        return result;
+    }
+    toJSON() {
+        return this.toObject();
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory Helpers                                                            */
+/* -------------------------------------------------------------------------- */
+export function createHeaders(init) {
+    return new HTTPHeaders(init);
+}
+export function normalizeHeaders(headers) {
+    if (headers === undefined) {
+        return new HTTPHeaders();
+    }
+    if (headers instanceof HTTPHeaders) {
+        return headers.clone();
+    }
+    const result = new HTTPHeaders();
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                result.append(name, item);
+            }
+            continue;
+        }
+        result.set(name, value);
+    }
+    return result;
+}
+/* -------------------------------------------------------------------------- */
+/* Header Name Helpers                                                        */
+/* -------------------------------------------------------------------------- */
+export function normalizeHeaderName(name) {
+    return name.trim().toLowerCase();
+}
+/* -------------------------------------------------------------------------- */
+/* Common Header Accessors                                                    */
+/* -------------------------------------------------------------------------- */
+export function setContentType(headers, value) {
+    headers.set(HEADER_CONTENT_TYPE, value);
+    return headers;
+}
+export function setContentLength(headers, length) {
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new RangeError("Content-Length must be a non-negative safe integer.");
+    }
+    headers.set(HEADER_CONTENT_LENGTH, String(length));
+    return headers;
+}
+export function getAuthorization(headers) {
+    return normalizeHeaders(headers).get(HEADER_AUTHORIZATION);
+}
+export function setAuthorization(headers, value) {
+    headers.set(HEADER_AUTHORIZATION, value);
+    return headers;
+}
+export function getUserAgent(headers) {
+    return normalizeHeaders(headers).get(HEADER_USER_AGENT);
+}
+export function setUserAgent(headers, value) {
+    headers.set(HEADER_USER_AGENT, value);
+    return headers;
+}
+export function getAccept(headers) {
+    return normalizeHeaders(headers).get(HEADER_ACCEPT);
+}
+export function setAccept(headers, value) {
+    headers.set(HEADER_ACCEPT, value);
+    return headers;
+}
+export function getCacheControl(headers) {
+    return normalizeHeaders(headers).get(HEADER_CACHE_CONTROL);
+}
+export function setCacheControl(headers, value) {
+    headers.set(HEADER_CACHE_CONTROL, value);
+    return headers;
+}
+export function getLocation(headers) {
+    return normalizeHeaders(headers).get(HEADER_LOCATION);
+}
+export function setLocation(headers, value) {
+    headers.set(HEADER_LOCATION, value);
+    return headers;
+}
+/* -------------------------------------------------------------------------- */
+/* Cookie Header Helpers                                                      */
+/* -------------------------------------------------------------------------- */
+export function getCookieHeader(headers) {
+    return normalizeHeaders(headers).get(HEADER_COOKIE);
+}
+export function setCookieHeader(headers, value) {
+    headers.set(HEADER_COOKIE, value);
+    return headers;
+}
+/* -------------------------------------------------------------------------- */
+/* Forwarded Header Helpers                                                   */
+/* -------------------------------------------------------------------------- */
+export function getForwardedFor(headers) {
+    return normalizeHeaders(headers).get(HEADER_X_FORWARDED_FOR);
+}
+export function getForwardedHost(headers) {
+    return normalizeHeaders(headers).get(HEADER_X_FORWARDED_HOST);
+}
+export function getForwardedProto(headers) {
+    return normalizeHeaders(headers).get(HEADER_X_FORWARDED_PROTO);
+}
+/* -------------------------------------------------------------------------- */
+/* Request ID                                                                 */
+/* -------------------------------------------------------------------------- */
+export function getRequestId(headers) {
+    return normalizeHeaders(headers).get(HEADER_X_REQUEST_ID);
+}
+export function setRequestId(headers, requestId) {
+    headers.set(HEADER_X_REQUEST_ID, requestId);
+    return headers;
+}
+/* -------------------------------------------------------------------------- */
+/* Security Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+export function hasSecurityHeaders(headers) {
+    const normalized = normalizeHeaders(headers);
+    return (normalized.has("strict-transport-security") ||
+        normalized.has("content-security-policy") ||
+        normalized.has("x-content-type-options") ||
+        normalized.has("x-frame-options"));
+}
+//# sourceMappingURL=http.headers.js.map

package/dist/httpHeaders/internal/httpHeaders.internal.typeGuards.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal type guards for HTTP header utilities.
+ *
+ * @module httpHeaders/internal/typeGuards
+ */
+/**
+ * Checks if a value is an iterable of header tuples.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an iterable of `[string, string | number | boolean]` tuples.
+ */
+export declare function isIterableHeaders(value: unknown): value is Iterable<readonly [string, string | number | boolean]>;
+//# sourceMappingURL=httpHeaders.internal.typeGuards.d.ts.map

package/dist/httpHeaders/internal/httpHeaders.internal.typeGuards.js

@@ -0,0 +1,15 @@
+/**
+ * Internal type guards for HTTP header utilities.
+ *
+ * @module httpHeaders/internal/typeGuards
+ */
+/**
+ * Checks if a value is an iterable of header tuples.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an iterable of `[string, string | number | boolean]` tuples.
+ */
+export function isIterableHeaders(value) {
+    return (typeof value === "object" && value !== null && Symbol.iterator in value);
+}
+//# sourceMappingURL=httpHeaders.internal.typeGuards.js.map

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

@@ -3,10 +3,5 @@
  *
  * HTTP headers internal utilities.
  */
-export * from "./httpHeaders.internal.cacheControl.js";
-export * from "./httpHeaders.internal.mediaType.js";
-export * from "./httpHeaders.internal.specificity.js";
 export * from "./httpHeaders.internal.typeGuards.js";
-export * from "./httpHeaders.internal.weightedValues.js";
-export * from "./index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpHeaders/internal/index.js

@@ -3,10 +3,5 @@
  *
  * HTTP headers internal utilities.
  */
-export * from "./httpHeaders.internal.cacheControl.js";
-export * from "./httpHeaders.internal.mediaType.js";
-export * from "./httpHeaders.internal.specificity.js";
 export * from "./httpHeaders.internal.typeGuards.js";
-export * from "./httpHeaders.internal.weightedValues.js";
-export * from "./index.js";
 //# sourceMappingURL=index.js.map

package/dist/httpHeaders/list/httpHeaders.list.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Header list reading utilities.
+ *
+ * @module httpHeaders/list
+ */
+import type { HTTPHeadersLike } from "../types/httpHeaders.type.js";
+/**
+ * Maximum number of elements parsed from one list-valued header.
+ */
+export declare const MAX_HEADER_LIST_ELEMENTS = 64;
+/**
+ * Splits a comma-separated header value into its list elements.
+ *
+ * The split honours `quoted-string` per RFC 9110 section 5.6.1: a comma
+ * inside quotes is data, not a delimiter, so `W/"foo,bar", "baz"` is two
+ * elements rather than three fragments — which is what made conditional
+ * requests silently fail to match.
+ *
+ * @param value - The raw header value string.
+ * @returns The trimmed, non-empty elements, capped at
+ *   {@link MAX_HEADER_LIST_ELEMENTS}.
+ */
+export declare function splitHeaderValues(value: string | undefined): string[];
+/**
+ * Retrieves all comma-separated values for a header as an array.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @returns An array of trimmed values.
+ */
+export declare function getHeaderValues(headers: HTTPHeadersLike, name: string): string[];
+//# sourceMappingURL=httpHeaders.list.d.ts.map

package/dist/httpHeaders/list/httpHeaders.list.js

@@ -0,0 +1,82 @@
+/**
+ * Header list reading utilities.
+ *
+ * @module httpHeaders/list
+ */
+import { asHTTPHeaders } from "../conversion/httpHeaders.conversion.js";
+/**
+ * Maximum number of elements parsed from one list-valued header.
+ */
+export const MAX_HEADER_LIST_ELEMENTS = 64;
+/**
+ * Splits a comma-separated header value into its list elements.
+ *
+ * The split honours `quoted-string` per RFC 9110 section 5.6.1: a comma
+ * inside quotes is data, not a delimiter, so `W/"foo,bar", "baz"` is two
+ * elements rather than three fragments — which is what made conditional
+ * requests silently fail to match.
+ *
+ * @param value - The raw header value string.
+ * @returns The trimmed, non-empty elements, capped at
+ *   {@link MAX_HEADER_LIST_ELEMENTS}.
+ */
+export function splitHeaderValues(value) {
+    if (value === undefined || value.trim() === "") {
+        return [];
+    }
+    const result = [];
+    let current = "";
+    let quoted = false;
+    let escaped = false;
+    for (const character of value) {
+        if (escaped) {
+            current += character;
+            escaped = false;
+            continue;
+        }
+        if (quoted && character === "\\") {
+            current += character;
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            quoted = !quoted;
+            current += character;
+            continue;
+        }
+        if (character === "," && !quoted) {
+            pushHeaderListElement(result, current);
+            current = "";
+            if (result.length >= MAX_HEADER_LIST_ELEMENTS) {
+                return result;
+            }
+            continue;
+        }
+        current += character;
+    }
+    pushHeaderListElement(result, current);
+    return result.slice(0, MAX_HEADER_LIST_ELEMENTS);
+}
+/**
+ * Appends one trimmed, non-empty list element.
+ *
+ * @param result - The accumulating element list.
+ * @param value - The raw element.
+ */
+function pushHeaderListElement(result, value) {
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+        result.push(trimmed);
+    }
+}
+/**
+ * Retrieves all comma-separated values for a header as an array.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @returns An array of trimmed values.
+ */
+export function getHeaderValues(headers, name) {
+    return splitHeaderValues(asHTTPHeaders(headers).get(name));
+}
+//# sourceMappingURL=httpHeaders.list.js.map

package/dist/httpHeaders/list/httpHeaders.listMutation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Header list mutation utilities.
+ *
+ * @module httpHeaders/listMutation
+ */
+import type { HTTPHeaders } from "../http.headers.js";
+/**
+ * Appends a value to a header only if it is not already present.
+ *
+ * @param headers - The headers to modify.
+ * @param name - The header name.
+ * @param value - The value to append.
+ * @returns The modified headers instance.
+ */
+export declare function appendUniqueHeaderValue(headers: HTTPHeaders, name: string, value: string): HTTPHeaders;
+/**
+ * Removes a specific value from a comma-separated header.
+ *
+ * @param headers - The headers to modify.
+ * @param name - The header name.
+ * @param value - The value to remove.
+ * @returns The modified headers instance.
+ */
+export declare function removeHeaderValue(headers: HTTPHeaders, name: string, value: string): HTTPHeaders;
+//# sourceMappingURL=httpHeaders.listMutation.d.ts.map

package/dist/httpHeaders/list/httpHeaders.listMutation.js

@@ -0,0 +1,40 @@
+/**
+ * Header list mutation utilities.
+ *
+ * @module httpHeaders/listMutation
+ */
+import { getHeaderValues } from "../list/httpHeaders.list.js";
+import { headerContains } from "../basic/httpHeaders.basicMatch.js";
+/**
+ * Appends a value to a header only if it is not already present.
+ *
+ * @param headers - The headers to modify.
+ * @param name - The header name.
+ * @param value - The value to append.
+ * @returns The modified headers instance.
+ */
+export function appendUniqueHeaderValue(headers, name, value) {
+    if (headerContains(headers, name, value)) {
+        return headers;
+    }
+    return headers.append(name, value);
+}
+/**
+ * Removes a specific value from a comma-separated header.
+ *
+ * @param headers - The headers to modify.
+ * @param name - The header name.
+ * @param value - The value to remove.
+ * @returns The modified headers instance.
+ */
+export function removeHeaderValue(headers, name, value) {
+    const existing = getHeaderValues(headers, name);
+    const filtered = existing.filter((item) => item.toLowerCase() !== value.trim().toLowerCase());
+    if (filtered.length === 0) {
+        headers.delete(name);
+        return headers;
+    }
+    headers.set(name, filtered.join(", "));
+    return headers;
+}
+//# sourceMappingURL=httpHeaders.listMutation.js.map

package/dist/httpHeaders/security/httpHeaders.security.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Header security utilities for preventing header injection.
+ *
+ * This module is the single hardened definition of "safe" for HTTP field
+ * names, field values and quoted-string parameter values in this package.
+ * Every module that emits a header name, a header value, or a
+ * `quoted-string` parameter must route through the helpers defined here so
+ * that CR, LF, NUL and the remaining C0/DEL controls cannot reach the wire.
+ *
+ * @module httpHeaders/security
+ */
+/**
+ * Checks if a string contains CR or LF characters.
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string contains `\r` or `\n`.
+ */
+export declare function containsCRLF(value: string): boolean;
+/**
+ * Checks if a string contains any character forbidden in an HTTP field value.
+ *
+ * This covers CR, LF, NUL, every other C0 control except HTAB, and DEL.
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string contains a forbidden control character.
+ */
+export declare function containsForbiddenHeaderChars(value: string): boolean;
+/**
+ * Checks whether a string is a valid RFC 9110 §5.5 `field-value`.
+ *
+ * A valid field value contains no forbidden control characters and has no
+ * leading or trailing SP/HTAB (which a recipient is required to strip, and
+ * whose presence therefore makes the value ambiguous on the wire).
+ *
+ * @param value - The candidate field value.
+ * @returns `true` if the value may be emitted verbatim.
+ */
+export declare function isValidHeaderFieldValue(value: string): boolean;
+/**
+ * Checks whether a string is a valid RFC 9110 §5.6.2 `token`, which is the
+ * grammar for an HTTP field name.
+ *
+ * @param name - The candidate field name.
+ * @returns `true` if the name is a valid token.
+ */
+export declare function isValidHeaderFieldName(name: string): boolean;
+/**
+ * Throws if a header value contains any character forbidden in a field value.
+ *
+ * @param value - The header value to validate.
+ * @throws {TypeError} If the value contains CR, LF, NUL or another C0/DEL
+ *   control character, or has leading/trailing whitespace.
+ */
+export declare function assertSafeHeaderValue(value: string): void;
+/**
+ * Throws if a header name is not a valid RFC 9110 `token`.
+ *
+ * @param name - The header name to validate.
+ * @throws {TypeError} If the name is empty or contains a non-token character.
+ */
+export declare function assertSafeHeaderName(name: string): void;
+/**
+ * Removes every character forbidden in an HTTP field value.
+ *
+ * CR, LF, NUL and the remaining C0/DEL controls are stripped; HTAB and
+ * printable characters are preserved. Leading and trailing whitespace is
+ * trimmed.
+ *
+ * @param value - The header value to sanitize.
+ * @returns The sanitized value.
+ */
+export declare function sanitizeHeaderValue(value: string): string;
+/**
+ * Escapes a string for emission inside an RFC 9110 `quoted-string`.
+ *
+ * Control characters cannot be represented inside a `quoted-string` — a
+ * `quoted-pair` may only escape a printable character — so any forbidden
+ * control character is rejected rather than escaped. This prevents the
+ * response-splitting class of defect in every module that emits a quoted
+ * parameter value.
+ *
+ * @param value - The raw parameter value.
+ * @returns The escaped value, without the surrounding quotes.
+ * @throws {TypeError} If the value contains a forbidden control character.
+ */
+export declare function escapeHeaderQuotedString(value: string): string;
+//# sourceMappingURL=httpHeaders.security.d.ts.map