@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/http-request/checksums.js

@@ -0,0 +1,72 @@
+"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 checksums_exports = {};
+__export(checksums_exports, {
+  fetchChecksums: () => fetchChecksums,
+  parseChecksums: () => parseChecksums
+});
+module.exports = __toCommonJS(checksums_exports);
+var import_error = require("../primordials/error");
+var import_string = require("../primordials/string");
+var import_request = require("./request");
+const CHECKSUM_BSD_RE = /^SHA256\s+\((.+)\)\s+=\s+([a-fA-F0-9]{64})$/;
+const CHECKSUM_GNU_RE = /^([a-fA-F0-9]{64})\s+(.+)$/;
+async function fetchChecksums(url, options) {
+  const {
+    ca,
+    headers = {},
+    timeout = 3e4
+  } = {
+    __proto__: null,
+    ...options
+  };
+  const response = await (0, import_request.httpRequest)(url, { ca, headers, timeout });
+  if (!response.ok) {
+    throw new import_error.ErrorCtor(
+      `Failed to fetch checksums from ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+  return parseChecksums(response.body.toString("utf8"));
+}
+function parseChecksums(text) {
+  const checksums = { __proto__: null };
+  for (const line of (0, import_string.StringPrototypeSplit)(text, "\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || (0, import_string.StringPrototypeStartsWith)(trimmed, "#")) {
+      continue;
+    }
+    const bsdMatch = CHECKSUM_BSD_RE.exec(trimmed);
+    if (bsdMatch) {
+      checksums[bsdMatch[1]] = bsdMatch[2].toLowerCase();
+      continue;
+    }
+    const gnuMatch = CHECKSUM_GNU_RE.exec(trimmed);
+    if (gnuMatch) {
+      checksums[gnuMatch[2]] = gnuMatch[1].toLowerCase();
+    }
+  }
+  return checksums;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchChecksums,
+  parseChecksums
+});

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

@@ -0,0 +1,104 @@
+/**
+ * @file Thin convenience wrappers over `httpRequest` — `httpJson` and
+ *   `httpText`. Both set sensible default `Accept` (and `Content-Type` when a
+ *   body is present) headers, then delegate to `httpRequest`. User-supplied
+ *   headers always win in the merge. Each wrapper throws `HttpResponseError` on
+ *   non-2xx responses (parallel to the `throwOnError` mode of `httpRequest`) so
+ *   callers never have to inspect `.ok` themselves.
+ */
+import type { HttpRequestOptions } from './request-types';
+/**
+ * Perform an HTTP request and parse JSON response. Convenience wrapper around
+ * `httpRequest` for JSON API calls. Automatically sets appropriate headers for
+ * JSON requests: - `Accept: application/json` (always) - `Content-Type:
+ * application/json` (when body is present) User-provided headers override these
+ * defaults.
+ *
+ * @example
+ *   ;```ts
+ *   // Simple JSON GET (automatically sets Accept: application/json)
+ *   const data = await httpJson('https://api.example.com/data')
+ *   console.log(data)
+ *
+ *   // With type safety
+ *   interface User {
+ *     id: number
+ *     name: string
+ *     email: string
+ *   }
+ *   const user = await httpJson<User>('https://api.example.com/user/123')
+ *   console.log(user.name, user.email)
+ *
+ *   // POST with JSON body (automatically sets Content-Type: application/json)
+ *   const result = await httpJson('https://api.example.com/users', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' }),
+ *   })
+ *
+ *   // With custom headers and retries
+ *   const data = await httpJson('https://api.example.com/data', {
+ *     headers: {
+ *       Authorization: 'Bearer token123',
+ *     },
+ *     retries: 3,
+ *     retryDelay: 1000,
+ *   })
+ *   ```
+ *
+ * @template T - Expected JSON response type (defaults to `unknown`)
+ *
+ * @param url - The URL to request (must start with http:// or https://)
+ * @param options - Request configuration options.
+ *
+ * @returns Promise resolving to parsed JSON data
+ *
+ * @throws {Error} When request fails, response is not ok (status < 200 or >=
+ *   300), or JSON parsing fails.
+ */
+export declare function httpJson<T = unknown>(url: string, options?: HttpRequestOptions | undefined): Promise<T>;
+/**
+ * Perform an HTTP request and return text response. Convenience wrapper around
+ * `httpRequest` for fetching text content. Automatically sets appropriate
+ * headers for text requests: - `Accept: text/plain` (always) - `Content-Type:
+ * text/plain` (when body is present) User-provided headers override these
+ * defaults.
+ *
+ * @example
+ *   ;```ts
+ *   // Fetch HTML (automatically sets Accept: text/plain)
+ *   const html = await httpText('https://example.com')
+ *   console.log(html.includes('<!DOCTYPE html>'))
+ *
+ *   // Fetch plain text
+ *   const text = await httpText('https://example.com/file.txt')
+ *   console.log(text)
+ *
+ *   // POST with text body (automatically sets Content-Type: text/plain)
+ *   const result = await httpText('https://example.com/api', {
+ *     method: 'POST',
+ *     body: 'raw text data',
+ *   })
+ *
+ *   // With custom headers (override defaults)
+ *   const text = await httpText('https://example.com/data.txt', {
+ *     headers: {
+ *       Authorization: 'Bearer token123',
+ *       Accept: 'text/html', // Override default Accept header
+ *     },
+ *   })
+ *
+ *   // With timeout
+ *   const text = await httpText('https://example.com/large-file.txt', {
+ *     timeout: 60000, // 1 minute
+ *   })
+ *   ```
+ *
+ * @param url - The URL to request (must start with http:// or https://)
+ * @param options - Request configuration options.
+ *
+ * @returns Promise resolving to response body as UTF-8 string
+ *
+ * @throws {Error} When request fails or response is not ok (status < 200 or >=
+ *   300)
+ */
+export declare function httpText(url: string, options?: HttpRequestOptions | undefined): Promise<string>;

package/dist/http-request/convenience.js

@@ -0,0 +1,96 @@
+"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 convenience_exports = {};
+__export(convenience_exports, {
+  httpJson: () => httpJson,
+  httpText: () => httpText
+});
+module.exports = __toCommonJS(convenience_exports);
+var import_error = require("../primordials/error");
+var import_request = require("./request");
+var import_response_types = require("./response-types");
+async function httpJson(url, options) {
+  const {
+    body,
+    headers = {},
+    ...restOptions
+  } = {
+    __proto__: null,
+    ...options
+  };
+  const defaultHeaders = {
+    Accept: "application/json"
+  };
+  if (body) {
+    defaultHeaders["Content-Type"] = "application/json";
+  }
+  const mergedHeaders = {
+    ...defaultHeaders,
+    ...headers
+  };
+  const response = await (0, import_request.httpRequest)(url, {
+    body,
+    headers: mergedHeaders,
+    ...restOptions
+  });
+  if (!response.ok) {
+    throw new import_response_types.HttpResponseError(response);
+  }
+  try {
+    return response.json();
+  } catch (e) {
+    throw new import_error.ErrorCtor("Failed to parse JSON response", { cause: e });
+  }
+}
+async function httpText(url, options) {
+  const {
+    body,
+    headers = {},
+    ...restOptions
+  } = {
+    __proto__: null,
+    ...options
+  };
+  const defaultHeaders = {
+    Accept: "text/plain"
+  };
+  if (body) {
+    defaultHeaders["Content-Type"] = "text/plain";
+  }
+  const mergedHeaders = {
+    ...defaultHeaders,
+    ...headers
+  };
+  const response = await (0, import_request.httpRequest)(url, {
+    body,
+    headers: mergedHeaders,
+    ...restOptions
+  });
+  if (!response.ok) {
+    throw new import_response_types.HttpResponseError(response);
+  }
+  return response.text();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  httpJson,
+  httpText
+});

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/logger';
+/**
+ * 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/logger'
+     *
+     *   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>;