@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/fs/read-json.js

@@ -0,0 +1,192 @@
+"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 read_json_exports = {};
+__export(read_json_exports, {
+  clearReadJsonCache: () => import_read_json_cache.clearReadJsonCache,
+  getReadJsonCacheStats: () => import_read_json_cache.getReadJsonCacheStats,
+  readJson: () => readJson,
+  readJsonSync: () => readJsonSync,
+  setReadJsonCacheMax: () => import_read_json_cache.setReadJsonCacheMax,
+  setReadJsonCacheTtlMs: () => import_read_json_cache.setReadJsonCacheTtlMs
+});
+module.exports = __toCommonJS(read_json_exports);
+var import_read_json_cache = require("./read-json-cache");
+var import_parse = require("../json/parse");
+var import_fs = require("../node/fs");
+var import_error = require("../primordials/error");
+var import_number = require("../primordials/number");
+// @__NO_SIDE_EFFECTS__
+async function readJson(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const { cache, reviver, throws, ...fsOptions } = {
+    __proto__: null,
+    ...opts
+  };
+  const shouldThrow = throws === void 0 || !!throws;
+  const cacheEnabled = cache !== false && reviver === void 0;
+  const fs = (0, import_fs.getNodeFs)();
+  const pathStr = String(filepath);
+  if (cacheEnabled) {
+    try {
+      const stat = await fs.promises.stat(filepath);
+      const cached = (0, import_read_json_cache.getCachedJson)(
+        pathStr,
+        (0, import_number.NumberCtor)(stat.ino),
+        (0, import_number.NumberCtor)(stat.size),
+        (0, import_number.NumberCtor)(stat.mtimeMs)
+      );
+      if (cached !== void 0) {
+        return cached;
+      }
+    } catch {
+    }
+  }
+  let content = "";
+  try {
+    content = await fs.promises.readFile(filepath, {
+      __proto__: null,
+      ...fsOptions,
+      encoding: "utf8"
+    });
+  } catch (e) {
+    if (shouldThrow) {
+      const code = e.code;
+      if (code === "ENOENT") {
+        throw new import_error.ErrorCtor(
+          `JSON file not found: ${filepath}
+Ensure the file exists or create it with the expected structure.`,
+          { cause: e }
+        );
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw new import_error.ErrorCtor(
+          `Permission denied reading JSON file: ${filepath}
+Check file permissions or run with appropriate access.`,
+          { cause: e }
+        );
+      }
+      throw e;
+    }
+    return void 0;
+  }
+  const parsed = (0, import_parse.parseJson)(content, {
+    filepath: pathStr,
+    reviver,
+    throws: shouldThrow
+  });
+  if (cacheEnabled && parsed !== void 0) {
+    try {
+      const stat = await fs.promises.stat(filepath);
+      (0, import_read_json_cache.setCachedJson)(
+        pathStr,
+        (0, import_number.NumberCtor)(stat.ino),
+        (0, import_number.NumberCtor)(stat.size),
+        (0, import_number.NumberCtor)(stat.mtimeMs),
+        parsed
+      );
+    } catch {
+    }
+  }
+  return parsed;
+}
+// @__NO_SIDE_EFFECTS__
+function readJsonSync(filepath, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const { cache, reviver, throws, ...fsOptions } = {
+    __proto__: null,
+    ...opts
+  };
+  const shouldThrow = throws === void 0 || !!throws;
+  const cacheEnabled = cache !== false && reviver === void 0;
+  const fs = (0, import_fs.getNodeFs)();
+  const pathStr = String(filepath);
+  if (cacheEnabled) {
+    try {
+      const stat = fs.statSync(filepath);
+      const cached = (0, import_read_json_cache.getCachedJson)(
+        pathStr,
+        (0, import_number.NumberCtor)(stat.ino),
+        (0, import_number.NumberCtor)(stat.size),
+        (0, import_number.NumberCtor)(stat.mtimeMs)
+      );
+      if (cached !== void 0) {
+        return cached;
+      }
+    } catch {
+    }
+  }
+  let content = "";
+  try {
+    content = fs.readFileSync(filepath, {
+      __proto__: null,
+      ...fsOptions,
+      encoding: "utf8"
+    });
+  } catch (e) {
+    if (shouldThrow) {
+      const code = e.code;
+      if (code === "ENOENT") {
+        throw new import_error.ErrorCtor(
+          `JSON file not found: ${filepath}
+Ensure the file exists or create it with the expected structure.`,
+          { cause: e }
+        );
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw new import_error.ErrorCtor(
+          `Permission denied reading JSON file: ${filepath}
+Check file permissions or run with appropriate access.`,
+          { cause: e }
+        );
+      }
+      throw e;
+    }
+    return void 0;
+  }
+  const parsed = (0, import_parse.parseJson)(content, {
+    filepath: pathStr,
+    reviver,
+    throws: shouldThrow
+  });
+  if (cacheEnabled && parsed !== void 0) {
+    try {
+      const stat = fs.statSync(filepath);
+      (0, import_read_json_cache.setCachedJson)(
+        pathStr,
+        (0, import_number.NumberCtor)(stat.ino),
+        (0, import_number.NumberCtor)(stat.size),
+        (0, import_number.NumberCtor)(stat.mtimeMs),
+        parsed
+      );
+    } catch {
+    }
+  }
+  return parsed;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearReadJsonCache,
+  getReadJsonCacheStats,
+  readJson,
+  readJsonSync,
+  setReadJsonCacheMax,
+  setReadJsonCacheTtlMs
+});

package/dist/fs/safe.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @file Safe deletion + idempotent directory creation. The delete helpers gate
+ *   destructive operations behind an "allowed directories" allow-list (temp
+ *   dir, cacache dir, ~/.socket); paths outside those need an explicit `force:
+ *   true`. The mkdir helpers default to `recursive: true` and swallow `EEXIST`
+ *   so concurrent callers don't race-condition each other.
+ */
+import './path-cache';
+import type { MakeDirectoryOptions, PathLike } from 'node:fs';
+import type { deleteAsync as deleteAsyncType, deleteSync as deleteSyncType } from '../external/del';
+import type { RemoveOptions } from './types';
+export declare function getDel(): {
+    deleteAsync: typeof deleteAsyncType;
+    deleteSync: typeof deleteSyncType;
+};
+/**
+ * Safely delete a file or directory asynchronously with built-in protections.
+ *
+ * Uses [`del`](https://socket.dev/npm/package/del/overview/8.0.1) for safer
+ * deletion with these safety features:
+ *
+ * - By default, prevents deleting the current working directory (cwd) and above
+ * - Allows deleting within cwd (descendant paths) without force option
+ * - Automatically uses force: true for temp directory, cacache, and ~/.socket
+ *   subdirectories
+ * - Protects against accidental deletion of parent directories via `../` paths
+ *
+ * @example
+ *   ;```ts
+ *   // Delete files within cwd (safe by default)
+ *   await safeDelete('./build')
+ *   await safeDelete('./dist')
+ *
+ *   // Delete with glob patterns
+ *   await safeDelete(['./temp/**', '!./temp/keep.txt'])
+ *
+ *   // Delete with custom retry settings
+ *   await safeDelete('./flaky-dir', { maxRetries: 5, retryDelay: 500 })
+ *
+ *   // Force delete cwd or above (requires explicit force: true)
+ *   await safeDelete('../parent-dir', { force: true })
+ *   ```
+ *
+ * @param filepath - Path or array of paths to delete (supports glob patterns)
+ * @param options - Deletion options including force, retries, and recursion.
+ * @param options.force - Set to true to allow deleting cwd and above (use with
+ *   caution)
+ *
+ * @throws {Error} When attempting to delete protected paths without force
+ *   option.
+ */
+export declare function safeDelete(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): Promise<void>;
+/**
+ * Safely delete a file or directory synchronously with built-in protections.
+ *
+ * Uses [`del`](https://socket.dev/npm/package/del/overview/8.0.1) for safer
+ * deletion with these safety features:
+ *
+ * - By default, prevents deleting the current working directory (cwd) and above
+ * - Allows deleting within cwd (descendant paths) without force option
+ * - Automatically uses force: true for temp directory, cacache, and ~/.socket
+ *   subdirectories
+ * - Protects against accidental deletion of parent directories via `../` paths
+ *
+ * @example
+ *   ;```ts
+ *   // Delete files within cwd (safe by default)
+ *   safeDeleteSync('./build')
+ *   safeDeleteSync('./dist')
+ *
+ *   // Delete with glob patterns
+ *   safeDeleteSync(['./temp/**', '!./temp/keep.txt'])
+ *
+ *   // Delete multiple paths
+ *   safeDeleteSync(['./coverage', './reports'])
+ *
+ *   // Force delete cwd or above (requires explicit force: true)
+ *   safeDeleteSync('../parent-dir', { force: true })
+ *   ```
+ *
+ * @param filepath - Path or array of paths to delete (supports glob patterns)
+ * @param options - Deletion options including force, retries, and recursion.
+ * @param options.force - Set to true to allow deleting cwd and above (use with
+ *   caution)
+ *
+ * @throws {Error} When attempting to delete protected paths without force
+ *   option.
+ */
+export declare function safeDeleteSync(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): void;
+/**
+ * Safely create a directory asynchronously, ignoring EEXIST errors. This
+ * function wraps fs.promises.mkdir and handles the race condition where the
+ * directory might already exist, which is common in concurrent code.
+ *
+ * Unlike fs.promises.mkdir with recursive:true, this function: - Silently
+ * ignores EEXIST errors (directory already exists) - Re-throws all other errors
+ * (permissions, invalid path, etc.) - Works reliably in
+ * multi-process/concurrent scenarios - Defaults to recursive: true for
+ * convenient nested directory creation.
+ *
+ * @example
+ *   ;```ts
+ *   // Create a directory recursively by default, no error if it exists
+ *   await safeMkdir('./config')
+ *
+ *   // Create nested directories (recursive: true is the default)
+ *   await safeMkdir('./data/cache/temp')
+ *
+ *   // Create with specific permissions
+ *   await safeMkdir('./secure', { mode: 0o700 })
+ *
+ *   // Explicitly disable recursive behavior
+ *   await safeMkdir('./single-level', { recursive: false })
+ *   ```
+ *
+ * @param path - Directory path to create.
+ * @param options - Options including recursive (default: true) and mode
+ *   settings.
+ *
+ * @returns Promise that resolves when directory is created or already exists
+ */
+export declare function safeMkdir(path: PathLike, options?: MakeDirectoryOptions | undefined): Promise<void>;
+/**
+ * Safely create a directory synchronously, ignoring EEXIST errors. This
+ * function wraps fs.mkdirSync and handles the race condition where the
+ * directory might already exist, which is common in concurrent code.
+ *
+ * Unlike fs.mkdirSync with recursive:true, this function: - Silently ignores
+ * EEXIST errors (directory already exists) - Re-throws all other errors
+ * (permissions, invalid path, etc.) - Works reliably in
+ * multi-process/concurrent scenarios - Defaults to recursive: true for
+ * convenient nested directory creation.
+ *
+ * @example
+ *   ;```ts
+ *   // Create a directory recursively by default, no error if it exists
+ *   safeMkdirSync('./config')
+ *
+ *   // Create nested directories (recursive: true is the default)
+ *   safeMkdirSync('./data/cache/temp')
+ *
+ *   // Create with specific permissions
+ *   safeMkdirSync('./secure', { mode: 0o700 })
+ *
+ *   // Explicitly disable recursive behavior
+ *   safeMkdirSync('./single-level', { recursive: false })
+ *   ```
+ *
+ * @param path - Directory path to create.
+ * @param options - Options including recursive (default: true) and mode
+ *   settings.
+ */
+export declare function safeMkdirSync(path: PathLike, options?: MakeDirectoryOptions | undefined): void;

package/dist/fs/safe.js

@@ -0,0 +1,182 @@
+"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 safe_exports = {};
+__export(safe_exports, {
+  getDel: () => getDel,
+  safeDelete: () => safeDelete,
+  safeDeleteSync: () => safeDeleteSync,
+  safeMkdir: () => safeMkdir,
+  safeMkdirSync: () => safeMkdirSync
+});
+module.exports = __toCommonJS(safe_exports);
+var import_predicates = require("../arrays/predicates");
+var import_predicates2 = require("../errors/predicates");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_mutate = require("../objects/mutate");
+var import_normalize = require("../paths/normalize");
+var import_array = require("../primordials/array");
+var import_globals = require("../primordials/globals");
+var import_string = require("../primordials/string");
+var import_retry = require("../promises/retry");
+var import_internal = require("./_internal");
+var import_path_cache = require("./path-cache");
+const defaultRemoveOptions = (0, import_mutate.objectFreeze)({
+  __proto__: null,
+  force: true,
+  maxRetries: 3,
+  recursive: true,
+  retryDelay: 200
+});
+let _del;
+// @__NO_SIDE_EFFECTS__
+function getDel() {
+  if (_del === void 0) {
+    _del = require("../external/del");
+  }
+  return _del;
+}
+async function safeDelete(filepath, options) {
+  const opts = { __proto__: null, ...options };
+  const patterns = (0, import_predicates.isArray)(filepath) ? filepath.map(import_normalize.pathLikeToString) : [(0, import_normalize.pathLikeToString)(filepath)];
+  let shouldForce = opts.force !== false;
+  if (!shouldForce && patterns.length > 0) {
+    const path = (0, import_path.getNodePath)();
+    const allowedDirs = (0, import_internal.getAllowedDirectories)();
+    const allInAllowedDirs = patterns.every((pattern) => {
+      const resolvedPath = path.resolve(pattern);
+      for (const allowedDir of allowedDirs) {
+        const isInAllowedDir = (0, import_string.StringPrototypeStartsWith)(resolvedPath, allowedDir + path.sep) || resolvedPath === allowedDir;
+        const relativePath = path.relative(allowedDir, resolvedPath);
+        const isGoingBackward = (0, import_string.StringPrototypeStartsWith)(relativePath, "..");
+        if (isInAllowedDir && !isGoingBackward) {
+          return true;
+        }
+      }
+      return false;
+    });
+    if (allInAllowedDirs) {
+      shouldForce = true;
+    }
+  }
+  const maxRetries = opts.maxRetries ?? defaultRemoveOptions.maxRetries;
+  const retryDelay = opts.retryDelay ?? defaultRemoveOptions.retryDelay;
+  const del = /* @__PURE__ */ getDel();
+  await (0, import_retry.pRetry)(
+    async () => {
+      await del.deleteAsync(patterns, {
+        dryRun: false,
+        force: shouldForce,
+        onlyFiles: false
+      });
+    },
+    {
+      retries: maxRetries,
+      baseDelayMs: retryDelay,
+      backoffFactor: 2,
+      signal: opts.signal
+    }
+  );
+}
+function safeDeleteSync(filepath, options) {
+  const opts = { __proto__: null, ...options };
+  const patterns = (0, import_predicates.isArray)(filepath) ? filepath.map(import_normalize.pathLikeToString) : [(0, import_normalize.pathLikeToString)(filepath)];
+  let shouldForce = opts.force !== false;
+  if (!shouldForce && patterns.length > 0) {
+    const path = (0, import_path.getNodePath)();
+    const allowedDirs = (0, import_internal.getAllowedDirectories)();
+    const allInAllowedDirs = patterns.every((pattern) => {
+      const resolvedPath = path.resolve(pattern);
+      for (const allowedDir of allowedDirs) {
+        const isInAllowedDir = (0, import_string.StringPrototypeStartsWith)(resolvedPath, allowedDir + path.sep) || resolvedPath === allowedDir;
+        const relativePath = path.relative(allowedDir, resolvedPath);
+        const isGoingBackward = (0, import_string.StringPrototypeStartsWith)(relativePath, "..");
+        if (isInAllowedDir && !isGoingBackward) {
+          return true;
+        }
+      }
+      return false;
+    });
+    if (allInAllowedDirs) {
+      shouldForce = true;
+    }
+  }
+  const maxRetries = opts.maxRetries ?? defaultRemoveOptions.maxRetries;
+  const retryDelay = opts.retryDelay ?? defaultRemoveOptions.retryDelay;
+  const del = /* @__PURE__ */ getDel();
+  let lastError;
+  let delay = retryDelay;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      del.deleteSync(patterns, {
+        dryRun: false,
+        force: shouldForce,
+        onlyFiles: false
+      });
+      return;
+    } catch (e) {
+      lastError = e;
+      if (attempt < maxRetries) {
+        const waitMs = delay;
+        (0, import_array.AtomicsWait)(
+          new import_array.Int32ArrayCtor(new import_globals.SharedArrayBufferCtor(4)),
+          0,
+          0,
+          waitMs
+        );
+        delay *= 2;
+      }
+    }
+  }
+  if (lastError) {
+    throw lastError;
+  }
+}
+async function safeMkdir(path, options) {
+  const fs = (0, import_fs.getNodeFs)();
+  const opts = { __proto__: null, recursive: true, ...options };
+  try {
+    await fs.promises.mkdir(path, opts);
+  } catch (e) {
+    if (!(0, import_predicates2.isErrnoException)(e) || e.code !== "EEXIST") {
+      throw e;
+    }
+  }
+}
+function safeMkdirSync(path, options) {
+  const fs = (0, import_fs.getNodeFs)();
+  const opts = { __proto__: null, recursive: true, ...options };
+  try {
+    fs.mkdirSync(path, opts);
+  } catch (e) {
+    if (!(0, import_predicates2.isErrnoException)(e) || e.code !== "EEXIST") {
+      throw e;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getDel,
+  safeDelete,
+  safeDeleteSync,
+  safeMkdir,
+  safeMkdirSync
+});