@zudojs/http 0.1.0 → 1.1.0

package/dist/httpAgent/http.agent.js

@@ -0,0 +1,297 @@
+import { Agent as HTTPAgent, } from "node:http";
+import { Agent as HTTPSAgent, } from "node:https";
+import { createHash } from "node:crypto";
+/* -------------------------------------------------------------------------- */
+/* Defaults                                                                   */
+/* -------------------------------------------------------------------------- */
+export const DEFAULT_AGENT_KEEP_ALIVE = true;
+export const DEFAULT_AGENT_KEEP_ALIVE_MSECS = 1_000;
+export const DEFAULT_AGENT_MAX_SOCKETS = 50;
+export const DEFAULT_AGENT_MAX_FREE_SOCKETS = 10;
+export const DEFAULT_AGENT_MAX_TOTAL_SOCKETS = 100;
+export const DEFAULT_AGENT_SCHEDULING = "lifo";
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createHTTPAgent(options = {}) {
+    validateAgentOptions(options);
+    const agentOptions = normalizeAgentOptions(options);
+    return new HTTPAgent(agentOptions);
+}
+export function createHTTPSAgent(options = {}) {
+    validateAgentOptions(options);
+    const agentOptions = normalizeHTTPSAgentOptions(options);
+    return new HTTPSAgent(agentOptions);
+}
+export function createAgent(options = {}) {
+    const protocol = options.protocol ?? "http";
+    if (protocol === "https") {
+        return createHTTPSAgent(options);
+    }
+    return createHTTPAgent(options);
+}
+/* -------------------------------------------------------------------------- */
+/* Normalization                                                              */
+/* -------------------------------------------------------------------------- */
+function normalizeAgentOptions(options) {
+    return {
+        keepAlive: options.keepAlive ?? DEFAULT_AGENT_KEEP_ALIVE,
+        keepAliveMsecs: options.keepAliveMsecs ?? DEFAULT_AGENT_KEEP_ALIVE_MSECS,
+        maxSockets: options.maxSockets ?? DEFAULT_AGENT_MAX_SOCKETS,
+        maxFreeSockets: options.maxFreeSockets ?? DEFAULT_AGENT_MAX_FREE_SOCKETS,
+        maxTotalSockets: options.maxTotalSockets ?? DEFAULT_AGENT_MAX_TOTAL_SOCKETS,
+        scheduling: options.scheduling ?? DEFAULT_AGENT_SCHEDULING,
+        timeout: options.timeout,
+    };
+}
+function normalizeHTTPSAgentOptions(options) {
+    return {
+        keepAlive: options.keepAlive ?? DEFAULT_AGENT_KEEP_ALIVE,
+        keepAliveMsecs: options.keepAliveMsecs ?? DEFAULT_AGENT_KEEP_ALIVE_MSECS,
+        maxSockets: options.maxSockets ?? DEFAULT_AGENT_MAX_SOCKETS,
+        maxFreeSockets: options.maxFreeSockets ?? DEFAULT_AGENT_MAX_FREE_SOCKETS,
+        maxTotalSockets: options.maxTotalSockets ?? DEFAULT_AGENT_MAX_TOTAL_SOCKETS,
+        scheduling: options.scheduling ?? DEFAULT_AGENT_SCHEDULING,
+        timeout: options.timeout,
+        rejectUnauthorized: options.rejectUnauthorized,
+        ca: options.ca,
+        cert: options.cert,
+        key: options.key,
+        servername: options.servername,
+    };
+}
+export function getAgentStats(agent) {
+    return {
+        sockets: countAgentEntries(agent.sockets),
+        freeSockets: countAgentEntries(agent.freeSockets),
+        requests: countAgentEntries(agent.requests),
+        totalSockets: countAgentEntries(agent.sockets) + countAgentEntries(agent.freeSockets),
+    };
+}
+function countAgentEntries(entries) {
+    let total = 0;
+    for (const value of Object.values(entries)) {
+        if (Array.isArray(value)) {
+            total += value.length;
+        }
+        else {
+            total += 1;
+        }
+    }
+    return total;
+}
+/* -------------------------------------------------------------------------- */
+/* Agent Lifecycle                                                            */
+/* -------------------------------------------------------------------------- */
+export function destroyAgent(agent) {
+    agent.destroy();
+}
+export function closeAgent(agent) {
+    agent.destroy();
+}
+/* -------------------------------------------------------------------------- */
+/* Socket Configuration                                                       */
+/* -------------------------------------------------------------------------- */
+export function configureAgentTimeout(agent, timeout) {
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new RangeError("Agent timeout must be a non-negative finite number.");
+    }
+    if ("options" in agent) {
+        agent.options.timeout = timeout;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Shared Agent Registry                                                      */
+/* -------------------------------------------------------------------------- */
+const agentRegistry = new Map();
+export function getOrCreateAgent(key, options = {}) {
+    const registryKey = normalizeRegistryKey(key);
+    /*
+     * The key includes the TLS-relevant options. Keying on protocol+host alone
+     * meant the first caller's `ca`/`cert`/`servername`/`rejectUnauthorized`
+     * silently applied to every later caller for that host: a staging call
+     * passing `rejectUnauthorized: false` would have disabled certificate
+     * verification for a caller that had pinned a CA, with no way to detect it.
+     */
+    const cacheKey = `${registryKey}|${tlsFingerprint(options)}`;
+    const existing = agentRegistry.get(cacheKey);
+    if (existing) {
+        return existing;
+    }
+    const agent = createAgent({
+        ...options,
+        protocol: registryKey.startsWith("https:")
+            ? "https"
+            : (options.protocol ?? "http"),
+    });
+    agentRegistry.set(cacheKey, agent);
+    return agent;
+}
+/**
+ * Builds a stable fingerprint of the TLS-relevant fields of an agent config.
+ */
+function tlsFingerprint(options) {
+    const tls = options;
+    const parts = [
+        describeCredential(tls.ca),
+        describeCredential(tls.cert),
+        describeCredential(tls.key),
+        tls.servername ?? "",
+        tls.rejectUnauthorized === undefined ? "" : String(tls.rejectUnauthorized),
+    ];
+    return parts.join("|");
+}
+function describeCredential(value) {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    if (value instanceof Uint8Array) {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => describeCredential(entry)).join(",");
+    }
+    return "opaque";
+}
+export function getAgent(key) {
+    return agentRegistry.get(normalizeRegistryKey(key));
+}
+export function hasAgent(key) {
+    return agentRegistry.has(normalizeRegistryKey(key));
+}
+export function removeAgent(key, destroy = true) {
+    const registryKey = normalizeRegistryKey(key);
+    const agent = agentRegistry.get(registryKey);
+    if (!agent) {
+        return false;
+    }
+    agentRegistry.delete(registryKey);
+    if (destroy) {
+        agent.destroy();
+    }
+    return true;
+}
+export function clearAgents(destroy = true) {
+    if (destroy) {
+        for (const agent of agentRegistry.values()) {
+            agent.destroy();
+        }
+    }
+    agentRegistry.clear();
+}
+export function getRegisteredAgentKeys() {
+    return Array.from(agentRegistry.keys());
+}
+/* -------------------------------------------------------------------------- */
+/* Registry Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+function normalizeRegistryKey(key) {
+    if (typeof key === "string") {
+        return normalizeURLKey(key);
+    }
+    const protocol = key.protocol === "https" ? "https:" : "http:";
+    return key.name ? `${protocol}//${key.name}` : protocol;
+}
+function normalizeURLKey(value) {
+    try {
+        const url = new URL(value.includes("://") ? value : `http://${value}`);
+        return `${url.protocol}//${url.host}`;
+    }
+    catch {
+        return value.trim();
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Global Defaults                                                            */
+/* -------------------------------------------------------------------------- */
+let defaultHTTPAgent;
+let defaultHTTPSAgent;
+export function getDefaultHTTPAgent() {
+    if (!defaultHTTPAgent) {
+        defaultHTTPAgent = createHTTPAgent();
+    }
+    return defaultHTTPAgent;
+}
+export function getDefaultHTTPSAgent() {
+    if (!defaultHTTPSAgent) {
+        defaultHTTPSAgent = createHTTPSAgent();
+    }
+    return defaultHTTPSAgent;
+}
+export function setDefaultHTTPAgent(agent) {
+    if (defaultHTTPAgent && defaultHTTPAgent !== agent) {
+        defaultHTTPAgent.destroy();
+    }
+    defaultHTTPAgent = agent;
+}
+export function setDefaultHTTPSAgent(agent) {
+    if (defaultHTTPSAgent && defaultHTTPSAgent !== agent) {
+        defaultHTTPSAgent.destroy();
+    }
+    defaultHTTPSAgent = agent;
+}
+export function resetDefaultAgents() {
+    defaultHTTPAgent?.destroy();
+    defaultHTTPSAgent?.destroy();
+    defaultHTTPAgent = undefined;
+    defaultHTTPSAgent = undefined;
+}
+/* -------------------------------------------------------------------------- */
+/* Agent Selection                                                            */
+/* -------------------------------------------------------------------------- */
+export function getAgentForProtocol(protocol) {
+    const normalized = protocol?.toLowerCase();
+    if (normalized === "https:" || normalized === "https") {
+        return getDefaultHTTPSAgent();
+    }
+    return getDefaultHTTPAgent();
+}
+export function isHTTPAgent(agent) {
+    return agent instanceof HTTPAgent;
+}
+export function isHTTPSAgent(agent) {
+    return agent instanceof HTTPSAgent;
+}
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                 */
+/* -------------------------------------------------------------------------- */
+export function validateAgentOptions(options) {
+    validateNonNegativeInteger(options.keepAliveMsecs, "keepAliveMsecs");
+    validatePositiveInteger(options.maxSockets, "maxSockets");
+    validatePositiveInteger(options.maxFreeSockets, "maxFreeSockets");
+    validatePositiveInteger(options.maxTotalSockets, "maxTotalSockets");
+    if (options.maxFreeSockets !== undefined &&
+        options.maxSockets !== undefined &&
+        options.maxFreeSockets > options.maxSockets) {
+        throw new RangeError("maxFreeSockets cannot exceed maxSockets.");
+    }
+    if (options.maxTotalSockets !== undefined &&
+        options.maxSockets !== undefined &&
+        options.maxTotalSockets < options.maxSockets) {
+        throw new RangeError("maxTotalSockets cannot be less than maxSockets.");
+    }
+    if (options.timeout !== undefined &&
+        (!Number.isFinite(options.timeout) || options.timeout < 0)) {
+        throw new RangeError("timeout must be a non-negative finite number.");
+    }
+}
+function validateNonNegativeInteger(value, name) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer.`);
+    }
+}
+function validatePositiveInteger(value, name) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer.`);
+    }
+}
+//# sourceMappingURL=http.agent.js.map

package/dist/httpBody/http.body.d.ts

@@ -3,12 +3,24 @@ export type HTTPBody = string | Buffer | Uint8Array | Record<string, unknown> |
 export interface HTTPBodyParseOptions {
     readonly limit?: number;
     readonly encoding?: BufferEncoding;
+    /**
+     * Enforce strict JSON body rules in {@link readJSON}: an empty body and a
+     * scalar top-level value (`5`, `null`, `"x"`) are rejected instead of being
+     * accepted as a body. Read only by {@link readJSON}; it has no meaning for
+     * the text, form or raw readers.
+     */
     readonly strict?: boolean;
 }
 export interface HTTPBodyReaderOptions extends HTTPBodyParseOptions {
     readonly request: IncomingMessage;
 }
-export declare const DEFAULT_BODY_LIMIT = 1048576;
+/**
+ * The package-wide default body limit.
+ *
+ * Aliases `HTTP_DEFAULTS.BODY_LIMIT` rather than repeating the literal, so
+ * the two cannot drift apart.
+ */
+export declare const DEFAULT_BODY_LIMIT: number;
 export declare const DEFAULT_BODY_ENCODING: BufferEncoding;
 export declare const BODY_CONTENT_TYPES: {
     readonly JSON: "application/json";
@@ -20,7 +32,14 @@ export declare const BODY_CONTENT_TYPES: {
 };
 export declare function readBody(options: HTTPBodyReaderOptions): Promise<Buffer>;
 export declare function readText(options: HTTPBodyReaderOptions): Promise<string>;
-export declare function readJSON<T = unknown>(options?: HTTPBodyReaderOptions): Promise<T>;
+/**
+ * Reads and parses a JSON request body.
+ *
+ * With `strict: true` an empty body is rejected and the top-level value must
+ * be an object or an array — a bare scalar such as `5`, `null` or `"x"` is
+ * not accepted as a request body.
+ */
+export declare function readJSON<T = unknown>(options: HTTPBodyReaderOptions): Promise<T>;
 export declare function readForm(options: HTTPBodyReaderOptions): Promise<Record<string, string | string[]>>;
 export declare function parseBody<T = unknown>(options: HTTPBodyReaderOptions): Promise<T | Buffer | string>;
 export declare function getContentType(request: IncomingMessage): string | undefined;
@@ -28,6 +47,16 @@ export declare function isJSONContentType(contentType: string | undefined): bool
 export declare function isFormContentType(contentType: string | undefined): boolean;
 export declare function isTextContentType(contentType: string | undefined): boolean;
 export declare function isMultipartContentType(contentType: string | undefined): boolean;
+/**
+ * Reads `Content-Length`.
+ *
+ * RFC 9112 §6.1 requires a recipient to reject a message that carries both
+ * `Content-Length` and `Transfer-Encoding`, and §6.3 to reject conflicting
+ * `Content-Length` values. Taking the first of a duplicated pair and ignoring
+ * the rest — as this did — is the attacker-favourable half of a CL.TE/CL.CL
+ * request-smuggling differential whenever the message reaches this helper
+ * from something other than Node's own HTTP/1 parser.
+ */
 export declare function getContentLength(request: IncomingMessage): number | undefined;
 export declare function bodyToBuffer(body: string | Buffer | Uint8Array, encoding?: BufferEncoding): Buffer;
 export declare function bodyToJSON(body: unknown): string;

package/dist/httpBody/http.body.js

@@ -1,7 +1,14 @@
+import { HTTP_DEFAULTS } from "../httpConstants/http.constants.js";
 /* -------------------------------------------------------------------------- */
 /* Defaults                                                                   */
 /* -------------------------------------------------------------------------- */
-export const DEFAULT_BODY_LIMIT = 1_048_576;
+/**
+ * The package-wide default body limit.
+ *
+ * Aliases `HTTP_DEFAULTS.BODY_LIMIT` rather than repeating the literal, so
+ * the two cannot drift apart.
+ */
+export const DEFAULT_BODY_LIMIT = HTTP_DEFAULTS.BODY_LIMIT;
 export const DEFAULT_BODY_ENCODING = "utf8";
 /* -------------------------------------------------------------------------- */
 /* Content Types                                                              */
@@ -60,6 +67,15 @@ export async function readBody(options) {
             if (settled) {
                 return;
             }
+            /*
+             * A body shorter than its declared Content-Length means the client
+             * stopped sending. Resolving it hands a silently truncated request to
+             * the caller as if it had arrived complete.
+             */
+            if (contentLength !== undefined && total !== contentLength) {
+                fail(new HTTPBodyParseError("Request body length does not match Content-Length."));
+                return;
+            }
             settled = true;
             cleanup();
             resolve(Buffer.concat(chunks, total));
@@ -92,19 +108,32 @@ export async function readText(options) {
 /* -------------------------------------------------------------------------- */
 /* JSON Parsing                                                               */
 /* -------------------------------------------------------------------------- */
-export async function readJSON(options = {
-    request: undefined,
-}) {
+/**
+ * Reads and parses a JSON request body.
+ *
+ * With `strict: true` an empty body is rejected and the top-level value must
+ * be an object or an array — a bare scalar such as `5`, `null` or `"x"` is
+ * not accepted as a request body.
+ */
+export async function readJSON(options) {
     const text = await readText(options);
     if (text.trim() === "") {
+        if (options.strict) {
+            throw new HTTPBodyParseError("Request body is empty.");
+        }
         return undefined;
     }
+    let parsed;
     try {
-        return JSON.parse(text);
+        parsed = JSON.parse(text);
     }
     catch (error) {
         throw new HTTPBodyParseError("Invalid JSON request body.", error);
     }
+    if (options.strict && (parsed === null || typeof parsed !== "object")) {
+        throw new HTTPBodyParseError("JSON request body must be an object or an array.");
+    }
+    return parsed;
 }
 /* -------------------------------------------------------------------------- */
 /* Form URL Encoded                                                           */
@@ -112,9 +141,15 @@ export async function readJSON(options = {
 export async function readForm(options) {
     const text = await readText(options);
     const params = new URLSearchParams(text);
-    const result = {};
+    /*
+     * A null-prototype container: a field named `__proto__` can neither replace
+     * the returned object's prototype nor be read back as an inherited member.
+     */
+    const result = Object.create(null);
     for (const [key, value] of params.entries()) {
-        const existing = result[key];
+        const existing = Object.prototype.hasOwnProperty.call(result, key)
+            ? result[key]
+            : undefined;
         if (existing === undefined) {
             result[key] = value;
             continue;
@@ -160,21 +195,21 @@ export function isJSONContentType(contentType) {
     if (!contentType) {
         return false;
     }
-    const normalized = contentType.split(";", 1)[0].trim().toLowerCase();
+    const normalized = (contentType.split(";", 1)[0] ?? "").trim().toLowerCase();
     return normalized === BODY_CONTENT_TYPES.JSON || normalized.endsWith("+json");
 }
 export function isFormContentType(contentType) {
     if (!contentType) {
         return false;
     }
-    return (contentType.split(";", 1)[0].trim().toLowerCase() ===
+    return ((contentType.split(";", 1)[0] ?? "").trim().toLowerCase() ===
         BODY_CONTENT_TYPES.FORM_URLENCODED);
 }
 export function isTextContentType(contentType) {
     if (!contentType) {
         return false;
     }
-    const normalized = contentType.split(";", 1)[0].trim().toLowerCase();
+    const normalized = (contentType.split(";", 1)[0] ?? "").trim().toLowerCase();
     return (normalized.startsWith("text/") || normalized === BODY_CONTENT_TYPES.HTML);
 }
 export function isMultipartContentType(contentType) {
@@ -189,23 +224,48 @@ export function isMultipartContentType(contentType) {
 /* -------------------------------------------------------------------------- */
 /* Content Length                                                             */
 /* -------------------------------------------------------------------------- */
+/**
+ * Reads `Content-Length`.
+ *
+ * RFC 9112 §6.1 requires a recipient to reject a message that carries both
+ * `Content-Length` and `Transfer-Encoding`, and §6.3 to reject conflicting
+ * `Content-Length` values. Taking the first of a duplicated pair and ignoring
+ * the rest — as this did — is the attacker-favourable half of a CL.TE/CL.CL
+ * request-smuggling differential whenever the message reaches this helper
+ * from something other than Node's own HTTP/1 parser.
+ */
 export function getContentLength(request) {
-    const value = request.headers["content-length"];
-    if (Array.isArray(value)) {
-        return parseContentLength(value[0]);
+    const header = request.headers["content-length"];
+    if (header === undefined) {
+        return undefined;
     }
-    if (typeof value !== "string") {
+    const values = (Array.isArray(header) ? header : [header]).flatMap((entry) => typeof entry === "string" ? entry.split(",") : []);
+    if (values.length === 0) {
         return undefined;
     }
-    return parseContentLength(value);
+    let length;
+    for (const value of values) {
+        const parsed = parseContentLength(value.trim());
+        if (parsed === undefined) {
+            throw new HTTPBodyParseError("Invalid Content-Length header.");
+        }
+        if (length !== undefined && parsed !== length) {
+            throw new HTTPBodyParseError("Conflicting Content-Length headers.");
+        }
+        length = parsed;
+    }
+    if (request.headers["transfer-encoding"] !== undefined) {
+        throw new HTTPBodyParseError("Content-Length and Transfer-Encoding must not both be present.");
+    }
+    return length;
 }
 function parseContentLength(value) {
-    if (!value) {
+    if (!/^\d+$/.test(value)) {
         return undefined;
     }
     const parsed = Number(value);
     if (!Number.isSafeInteger(parsed) || parsed < 0) {
-        throw new HTTPBodyParseError("Invalid Content-Length header.");
+        return undefined;
     }
     return parsed;
 }

package/dist/httpBody/httpBody.formData.d.ts

@@ -40,7 +40,22 @@ export declare const DEFAULT_MAX_FILES = 100;
 export declare function isMultipartContentType(contentType: string | undefined): boolean;
 export declare function getMultipartBoundary(contentType: string | undefined): string | undefined;
 export declare function parseFormData(options: HTTPFormDataParseOptions): Promise<HTTPFormData>;
+/**
+ * Parses a multipart body into an {@link HTTPFormData}.
+ *
+ * The parsing itself is delegated to `httpMultipart`, which is the package's
+ * single multipart engine. This function only applies the form-data limits
+ * and shapes the result. Routing both entry points through one parser is what
+ * guarantees two components in the same application cannot see different
+ * field names, different filenames or different bytes for the same request.
+ */
 export declare function parseMultipartBody(body: Buffer, boundary: string, options: Omit<HTTPFormDataParseOptions, "request" | "limit">): HTTPFormData;
+/**
+ * Reduces an uploaded filename to a safe basename.
+ *
+ * Delegates to the single implementation in `httpMultipart` so the three
+ * copies that used to exist cannot drift apart.
+ */
 export declare function sanitizeFilename(filename: string): string;
 import { HttpFormDataError as HTTPFormDataError, HttpFormDataLimitError as HTTPFormDataLimitError, HttpFormDataParseError as HTTPFormDataParseError } from "@zudojs/errors";
 export { HTTPFormDataError, HTTPFormDataLimitError, HTTPFormDataParseError };