@socketsecurity/lib 5.14.0 → 5.16.0

package/dist/external/tar-fs.js

@@ -547,9 +547,9 @@ var require_text_decoder = __commonJS({
   }
 });
 
-// node_modules/.pnpm/streamx@2.23.0/node_modules/streamx/index.js
+// node_modules/.pnpm/streamx@2.25.0/node_modules/streamx/index.js
 var require_streamx = __commonJS({
-  "node_modules/.pnpm/streamx@2.23.0/node_modules/streamx/index.js"(exports2, module2) {
+  "node_modules/.pnpm/streamx@2.25.0/node_modules/streamx/index.js"(exports2, module2) {
     var { EventEmitter } = require_default();
     var STREAM_DESTROYED = new Error("Stream was destroyed");
     var PREMATURE_CLOSE = new Error("Premature close");
@@ -660,6 +660,9 @@ var require_streamx = __commonJS({
         this.afterWrite = afterWrite.bind(this);
         this.afterUpdateNextTick = updateWriteNT.bind(this);
       }
+      get ending() {
+        return (this.stream._duplexState & WRITE_FINISHING) !== 0;
+      }
       get ended() {
         return (this.stream._duplexState & WRITE_DONE) !== 0;
       }
@@ -761,6 +764,9 @@ var require_streamx = __commonJS({
         this.afterRead = afterRead.bind(this);
         this.afterUpdateNextTick = updateReadNT.bind(this);
       }
+      get ending() {
+        return (this.stream._duplexState & READ_ENDING) !== 0;
+      }
       get ended() {
         return (this.stream._duplexState & READ_DONE) !== 0;
       }
@@ -825,7 +831,8 @@ var require_streamx = __commonJS({
         const stream = this.stream;
         if ((stream._duplexState & READ_STATUS) === READ_QUEUED) {
           const data = this.shift();
-          if (this.pipeTo !== null && this.pipeTo.write(data) === false) stream._duplexState &= READ_PIPE_NOT_DRAINED;
+          if (this.pipeTo !== null && this.pipeTo.write(data) === false)
+            stream._duplexState &= READ_PIPE_NOT_DRAINED;
           if ((stream._duplexState & READ_EMIT_DATA) !== 0) stream.emit("data", data);
           return data;
         }
@@ -839,7 +846,8 @@ var require_streamx = __commonJS({
         const stream = this.stream;
         while ((stream._duplexState & READ_STATUS) === READ_QUEUED && (stream._duplexState & READ_FLOWING) !== 0) {
           const data = this.shift();
-          if (this.pipeTo !== null && this.pipeTo.write(data) === false) stream._duplexState &= READ_PIPE_NOT_DRAINED;
+          if (this.pipeTo !== null && this.pipeTo.write(data) === false)
+            stream._duplexState &= READ_PIPE_NOT_DRAINED;
           if ((stream._duplexState & READ_EMIT_DATA) !== 0) stream.emit("data", data);
         }
       }
@@ -1001,7 +1009,8 @@ var require_streamx = __commonJS({
     function afterRead(err) {
       if (err) this.stream.destroy(err);
       this.stream._duplexState &= READ_NOT_ACTIVE;
-      if (this.readAhead === false && (this.stream._duplexState & READ_RESUMED) === 0) this.stream._duplexState &= READ_NO_READ_AHEAD;
+      if (this.readAhead === false && (this.stream._duplexState & READ_RESUMED) === 0)
+        this.stream._duplexState &= READ_NO_READ_AHEAD;
       this.updateCallback();
     }
     __name(afterRead, "afterRead");
@@ -1265,7 +1274,8 @@ var require_streamx = __commonJS({
         function ondata(data) {
           if (promiseReject === null) return;
           if (error) promiseReject(error);
-          else if (data === null && (stream._duplexState & READ_DONE) === 0) promiseReject(STREAM_DESTROYED);
+          else if (data === null && (stream._duplexState & READ_DONE) === 0)
+            promiseReject(STREAM_DESTROYED);
           else promiseResolve({ value: data, done: data === null });
           promiseReject = promiseResolve = null;
         }
@@ -1512,10 +1522,18 @@ var require_streamx = __commonJS({
       return typeof stream._duplexState === "number" && isStream(stream);
     }
     __name(isStreamx, "isStreamx");
+    function isEnding(stream) {
+      return !!stream._readableState && stream._readableState.ending;
+    }
+    __name(isEnding, "isEnding");
     function isEnded(stream) {
       return !!stream._readableState && stream._readableState.ended;
     }
     __name(isEnded, "isEnded");
+    function isFinishing(stream) {
+      return !!stream._writableState && stream._writableState.ending;
+    }
+    __name(isFinishing, "isFinishing");
     function isFinished(stream) {
       return !!stream._writableState && stream._writableState.ended;
     }
@@ -1530,7 +1548,7 @@ var require_streamx = __commonJS({
     }
     __name(isReadStreamx, "isReadStreamx");
     function isDisturbed(stream) {
-      return (stream._duplexState & OPENING) !== OPENING || (stream._duplexState & ACTIVE_OR_TICKING) !== 0;
+      return (stream._duplexState & OPENING) !== OPENING || (stream._duplexState & DESTROYING) === DESTROYING || (stream._duplexState & ACTIVE_OR_TICKING) !== 0;
     }
     __name(isDisturbed, "isDisturbed");
     function isTypedArray(data) {
@@ -1557,7 +1575,9 @@ var require_streamx = __commonJS({
       pipelinePromise,
       isStream,
       isStreamx,
+      isEnding,
       isEnded,
+      isFinishing,
       isFinished,
       isDisturbed,
       getStreamError,

package/dist/fs.d.ts

@@ -283,6 +283,12 @@ export declare function findUpSync(name: string | string[] | readonly string[],
  * Called automatically by the paths/rewire module when paths are overridden in tests.
  *
  * @internal Used for test rewiring
+ *
+ * @example
+ * ```typescript
+ * invalidatePathCache()
+ * // Cached allowed directories are now cleared
+ * ```
  */
 export declare function invalidatePathCache(): void;
 /**
@@ -382,6 +388,13 @@ export declare function normalizeEncoding(enc: BufferEncoding | string | null |
  *
  * @param enc - Encoding to normalize
  * @returns Normalized encoding string, defaults to 'utf8' for unknown encodings
+ *
+ * @example
+ * ```typescript
+ * normalizeEncodingSlow('ucs2')    // 'utf16le'
+ * normalizeEncodingSlow('LATIN1')  // 'latin1'
+ * normalizeEncodingSlow('binary')  // 'latin1'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function normalizeEncodingSlow(enc: string): BufferEncoding;

package/dist/functions.d.ts

@@ -7,21 +7,51 @@ export type AsyncFunction<TArgs extends unknown[], TResult> = (...args: TArgs) =
 export type AnyFunction = (...args: unknown[]) => unknown;
 /**
  * A no-op function that does nothing.
+ *
+ * @example
+ * ```typescript
+ * const callback = noop
+ * callback()  // does nothing
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function noop(): void;
 /**
  * Create a function that only executes once.
+ *
+ * @example
+ * ```typescript
+ * const init = once(() => Math.random())
+ * init()  // 0.456 (random value)
+ * init()  // 0.456 (same value, not recalculated)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function once<T extends AnyFunction>(fn: T): T;
 /**
  * Wrap an async function to silently catch and ignore errors.
+ *
+ * @example
+ * ```typescript
+ * const safeFetch = silentWrapAsync(async (url: string) => {
+ *   const res = await fetch(url)
+ *   return res.json()
+ * })
+ * await safeFetch('https://example.com')  // result or undefined on error
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function silentWrapAsync<TArgs extends unknown[], TResult>(fn: AsyncFunction<TArgs, TResult>): (...args: TArgs) => Promise<TResult | undefined>;
 /**
  * Execute a function with tail call optimization via trampoline.
+ *
+ * @example
+ * ```typescript
+ * const factorial = trampoline((n: number, acc = 1): any =>
+ *   n <= 1 ? acc : () => factorial(n - 1, n * acc)
+ * )
+ * factorial(5)  // 120
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function trampoline<T extends AnyFunction>(fn: T): T;

package/dist/globs.d.ts

@@ -32,11 +32,26 @@ export type { Pattern, FastGlobOptions };
 export declare const defaultIgnore: readonly string[];
 /**
  * Create a stream of license file paths matching glob patterns.
+ *
+ * @example
+ * ```typescript
+ * const stream = globStreamLicenses('/tmp/my-package')
+ * for await (const licensePath of stream) {
+ *   console.log(licensePath)
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function globStreamLicenses(dirname: string, options?: GlobOptions): NodeJS.ReadableStream;
 /**
  * Get a cached glob matcher function.
+ *
+ * @example
+ * ```typescript
+ * const isMatch = getGlobMatcher('*.ts')
+ * isMatch('index.ts')  // true
+ * isMatch('index.js')  // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
@@ -47,12 +62,24 @@ export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
 /**
  * Asynchronously find files matching glob patterns.
  * Wrapper around fast-glob.
+ *
+ * @example
+ * ```typescript
+ * const files = await glob('src/*.ts', { cwd: '/tmp/project' })
+ * console.log(files) // ['src/index.ts', 'src/utils.ts']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function glob(patterns: Pattern | Pattern[], options?: FastGlobOptions): Promise<string[]>;
 /**
  * Synchronously find files matching glob patterns.
  * Wrapper around fast-glob.sync.
+ *
+ * @example
+ * ```typescript
+ * const files = globSync('*.json', { cwd: '/tmp/project' })
+ * console.log(files) // ['package.json', 'tsconfig.json']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function globSync(patterns: Pattern | Pattern[], options?: FastGlobOptions): string[];

package/dist/http-request.d.ts

@@ -277,6 +277,20 @@ export interface HttpRequestOptions {
      * })
      * ```
      */
+    /**
+     * 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.
@@ -415,6 +429,13 @@ export interface HttpResponse {
  * `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.
+ *
+ * @example
+ * ```typescript
+ * const raw = await makeRawRequest('https://example.com/api')
+ * const response = await readIncomingResponse(raw)
+ * console.log(response.status, response.body.toString('utf8'))
+ * ```
  */
 export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
 /**
@@ -657,26 +678,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.
@@ -766,6 +779,15 @@ export declare function fetchChecksums(url: string, options?: FetchChecksumsOpti
 /**
  * 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 (err) {
+ *   console.error(enrichErrorMessage('https://api.example.com', 'GET', err))
+ * }
+ * ```
  */
 export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
 /**

package/dist/http-request.js

@@ -193,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) {
@@ -355,6 +281,7 @@ async function httpRequestAttempt(url, options) {
     maxRedirects = 5,
     maxResponseSize,
     method = "GET",
+    stream = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
   const startTime = Date.now();
@@ -452,11 +379,37 @@ 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) => {
@@ -533,12 +486,12 @@ async function httpRequestAttempt(url, options) {
     });
     if (body) {
       if (typeof body === "object" && typeof body.pipe === "function") {
-        const stream = body;
-        stream.on("error", (err) => {
+        const stream2 = body;
+        stream2.on("error", (err) => {
           request.destroy();
           rejectOnce(err);
         });
-        stream.pipe(request);
+        stream2.pipe(request);
         return;
       }
       request.write(body);
@@ -613,8 +566,8 @@ Computed: ${computedHash}`
       }
       await fs.promises.rename(tempPath, destPath);
       return {
-        path: destPath,
-        size: result.size
+        ...result,
+        path: destPath
       };
     } catch (e) {
       lastError = e;
@@ -676,6 +629,7 @@ async function httpRequest(url, options) {
     onRetry,
     retries = 0,
     retryDelay = 1e3,
+    stream = false,
     throwOnError = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
@@ -696,6 +650,7 @@ async function httpRequest(url, options) {
     maxRedirects,
     maxResponseSize,
     method,
+    stream,
     timeout
   };
   let lastError;

package/dist/json/format.d.ts

@@ -69,6 +69,12 @@ export declare function extractFormatting(json: string): JsonFormatting;
  * Get default formatting for JSON files.
  *
  * @returns Default formatting (2 spaces, LF line endings)
+ *
+ * @example
+ * ```typescript
+ * const fmt = getDefaultFormatting()
+ * // { indent: 2, newline: '\n' }
+ * ```
  */
 export declare function getDefaultFormatting(): JsonFormatting;
 /**
@@ -109,6 +115,12 @@ export declare function stringifyWithFormatting(content: Record<string, unknown>
  *
  * @param content - Content object with potential symbol properties
  * @returns Object with symbols removed
+ *
+ * @example
+ * ```typescript
+ * const obj = { key: "value", [Symbol.for("indent")]: 2 }
+ * stripFormattingSymbols(obj)  // { key: "value" }
+ * ```
  */
 export declare function stripFormattingSymbols(content: Record<string | symbol, unknown>): Record<string, unknown>;
 /**
@@ -116,6 +128,12 @@ export declare function stripFormattingSymbols(content: Record<string | symbol,
  *
  * @param content - Content object with Symbol.for('indent') and Symbol.for('newline')
  * @returns Formatting metadata, or defaults if symbols not present
+ *
+ * @example
+ * ```typescript
+ * const content = { [Symbol.for("indent")]: 4, [Symbol.for("newline")]: "\r\n" }
+ * getFormattingFromContent(content)  // { indent: 4, newline: "\r\n" }
+ * ```
  */
 export declare function getFormattingFromContent(content: Record<string | symbol, unknown>): JsonFormatting;
 /**

package/dist/memoization.d.ts

@@ -79,6 +79,11 @@ export declare function Memoize(options?: MemoizeOptions<unknown[], unknown>): (
 /**
  * Clear all memoization caches.
  * Useful for testing or when you need to force recomputation.
+ *
+ * @example
+ * ```typescript
+ * clearAllMemoizationCaches()
+ * ```
  */
 export declare function clearAllMemoizationCaches(): void;
 /**