@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/ipc/_internal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Private internals for `ipc/*` modules — lazy node:fs / node:path
+ *   accessors, the IpcStub schema, and the shared platform check. Used by every
+ *   public IPC entrypoint.
+ */
+/**
+ * IPC stub file schema - validates the structure of stub files. Stub files are
+ * used for passing data between processes via filesystem.
+ */
+export declare const IpcStubSchema: import("@sinclair/typebox").TObject<{
+    /**
+     * Process ID that created the stub.
+     */
+    pid: import("@sinclair/typebox").TInteger;
+    /**
+     * Creation timestamp for age validation.
+     */
+    timestamp: import("@sinclair/typebox").TNumber;
+    /**
+     * The actual data payload.
+     */
+    data: import("@sinclair/typebox").TUnknown;
+}>;
+export { getNodeFs as getFs } from '../node/fs';
+export { getNodePath as getPath } from '../node/path';

package/dist/ipc/_internal.js

@@ -0,0 +1,50 @@
+"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 internal_exports = {};
+__export(internal_exports, {
+  IpcStubSchema: () => IpcStubSchema,
+  getFs: () => import_fs.getNodeFs,
+  getPath: () => import_path.getNodePath
+});
+module.exports = __toCommonJS(internal_exports);
+var import_typebox = require("../external/@sinclair/typebox");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+const IpcStubSchema = import_typebox.Type.Object({
+  /**
+   * Process ID that created the stub.
+   */
+  pid: import_typebox.Type.Integer({ minimum: 1 }),
+  /**
+   * Creation timestamp for age validation.
+   */
+  timestamp: import_typebox.Type.Number({ exclusiveMinimum: 0 }),
+  /**
+   * The actual data payload.
+   */
+  data: import_typebox.Type.Unknown()
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IpcStubSchema,
+  getFs,
+  getPath
+});

package/dist/ipc/directory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Stub-directory creation + permission audit. The IPC directory is
+ *   created with 0o700 so other users can't read or plant files; on POSIX we
+ *   also verify ownership and permission bits before any write, since a
+ *   pre-existing directory could belong to a different user or have permissive
+ *   modes inherited from umask.
+ */
+/**
+ * Ensure IPC directory exists for stub file creation. Uses restrictive (0o700)
+ * permissions so other users cannot read or write stub files. On POSIX, after
+ * `mkdir` we verify the directory is owned by the current user and not
+ * world/group-writable — protects against a prior local attacker pre-creating
+ * `.socket-ipc/<app>/` with permissive modes and planting symlinks for stub
+ * filenames. Throws if the directory fails the check.
+ *
+ * @internal
+ */
+export declare function ensureIpcDirectory(filePath: string): Promise<void>;

package/dist/ipc/directory.js

@@ -0,0 +1,66 @@
+"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 directory_exports = {};
+__export(directory_exports, {
+  ensureIpcDirectory: () => ensureIpcDirectory
+});
+module.exports = __toCommonJS(directory_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_error = require("../primordials/error");
+var import_internal = require("./_internal");
+async function ensureIpcDirectory(filePath) {
+  const fs = (0, import_internal.getFs)();
+  const path = (0, import_internal.getPath)();
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true, mode: 448 });
+  if (import_node_process.default.platform === "win32") {
+    return;
+  }
+  const stats = await fs.promises.lstat(dir);
+  if (!stats.isDirectory()) {
+    throw new import_error.ErrorCtor(`IPC path is not a directory: ${dir}`);
+  }
+  const getuid = import_node_process.default.getuid;
+  const ownUid = typeof getuid === "function" ? getuid.call(import_node_process.default) : -1;
+  if (ownUid !== -1 && stats.uid !== ownUid) {
+    throw new import_error.ErrorCtor(
+      `IPC directory ${dir} is owned by another user (uid ${stats.uid}); refusing to use it.`
+    );
+  }
+  const mode = stats.mode & 511;
+  if ((mode & 63) !== 0) {
+    await fs.promises.chmod(dir, 448);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ensureIpcDirectory
+});

package/dist/ipc/paths.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file IPC stub path resolution. The on-disk layout is
+ *   `<tmpDir>/.socket-ipc/<appName>/stub-<pid>.json`, computed here once so
+ *   writers and readers agree on where stubs land.
+ */
+/**
+ * Get the IPC stub path for a given application.
+ *
+ * Generates a unique file path for IPC stub files that are used to pass data
+ * between processes. The stub files are stored in a hidden directory within the
+ * system's temporary folder.
+ *
+ * ## Path Structure:
+ *
+ * - Base: System temp directory (e.g., /tmp on Unix, %TEMP% on Windows)
+ * - Directory: `.socket-ipc/{appName}/`
+ * - Filename: `stub-{pid}.json`
+ *
+ * ## Security Features:
+ *
+ * - Files are isolated per application via appName parameter
+ * - Process ID in filename prevents collisions between concurrent processes
+ * - Temporary directory location ensures automatic cleanup on system restart
+ *
+ * @example
+ *   ;```typescript
+ *   const stubPath = getIpcStubPath('socket-cli')
+ *   // Returns: '/tmp/.socket-ipc/socket-cli/stub-12345.json' (Unix)
+ *   // Returns: 'C:\\Users\\Name\\AppData\\Local\\Temp\\.socket-ipc\\socket-cli\\stub-12345.json' (Windows)
+ *   ```
+ *
+ * @param appName - The application identifier (e.g., 'socket-cli',
+ *   'socket-dlx')
+ *
+ * @returns Full path to the IPC stub file
+ */
+export declare function getIpcStubPath(appName: string): string;

package/dist/ipc/paths.js

@@ -0,0 +1,48 @@
+"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 paths_exports = {};
+__export(paths_exports, {
+  getIpcStubPath: () => getIpcStubPath
+});
+module.exports = __toCommonJS(paths_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_socket = require("../paths/socket");
+var import_internal = require("./_internal");
+function getIpcStubPath(appName) {
+  const tempDir = (0, import_socket.getOsTmpDir)();
+  const path = (0, import_internal.getPath)();
+  const stubDir = path.join(tempDir, ".socket-ipc", appName);
+  return path.join(stubDir, `stub-${import_node_process.default.pid}.json`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getIpcStubPath
+});

package/dist/ipc/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Public type surface for `ipc/*` modules — the `IpcStub` shape that
+ *   backs the file-based handoff. Pure types, no runtime side effects.
+ */
+/**
+ * IPC stub file interface. Represents the structure of stub files used for
+ * filesystem-based IPC.
+ */
+export interface IpcStub {
+    /**
+     * The actual data payload.
+     */
+    data: unknown;
+    /**
+     * Process ID that created the stub.
+     */
+    pid: number;
+    /**
+     * Creation timestamp for age validation.
+     */
+    timestamp: number;
+}

package/dist/ipc/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/ipc/write.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Atomic stub write — `O_CREAT|O_WRONLY|O_EXCL| O_NOFOLLOW` so we refuse
+ *   to overwrite a pre-existing stub (collision with attacker-planted file or
+ *   PID reuse) and refuse to follow symlinks at the final path component. One
+ *   retry on EEXIST after `safeDelete` to handle the legitimate stale-stub case
+ *   where the previous owner exited ungracefully.
+ */
+/**
+ * Write IPC data to a stub file for inter-process data transfer.
+ *
+ * Creates a stub file containing data that needs to be passed between
+ * processes. The file is written with 0o600 permissions so only the invoking
+ * user can read it.
+ *
+ * ## File Structure:
+ *
+ * ```json
+ * {
+ *   "pid": 12345,
+ *   "timestamp": 1699564234567,
+ *   "data": { ... }
+ * }
+ * ```
+ *
+ * @example
+ *   ;```typescript
+ *   const stubPath = await writeIpcStub('socket-cli', {
+ *   apiToken: 'secret-token',
+ *   config: { ... }
+ *   })
+ *   // Pass stubPath to child process for reading
+ *   ```
+ *
+ * @param appName - The application identifier.
+ * @param data - The data to write to the stub file.
+ *
+ * @returns Promise resolving to the stub file path
+ */
+export declare function writeIpcStub(appName: string, data: unknown): Promise<string>;

package/dist/ipc/write.js

@@ -0,0 +1,77 @@
+"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 write_exports = {};
+__export(write_exports, {
+  writeIpcStub: () => writeIpcStub
+});
+module.exports = __toCommonJS(write_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_safe = require("../fs/safe");
+var import_parse = require("../schema/parse");
+var import_date = require("../primordials/date");
+var import_json = require("../primordials/json");
+var import_internal = require("./_internal");
+var import_directory = require("./directory");
+var import_paths = require("./paths");
+async function writeIpcStub(appName, data) {
+  const stubPath = (0, import_paths.getIpcStubPath)(appName);
+  await (0, import_directory.ensureIpcDirectory)(stubPath);
+  const ipcData = {
+    data,
+    pid: import_node_process.default.pid,
+    timestamp: (0, import_date.DateNow)()
+  };
+  const validated = (0, import_parse.parseSchema)(import_internal.IpcStubSchema, ipcData);
+  const fs = (0, import_internal.getFs)();
+  const flags = fs.constants.O_CREAT | fs.constants.O_WRONLY | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW;
+  let handle;
+  try {
+    handle = await fs.promises.open(stubPath, flags, 384);
+  } catch (e) {
+    const err = e;
+    if (err.code === "EEXIST") {
+      await (0, import_safe.safeDelete)(stubPath);
+      handle = await fs.promises.open(stubPath, flags, 384);
+    } else {
+      throw err;
+    }
+  }
+  try {
+    await handle.writeFile((0, import_json.JSONStringify)(validated, void 0, 2), "utf8");
+  } finally {
+    await handle.close();
+  }
+  return stubPath;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  writeIpcStub
+});

package/dist/ipc-cli/get.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Socket CLI child-process IPC object getter. Lazily builds an
+ *   `IpcObject` from `SOCKET_CLI_*` environment variables so child processes
+ *   can read flags and tokens forwarded by the parent Socket CLI without
+ *   re-parsing `process.env` each call. Complements the filesystem stub IPC in
+ *   `@socketsecurity/lib/ipc` (`getIpcStubPath`, `writeIpcStub`) for cases
+ *   where data exceeds env-var size limits.
+ */
+import type { IpcObject } from './types';
+/**
+ * Get IPC data forwarded by a parent Socket CLI via `SOCKET_CLI_*` env vars.
+ * Call without arguments to receive the full frozen `IpcObject`, or pass a key
+ * to read a single field. The object is lazily built and cached; keys that
+ * weren't set in the environment are returned as `undefined`.
+ *
+ * @param key - Optional `IpcObject` field name to read.
+ *
+ * @returns The full `IpcObject` or the value at `key` (possibly `undefined`).
+ */
+export declare function getIpc(): Promise<IpcObject>;
+export declare function getIpc<K extends keyof IpcObject>(key: K): Promise<IpcObject[K]>;

package/dist/{ipc-cli.js → ipc-cli/get.js}

@@ -18,12 +18,12 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var ipc_cli_exports = {};
-__export(ipc_cli_exports, {
+var get_exports = {};
+__export(get_exports, {
   getIpc: () => getIpc
 });
-module.exports = __toCommonJS(ipc_cli_exports);
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(get_exports);
+var import_object = require("../primordials/object");
 let _ipcObject;
 async function getIpc(key) {
   if (_ipcObject === void 0) {
@@ -50,7 +50,7 @@ async function getIpc(key) {
     if (env["SOCKET_CLI_SHADOW_SILENT"]) {
       _ipcObject.SOCKET_CLI_SHADOW_SILENT = env["SOCKET_CLI_SHADOW_SILENT"] === "true" || env["SOCKET_CLI_SHADOW_SILENT"] === "1";
     }
-    (0, import_primordials.ObjectFreeze)(_ipcObject);
+    (0, import_object.ObjectFreeze)(_ipcObject);
   }
   return key ? _ipcObject[key] : _ipcObject;
 }

package/dist/ipc-cli/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Public type surface for `ipc-cli/*` modules — the `IpcObject` record
+ *   describing the `SOCKET_CLI_*` env-var shape forwarded from a parent Socket
+ *   CLI to a child process. Pure types, no runtime side effects.
+ */
+export interface IpcObject {
+    SOCKET_CLI_FIX?: string | undefined;
+    SOCKET_CLI_OPTIMIZE?: boolean | undefined;
+    SOCKET_CLI_SHADOW_ACCEPT_RISKS?: boolean | undefined;
+    SOCKET_CLI_SHADOW_API_TOKEN?: string | undefined;
+    SOCKET_CLI_SHADOW_BIN?: string | undefined;
+    SOCKET_CLI_SHADOW_PROGRESS?: boolean | undefined;
+    SOCKET_CLI_SHADOW_SILENT?: boolean | undefined;
+}

package/dist/ipc-cli/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/json/edit.d.ts

@@ -1,18 +1,32 @@
 /**
- * @fileoverview Editable JSON file manipulation with formatting preservation.
+ * @file Editable JSON file manipulation with formatting preservation.
  */
 import type { EditableJsonConstructor } from './types';
 /**
  * Get the EditableJson class for JSON file manipulation.
  *
  * @example
- * ```ts
- * import { getEditableJsonClass } from '@socketsecurity/lib/json/edit'
+ *   ;```ts
+ *   import { getEditableJsonClass } from '@socketsecurity/lib/json/edit'
  *
- * const EditableJson = getEditableJsonClass<MyConfigType>()
- * const config = await EditableJson.load('./config.json')
- * config.update({ someField: 'newValue' })
- * await config.save({ sort: true })
- * ```
+ *   const EditableJson = getEditableJsonClass<MyConfigType>()
+ *   const config = await EditableJson.load('./config.json')
+ *   config.update({ someField: 'newValue' })
+ *   await config.save({ sort: true })
+ *   ```
  */
 export declare function getEditableJsonClass<T = Record<string, unknown>>(): EditableJsonConstructor<T>;
+/**
+ * Read file content from disk with retry logic for ENOENT errors.
+ *
+ * @private
+ */
+export declare function readFile(filepath: string): Promise<string>;
+/**
+ * Retry a file write operation with exponential backoff on Windows EPERM
+ * errors. Windows can have transient file locking issues with temp
+ * directories.
+ *
+ * @private
+ */
+export declare function retryWrite(filepath: string, content: string, retries?: number, baseDelay?: number): Promise<void>;