@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/archives/tar.js

@@ -0,0 +1,233 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tar_exports = {};
+__export(tar_exports, {
+  extractTar: () => extractTar,
+  extractTarGz: () => extractTarGz
+});
+module.exports = __toCommonJS(tar_exports);
+var import_node_fs = require("node:fs");
+var import_node_process = __toESM(require("node:process"));
+var import_promises = require("node:stream/promises");
+var import_node_zlib = require("node:zlib");
+var import_safe = require("../fs/safe");
+var import_normalize = require("../paths/normalize");
+var import_error = require("../primordials/error");
+var import_internal = require("./_internal");
+async function extractTar(archivePath, outputDir, options = {}) {
+  (0, import_internal.assertArchiveExists)(archivePath);
+  const {
+    maxEntries = import_internal.DEFAULT_MAX_ENTRIES,
+    maxFileSize = import_internal.DEFAULT_MAX_FILE_SIZE,
+    maxTotalSize = import_internal.DEFAULT_MAX_TOTAL_SIZE,
+    strip = 0
+  } = options;
+  const normalizedOutputDir = (0, import_normalize.normalizePath)(outputDir);
+  await (0, import_safe.safeMkdir)(normalizedOutputDir);
+  let totalExtractedSize = 0;
+  let entryCount = 0;
+  let destroyScheduled = false;
+  const tarFs = (0, import_internal.getTarFs)();
+  const extractStream = tarFs.extract(normalizedOutputDir, {
+    map: (header) => {
+      if (destroyScheduled) {
+        return header;
+      }
+      entryCount += 1;
+      if (entryCount > maxEntries) {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `Archive has too many entries: exceeded limit of ${maxEntries}`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.name.includes("\0")) {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `Invalid null byte in archive entry name: ${header.name}`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.type === "symlink" || header.type === "link") {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size && header.size > maxFileSize) {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `File size exceeds limit: ${header.name} (${header.size} bytes > ${maxFileSize} bytes)`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size) {
+        totalExtractedSize += header.size;
+        if (totalExtractedSize > maxTotalSize) {
+          destroyScheduled = true;
+          import_node_process.default.nextTick(() => {
+            extractStream.destroy(
+              new import_error.ErrorCtor(
+                `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`
+              )
+            );
+          });
+          return header;
+        }
+      }
+      return header;
+    },
+    strip
+  });
+  extractStream.on("error", () => {
+  });
+  const readStream = (0, import_node_fs.createReadStream)(archivePath);
+  try {
+    await (0, import_promises.pipeline)(readStream, extractStream);
+  } catch (e) {
+    readStream.destroy();
+    throw e;
+  }
+}
+async function extractTarGz(archivePath, outputDir, options = {}) {
+  (0, import_internal.assertArchiveExists)(archivePath);
+  const {
+    maxEntries = import_internal.DEFAULT_MAX_ENTRIES,
+    maxFileSize = import_internal.DEFAULT_MAX_FILE_SIZE,
+    maxTotalSize = import_internal.DEFAULT_MAX_TOTAL_SIZE,
+    strip = 0
+  } = options;
+  const normalizedOutputDir = (0, import_normalize.normalizePath)(outputDir);
+  await (0, import_safe.safeMkdir)(normalizedOutputDir);
+  let totalExtractedSize = 0;
+  let entryCount = 0;
+  let destroyScheduled = false;
+  const tarFs = (0, import_internal.getTarFs)();
+  const extractStream = tarFs.extract(normalizedOutputDir, {
+    map: (header) => {
+      if (destroyScheduled) {
+        return header;
+      }
+      entryCount += 1;
+      if (entryCount > maxEntries) {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `Archive has too many entries: exceeded limit of ${maxEntries}`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.name.includes("\0")) {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `Invalid null byte in archive entry name: ${header.name}`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.type === "symlink" || header.type === "link") {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size && header.size > maxFileSize) {
+        destroyScheduled = true;
+        import_node_process.default.nextTick(() => {
+          extractStream.destroy(
+            new import_error.ErrorCtor(
+              `File size exceeds limit: ${header.name} (${header.size} bytes > ${maxFileSize} bytes)`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size) {
+        totalExtractedSize += header.size;
+        if (totalExtractedSize > maxTotalSize) {
+          destroyScheduled = true;
+          import_node_process.default.nextTick(() => {
+            extractStream.destroy(
+              new import_error.ErrorCtor(
+                `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`
+              )
+            );
+          });
+          return header;
+        }
+      }
+      return header;
+    },
+    strip
+  });
+  extractStream.on("error", () => {
+  });
+  const readStream = (0, import_node_fs.createReadStream)(archivePath);
+  try {
+    await (0, import_promises.pipeline)(readStream, (0, import_node_zlib.createGunzip)(), extractStream);
+  } catch (e) {
+    readStream.destroy();
+    throw e;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractTar,
+  extractTarGz
+});

package/dist/archives/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Public type surface for `archives/*` modules — the `ArchiveFormat`
+ *   union and the `ExtractOptions` security-limit record. Pure types, no
+ *   runtime side effects.
+ */
+/**
+ * Archive format type.
+ */
+export type ArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip';
+/**
+ * Options for archive extraction.
+ */
+export interface ExtractOptions {
+    /**
+     * Suppress log messages.
+     */
+    quiet?: boolean | undefined;
+    /**
+     * Strip leading path components (like tar --strip-components)
+     */
+    strip?: number | undefined;
+    /**
+     * Maximum number of entries to extract (default: 100,000)
+     */
+    maxEntries?: number | undefined;
+    /**
+     * Maximum size of a single extracted file in bytes (default: 100MB)
+     */
+    maxFileSize?: number | undefined;
+    /**
+     * Maximum total extracted size in bytes (default: 1GB)
+     */
+    maxTotalSize?: number | undefined;
+}

package/dist/archives/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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/archives/zip.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Zip extraction with security limits and path traversal validation. Uses
+ *   adm-zip under the hood; pre-validates every entry before extraction so the
+ *   disk-write phase can't be tricked into escaping the target directory.
+ */
+import type { ExtractOptions } from './types';
+/**
+ * Extract a zip archive to a directory.
+ *
+ * @example
+ *   ;```typescript
+ *   await extractZip('/tmp/archive.zip', '/tmp/output')
+ *   await extractZip('/tmp/archive.zip', '/tmp/output', { strip: 1 })
+ *   ```
+ *
+ * @param archivePath - Path to zip file.
+ * @param outputDir - Directory to extract to.
+ * @param options - Extraction options.
+ */
+export declare function extractZip(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;

package/dist/archives/zip.js

@@ -0,0 +1,124 @@
+"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 zip_exports = {};
+__export(zip_exports, {
+  extractZip: () => extractZip
+});
+module.exports = __toCommonJS(zip_exports);
+var import_safe = require("../fs/safe");
+var import_normalize = require("../paths/normalize");
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_map_set = require("../primordials/map-set");
+var import_promise = require("../primordials/promise");
+var import_internal = require("./_internal");
+async function extractZip(archivePath, outputDir, options = {}) {
+  (0, import_internal.assertArchiveExists)(archivePath);
+  const {
+    maxEntries = import_internal.DEFAULT_MAX_ENTRIES,
+    maxFileSize = import_internal.DEFAULT_MAX_FILE_SIZE,
+    maxTotalSize = import_internal.DEFAULT_MAX_TOTAL_SIZE,
+    strip = 0
+  } = options;
+  const normalizedOutputDir = (0, import_normalize.normalizePath)(outputDir);
+  await (0, import_safe.safeMkdir)(normalizedOutputDir);
+  const AdmZip = (0, import_internal.getAdmZip)();
+  const zip = new AdmZip(archivePath);
+  const path = (0, import_internal.getPath)();
+  const entries = zip.getEntries();
+  if (entries.length > maxEntries) {
+    throw new import_error.ErrorCtor(
+      `Archive has too many entries: ${entries.length} (limit: ${maxEntries})`
+    );
+  }
+  let totalExtractedSize = 0;
+  for (const entry of entries) {
+    if (entry.isDirectory) {
+      continue;
+    }
+    if (entry.entryName.includes("\0")) {
+      throw new import_error.ErrorCtor(
+        `Invalid null byte in archive entry name: ${entry.entryName}`
+      );
+    }
+    const uncompressedSize = entry.header.size;
+    if (uncompressedSize > maxFileSize) {
+      throw new import_error.ErrorCtor(
+        `File size exceeds limit: ${entry.entryName} (${uncompressedSize} bytes > ${maxFileSize} bytes)`
+      );
+    }
+    totalExtractedSize += uncompressedSize;
+    if (totalExtractedSize > maxTotalSize) {
+      throw new import_error.ErrorCtor(
+        `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`
+      );
+    }
+    const parts = entry.entryName.split("/");
+    if (parts.length <= strip) {
+      continue;
+    }
+    const strippedPath = (0, import_array.ArrayPrototypeSlice)(parts, strip).join("/");
+    const targetPath = path.join(normalizedOutputDir, strippedPath);
+    (0, import_internal.validatePathWithinBase)(targetPath, normalizedOutputDir, entry.entryName);
+  }
+  if (strip === 0) {
+    for (const entry of entries) {
+      if (!entry.isDirectory) {
+        const targetPath = path.join(normalizedOutputDir, entry.entryName);
+        (0, import_internal.validatePathWithinBase)(targetPath, normalizedOutputDir, entry.entryName);
+      }
+    }
+    zip.extractAllTo(normalizedOutputDir, true);
+  } else {
+    const path2 = (0, import_internal.getPath)();
+    const entries2 = zip.getEntries();
+    const dirsToCreate = new import_map_set.SetCtor();
+    for (const entry of entries2) {
+      if (entry.isDirectory) {
+        continue;
+      }
+      const parts = entry.entryName.split("/");
+      if (parts.length <= strip) {
+        continue;
+      }
+      const strippedPath = (0, import_array.ArrayPrototypeSlice)(parts, strip).join("/");
+      const targetPath = path2.join(normalizedOutputDir, strippedPath);
+      dirsToCreate.add(path2.dirname(targetPath));
+    }
+    await (0, import_promise.PromiseAll)((0, import_array.ArrayFrom)(dirsToCreate).map((dir) => (0, import_safe.safeMkdir)(dir)));
+    for (const entry of entries2) {
+      if (entry.isDirectory) {
+        continue;
+      }
+      const parts = entry.entryName.split("/");
+      if (parts.length <= strip) {
+        continue;
+      }
+      const strippedPath = (0, import_array.ArrayPrototypeSlice)(parts, strip).join("/");
+      const targetPath = path2.join(normalizedOutputDir, strippedPath);
+      zip.extractEntryTo(entry, path2.dirname(targetPath), false, true);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractZip
+});

package/dist/argv/flag-predicates.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @file Flag predicates — `is*` checks across parsed `FlagValues`, raw
+ *   `process.argv`, or no input. Split out of `argv/flags.ts` for size hygiene.
+ *   Every predicate follows the same 3-branch shape, so they're built via a
+ *   single `makeFlagPredicate` factory:
+ *
+ *   1. no input → consult the frozen `processArg` snapshot
+ *   2. string[] input → `Array.includes` lookup of each flag form
+ *   3. FlagValues input → boolean-coerce each key Long forms, short aliases, and
+ *      `FlagValues` keys are all configurable per predicate (e.g. `isQuiet`
+ *      accepts both `--quiet` and `--silent`).
+ */
+import type { FlagInput } from './flag-types';
+/**
+ * Build a flag predicate that accepts `FlagValues`, `string[]`, or `undefined`
+ * (in which case it consults the frozen `processArg`).
+ *
+ * @private
+ *
+ * @param longFlags - Long-form flags to match in argv arrays (e.g. `['--quiet',
+ *   '--silent']`).
+ * @param shortFlags - Short-form flags to match in argv arrays (e.g. `['-q']`).
+ * @param keys - `FlagValues` keys to coerce when given a parsed object
+ *   (defaults to the first long flag with `--` stripped).
+ */
+export declare function makeFlagPredicate(longFlags: readonly string[], shortFlags?: readonly string[], keys?: readonly string[]): (input?: FlagInput) => boolean;
+/**
+ * Check if all flag is set. Accepts FlagValues object, process.argv array, or
+ * undefined (uses process.argv).
+ *
+ * @example
+ *   ;```typescript
+ *   isAll({ all: true }) // true
+ *   isAll(['--all']) // true
+ *   ```
+ */
+export declare const isAll: (input?: FlagInput) => boolean;
+/**
+ * Check if changed files mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isChanged({ changed: true }) // true
+ *   isChanged(['--changed']) // true
+ *   ```
+ */
+export declare const isChanged: (input?: FlagInput) => boolean;
+/**
+ * Check if coverage mode is enabled. Checks both 'coverage' and 'cover' flags.
+ *
+ * @example
+ *   ;```typescript
+ *   isCoverage({ coverage: true }) // true
+ *   isCoverage(['--cover']) // true
+ *   ```
+ */
+export declare const isCoverage: (input?: FlagInput) => boolean;
+/**
+ * Check if debug mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isDebug({ debug: true }) // true
+ *   isDebug(['--debug']) // true
+ *   ```
+ */
+export declare const isDebug: (input?: FlagInput) => boolean;
+/**
+ * Check if dry-run mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isDryRun({ 'dry-run': true }) // true
+ *   isDryRun(['--dry-run']) // true
+ *   ```
+ */
+export declare const isDryRun: (input?: FlagInput) => boolean;
+/**
+ * Check if fix/autofix mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isFix({ fix: true }) // true
+ *   isFix(['--fix']) // true
+ *   ```
+ */
+export declare const isFix: (input?: FlagInput) => boolean;
+/**
+ * Check if force mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isForce({ force: true }) // true
+ *   isForce(['--force']) // true
+ *   ```
+ */
+export declare const isForce: (input?: FlagInput) => boolean;
+/**
+ * Check if help flag is set.
+ *
+ * @example
+ *   ;```typescript
+ *   isHelp({ help: true }) // true
+ *   isHelp(['-h']) // true
+ *   ```
+ */
+export declare const isHelp: (input?: FlagInput) => boolean;
+/**
+ * Check if JSON output is requested.
+ *
+ * @example
+ *   ;```typescript
+ *   isJson({ json: true }) // true
+ *   isJson(['--json']) // true
+ *   ```
+ */
+export declare const isJson: (input?: FlagInput) => boolean;
+/**
+ * Check if quiet/silent mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isQuiet({ quiet: true }) // true
+ *   isQuiet(['--silent']) // true
+ *   ```
+ */
+export declare const isQuiet: (input?: FlagInput) => boolean;
+/**
+ * Check if staged files mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isStaged({ staged: true }) // true
+ *   isStaged(['--staged']) // true
+ *   ```
+ */
+export declare const isStaged: (input?: FlagInput) => boolean;
+/**
+ * Check if update mode is enabled (for snapshots, dependencies, etc).
+ *
+ * @example
+ *   ;```typescript
+ *   isUpdate({ update: true }) // true
+ *   isUpdate(['-u']) // true
+ *   ```
+ */
+export declare const isUpdate: (input?: FlagInput) => boolean;
+/**
+ * Check if verbose mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isVerbose({ verbose: true }) // true
+ *   isVerbose(['--verbose']) // true
+ *   ```
+ */
+export declare const isVerbose: (input?: FlagInput) => boolean;
+/**
+ * Check if watch mode is enabled.
+ *
+ * @example
+ *   ;```typescript
+ *   isWatch({ watch: true }) // true
+ *   isWatch(['-w']) // true
+ *   ```
+ */
+export declare const isWatch: (input?: FlagInput) => boolean;
+/**
+ * Get the appropriate log level based on flags. Returns 'silent', 'error',
+ * 'warn', 'info', 'verbose', or 'debug'.
+ *
+ * @example
+ *   ;```typescript
+ *   getLogLevel() // 'info' (default)
+ *   getLogLevel({ quiet: true }) // 'silent'
+ *   getLogLevel(['--debug']) // 'debug'
+ *   ```
+ */
+export declare function getLogLevel(input?: FlagInput): string;