@socketsecurity/lib 5.28.0 → 6.0.0

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;

package/dist/argv/flag-predicates.js

@@ -0,0 +1,118 @@
+"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 flag_predicates_exports = {};
+__export(flag_predicates_exports, {
+  getLogLevel: () => getLogLevel,
+  isAll: () => isAll,
+  isChanged: () => isChanged,
+  isCoverage: () => isCoverage,
+  isDebug: () => isDebug,
+  isDryRun: () => isDryRun,
+  isFix: () => isFix,
+  isForce: () => isForce,
+  isHelp: () => isHelp,
+  isJson: () => isJson,
+  isQuiet: () => isQuiet,
+  isStaged: () => isStaged,
+  isUpdate: () => isUpdate,
+  isVerbose: () => isVerbose,
+  isWatch: () => isWatch,
+  makeFlagPredicate: () => makeFlagPredicate
+});
+module.exports = __toCommonJS(flag_predicates_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_array = require("../primordials/array");
+const processArg = [...import_node_process.default.argv];
+function makeFlagPredicate(longFlags, shortFlags = [], keys = [longFlags[0].replace(/^--/, "")]) {
+  const argvForms = [...longFlags, ...shortFlags];
+  return function check(input) {
+    if (!input) {
+      return argvForms.some((f) => processArg.includes(f));
+    }
+    if ((0, import_array.ArrayIsArray)(input)) {
+      return argvForms.some((f) => (0, import_array.ArrayPrototypeIncludes)(input, f));
+    }
+    return keys.some((k) => !!input[k]);
+  };
+}
+const isAll = makeFlagPredicate(["--all"]);
+const isChanged = makeFlagPredicate(["--changed"]);
+const isCoverage = makeFlagPredicate(
+  ["--coverage", "--cover"],
+  [],
+  ["coverage", "cover"]
+);
+const isDebug = makeFlagPredicate(["--debug"]);
+const isDryRun = makeFlagPredicate(["--dry-run"], [], ["dry-run"]);
+const isFix = makeFlagPredicate(["--fix"]);
+const isForce = makeFlagPredicate(["--force"]);
+const isHelp = makeFlagPredicate(["--help"], ["-h"]);
+const isJson = makeFlagPredicate(["--json"]);
+const isQuiet = makeFlagPredicate(
+  ["--quiet", "--silent"],
+  [],
+  ["quiet", "silent"]
+);
+const isStaged = makeFlagPredicate(["--staged"]);
+const isUpdate = makeFlagPredicate(["--update"], ["-u"]);
+const isVerbose = makeFlagPredicate(["--verbose"]);
+const isWatch = makeFlagPredicate(["--watch"], ["-w"]);
+function getLogLevel(input) {
+  if (isQuiet(input)) {
+    return "silent";
+  }
+  if (isDebug(input)) {
+    return "debug";
+  }
+  if (isVerbose(input)) {
+    return "verbose";
+  }
+  return "info";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getLogLevel,
+  isAll,
+  isChanged,
+  isCoverage,
+  isDebug,
+  isDryRun,
+  isFix,
+  isForce,
+  isHelp,
+  isJson,
+  isQuiet,
+  isStaged,
+  isUpdate,
+  isVerbose,
+  isWatch,
+  makeFlagPredicate
+});

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

@@ -0,0 +1,123 @@
+/**
+ * @file Types + `COMMON_FLAGS` table for argv flag parsing. Split out of
+ *   `argv/flags.ts` for size hygiene. Pure values + types only; no I/O or
+ *   runtime side effects so this module stays cheap to import everywhere.
+ */
+/**
+ * Flag values object from parsed arguments.
+ */
+export interface FlagValues {
+    [key: string]: unknown;
+    quiet?: boolean;
+    silent?: boolean;
+    verbose?: boolean;
+    help?: boolean;
+    all?: boolean;
+    fix?: boolean;
+    force?: boolean;
+    'dry-run'?: boolean;
+    json?: boolean;
+    debug?: boolean;
+    watch?: boolean;
+    coverage?: boolean;
+    cover?: boolean;
+    update?: boolean;
+    staged?: boolean;
+    changed?: boolean;
+}
+/**
+ * Accepted input types for flag checking functions. Can be parsed flag values,
+ * process.argv array, or undefined (uses process.argv).
+ */
+export type FlagInput = FlagValues | string[] | readonly string[] | undefined;
+/**
+ * Common flag definitions for parseArgs configuration. Can be spread into
+ * parseArgs options for consistency.
+ */
+export declare const COMMON_FLAGS: {
+    all: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    changed: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    coverage: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    cover: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    debug: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    'dry-run': {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    fix: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    force: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    help: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    json: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    quiet: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    silent: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    staged: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    update: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    verbose: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    watch: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+};