@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/http-request/headers.js

@@ -0,0 +1,86 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var headers_exports = {};
+__export(headers_exports, {
+  parseRetryAfterHeader: () => parseRetryAfterHeader,
+  sanitizeHeaders: () => sanitizeHeaders
+});
+module.exports = __toCommonJS(headers_exports);
+var import_array = require("../primordials/array");
+var import_date = require("../primordials/date");
+var import_map_set = require("../primordials/map-set");
+var import_number = require("../primordials/number");
+var import_object = require("../primordials/object");
+const RETRY_AFTER_INT_RE = /^\d+$/;
+function parseRetryAfterHeader(value) {
+  if (!value) {
+    return void 0;
+  }
+  const raw = (0, import_array.ArrayIsArray)(value) ? value[0] : value;
+  if (!raw) {
+    return void 0;
+  }
+  const trimmed = raw.trim();
+  if (RETRY_AFTER_INT_RE.test(trimmed)) {
+    const seconds = Number(trimmed);
+    return seconds * 1e3;
+  }
+  const date = new import_date.DateCtor(raw);
+  if (!(0, import_number.NumberIsNaN)(date.getTime())) {
+    const delayMs = date.getTime() - (0, import_date.DateNow)();
+    if (delayMs > 0) {
+      return delayMs;
+    }
+  }
+  return void 0;
+}
+function sanitizeHeaders(headers) {
+  if (!headers) {
+    return {};
+  }
+  const sensitiveHeaders = new import_map_set.SetCtor([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "proxy-authenticate",
+    "set-cookie",
+    "www-authenticate"
+  ]);
+  const result = {
+    __proto__: null
+  };
+  for (const key of (0, import_object.ObjectKeys)(headers)) {
+    const value = headers[key];
+    if (sensitiveHeaders.has(key.toLowerCase())) {
+      result[key] = "[REDACTED]";
+    } else if ((0, import_array.ArrayIsArray)(value)) {
+      result[key] = value.join(", ");
+    } else if (value !== void 0 && value !== null) {
+      result[key] = String(value);
+    }
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseRetryAfterHeader,
+  sanitizeHeaders
+});

package/dist/http-request/request-attempt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Single HTTP request attempt — the workhorse beneath the retrying
+ *   `httpRequest` orchestrator. Split out of `http-request/request.ts` for size
+ *   hygiene. Handles:
+ *
+ *   - Native `http`/`https` request issuance
+ *   - Redirect chasing (with cross-origin auth-header stripping + HTTPS→HTTP
+ *     downgrade refusal)
+ *   - Stream-mode bodies (Readable / form-data duck-typed)
+ *   - `maxResponseSize` enforcement
+ *   - Hook lifecycle (`onRequest` pre-issue, `onResponse` settle-or-error)
+ *     Exported (not private) so `download.ts` can drive it in stream mode for
+ *     its own download-attempt loop.
+ */
+import type { HttpRequestOptions } from './request-types';
+import type { HttpResponse } from './response-types';
+/**
+ * Single HTTP request attempt (used internally by httpRequest with retry
+ * logic). Supports hooks (fire per-attempt), maxResponseSize, and rawResponse.
+ */
+export declare function httpRequestAttempt(url: string, options: HttpRequestOptions): Promise<HttpResponse>;

package/dist/http-request/request-attempt.js

@@ -0,0 +1,288 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var request_attempt_exports = {};
+__export(request_attempt_exports, {
+  httpRequestAttempt: () => httpRequestAttempt
+});
+module.exports = __toCommonJS(request_attempt_exports);
+var import_date = require("../primordials/date");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_object = require("../primordials/object");
+var import_promise = require("../primordials/promise");
+var import_url = require("../primordials/url");
+var import_internal = require("./_internal");
+var import_errors = require("./errors");
+var import_user_agent = require("./user-agent");
+async function httpRequestAttempt(url, options) {
+  const {
+    body,
+    ca,
+    followRedirects = true,
+    headers = {},
+    hooks,
+    maxRedirects = 5,
+    maxResponseSize,
+    method = "GET",
+    signal,
+    stream = false,
+    timeout = 3e4
+  } = { __proto__: null, ...options };
+  const startTime = (0, import_date.DateNow)();
+  const streamHeaders = body && typeof body === "object" && "getHeaders" in body && typeof body.getHeaders === "function" ? body.getHeaders() : void 0;
+  const mergedHeaders = {
+    "User-Agent": (0, import_user_agent.getSocketCallerUserAgent)(),
+    ...streamHeaders,
+    ...headers
+  };
+  hooks?.onRequest?.({ method, url, headers: mergedHeaders, timeout });
+  return await new import_promise.PromiseCtor((resolve, reject) => {
+    let settled = false;
+    const resolveOnce = (response) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(response);
+    };
+    const rejectOnce = (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (body && typeof body === "object" && typeof body.destroy === "function") {
+        ;
+        body.destroy();
+      }
+      emitResponse({ error: err });
+      reject(err);
+    };
+    const parsedUrl = new import_url.URLCtor(url);
+    const isHttps = parsedUrl.protocol === "https:";
+    const httpModule = isHttps ? (0, import_internal.getHttps)() : (0, import_internal.getHttp)();
+    const requestOptions = {
+      headers: mergedHeaders,
+      hostname: parsedUrl.hostname,
+      method,
+      path: parsedUrl.pathname + parsedUrl.search,
+      port: parsedUrl.port,
+      timeout
+    };
+    if (ca && isHttps) {
+      requestOptions["ca"] = ca;
+    }
+    if (signal) {
+      requestOptions["signal"] = signal;
+    }
+    const emitResponse = (info) => {
+      try {
+        hooks?.onResponse?.({
+          duration: (0, import_date.DateNow)() - startTime,
+          method,
+          url,
+          ...info
+        });
+      } catch {
+      }
+    };
+    const request = httpModule.request(
+      requestOptions,
+      (res) => {
+        if (followRedirects && res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          emitResponse({
+            headers: res.headers,
+            status: res.statusCode,
+            statusText: res.statusMessage
+          });
+          if (maxRedirects <= 0) {
+            settled = true;
+            reject(
+              new import_error.ErrorCtor(
+                `Too many redirects (exceeded maximum: ${maxRedirects})`
+              )
+            );
+            return;
+          }
+          const redirectUrl = res.headers.location.startsWith("http") ? res.headers.location : new URL(res.headers.location, url).toString();
+          const redirectParsed = new URL(redirectUrl);
+          if (isHttps && redirectParsed.protocol !== "https:") {
+            settled = true;
+            reject(
+              new import_error.ErrorCtor(
+                `Redirect from HTTPS to HTTP is not allowed: ${redirectUrl}`
+              )
+            );
+            return;
+          }
+          let redirectHeaders = headers;
+          if (new URL(url).origin !== redirectParsed.origin) {
+            redirectHeaders = { __proto__: null };
+            const stripped = /* @__PURE__ */ new Set([
+              "authorization",
+              "cookie",
+              "proxy-authenticate",
+              "proxy-authorization"
+            ]);
+            for (const key of (0, import_object.ObjectKeys)(headers)) {
+              if (!stripped.has(key.toLowerCase())) {
+                ;
+                redirectHeaders[key] = headers[key];
+              }
+            }
+          }
+          settled = true;
+          resolve(
+            httpRequestAttempt(redirectUrl, {
+              body,
+              ca,
+              followRedirects,
+              headers: redirectHeaders,
+              hooks,
+              maxRedirects: maxRedirects - 1,
+              maxResponseSize,
+              method,
+              stream,
+              timeout
+            })
+          );
+          return;
+        }
+        if (stream) {
+          const status = res.statusCode || 0;
+          const statusText = res.statusMessage || "";
+          const ok = status >= 200 && status < 300;
+          emitResponse({
+            headers: res.headers,
+            status,
+            statusText
+          });
+          const emptyBody = Buffer.alloc(0);
+          resolveOnce({
+            arrayBuffer: () => emptyBody.buffer,
+            body: emptyBody,
+            headers: res.headers,
+            json: () => {
+              throw new import_error.ErrorCtor("Cannot parse JSON from a streaming response");
+            },
+            ok,
+            rawResponse: res,
+            status,
+            statusText,
+            text: () => ""
+          });
+          return;
+        }
+        const chunks = [];
+        let totalBytes = 0;
+        res.on("data", (chunk) => {
+          totalBytes += chunk.length;
+          if (maxResponseSize && totalBytes > maxResponseSize) {
+            res.destroy();
+            request.destroy();
+            const sizeMB = (totalBytes / (1024 * 1024)).toFixed(2);
+            const maxMB = (maxResponseSize / (1024 * 1024)).toFixed(2);
+            rejectOnce(
+              new import_error.ErrorCtor(
+                `Response exceeds maximum size limit (${sizeMB}MB > ${maxMB}MB)`
+              )
+            );
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on("end", () => {
+          if (settled) {
+            return;
+          }
+          const responseBody = Buffer.concat(chunks);
+          const ok = res.statusCode !== void 0 && res.statusCode >= 200 && res.statusCode < 300;
+          const response = {
+            arrayBuffer() {
+              return responseBody.buffer.slice(
+                responseBody.byteOffset,
+                responseBody.byteOffset + responseBody.byteLength
+              );
+            },
+            body: responseBody,
+            headers: res.headers,
+            json() {
+              return (0, import_json.JSONParse)(responseBody.toString("utf8"));
+            },
+            ok,
+            rawResponse: res,
+            status: res.statusCode || 0,
+            statusText: res.statusMessage || "",
+            text() {
+              return responseBody.toString("utf8");
+            }
+          };
+          emitResponse({
+            headers: res.headers,
+            status: res.statusCode,
+            statusText: res.statusMessage
+          });
+          resolveOnce(response);
+        });
+        res.on("error", (error) => {
+          rejectOnce(error);
+        });
+      }
+    );
+    request.on("error", (error) => {
+      const message = (0, import_errors.enrichErrorMessage)(
+        url,
+        method,
+        error
+      );
+      rejectOnce(new import_error.ErrorCtor(message, { cause: error }));
+    });
+    request.on("timeout", () => {
+      request.destroy();
+      rejectOnce(
+        new import_error.ErrorCtor(
+          `${method} request timed out after ${timeout}ms: ${url}
+\u2192 Server did not respond in time.
+\u2192 Try: Increase timeout or check network connectivity.`
+        )
+      );
+    });
+    if (body) {
+      if (typeof body === "object" && typeof body.pipe === "function") {
+        const stream2 = body;
+        stream2.on("error", (err) => {
+          request.destroy();
+          rejectOnce(err);
+        });
+        stream2.pipe(request);
+        return;
+      }
+      request.write(body);
+      request.end();
+    } else {
+      request.end();
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  httpRequestAttempt
+});

package/dist/http-request/request-types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @file Types for HTTP request configuration — options, hooks, and Node
+ *   `IncomingMessage` aliases. Split out of `http-request/types.ts` for size
+ *   hygiene.
+ *
+ *   - `IncomingResponse` / `IncomingRequest` — Node IncomingMessage aliases
+ *   - `HttpHookRequestInfo` / `HttpHookResponseInfo` / `HttpHooks` —
+ *     observability
+ *   - `HttpRequestOptions` — the main request configuration interface
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Readable } from 'node:stream';
+/**
+ * IncomingMessage received as a response to a client request (http.request
+ * callback).
+ */
+export type IncomingResponse = IncomingMessage;
+/**
+ * IncomingMessage received as a request in a server handler (http.createServer
+ * callback).
+ */
+export type IncomingRequest = IncomingMessage;
+/**
+ * Information passed to the onRequest hook before each request attempt.
+ */
+export interface HttpHookRequestInfo {
+    headers: Record<string, string>;
+    method: string;
+    timeout: number;
+    url: string;
+}
+/**
+ * Information passed to the onResponse hook after each request attempt.
+ */
+export interface HttpHookResponseInfo {
+    duration: number;
+    error?: Error | undefined;
+    headers?: import('node:http').IncomingHttpHeaders | undefined;
+    method: string;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    url: string;
+}
+/**
+ * Lifecycle hooks for observing HTTP request/response events. Hooks fire
+ * per-attempt (retries produce multiple hook calls).
+ */
+export interface HttpHooks {
+    onRequest?: ((info: HttpHookRequestInfo) => void) | undefined;
+    onResponse?: ((info: HttpHookResponseInfo) => void) | undefined;
+}
+/**
+ * Configuration options for HTTP/HTTPS requests.
+ */
+export interface HttpRequestOptions {
+    /**
+     * Request body to send. Can be a string, Buffer, or Readable stream.
+     *
+     * When a Readable stream is provided, it is piped directly to the request. If
+     * the stream has a `getHeaders()` method (duck-typed, e.g., the `form-data`
+     * npm package), its headers (Content-Type with boundary) are automatically
+     * merged into the request headers.
+     *
+     * **Note:** Streaming bodies are one-shot — they cannot be replayed. Using a
+     * Readable body with `retries > 0` throws an error. Buffer the body as a
+     * string/Buffer if retries are needed. Redirects are also disabled for
+     * streaming bodies since the stream is consumed on the first request.
+     *
+     * @example
+     *   ;```ts
+     *   // Send JSON data
+     *   await httpRequest('https://api.example.com/data', {
+     *     method: 'POST',
+     *     body: JSON.stringify({ name: 'Alice' }),
+     *     headers: { 'Content-Type': 'application/json' },
+     *   })
+     *
+     *   // Send binary data
+     *   const buffer = Buffer.from([0x00, 0x01, 0x02])
+     *   await httpRequest('https://api.example.com/upload', {
+     *     method: 'POST',
+     *     body: buffer,
+     *   })
+     *
+     *   // Stream form-data (npm package, not native FormData)
+     *   import FormData from 'form-data'
+     *   const form = new FormData()
+     *   form.append('file', createReadStream('data.json'))
+     *   await httpRequest('https://api.example.com/upload', {
+     *     method: 'POST',
+     *     body: form, // auto-merges form.getHeaders()
+     *   })
+     *   ```
+     */
+    body?: Buffer | Readable | string | undefined;
+    /**
+     * Custom CA certificates for TLS connections. When provided, these
+     * certificates are combined with the default trust store via an HTTPS agent.
+     * Useful when SSL_CERT_FILE is set but NODE_EXTRA_CA_CERTS was not available
+     * at process startup.
+     *
+     * @example
+     *   ;```ts
+     *   import { rootCertificates } from 'node:tls'
+     *   import { readFileSync } from 'node:fs'
+     *
+     *   const extraCerts = readFileSync('/path/to/cert.pem', 'utf-8')
+     *   await httpRequest('https://api.example.com', {
+     *     ca: [...rootCertificates, extraCerts],
+     *   })
+     *   ```
+     */
+    ca?: string[] | undefined;
+    /**
+     * Whether to automatically follow HTTP redirects (3xx status codes).
+     *
+     * @example
+     *   ;```ts
+     *   // Follow redirects (default)
+     *   await httpRequest('https://example.com/redirect')
+     *
+     *   // Don't follow redirects
+     *   const response = await httpRequest('https://example.com/redirect', {
+     *     followRedirects: false,
+     *   })
+     *   console.log(response.status) // 301 or 302
+     *   ```
+     *
+     * @default true
+     */
+    followRedirects?: boolean | undefined;
+    /**
+     * Lifecycle hooks for observing request/response events. Hooks fire
+     * per-attempt — retries and redirects each trigger separate hook calls.
+     */
+    hooks?: HttpHooks | undefined;
+    /**
+     * HTTP headers to send with the request. A `User-Agent` header is
+     * automatically added if not provided.
+     *
+     * @example
+     *   ;```ts
+     *   await httpRequest('https://api.example.com/data', {
+     *     headers: {
+     *       Authorization: 'Bearer token123',
+     *       'Content-Type': 'application/json',
+     *       Accept: 'application/json',
+     *     },
+     *   })
+     *   ```
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Maximum number of redirects to follow before throwing an error. Only
+     * relevant when `followRedirects` is `true`.
+     *
+     * @default 5
+     */
+    maxRedirects?: number | undefined;
+    /**
+     * Maximum response body size in bytes. Responses exceeding this limit will be
+     * rejected with an error. Prevents memory exhaustion from unexpectedly large
+     * responses.
+     *
+     * @default undefined (no limit)
+     */
+    maxResponseSize?: number | undefined;
+    /**
+     * HTTP method to use for the request.
+     *
+     * @example
+     *   ;```ts
+     *   await httpRequest('https://api.example.com/data', {
+     *     method: 'POST',
+     *     body: JSON.stringify({ name: 'Alice' }),
+     *   })
+     *   ```
+     *
+     * @default 'GET'
+     */
+    method?: string | undefined;
+    /**
+     * Callback invoked before each retry attempt. Allows customizing retry
+     * behavior per-attempt (e.g., skip 4xx, honor Retry-After).
+     *
+     * @param attempt - Current retry attempt number (1-based)
+     * @param error - The error that triggered the retry (HttpResponseError for
+     *   HTTP errors)
+     * @param delay - The calculated delay in ms before next retry.
+     *
+     * @returns `false` to stop retrying and rethrow, a `number` to override the
+     *   delay (ms), or `undefined` to use the calculated delay.
+     */
+    onRetry?: ((attempt: number, error: unknown, delay: number) => boolean | number | undefined) | undefined;
+    /**
+     * Number of retry attempts for failed requests. Uses exponential backoff:
+     * delay = `retryDelay` * 2^attempt.
+     *
+     * @default 0
+     */
+    retries?: number | undefined;
+    /**
+     * Initial delay in milliseconds before first retry. Subsequent retries use
+     * exponential backoff.
+     *
+     * @default 1000
+     */
+    retryDelay?: number | undefined;
+    /**
+     * AbortSignal forwarded to the underlying `http.request` / `https.request`
+     * call. Supported in Node 22+ via `node:http` request options. When both
+     * `signal` and `timeout` are provided, either can cancel the in-flight
+     * request (whichever fires first). Aborts are NOT retried — an external
+     * cancel is treated as an explicit caller decision.
+     *
+     * @example
+     *   ;```ts
+     *   const ac = new AbortController()
+     *   setTimeout(() => ac.abort(), 5000)
+     *   await httpRequest('https://api.example.com/x', { signal: ac.signal })
+     *   ```
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * When true, resolve with an HttpResponse whose body is NOT buffered. The
+     * `rawResponse` property contains the unconsumed IncomingResponse stream for
+     * piping to files or other destinations.
+     *
+     * `body`, `text()`, `json()`, and `arrayBuffer()` return empty/zero values
+     * since the stream has not been read.
+     *
+     * Incompatible with `maxResponseSize` (size enforcement requires reading the
+     * body).
+     *
+     * @default false
+     */
+    stream?: boolean | undefined;
+    /**
+     * When true, non-2xx HTTP responses throw an `HttpResponseError` instead of
+     * resolving with `response.ok === false`. This makes HTTP error responses
+     * eligible for retry via the `retries` option.
+     *
+     * @default false
+     */
+    throwOnError?: boolean | undefined;
+    /**
+     * Request timeout in milliseconds. If the request takes longer than this, it
+     * will be aborted.
+     *
+     * @default 30000
+     */
+    timeout?: number | undefined;
+}

package/dist/http-request/request-types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var request_types_exports = {};
+module.exports = __toCommonJS(request_types_exports);