@socketsecurity/lib 5.13.0 → 5.15.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
+
+### Added — http-request
+
+- `stream` option on `HttpRequestOptions` — resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
+- `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
+
+### Changed — http-request
+
+- `httpDownload` now uses `httpRequest` with `stream: true` internally, eliminating ~120 lines of duplicated HTTP plumbing
+
+## [5.14.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.14.0) - 2026-04-06
+
+### Added — http-request
+
+- `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled, carries the full `HttpResponse`
+- `throwOnError` option on `HttpRequestOptions` — non-2xx responses throw instead of resolving with `ok: false`, enabling retry of HTTP errors
+- `onRetry` callback on `HttpRequestOptions` — customize retry behavior per-attempt (return `false` to stop, a `number` to override delay, `undefined` for default backoff)
+- Streaming body support — `body` accepts `Readable` streams (incl. `form-data` npm package), auto-merges `getHeaders()` when present
+- `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 `Retry-After` header parser (strict integer seconds + HTTP-date formats)
+- `sanitizeHeaders()` — redact sensitive headers (`authorization`, `cookie`, `set-cookie`, `proxy-authorization`, `proxy-authenticate`, `www-authenticate`) for safe logging
+
+### Changed — http-request
+
+- `HttpRequestOptions.body` type widened from `Buffer | string` to `Buffer | Readable | string`
+- Redirect responses now drained via `res.resume()` to free sockets
+- `maxResponseSize` exceeded now cleans up both response and request
+- `onResponse` hooks wrapped in try/catch — user hook errors can no longer leave promises pending
+
 ## [5.13.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.13.0) - 2026-04-05
 
 ### Added — http-request

package/dist/http-request.d.ts

@@ -1,3 +1,19 @@
+/**
+ * @fileoverview HTTP/HTTPS request utilities using Node.js built-in modules with retry logic, redirects, and download support.
+ *
+ * This module provides a fetch-like API built on top of Node.js native `http` and `https` modules.
+ * It supports automatic retries with exponential backoff, redirect following, streaming downloads,
+ * and provides a familiar fetch-style response interface.
+ *
+ * Key Features:
+ * - Automatic retries with exponential backoff for failed requests.
+ * - Redirect following with configurable max redirects.
+ * - Streaming downloads with progress callbacks.
+ * - Fetch-like response interface (`.json()`, `.text()`, `.arrayBuffer()`).
+ * - Timeout support for all operations.
+ * - Zero dependencies on external HTTP libraries.
+ */
+import type { Readable } from 'node:stream';
 import type { IncomingHttpHeaders, IncomingMessage } from 'http';
 /** IncomingMessage received as a response to a client request (http.request callback). */
 export type IncomingResponse = IncomingMessage;
@@ -39,7 +55,17 @@ export interface HttpHooks {
 export interface HttpRequestOptions {
     /**
      * Request body to send.
-     * Can be a string (e.g., JSON) or Buffer (e.g., binary data).
+     * 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
@@ -56,9 +82,18 @@ export interface HttpRequestOptions {
      *   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 | string | undefined;
+    body?: Buffer | Readable | string | undefined;
     /**
      * Custom CA certificates for TLS connections.
      * When provided, these certificates are combined with the default trust
@@ -162,6 +197,38 @@ export interface HttpRequestOptions {
      * ```
      */
     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
+     *
+     * @example
+     * ```ts
+     * await httpRequest('https://api.example.com/data', {
+     *   retries: 3,
+     *   throwOnError: true,
+     *   onRetry: (attempt, error, delay) => {
+     *     // Don't retry client errors (except 429)
+     *     if (error instanceof HttpResponseError) {
+     *       if (error.response.status === 429) {
+     *         const retryAfter = parseRetryAfterHeader(error.response.headers['retry-after'])
+     *         return retryAfter ?? undefined
+     *       }
+     *       if (error.response.status >= 400 && error.response.status < 500) {
+     *         return false
+     *       }
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    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.
@@ -194,6 +261,37 @@ export interface HttpRequestOptions {
      * ```
      */
     retryDelay?: number | 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
+     *
+     * @example
+     * ```ts
+     * // Throw on 4xx/5xx responses (enabling retry for 5xx)
+     * await httpRequest('https://api.example.com/data', {
+     *   throwOnError: true,
+     *   retries: 3
+     * })
+     * ```
+     */
+    /**
+     * 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;
+    throwOnError?: boolean | undefined;
     /**
      * Request timeout in milliseconds.
      * If the request takes longer than this, it will be aborted.
@@ -333,6 +431,56 @@ export interface HttpResponse {
  * into the standard HttpResponse interface.
  */
 export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
+/**
+ * Error thrown when an HTTP response has a non-2xx status code
+ * and `throwOnError` is enabled. Carries the full `HttpResponse`
+ * so callers can inspect status, headers, and body.
+ */
+export declare class HttpResponseError extends Error {
+    response: HttpResponse;
+    constructor(response: HttpResponse, message?: string | undefined);
+}
+/**
+ * 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.
+ *
+ * @param value - The raw Retry-After header value(s)
+ * @returns Delay in milliseconds, or `undefined` if the value cannot be parsed
+ *
+ * @example
+ * ```ts
+ * const delay = parseRetryAfterHeader(response.headers['retry-after'])
+ * if (delay !== undefined) {
+ *   await new Promise(resolve => setTimeout(resolve, delay))
+ * }
+ * ```
+ */
+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 `', '`.
+ *
+ * @param headers - HTTP headers to sanitize
+ * @returns A new object with sensitive values redacted
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeHeaders({
+ *   'authorization': 'Bearer secret',
+ *   'content-type': 'application/json'
+ * })
+ * // { authorization: '[REDACTED]', 'content-type': 'application/json' }
+ * ```
+ */
+export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined): Record<string, string>;
 /**
  * Configuration options for file downloads.
  */
@@ -523,26 +671,18 @@ export interface HttpDownloadOptions {
  * Result of a successful file download.
  */
 export interface HttpDownloadResult {
-    /**
-     * Absolute path where the file was saved.
-     *
-     * @example
-     * ```ts
-     * const result = await httpDownload('https://example.com/file.zip', '/tmp/file.zip')
-     * console.log(`Downloaded to: ${result.path}`)
-     * ```
-     */
+    /** 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.
-     *
-     * @example
-     * ```ts
-     * const result = await httpDownload('https://example.com/file.zip', '/tmp/file.zip')
-     * console.log(`Downloaded ${result.size} bytes`)
-     * ```
-     */
+    /** 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.

package/dist/http-request.js

@@ -19,6 +19,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var http_request_exports = {};
 __export(http_request_exports, {
+  HttpResponseError: () => HttpResponseError,
   enrichErrorMessage: () => enrichErrorMessage,
   fetchChecksums: () => fetchChecksums,
   httpDownload: () => httpDownload,
@@ -26,7 +27,9 @@ __export(http_request_exports, {
   httpRequest: () => httpRequest,
   httpText: () => httpText,
   parseChecksums: () => parseChecksums,
-  readIncomingResponse: () => readIncomingResponse
+  parseRetryAfterHeader: () => parseRetryAfterHeader,
+  readIncomingResponse: () => readIncomingResponse,
+  sanitizeHeaders: () => sanitizeHeaders
 });
 module.exports = __toCommonJS(http_request_exports);
 var import_fs = require("./fs.js");
@@ -85,6 +88,64 @@ async function readIncomingResponse(msg) {
     text: () => body.toString("utf8")
   };
 }
+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;
+    Error.captureStackTrace(this, HttpResponseError);
+  }
+}
+function parseRetryAfterHeader(value) {
+  if (!value) {
+    return void 0;
+  }
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (!raw) {
+    return void 0;
+  }
+  const trimmed = raw.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    return seconds * 1e3;
+  }
+  const date = new Date(raw);
+  if (!Number.isNaN(date.getTime())) {
+    const delayMs = date.getTime() - Date.now();
+    if (delayMs > 0) {
+      return delayMs;
+    }
+  }
+  return void 0;
+}
+function sanitizeHeaders(headers) {
+  if (!headers) {
+    return {};
+  }
+  const sensitiveHeaders = /* @__PURE__ */ new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "proxy-authenticate",
+    "set-cookie",
+    "www-authenticate"
+  ]);
+  const result = { __proto__: null };
+  for (const key of Object.keys(headers)) {
+    const value = headers[key];
+    if (sensitiveHeaders.has(key.toLowerCase())) {
+      result[key] = "[REDACTED]";
+    } else if (Array.isArray(value)) {
+      result[key] = value.join(", ");
+    } else if (value !== void 0 && value !== null) {
+      result[key] = String(value);
+    }
+  }
+  return result;
+}
 function parseChecksums(text) {
   const checksums = { __proto__: null };
   for (const line of text.split("\n")) {
@@ -132,135 +193,61 @@ async function httpDownloadAttempt(url, destPath, options) {
     onProgress,
     timeout = 12e4
   } = { __proto__: null, ...options };
+  const response = await httpRequestAttempt(url, {
+    ca,
+    followRedirects,
+    headers,
+    maxRedirects,
+    method: "GET",
+    stream: true,
+    timeout
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Download failed: HTTP ${response.status} ${response.statusText}`
+    );
+  }
+  const res = response.rawResponse;
+  if (!res) {
+    throw new Error("Stream response missing rawResponse");
+  }
+  const { createWriteStream } = /* @__PURE__ */ getFs();
+  const totalSize = Number.parseInt(
+    response.headers["content-length"] || "0",
+    10
+  );
   return await new Promise((resolve, reject) => {
-    const parsedUrl = new URL(url);
-    const isHttps = parsedUrl.protocol === "https:";
-    const httpModule = isHttps ? /* @__PURE__ */ getHttps() : /* @__PURE__ */ getHttp();
-    const requestOptions = {
-      headers: {
-        "User-Agent": "socket-registry/1.0",
-        ...headers
-      },
-      hostname: parsedUrl.hostname,
-      method: "GET",
-      path: parsedUrl.pathname + parsedUrl.search,
-      port: parsedUrl.port,
-      timeout
-    };
-    if (ca && isHttps) {
-      requestOptions["ca"] = ca;
-    }
-    const { createWriteStream } = /* @__PURE__ */ getFs();
-    let fileStream;
-    let streamClosed = false;
-    const closeStream = () => {
-      if (!streamClosed && fileStream) {
-        streamClosed = true;
-        fileStream.close();
+    let downloadedSize = 0;
+    const fileStream = createWriteStream(destPath);
+    fileStream.on("error", (error) => {
+      fileStream.close();
+      reject(
+        new Error(`Failed to write file: ${error.message}`, { cause: error })
+      );
+    });
+    res.on("data", (chunk) => {
+      downloadedSize += chunk.length;
+      if (onProgress && totalSize > 0) {
+        onProgress(downloadedSize, totalSize);
       }
-    };
-    const request = httpModule.request(
-      requestOptions,
-      (res) => {
-        if (followRedirects && res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          if (maxRedirects <= 0) {
-            reject(
-              new Error(
-                `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:") {
-            reject(
-              new Error(
-                `Redirect from HTTPS to HTTP is not allowed: ${redirectUrl}`
-              )
-            );
-            return;
-          }
-          resolve(
-            httpDownloadAttempt(redirectUrl, destPath, {
-              ca,
-              followRedirects,
-              headers,
-              maxRedirects: maxRedirects - 1,
-              onProgress,
-              timeout
-            })
-          );
-          return;
-        }
-        if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
-          closeStream();
-          reject(
-            new Error(
-              `Download failed: HTTP ${res.statusCode} ${res.statusMessage}`
-            )
-          );
-          return;
-        }
-        const totalSize = Number.parseInt(
-          res.headers["content-length"] || "0",
-          10
-        );
-        let downloadedSize = 0;
-        fileStream = createWriteStream(destPath);
-        fileStream.on("error", (error) => {
-          closeStream();
-          const err = new Error(`Failed to write file: ${error.message}`, {
-            cause: error
-          });
-          reject(err);
-        });
-        res.on("data", (chunk) => {
-          downloadedSize += chunk.length;
-          if (onProgress && totalSize > 0) {
-            onProgress(downloadedSize, totalSize);
-          }
-        });
-        res.on("end", () => {
-          fileStream?.close(() => {
-            streamClosed = true;
-            resolve({
-              path: destPath,
-              size: downloadedSize
-            });
-          });
-        });
-        res.on("error", (error) => {
-          closeStream();
-          reject(error);
+    });
+    res.on("end", () => {
+      fileStream.close(() => {
+        resolve({
+          headers: response.headers,
+          ok: true,
+          path: destPath,
+          size: downloadedSize,
+          status: response.status,
+          statusText: response.statusText
         });
-        res.pipe(fileStream);
-      }
-    );
-    request.on("error", (error) => {
-      closeStream();
-      const code = error.code;
-      let message = `HTTP download failed for ${url}: ${error.message}
-`;
-      if (code === "ENOTFOUND") {
-        message += "DNS lookup failed. Check the hostname and your network connection.";
-      } else if (code === "ECONNREFUSED") {
-        message += "Connection refused. Verify the server is running and accessible.";
-      } else if (code === "ETIMEDOUT") {
-        message += "Request timed out. Check your network or increase the timeout value.";
-      } else if (code === "ECONNRESET") {
-        message += "Connection reset. The server may have closed the connection unexpectedly.";
-      } else {
-        message += "Check your network connection and verify the URL is correct.";
-      }
-      reject(new Error(message, { cause: error }));
+      });
     });
-    request.on("timeout", () => {
-      request.destroy();
-      closeStream();
-      reject(new Error(`Download timed out after ${timeout}ms`));
+    res.on("error", (error) => {
+      fileStream.close();
+      reject(error);
     });
-    request.end();
+    res.pipe(fileStream);
   });
 }
 function enrichErrorMessage(url, method, error) {
@@ -294,15 +281,38 @@ async function httpRequestAttempt(url, options) {
     maxRedirects = 5,
     maxResponseSize,
     method = "GET",
+    stream = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
   const startTime = Date.now();
+  const streamHeaders = body && typeof body === "object" && "getHeaders" in body && typeof body.getHeaders === "function" ? body.getHeaders() : void 0;
   const mergedHeaders = {
     "User-Agent": "socket-registry/1.0",
+    ...streamHeaders,
     ...headers
   };
   hooks?.onRequest?.({ method, url, headers: mergedHeaders, timeout });
   return await new Promise((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 URL(url);
     const isHttps = parsedUrl.protocol === "https:";
     const httpModule = isHttps ? /* @__PURE__ */ getHttps() : /* @__PURE__ */ getHttp();
@@ -318,23 +328,28 @@ async function httpRequestAttempt(url, options) {
       requestOptions["ca"] = ca;
     }
     const emitResponse = (info) => {
-      hooks?.onResponse?.({
-        duration: Date.now() - startTime,
-        method,
-        url,
-        ...info
-      });
+      try {
+        hooks?.onResponse?.({
+          duration: Date.now() - 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 Error(
                 `Too many redirects (exceeded maximum: ${maxRedirects})`
@@ -345,6 +360,7 @@ async function httpRequestAttempt(url, options) {
           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 Error(
                 `Redirect from HTTPS to HTTP is not allowed: ${redirectUrl}`
@@ -352,6 +368,7 @@ async function httpRequestAttempt(url, options) {
             );
             return;
           }
+          settled = true;
           resolve(
             httpRequestAttempt(redirectUrl, {
               body,
@@ -362,29 +379,59 @@ async function httpRequestAttempt(url, options) {
               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 Error("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);
-            const err = new Error(
-              `Response exceeds maximum size limit (${sizeMB}MB > ${maxMB}MB)`
+            rejectOnce(
+              new Error(
+                `Response exceeds maximum size limit (${sizeMB}MB > ${maxMB}MB)`
+              )
             );
-            emitResponse({ error: err });
-            reject(err);
             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 = {
@@ -412,11 +459,10 @@ async function httpRequestAttempt(url, options) {
             status: res.statusCode,
             statusText: res.statusMessage
           });
-          resolve(response);
+          resolveOnce(response);
         });
         res.on("error", (error) => {
-          emitResponse({ error });
-          reject(error);
+          rejectOnce(error);
         });
       }
     );
@@ -426,24 +472,33 @@ async function httpRequestAttempt(url, options) {
         method,
         error
       );
-      const enhanced = new Error(message, { cause: error });
-      emitResponse({ error: enhanced });
-      reject(enhanced);
+      rejectOnce(new Error(message, { cause: error }));
     });
     request.on("timeout", () => {
       request.destroy();
-      const err = new Error(
-        `${method} request timed out after ${timeout}ms: ${url}
+      rejectOnce(
+        new Error(
+          `${method} request timed out after ${timeout}ms: ${url}
 \u2192 Server did not respond in time.
 \u2192 Try: Increase timeout or check network connectivity.`
+        )
       );
-      emitResponse({ error: err });
-      reject(err);
     });
     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();
     }
-    request.end();
   });
 }
 async function httpDownload(url, destPath, options) {
@@ -511,8 +566,8 @@ Computed: ${computedHash}`
       }
       await fs.promises.rename(tempPath, destPath);
       return {
-        path: destPath,
-        size: result.size
+        ...result,
+        path: destPath
       };
     } catch (e) {
       lastError = e;
@@ -571,31 +626,57 @@ async function httpRequest(url, options) {
     maxRedirects = 5,
     maxResponseSize,
     method = "GET",
+    onRetry,
     retries = 0,
     retryDelay = 1e3,
+    stream = false,
+    throwOnError = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
+  const isStreamBody = body !== void 0 && typeof body === "object" && typeof body.pipe === "function";
+  if (isStreamBody && retries > 0) {
+    throw new Error(
+      "Streaming body (Readable/FormData) cannot be used with retries. Streams are consumed on first attempt and cannot be replayed. Set retries: 0 or buffer the body as a string/Buffer."
+    );
+  }
+  const attemptOpts = {
+    body,
+    ca,
+    // Disable redirect following for stream bodies — the stream is consumed
+    // on the first request and cannot be re-piped to the redirect target.
+    followRedirects: isStreamBody ? false : followRedirects,
+    headers,
+    hooks,
+    maxRedirects,
+    maxResponseSize,
+    method,
+    stream,
+    timeout
+  };
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
-      return await httpRequestAttempt(url, {
-        body,
-        ca,
-        followRedirects,
-        headers,
-        hooks,
-        maxRedirects,
-        maxResponseSize,
-        method,
-        timeout
-      });
+      const response = await httpRequestAttempt(url, attemptOpts);
+      if (throwOnError && !response.ok) {
+        throw new HttpResponseError(response);
+      }
+      return response;
     } catch (e) {
       lastError = e;
       if (attempt === retries) {
         break;
       }
       const delayMs = retryDelay * 2 ** attempt;
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      if (onRetry) {
+        const retryResult = onRetry(attempt + 1, e, delayMs);
+        if (retryResult === false) {
+          break;
+        }
+        const actualDelay = typeof retryResult === "number" && !Number.isNaN(retryResult) ? Math.max(0, retryResult) : delayMs;
+        await new Promise((resolve) => setTimeout(resolve, actualDelay));
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
     }
   }
   throw lastError || new Error("Request failed after retries");
@@ -631,6 +712,7 @@ async function httpText(url, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HttpResponseError,
   enrichErrorMessage,
   fetchChecksums,
   httpDownload,
@@ -638,5 +720,7 @@ async function httpText(url, options) {
   httpRequest,
   httpText,
   parseChecksums,
-  readIncomingResponse
+  parseRetryAfterHeader,
+  readIncomingResponse,
+  sanitizeHeaders
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.13.0",
+  "version": "5.15.0",
   "packageManager": "pnpm@10.33.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -717,7 +717,7 @@
     "update": "node scripts/update.mjs"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-code": "2.1.89",
+    "@anthropic-ai/claude-code": "2.1.92",
     "@babel/core": "7.28.4",
     "@babel/parser": "7.28.4",
     "@babel/traverse": "7.28.4",
@@ -735,7 +735,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.4.1",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.12.0",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.14.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",