@socketsecurity/lib 5.28.0 → 6.0.1

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

@@ -0,0 +1,224 @@
+/**
+ * @file Types for HTTP download + checksum-fetch operations. Split out of
+ *   `http-request/types.ts` for size hygiene.
+ *
+ *   - `HttpDownloadOptions` / `HttpDownloadResult` — file-download surface
+ *   - `Checksums` / `FetchChecksumsOptions` — checksum-file helpers
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+import type { Logger } from '../logger/default';
+/**
+ * Configuration options for file downloads.
+ */
+export interface HttpDownloadOptions {
+    /**
+     * Custom CA certificates for TLS connections. When provided, these
+     * certificates are used for the download request. See `HttpRequestOptions.ca`
+     * for details.
+     */
+    ca?: string[] | undefined;
+    /**
+     * Whether to automatically follow HTTP redirects (3xx status codes). This is
+     * essential for downloading from services that use CDN redirects, such as
+     * GitHub release assets which return HTTP 302 to their CDN.
+     *
+     * @example
+     *   ;```ts
+     *   // Follow redirects (default) - works with GitHub releases
+     *   await httpDownload(
+     *     'https://github.com/org/repo/releases/download/v1.0.0/file.zip',
+     *     '/tmp/file.zip',
+     *   )
+     *   ```
+     *
+     * @default true
+     */
+    followRedirects?: boolean | undefined;
+    /**
+     * HTTP headers to send with the download request. A `User-Agent` header is
+     * automatically added if not provided.
+     *
+     * @example
+     *   ;```ts
+     *   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *     headers: {
+     *       Authorization: 'Bearer token123',
+     *     },
+     *   })
+     *   ```
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Logger instance for automatic progress logging. When provided with
+     * `progressInterval`, will automatically log download progress. If both
+     * `onProgress` and `logger` are provided, `onProgress` takes precedence.
+     *
+     * @example
+     *   ;```ts
+     *   import { getDefaultLogger } from '@socketsecurity/lib/logger/default'
+     *
+     *   const logger = getDefaultLogger()
+     *   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *     logger,
+     *     progressInterval: 10, // Log every 10%
+     *   })
+     *   ```
+     */
+    logger?: Logger | undefined;
+    /**
+     * Maximum number of redirects to follow before throwing an error. Only
+     * relevant when `followRedirects` is `true`.
+     *
+     * @default 5
+     */
+    maxRedirects?: number | undefined;
+    /**
+     * Callback for tracking download progress. Called periodically as data is
+     * received. Takes precedence over `logger` if both are provided.
+     *
+     * @example
+     *   ```ts
+     *   await httpDownload(
+     *   'https://example.com/large-file.zip',
+     *   '/tmp/file.zip',
+     *   {
+     *   onProgress: (downloaded, total) => {
+     *   const percent = ((downloaded / total) * 100).toFixed(1)
+     *   console.log(`Progress: ${percent}%`)
+     *   },
+     *   },
+     *   )
+     *   ```
+     *
+     * @param downloaded - Number of bytes downloaded so far.
+     * @param total - Total file size in bytes (from Content-Length header)
+     */
+    onProgress?: ((downloaded: number, total: number) => void) | undefined;
+    /**
+     * Progress reporting interval as a percentage (0-100). Only used when
+     * `logger` is provided. Progress will be logged each time the download
+     * advances by this percentage.
+     *
+     * @default 10
+     */
+    progressInterval?: number | undefined;
+    /**
+     * Number of retry attempts for failed downloads. Uses exponential backoff:
+     * delay = `retryDelay` * 2^attempt.
+     *
+     * @example
+     *   ;```ts
+     *   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *     retries: 3,
+     *     retryDelay: 2000,
+     *   })
+     *   ```
+     *
+     * @default 0
+     */
+    retries?: number | undefined;
+    /**
+     * Initial delay in milliseconds before first retry. Subsequent retries use
+     * exponential backoff.
+     *
+     * @default 1000
+     */
+    retryDelay?: number | undefined;
+    /**
+     * Download timeout in milliseconds. If the download takes longer than this,
+     * it will be aborted.
+     *
+     * @default 120000
+     */
+    timeout?: number | undefined;
+    /**
+     * Expected SHA256 hash of the downloaded file. If provided, the download will
+     * fail if the computed hash doesn't match. The hash should be a lowercase hex
+     * string (64 characters).
+     *
+     * Use `fetchChecksums()` to fetch hashes from a checksums URL, then pass the
+     * specific hash here.
+     *
+     * @example
+     *   ;```ts
+     *   // Verify download integrity with direct hash
+     *   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *     sha256:
+     *       'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+     *   })
+     *
+     *   // Verify using checksums from a URL
+     *   const checksums = await fetchChecksums(
+     *     'https://example.com/checksums.txt',
+     *   )
+     *   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *     sha256: checksums['file.zip'],
+     *   })
+     *   ```
+     */
+    sha256?: string | undefined;
+}
+/**
+ * Result of a successful file download.
+ */
+export interface HttpDownloadResult {
+    /**
+     * HTTP response headers from the final response (after redirects).
+     */
+    headers: IncomingHttpHeaders;
+    /**
+     * Whether the download succeeded (status 200-299). Always true on success
+     * (non-2xx throws).
+     */
+    ok: true;
+    /**
+     * Absolute path where the file was saved.
+     */
+    path: string;
+    /**
+     * Total size of downloaded file in bytes.
+     */
+    size: number;
+    /**
+     * HTTP status code from the final response (after redirects).
+     */
+    status: number;
+    /**
+     * HTTP status message from the final response (after redirects).
+     */
+    statusText: string;
+}
+/**
+ * Map of filenames to their SHA256 hashes. Keys are filenames (not paths),
+ * values are lowercase hex-encoded SHA256 hashes.
+ *
+ * @example
+ *   ;```ts
+ *   const checksums: Checksums = {
+ *     'file.zip':
+ *       'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+ *     'other.tar.gz': 'abc123...',
+ *   }
+ *   ```
+ */
+export type Checksums = Record<string, string>;
+/**
+ * Options for fetching checksums from a URL.
+ */
+export interface FetchChecksumsOptions {
+    /**
+     * Custom CA certificates for TLS connections. See `HttpRequestOptions.ca` for
+     * details.
+     */
+    ca?: string[] | undefined;
+    /**
+     * HTTP headers to send with the request.
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * @default 30000
+     */
+    timeout?: number | undefined;
+}

package/dist/http-request/download-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 download_types_exports = {};
+module.exports = __toCommonJS(download_types_exports);

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

@@ -0,0 +1,71 @@
+/**
+ * @file Streaming file downloads with retries, progress callbacks, and SHA-256
+ *   verification. `httpDownload` is the public entry — it writes to a
+ *   randomly-named sibling temp file first, then atomic-renames into place on
+ *   success so a failed run never leaves a half-written file at `destPath`.
+ *   `httpDownloadAttempt` is one streaming pass; the retry / hash-check loop
+ *   sits in `httpDownload`. `httpDownloadAttempt` is exported (not private) per
+ *   `export-top-level-functions` — it lives here next to the only caller, and
+ *   it uses `httpRequestAttempt(... { stream: true })` from `request.ts` to
+ *   obtain the unconsumed `rawResponse` it pipes to disk.
+ */
+import type { HttpDownloadOptions, HttpDownloadResult } from './download-types';
+/**
+ * Download a file from a URL to a local path with redirect support, retry
+ * logic, and progress callbacks. Uses streaming to avoid loading entire file in
+ * memory.
+ *
+ * The download is streamed directly to disk, making it memory-efficient even
+ * for large files. Progress callbacks allow for real-time download status
+ * updates.
+ *
+ * Automatically follows HTTP redirects (3xx status codes) by default, making it
+ * suitable for downloading from services like GitHub releases that redirect to
+ * CDN URLs.
+ *
+ * @example
+ *   ```ts
+ *   // Simple download
+ *   const result = await httpDownload(
+ *   'https://example.com/file.zip',
+ *   '/tmp/file.zip',
+ *   )
+ *   console.log(`Downloaded ${result.size} bytes to ${result.path}`)
+ *
+ *   // Download from GitHub releases (handles 302 redirect automatically)
+ *   await httpDownload(
+ *   'https://github.com/org/repo/releases/download/v1.0.0/binary.tar.gz',
+ *   '/tmp/binary.tar.gz',
+ *   )
+ *
+ *   // With progress tracking
+ *   await httpDownload('https://example.com/large-file.zip', '/tmp/file.zip', {
+ *   onProgress: (downloaded, total) => {
+ *   const percent = ((downloaded / total) * 100).toFixed(1)
+ *   console.log(`Progress: ${percent}% (${downloaded}/${total} bytes)`)
+ *   },
+ *   })
+ *
+ *   // With retries and custom timeout
+ *   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+ *   retries: 3,
+ *   retryDelay: 2000,
+ *   timeout: 300000, // 5 minutes
+ *   headers: { Authorization: 'Bearer token123' },
+ *   })
+ *   ```
+ *
+ * @param url - The URL to download from (must start with http:// or https://)
+ * @param destPath - Absolute path where the file should be saved.
+ * @param options - Download configuration options.
+ *
+ * @returns Promise resolving to download result with path and size
+ *
+ * @throws {Error} When all retries are exhausted, download fails, or file
+ *   cannot be written.
+ */
+export declare function httpDownload(url: string, destPath: string, options?: HttpDownloadOptions | undefined): Promise<HttpDownloadResult>;
+/**
+ * Single download attempt using httpRequestAttempt with stream: true.
+ */
+export declare function httpDownloadAttempt(url: string, destPath: string, options: HttpDownloadOptions): Promise<HttpDownloadResult>;

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