@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/http-request/download.js

@@ -0,0 +1,201 @@
+"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 download_exports = {};
+__export(download_exports, {
+  httpDownload: () => httpDownload,
+  httpDownloadAttempt: () => httpDownloadAttempt
+});
+module.exports = __toCommonJS(download_exports);
+var import_promises = require("node:timers/promises");
+var import_safe = require("../fs/safe");
+var import_buffer = require("../primordials/buffer");
+var import_error = require("../primordials/error");
+var import_math = require("../primordials/math");
+var import_number = require("../primordials/number");
+var import_promise = require("../primordials/promise");
+var import_internal = require("./_internal");
+var import_request = require("./request");
+var import_response_types = require("./response-types");
+async function httpDownload(url, destPath, options) {
+  const {
+    ca,
+    followRedirects = true,
+    headers = {},
+    logger,
+    maxRedirects = 5,
+    onProgress,
+    progressInterval = 10,
+    retries = 0,
+    retryDelay = 1e3,
+    sha256,
+    timeout = 12e4
+  } = { __proto__: null, ...options };
+  let progressCallback;
+  if (onProgress) {
+    progressCallback = onProgress;
+  } else if (logger) {
+    let lastPercent = 0;
+    progressCallback = (downloaded, total) => {
+      const percent = total === 0 ? 0 : (0, import_math.MathFloor)(downloaded / total * 100);
+      if (percent >= lastPercent + progressInterval) {
+        logger.log(
+          `  Progress: ${percent}% (${(downloaded / 1024 / 1024).toFixed(1)} MB / ${(total / 1024 / 1024).toFixed(1)} MB)`
+        );
+        lastPercent = percent;
+      }
+    };
+  }
+  const crypto = (0, import_internal.getCrypto)();
+  const fs = (0, import_internal.getFs)();
+  const tempSuffix = crypto.randomBytes(6).toString("hex");
+  const tempPath = `${destPath}.${tempSuffix}.download`;
+  if (fs.existsSync(tempPath)) {
+    await (0, import_safe.safeDelete)(tempPath);
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const result = await httpDownloadAttempt(url, tempPath, {
+        ca,
+        followRedirects,
+        headers,
+        maxRedirects,
+        onProgress: progressCallback,
+        timeout
+      });
+      if (sha256) {
+        const fileContent = await fs.promises.readFile(tempPath);
+        const computedHash = crypto.createHash("sha256").update(fileContent).digest("hex");
+        const expectedHash = sha256.toLowerCase();
+        if (computedHash.length !== expectedHash.length || !crypto.timingSafeEqual(
+          (0, import_buffer.BufferFrom)(computedHash),
+          Buffer.from(expectedHash)
+        )) {
+          await (0, import_safe.safeDelete)(tempPath);
+          throw new import_error.ErrorCtor(
+            `Checksum verification failed for ${url}
+Expected: ${expectedHash}
+Computed: ${computedHash}`
+          );
+        }
+      }
+      await fs.promises.rename(tempPath, destPath);
+      return {
+        ...result,
+        path: destPath
+      };
+    } catch (e) {
+      lastError = e;
+      if (fs.existsSync(tempPath)) {
+        await (0, import_safe.safeDelete)(tempPath);
+      }
+      if (attempt === retries) {
+        break;
+      }
+      const delayMs = retryDelay * 2 ** attempt;
+      await (0, import_promises.setTimeout)(delayMs);
+    }
+  }
+  throw lastError || new import_error.ErrorCtor("Download failed after retries");
+}
+async function httpDownloadAttempt(url, destPath, options) {
+  const {
+    ca,
+    followRedirects = true,
+    headers = {},
+    maxRedirects = 5,
+    onProgress,
+    timeout = 12e4
+  } = { __proto__: null, ...options };
+  const response = await (0, import_request.httpRequestAttempt)(url, {
+    ca,
+    followRedirects,
+    headers,
+    maxRedirects,
+    method: "GET",
+    stream: true,
+    timeout
+  });
+  if (!response.ok) {
+    throw new import_response_types.HttpResponseError(
+      response,
+      `Download failed: HTTP ${response.status} ${response.statusText}`
+    );
+  }
+  const res = response.rawResponse;
+  if (!res) {
+    throw new import_error.ErrorCtor("Stream response missing rawResponse");
+  }
+  const { createWriteStream } = (0, import_internal.getFs)();
+  const totalSize = (0, import_number.NumberParseInt)(
+    response.headers["content-length"] || "0",
+    10
+  );
+  return await new import_promise.PromiseCtor((resolve, reject) => {
+    let downloadedSize = 0;
+    const fileStream = createWriteStream(destPath);
+    const cleanupPartial = () => {
+      ;
+      (async () => {
+        try {
+          await (0, import_safe.safeDelete)(destPath);
+        } catch {
+        }
+      })();
+    };
+    fileStream.on("error", (error) => {
+      fileStream.destroy();
+      cleanupPartial();
+      reject(
+        new import_error.ErrorCtor(`Failed to write file: ${error.message}`, {
+          cause: error
+        })
+      );
+    });
+    res.on("data", (chunk) => {
+      downloadedSize += chunk.length;
+      if (onProgress && totalSize > 0) {
+        onProgress(downloadedSize, totalSize);
+      }
+    });
+    fileStream.on("finish", () => {
+      resolve({
+        headers: response.headers,
+        ok: true,
+        path: destPath,
+        size: downloadedSize,
+        status: response.status,
+        statusText: response.statusText
+      });
+    });
+    res.on("error", (error) => {
+      fileStream.destroy();
+      cleanupPartial();
+      reject(error);
+    });
+    res.pipe(fileStream);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  httpDownload,
+  httpDownloadAttempt
+});

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

@@ -0,0 +1,23 @@
+/**
+ * @file Error-message enrichment for HTTP/HTTPS requests. `enrichErrorMessage`
+ *   translates Node.js network error codes (`ECONNREFUSED`, `ENOTFOUND`,
+ *   `ETIMEDOUT`, etc.) into user-facing guidance prefixed with the failing
+ *   method + URL. The wording is generic — no product-specific branding — so
+ *   the request leaves can use it for any caller. `request.ts` invokes this on
+ *   the `request` `'error'` event before rejecting, which is what surfaces the
+ *   actionable messages to consumers.
+ */
+/**
+ * Build an enriched error message based on the error code. Generic guidance (no
+ * product-specific branding).
+ *
+ * @example
+ *   ;```typescript
+ *   try {
+ *     await fetch('https://api.example.com')
+ *   } catch (e) {
+ *     console.error(enrichErrorMessage('https://api.example.com', 'GET', e))
+ *   }
+ *   ```
+ */
+export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;

package/dist/http-request/errors.js

@@ -0,0 +1,50 @@
+"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 errors_exports = {};
+__export(errors_exports, {
+  enrichErrorMessage: () => enrichErrorMessage
+});
+module.exports = __toCommonJS(errors_exports);
+function enrichErrorMessage(url, method, error) {
+  const code = error.code;
+  let message = `${method} request failed: ${url}`;
+  if (code === "ECONNREFUSED") {
+    message += "\n\u2192 Connection refused. Server is unreachable.\n\u2192 Check: Network connectivity and firewall settings.";
+  } else if (code === "ENOTFOUND") {
+    message += "\n\u2192 DNS lookup failed. Cannot resolve hostname.\n\u2192 Check: Internet connection and DNS settings.";
+  } else if (code === "ETIMEDOUT") {
+    message += "\n\u2192 Connection timed out. Network or server issue.\n\u2192 Try: Check network connectivity and retry.";
+  } else if (code === "ECONNRESET") {
+    message += "\n\u2192 Connection reset by server. Possible network interruption.\n\u2192 Try: Retry the request.";
+  } else if (code === "EPIPE") {
+    message += "\n\u2192 Broken pipe. Server closed connection unexpectedly.\n\u2192 Check: Authentication credentials and permissions.";
+  } else if (code === "CERT_HAS_EXPIRED" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") {
+    message += "\n\u2192 SSL/TLS certificate error.\n\u2192 Check: System time and date are correct.\n\u2192 Try: Update CA certificates on your system.";
+  } else if (code) {
+    message += `
+\u2192 Error code: ${code}`;
+  }
+  return message;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  enrichErrorMessage
+});

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

@@ -0,0 +1,57 @@
+/**
+ * @file Header utilities for HTTP/HTTPS requests. Two pure-data helpers:
+ *
+ *   - `parseRetryAfterHeader` turns a `Retry-After` header value (delay-seconds
+ *     OR HTTP-date per RFC 7231 §7.1.3) into a millisecond delay for `onRetry`
+ *     callbacks.
+ *   - `sanitizeHeaders` redacts `Authorization`, `Cookie`, and the other
+ *     credential-bearing headers before they reach a logger or telemetry
+ *     payload. No I/O — these can be imported anywhere without dragging the
+ *     Node.js `http`/`https` modules into the bundle.
+ */
+/**
+ * Parse a `Retry-After` HTTP header value into milliseconds.
+ *
+ * Supports both formats defined in RFC 7231 §7.1.3:
+ *
+ * - **delay-seconds**: integer number of seconds (e.g., `"120"`)
+ * - **HTTP-date**: an absolute date/time (e.g., `"Fri, 31 Dec 2027 23:59:59
+ *   GMT"`)
+ *
+ * When the header is an array (multiple values), the first element is used.
+ *
+ * @example
+ *   ;```ts
+ *   import { setTimeout as delay } from 'node:timers/promises'
+ *   const ms = parseRetryAfterHeader(response.headers['retry-after'])
+ *   if (ms !== undefined) {
+ *     await delay(ms)
+ *   }
+ *   ```
+ *
+ * @param value - The raw Retry-After header value(s)
+ *
+ * @returns Delay in milliseconds, or `undefined` if the value cannot be parsed
+ */
+export declare function parseRetryAfterHeader(value: string | string[] | undefined): number | undefined;
+/**
+ * Redact sensitive HTTP headers for safe logging and telemetry.
+ *
+ * Replaces values of sensitive headers (Authorization, Cookie, etc.) with
+ * `[REDACTED]`. Non-sensitive headers are passed through unchanged. Array
+ * values are joined with `', '`.
+ *
+ * @example
+ *   ;```ts
+ *   const safe = sanitizeHeaders({
+ *     authorization: 'Bearer secret',
+ *     'content-type': 'application/json',
+ *   })
+ *   // { authorization: '[REDACTED]', 'content-type': 'application/json' }
+ *   ```
+ *
+ * @param headers - HTTP headers to sanitize.
+ *
+ * @returns A new object with sensitive values redacted
+ */
+export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined): Record<string, string>;

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>;