@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/http-request/browser.js

@@ -0,0 +1,224 @@
+"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 browser_exports = {};
+__export(browser_exports, {
+  HttpResponseError: () => HttpResponseError,
+  attempt: () => attempt,
+  combineSignals: () => combineSignals,
+  decodeText: () => decodeText,
+  headersToRecord: () => headersToRecord,
+  httpJson: () => httpJson,
+  httpRequest: () => httpRequest,
+  httpText: () => httpText,
+  sleep: () => sleep
+});
+module.exports = __toCommonJS(browser_exports);
+var import_browser_fetch = require("./browser-fetch");
+class HttpResponseError extends Error {
+  response;
+  constructor(response, message) {
+    const statusCode = response.status ?? "unknown";
+    const statusMessage = response.statusText || "No status message";
+    super(message ?? `HTTP ${statusCode}: ${statusMessage}`);
+    this.name = "HttpResponseError";
+    this.response = response;
+  }
+}
+function combineSignals(external, timeoutMs) {
+  if (!timeoutMs) {
+    return { signal: external, cleanup: () => {
+    } };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let externalListener;
+  if (external) {
+    if (external.aborted) {
+      controller.abort();
+    } else {
+      externalListener = () => controller.abort();
+      external.addEventListener("abort", externalListener);
+    }
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      if (external && externalListener) {
+        external.removeEventListener("abort", externalListener);
+      }
+    }
+  };
+}
+async function attempt(url, options) {
+  const method = options.method ?? "GET";
+  const init = { method };
+  if (options.headers) {
+    init.headers = options.headers;
+  }
+  if (options.body !== void 0) {
+    ;
+    init.body = options.body;
+  }
+  if (options.followRedirects === false) {
+    init.redirect = "manual";
+  }
+  const { signal, cleanup } = combineSignals(options.signal, options.timeout);
+  if (signal) {
+    init.signal = signal;
+  }
+  const startedAt = Date.now();
+  if (options.hooks?.onRequest) {
+    options.hooks.onRequest({
+      method,
+      url,
+      headers: options.headers,
+      timeout: options.timeout
+    });
+  }
+  try {
+    const response = await (0, import_browser_fetch.doFetch)(url, init);
+    const buffer = await response.arrayBuffer();
+    if (options.maxResponseSize !== void 0 && buffer.byteLength > options.maxResponseSize) {
+      throw new Error(
+        `Response body (${buffer.byteLength} bytes) exceeds maxResponseSize (${options.maxResponseSize})`
+      );
+    }
+    const body = new Uint8Array(buffer);
+    const headers = headersToRecord(response.headers);
+    if (options.hooks?.onResponse) {
+      options.hooks.onResponse({
+        method,
+        url,
+        duration: Date.now() - startedAt,
+        status: response.status,
+        statusText: response.statusText,
+        headers
+      });
+    }
+    return {
+      body,
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+      ok: response.ok,
+      url: response.url,
+      arrayBuffer() {
+        return buffer;
+      },
+      text() {
+        return decodeText(body);
+      },
+      json() {
+        return JSON.parse(decodeText(body));
+      }
+    };
+  } catch (err) {
+    if (options.hooks?.onResponse) {
+      options.hooks.onResponse({
+        method,
+        url,
+        duration: Date.now() - startedAt,
+        error: err instanceof Error ? err : new Error(String(err))
+      });
+    }
+    throw err;
+  } finally {
+    cleanup();
+  }
+}
+function decodeText(bytes) {
+  return new TextDecoder("utf-8").decode(bytes);
+}
+function headersToRecord(headers) {
+  const out = {};
+  headers.forEach((value, key) => {
+    out[key.toLowerCase()] = value;
+  });
+  return out;
+}
+async function httpJson(url, options) {
+  const opts = options ?? {};
+  const headers = {
+    Accept: "application/json",
+    ...opts.headers ?? {}
+  };
+  if (opts.body !== void 0 && !("Content-Type" in headers)) {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await httpRequest(url, {
+    ...opts,
+    headers,
+    throwOnError: true
+  });
+  return response.json();
+}
+async function httpRequest(url, options) {
+  const opts = options ?? {};
+  const maxAttempts = (opts.retries ?? 0) + 1;
+  const baseDelay = opts.retryDelay ?? 250;
+  let lastError;
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      const response = await attempt(url, opts);
+      if (response.status >= 500 && i + 1 < maxAttempts) {
+        await sleep(baseDelay * Math.pow(2, i));
+        continue;
+      }
+      if (opts.throwOnError && !response.ok) {
+        throw new HttpResponseError(response);
+      }
+      return response;
+    } catch (err) {
+      lastError = err;
+      if (err instanceof HttpResponseError) {
+        throw err;
+      }
+      if (i + 1 < maxAttempts) {
+        await sleep(baseDelay * Math.pow(2, i));
+        continue;
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(`HTTP request to ${url} failed`);
+}
+async function httpText(url, options) {
+  const response = await httpRequest(url, {
+    ...options ?? {},
+    throwOnError: true
+  });
+  return response.text();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HttpResponseError,
+  attempt,
+  combineSignals,
+  decodeText,
+  headersToRecord,
+  httpJson,
+  httpRequest,
+  httpText,
+  sleep
+});

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

@@ -0,0 +1,69 @@
+/**
+ * @file Checksum file fetching + parsing for download verification.
+ *   `parseChecksums` understands the three common file shapes:
+ *
+ *   - BSD style: `SHA256 (filename) = hash`
+ *   - GNU style: `hash filename` (two spaces)
+ *   - Simple: `hash filename` (single space) Comment lines (`#…`) and blank lines
+ *     are skipped. Hashes are lowercased. `fetchChecksums` is the URL helper —
+ *     it fetches a checksums file via `httpRequest` and runs the body through
+ *     `parseChecksums`. The pair lets `httpDownload({ sha256:
+ *     checksums['file.zip'] })` keep the verification logic close to the
+ *     manifest source.
+ */
+import type { Checksums, FetchChecksumsOptions } from './download-types';
+/**
+ * Fetch and parse a checksums file from a URL.
+ *
+ * This is useful for verifying downloads from GitHub releases which typically
+ * publish a checksums.txt file alongside release assets.
+ *
+ * @example
+ *   ;```ts
+ *   // Fetch checksums from GitHub release
+ *   const checksums = await fetchChecksums(
+ *     'https://github.com/org/repo/releases/download/v1.0.0/checksums.txt',
+ *   )
+ *
+ *   // Use with httpDownload
+ *   await httpDownload(
+ *     'https://github.com/org/repo/releases/download/v1.0.0/tool_linux.tar.gz',
+ *     '/tmp/tool.tar.gz',
+ *     { sha256: checksums['tool_linux.tar.gz'] },
+ *   )
+ *   ```
+ *
+ * @param url - URL to the checksums file.
+ * @param options - Request options.
+ *
+ * @returns Map of filenames to lowercase SHA256 hashes
+ *
+ * @throws {Error} When the checksums file cannot be fetched
+ */
+export declare function fetchChecksums(url: string, options?: FetchChecksumsOptions | undefined): Promise<Checksums>;
+/**
+ * Parse a checksums file text into a filename-to-hash map.
+ *
+ * Supports standard checksums file formats: - BSD style: "SHA256 (filename) =
+ * hash" - GNU style: "hash filename" (two spaces) - Simple style: "hash
+ * filename" (single space)
+ *
+ * Lines starting with '#' are treated as comments and ignored. Empty lines are
+ * ignored.
+ *
+ * @example
+ *   ```ts
+ *   const text = `
+ *   # SHA256 checksums
+ *   e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  file.zip
+ *   abc123def456...  other.tar.gz
+ *   `
+ *   const checksums = parseChecksums(text)
+ *   console.log(checksums['file.zip']) // 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+ *   ```
+ *
+ * @param text - Raw text content of a checksums file.
+ *
+ * @returns Map of filenames to lowercase SHA256 hashes
+ */
+export declare function parseChecksums(text: string): Checksums;

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
+});