@socketsecurity/lib 5.11.4 → 5.13.0

package/dist/http-request.d.ts

@@ -1,4 +1,38 @@
+import type { IncomingHttpHeaders, IncomingMessage } from 'http';
+/** IncomingMessage received as a response to a client request (http.request callback). */
+export type IncomingResponse = IncomingMessage;
+/** IncomingMessage received as a request in a server handler (http.createServer callback). */
+export type IncomingRequest = IncomingMessage;
 import type { Logger } from './logger.js';
+/**
+ * Information passed to the onRequest hook before each request attempt.
+ */
+export interface HttpHookRequestInfo {
+    headers: Record<string, string>;
+    method: string;
+    timeout: number;
+    url: string;
+}
+/**
+ * Information passed to the onResponse hook after each request attempt.
+ */
+export interface HttpHookResponseInfo {
+    duration: number;
+    error?: Error | undefined;
+    headers?: IncomingHttpHeaders | undefined;
+    method: string;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    url: string;
+}
+/**
+ * Lifecycle hooks for observing HTTP request/response events.
+ * Hooks fire per-attempt (retries produce multiple hook calls).
+ */
+export interface HttpHooks {
+    onRequest?: ((info: HttpHookRequestInfo) => void) | undefined;
+    onResponse?: ((info: HttpHookResponseInfo) => void) | undefined;
+}
 /**
  * Configuration options for HTTP/HTTPS requests.
  */
@@ -61,6 +95,11 @@ export interface HttpRequestOptions {
      * ```
      */
     followRedirects?: boolean | undefined;
+    /**
+     * Lifecycle hooks for observing request/response events.
+     * Hooks fire per-attempt — retries and redirects each trigger separate hook calls.
+     */
+    hooks?: HttpHooks | undefined;
     /**
      * HTTP headers to send with the request.
      * A `User-Agent` header is automatically added if not provided.
@@ -92,6 +131,14 @@ export interface HttpRequestOptions {
      * ```
      */
     maxRedirects?: number | undefined;
+    /**
+     * Maximum response body size in bytes. Responses exceeding this limit
+     * will be rejected with an error. Prevents memory exhaustion from
+     * unexpectedly large responses.
+     *
+     * @default undefined (no limit)
+     */
+    maxResponseSize?: number | undefined;
     /**
      * HTTP method to use for the request.
      *
@@ -205,7 +252,7 @@ export interface HttpResponse {
      * console.log(response.headers['set-cookie']) // May be string[]
      * ```
      */
-    headers: Record<string, string | string[] | undefined>;
+    headers: IncomingHttpHeaders;
     /**
      * Parse response body as JSON.
      * Type parameter `T` allows specifying the expected JSON structure.
@@ -270,7 +317,22 @@ export interface HttpResponse {
      * ```
      */
     text(): string;
+    /**
+     * The underlying Node.js IncomingResponse for advanced use cases
+     * (e.g., streaming, custom header inspection). Only available when
+     * the response was not consumed by the convenience methods.
+     */
+    rawResponse?: IncomingResponse | undefined;
 }
+/**
+ * Read and buffer a client-side IncomingResponse into an HttpResponse.
+ *
+ * Useful when you have a raw response from code that bypasses
+ * `httpRequest()` (e.g., multipart form-data uploads via `http.request()`,
+ * or responses from third-party HTTP libraries) and need to convert it
+ * into the standard HttpResponse interface.
+ */
+export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
 /**
  * Configuration options for file downloads.
  */
@@ -567,6 +629,11 @@ export interface FetchChecksumsOptions {
  * ```
  */
 export declare function fetchChecksums(url: string, options?: FetchChecksumsOptions | undefined): Promise<Checksums>;
+/**
+ * Build an enriched error message based on the error code.
+ * Generic guidance (no product-specific branding).
+ */
+export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
 /**
  * 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.

package/dist/http-request.js

@@ -19,12 +19,14 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var http_request_exports = {};
 __export(http_request_exports, {
+  enrichErrorMessage: () => enrichErrorMessage,
   fetchChecksums: () => fetchChecksums,
   httpDownload: () => httpDownload,
   httpJson: () => httpJson,
   httpRequest: () => httpRequest,
   httpText: () => httpText,
-  parseChecksums: () => parseChecksums
+  parseChecksums: () => parseChecksums,
+  readIncomingResponse: () => readIncomingResponse
 });
 module.exports = __toCommonJS(http_request_exports);
 var import_fs = require("./fs.js");
@@ -60,6 +62,29 @@ function getHttps() {
   }
   return _https;
 }
+async function readIncomingResponse(msg) {
+  const chunks = [];
+  for await (const chunk of msg) {
+    chunks.push(chunk);
+  }
+  const body = Buffer.concat(chunks);
+  const status = msg.statusCode ?? 0;
+  const statusText = msg.statusMessage ?? "";
+  return {
+    arrayBuffer: () => body.buffer.slice(
+      body.byteOffset,
+      body.byteOffset + body.byteLength
+    ),
+    body,
+    headers: msg.headers,
+    json: () => JSON.parse(body.toString("utf8")),
+    ok: status >= 200 && status < 300,
+    rawResponse: msg,
+    status,
+    statusText,
+    text: () => body.toString("utf8")
+  };
+}
 function parseChecksums(text) {
   const checksums = { __proto__: null };
   for (const line of text.split("\n")) {
@@ -238,25 +263,51 @@ async function httpDownloadAttempt(url, destPath, options) {
     request.end();
   });
 }
+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;
+}
 async function httpRequestAttempt(url, options) {
   const {
     body,
     ca,
     followRedirects = true,
     headers = {},
+    hooks,
     maxRedirects = 5,
+    maxResponseSize,
     method = "GET",
     timeout = 3e4
   } = { __proto__: null, ...options };
+  const startTime = Date.now();
+  const mergedHeaders = {
+    "User-Agent": "socket-registry/1.0",
+    ...headers
+  };
+  hooks?.onRequest?.({ method, url, headers: mergedHeaders, timeout });
   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
-      },
+      headers: mergedHeaders,
       hostname: parsedUrl.hostname,
       method,
       path: parsedUrl.pathname + parsedUrl.search,
@@ -266,10 +317,23 @@ async function httpRequestAttempt(url, options) {
     if (ca && isHttps) {
       requestOptions["ca"] = ca;
     }
+    const emitResponse = (info) => {
+      hooks?.onResponse?.({
+        duration: Date.now() - startTime,
+        method,
+        url,
+        ...info
+      });
+    };
     const request = httpModule.request(
       requestOptions,
       (res) => {
         if (followRedirects && res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          emitResponse({
+            headers: res.headers,
+            status: res.statusCode,
+            statusText: res.statusMessage
+          });
           if (maxRedirects <= 0) {
             reject(
               new Error(
@@ -294,7 +358,9 @@ async function httpRequestAttempt(url, options) {
               ca,
               followRedirects,
               headers,
+              hooks,
               maxRedirects: maxRedirects - 1,
+              maxResponseSize,
               method,
               timeout
             })
@@ -302,7 +368,20 @@ async function httpRequestAttempt(url, options) {
           return;
         }
         const chunks = [];
+        let totalBytes = 0;
         res.on("data", (chunk) => {
+          totalBytes += chunk.length;
+          if (maxResponseSize && totalBytes > maxResponseSize) {
+            res.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)`
+            );
+            emitResponse({ error: err });
+            reject(err);
+            return;
+          }
           chunks.push(chunk);
         });
         res.on("end", () => {
@@ -321,39 +400,45 @@ async function httpRequestAttempt(url, options) {
               return JSON.parse(responseBody.toString("utf8"));
             },
             ok,
+            rawResponse: res,
             status: res.statusCode || 0,
             statusText: res.statusMessage || "",
             text() {
               return responseBody.toString("utf8");
             }
           };
+          emitResponse({
+            headers: res.headers,
+            status: res.statusCode,
+            statusText: res.statusMessage
+          });
           resolve(response);
         });
         res.on("error", (error) => {
+          emitResponse({ error });
           reject(error);
         });
       }
     );
     request.on("error", (error) => {
-      const code = error.code;
-      let message = `HTTP request 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 }));
+      const message = enrichErrorMessage(
+        url,
+        method,
+        error
+      );
+      const enhanced = new Error(message, { cause: error });
+      emitResponse({ error: enhanced });
+      reject(enhanced);
     });
     request.on("timeout", () => {
       request.destroy();
-      reject(new Error(`Request timed out after ${timeout}ms`));
+      const err = 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) {
       request.write(body);
@@ -482,7 +567,9 @@ async function httpRequest(url, options) {
     ca,
     followRedirects = true,
     headers = {},
+    hooks,
     maxRedirects = 5,
+    maxResponseSize,
     method = "GET",
     retries = 0,
     retryDelay = 1e3,
@@ -496,7 +583,9 @@ async function httpRequest(url, options) {
         ca,
         followRedirects,
         headers,
+        hooks,
         maxRedirects,
+        maxResponseSize,
         method,
         timeout
       });
@@ -542,10 +631,12 @@ async function httpText(url, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  enrichErrorMessage,
   fetchChecksums,
   httpDownload,
   httpJson,
   httpRequest,
   httpText,
-  parseChecksums
+  parseChecksums,
+  readIncomingResponse
 });

package/package.json

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