@socketsecurity/lib 5.18.2 → 5.19.0

package/dist/ipc.d.ts

@@ -1,56 +1,9 @@
-import { z } from './zod';
-// Define BufferEncoding type for TypeScript compatibility.
-type BufferEncoding = globalThis.BufferEncoding;
 /**
- * IPC handshake schema - used for initial connection establishment.
- * The handshake includes version info and authentication tokens.
- * @internal Exported for testing purposes.
+ * @fileoverview Secure inter-process communication utilities for Socket CLI.
+ * File-based stub handoff (restricted-perm temp files with unique IDs and
+ * timestamps) for transferring data between processes that exceeds the size
+ * or exposure limits of environment variables.
  */
-export declare const IpcHandshakeSchema: z.ZodObject<{
-    id: z.ZodString;
-    timestamp: z.ZodNumber;
-    type: z.ZodLiteral<"handshake">;
-    data: z.ZodObject<{
-        version: z.ZodString;
-        pid: z.ZodNumber;
-        apiToken: z.ZodOptional<z.ZodString>;
-        appName: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-/**
- * TypeScript interfaces for IPC communication.
- * These types ensure type consistency across the IPC module.
- */
-/**
- * Base IPC message interface.
- * All IPC messages must conform to this structure.
- */
-export interface IpcMessage<T = unknown> {
-    /** Unique identifier for message tracking and response correlation. */
-    id: string;
-    /** Unix timestamp for freshness validation and replay prevention. */
-    timestamp: number;
-    /** Message type identifier for routing and handling. */
-    type: string;
-    /** Payload data - can be any JSON-serializable value. */
-    data: T;
-}
-/**
- * IPC handshake message interface.
- * Used for initial connection establishment.
- */
-export interface IpcHandshake extends IpcMessage<{
-    /** Protocol version for compatibility checking. */
-    version: string;
-    /** Process ID for identification. */
-    pid: number;
-    /** Optional API token for authentication. */
-    apiToken?: string;
-    /** Application name for multi-app support. */
-    appName: string;
-}> {
-    type: 'handshake';
-}
 /**
  * IPC stub file interface.
  * Represents the structure of stub files used for filesystem-based IPC.
@@ -63,38 +16,11 @@ export interface IpcStub {
     /** Creation timestamp for age validation. */
     timestamp: number;
 }
-/**
- * Options for IPC communication
- */
-export interface IpcOptions {
-    /** Text encoding for message serialization. */
-    encoding?: BufferEncoding;
-    /** Timeout in milliseconds for async operations. */
-    timeout?: number;
-}
-/**
- * Create a unique IPC channel identifier for message correlation.
- *
- * Generates a unique identifier that combines:
- * - A prefix for namespacing (defaults to 'socket')
- * - The current process ID for process identification
- * - A random hex string for uniqueness
- *
- * @param prefix - Optional prefix to namespace the channel ID
- * @returns A unique channel identifier string
- *
- * @example
- * ```typescript
- * const channelId = createIpcChannelId('socket-cli')
- * // Returns: 'socket-cli-12345-a1b2c3d4e5f6g7h8'
- * ```
- */
-export declare function createIpcChannelId(prefix?: string): string;
 /**
  * Get the IPC stub path for a given application.
  *
- * This function 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
+ * 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:
@@ -116,16 +42,14 @@ export declare function createIpcChannelId(prefix?: string): string;
  * // 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)
  * ```
- *
- * @used Currently used by socket-cli for self-update and inter-process communication
  */
 export declare function getIpcStubPath(appName: string): string;
 /**
  * Write IPC data to a stub file for inter-process data transfer.
  *
- * This function creates a stub file containing data that needs to be passed
- * between processes. The stub file includes metadata like process ID and
- * timestamp for validation.
+ * 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
@@ -136,11 +60,6 @@ export declare function getIpcStubPath(appName: string): string;
  * }
  * ```
  *
- * ## Use Cases:
- * - Passing API tokens to child processes
- * - Transferring configuration between Socket CLI components
- * - Sharing large data that exceeds environment variable limits
- *
  * @param appName - The application identifier
  * @param data - The data to write to the stub file
  * @returns Promise resolving to the stub file path
@@ -155,212 +74,3 @@ export declare function getIpcStubPath(appName: string): string;
  * ```
  */
 export declare function writeIpcStub(appName: string, data: unknown): Promise<string>;
-/**
- * Read IPC data from a stub file with automatic cleanup.
- *
- * This function reads data from an IPC stub file and validates its freshness.
- * Stale files (older than 5 minutes) are automatically cleaned up to prevent
- * accumulation of temporary files.
- *
- * ## Validation Steps:
- * 1. Read and parse JSON file
- * 2. Validate structure with Zod schema
- * 3. Check timestamp freshness
- * 4. Clean up if stale
- * 5. Return data if valid
- *
- * @param stubPath - Path to the stub file to read
- * @returns Promise resolving to the data or null if invalid/stale
- *
- * @example
- * ```typescript
- * const data = await readIpcStub('/tmp/.socket-ipc/socket-cli/stub-12345.json')
- * if (data) {
- *   console.log('Received:', data)
- * }
- * ```
- *
- * @unused Reserved for future implementation
- */
-export declare function readIpcStub(stubPath: string): Promise<unknown>;
-/**
- * Clean up IPC stub files for an application.
- *
- * This maintenance function removes stale IPC stub files to prevent
- * accumulation in the temporary directory. It's designed to be called
- * periodically or on application startup.
- *
- * ## Cleanup Rules:
- * - Files older than 5 minutes are removed (checked via both filesystem mtime and JSON timestamp)
- * - Only stub files (stub-*.json) are processed
- * - Errors are silently ignored (best-effort cleanup)
- *
- * @param appName - The application identifier
- * @returns Promise that resolves when cleanup is complete
- *
- * @example
- * ```typescript
- * // Clean up on application startup
- * await cleanupIpcStubs('socket-cli')
- * ```
- *
- * @unused Reserved for future implementation
- */
-export declare function cleanupIpcStubs(appName: string): Promise<void>;
-/**
- * Send data through Node.js IPC channel.
- *
- * This function sends structured messages through the Node.js IPC channel
- * when available. The IPC channel must be established with stdio: ['pipe', 'pipe', 'pipe', 'ipc'].
- *
- * ## Requirements:
- * - Process must have been spawned with IPC channel enabled
- * - Message must be serializable to JSON
- * - Process.send() must be available
- *
- * @param process - The process object with IPC channel
- * @param message - The IPC message to send
- * @returns true if message was sent, false otherwise
- *
- * @example
- * ```typescript
- * const message = createIpcMessage('handshake', { version: '1.0.0' })
- * const sent = sendIpc(childProcess, message)
- * ```
- *
- * @unused Reserved for bidirectional communication implementation
- */
-export declare function sendIpc(process: NodeJS.Process | unknown, message: IpcMessage): boolean;
-/**
- * Receive data through Node.js IPC channel.
- *
- * Sets up a listener for IPC messages with automatic validation and parsing.
- * Returns a cleanup function to remove the listener when no longer needed.
- *
- * ## Message Flow:
- * 1. Receive raw message from IPC channel
- * 2. Validate with parseIpcMessage
- * 3. Call handler if valid
- * 4. Ignore invalid messages
- *
- * @param handler - Function to call with valid IPC messages
- * @returns Cleanup function to remove the listener
- *
- * @example
- * ```typescript
- * const cleanup = onIpc((message) => {
- *   console.log('Received:', message.type, message.data)
- * })
- * // Later...
- * cleanup() // Remove listener
- * ```
- *
- * @unused Reserved for bidirectional communication
- */
-export declare function onIpc(handler: (message: IpcMessage) => void): () => void;
-/**
- * Create a promise that resolves when a specific IPC message is received.
- *
- * This utility function provides async/await support for IPC communication,
- * allowing you to wait for specific message types with timeout support.
- *
- * ## Features:
- * - Automatic timeout handling
- * - Type-safe message data
- * - Resource cleanup on completion
- * - Promise-based API
- *
- * @param messageType - The message type to wait for
- * @param options - Options including timeout configuration
- * @returns Promise resolving to the message data
- *
- * @example
- * ```typescript
- * try {
- *   const response = await waitForIpc<ConfigData>('config-response', {
- *     timeout: 5000 // 5 seconds
- *   })
- *   console.log('Config received:', response)
- * } catch (error) {
- *   console.error('Timeout waiting for config')
- * }
- * ```
- *
- * @unused Reserved for request-response pattern implementation
- */
-export declare function waitForIpc<T = unknown>(messageType: string, options?: IpcOptions): Promise<T>;
-/**
- * Create an IPC message with proper structure and metadata.
- *
- * This factory function creates properly structured IPC messages with:
- * - Unique ID for tracking
- * - Timestamp for freshness
- * - Type for routing
- * - Data payload
- *
- * @param type - The message type identifier
- * @param data - The message payload
- * @returns A properly structured IPC message
- *
- * @example
- * ```typescript
- * const handshake = createIpcMessage('handshake', {
- *   version: '1.0.0',
- *   pid: process.pid,
- *   appName: 'socket-cli'
- * })
- * ```
- *
- * @unused Reserved for future message creation needs
- */
-export declare function createIpcMessage<T = unknown>(type: string, data: T): IpcMessage<T>;
-/**
- * Check if process has IPC channel available.
- *
- * This utility checks whether a process object has the necessary
- * properties for IPC communication. Used to determine if IPC
- * messaging is possible before attempting to send.
- *
- * @param process - The process object to check
- * @returns true if IPC is available, false otherwise
- *
- * @example
- * ```typescript
- * if (hasIpcChannel(childProcess)) {
- *   sendIpc(childProcess, message)
- * } else {
- *   // Fall back to alternative communication method
- * }
- * ```
- *
- * @unused Reserved for IPC availability detection
- */
-export declare function hasIpcChannel(process: unknown): boolean;
-/**
- * Safely parse and validate IPC messages.
- *
- * This function performs runtime validation of incoming messages
- * to ensure they conform to the IPC message structure. It uses
- * Zod schemas for robust validation.
- *
- * ## Validation Steps:
- * 1. Check if message is an object
- * 2. Validate required fields exist
- * 3. Validate field types
- * 4. Return typed message or null
- *
- * @param message - The raw message to parse
- * @returns Parsed IPC message or null if invalid
- *
- * @example
- * ```typescript
- * const parsed = parseIpcMessage(rawMessage)
- * if (parsed) {
- *   handleMessage(parsed)
- * }
- * ```
- *
- * @unused Reserved for message validation needs
- */
-export declare function parseIpcMessage(message: unknown): IpcMessage | null;
-export {};

package/dist/ipc.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -29,95 +30,49 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var ipc_exports = {};
 __export(ipc_exports, {
-  IpcHandshakeSchema: () => IpcHandshakeSchema,
-  cleanupIpcStubs: () => cleanupIpcStubs,
-  createIpcChannelId: () => createIpcChannelId,
-  createIpcMessage: () => createIpcMessage,
   getIpcStubPath: () => getIpcStubPath,
-  hasIpcChannel: () => hasIpcChannel,
-  onIpc: () => onIpc,
-  parseIpcMessage: () => parseIpcMessage,
-  readIpcStub: () => readIpcStub,
-  sendIpc: () => sendIpc,
-  waitForIpc: () => waitForIpc,
   writeIpcStub: () => writeIpcStub
 });
 module.exports = __toCommonJS(ipc_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_fs = require("./fs");
 var import_socket = require("./paths/socket");
 var import_zod = require("./zod");
-let _crypto;
-// @__NO_SIDE_EFFECTS__
-function getCrypto() {
-  if (_crypto === void 0) {
-    _crypto = require("crypto");
-  }
-  return _crypto;
-}
+const IpcStubSchema = import_zod.z.object({
+  /** Process ID that created the stub. */
+  pid: import_zod.z.number().int().positive(),
+  /** Creation timestamp for age validation. */
+  timestamp: import_zod.z.number().positive(),
+  /** The actual data payload. */
+  data: import_zod.z.unknown()
+});
 let _fs;
+let _path;
+async function ensureIpcDirectory(filePath) {
+  const fs = /* @__PURE__ */ getFs();
+  const path = /* @__PURE__ */ getPath();
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true, mode: 448 });
+}
 // @__NO_SIDE_EFFECTS__
 function getFs() {
   if (_fs === void 0) {
-    _fs = require("fs");
+    _fs = require("node:fs");
   }
   return _fs;
 }
-let _path;
 // @__NO_SIDE_EFFECTS__
 function getPath() {
   if (_path === void 0) {
-    _path = require("path");
+    _path = require("node:path");
   }
   return _path;
 }
-const IpcMessageSchema = import_zod.z.object({
-  /** Unique identifier for message tracking and response correlation. */
-  id: import_zod.z.string().min(1),
-  /** Unix timestamp for freshness validation and replay prevention. */
-  timestamp: import_zod.z.number().positive(),
-  /** Message type identifier for routing and handling. */
-  type: import_zod.z.string().min(1),
-  /** Payload data - can be any JSON-serializable value. */
-  data: import_zod.z.unknown()
-});
-const IpcHandshakeSchema = IpcMessageSchema.extend({
-  type: import_zod.z.literal("handshake"),
-  data: import_zod.z.object({
-    /** Protocol version for compatibility checking. */
-    version: import_zod.z.string(),
-    /** Process ID for identification. */
-    pid: import_zod.z.number().int().positive(),
-    /** Optional API token for authentication. */
-    apiToken: import_zod.z.string().optional(),
-    /** Application name for multi-app support. */
-    appName: import_zod.z.string()
-  })
-});
-const IpcStubSchema = import_zod.z.object({
-  /** Process ID that created the stub. */
-  pid: import_zod.z.number().int().positive(),
-  /** Creation timestamp for age validation. */
-  timestamp: import_zod.z.number().positive(),
-  /** The actual data payload. */
-  data: import_zod.z.unknown()
-});
-function createIpcChannelId(prefix = "socket") {
-  const crypto = /* @__PURE__ */ getCrypto();
-  return `${prefix}-${import_node_process.default.pid}-${crypto.randomBytes(8).toString("hex")}`;
-}
 function getIpcStubPath(appName) {
   const tempDir = (0, import_socket.getOsTmpDir)();
   const path = /* @__PURE__ */ getPath();
   const stubDir = path.join(tempDir, ".socket-ipc", appName);
   return path.join(stubDir, `stub-${import_node_process.default.pid}.json`);
 }
-async function ensureIpcDirectory(filePath) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
-  const dir = path.dirname(filePath);
-  await fs.promises.mkdir(dir, { recursive: true, mode: 448 });
-}
 async function writeIpcStub(appName, data) {
   const stubPath = getIpcStubPath(appName);
   await ensureIpcDirectory(stubPath);
@@ -134,149 +89,8 @@ async function writeIpcStub(appName, data) {
   });
   return stubPath;
 }
-async function readIpcStub(stubPath) {
-  try {
-    const fs = /* @__PURE__ */ getFs();
-    const content = await fs.promises.readFile(stubPath, "utf8");
-    const parsed = JSON.parse(content);
-    const validated = IpcStubSchema.parse(parsed);
-    const ageMs = Date.now() - validated.timestamp;
-    const maxAgeMs = 5 * 60 * 1e3;
-    if (ageMs > maxAgeMs) {
-      try {
-        (0, import_fs.safeDeleteSync)(stubPath, { force: true });
-      } catch {
-      }
-      return null;
-    }
-    return validated.data;
-  } catch {
-    return null;
-  }
-}
-async function cleanupIpcStubs(appName) {
-  const tempDir = (0, import_socket.getOsTmpDir)();
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
-  const stubDir = path.join(tempDir, ".socket-ipc", appName);
-  try {
-    const files = await fs.promises.readdir(stubDir);
-    const now = Date.now();
-    const maxAgeMs = 5 * 60 * 1e3;
-    await Promise.allSettled(
-      files.map(async (file) => {
-        if (file.startsWith("stub-") && file.endsWith(".json")) {
-          const filePath = path.join(stubDir, file);
-          try {
-            const stats = await fs.promises.stat(filePath);
-            const mtimeAge = now - stats.mtimeMs;
-            let isStale = mtimeAge > maxAgeMs;
-            try {
-              const content = await fs.promises.readFile(filePath, "utf8");
-              const parsed = JSON.parse(content);
-              const validated = IpcStubSchema.parse(parsed);
-              const contentAge = now - validated.timestamp;
-              isStale = isStale || contentAge > maxAgeMs;
-            } catch {
-              isStale = true;
-            }
-            if (isStale) {
-              (0, import_fs.safeDeleteSync)(filePath, { force: true });
-            }
-          } catch {
-          }
-        }
-      })
-    );
-  } catch {
-  }
-}
-function sendIpc(process2, message) {
-  if (process2 && typeof process2 === "object" && "send" in process2 && typeof process2.send === "function") {
-    try {
-      const validated = IpcMessageSchema.parse(message);
-      return process2.send(validated);
-    } catch {
-      return false;
-    }
-  }
-  return false;
-}
-function onIpc(handler) {
-  const listener = (message) => {
-    const parsed = parseIpcMessage(message);
-    if (parsed) {
-      handler(parsed);
-    }
-  };
-  import_node_process.default.on("message", listener);
-  return () => {
-    import_node_process.default.off("message", listener);
-  };
-}
-function waitForIpc(messageType, options = {}) {
-  const { timeout = 3e4 } = options;
-  return new Promise((resolve, reject) => {
-    let cleanup = null;
-    let timeoutId = null;
-    const handleTimeout = () => {
-      if (cleanup) {
-        cleanup();
-      }
-      reject(new Error(`IPC timeout waiting for message type: ${messageType}`));
-    };
-    const handleMessage = (message) => {
-      if (message.type === messageType) {
-        if (timeoutId) {
-          clearTimeout(timeoutId);
-        }
-        if (cleanup) {
-          cleanup();
-        }
-        resolve(message.data);
-      }
-    };
-    cleanup = onIpc(handleMessage);
-    if (timeout > 0) {
-      timeoutId = setTimeout(handleTimeout, timeout);
-      timeoutId.unref();
-    }
-  });
-}
-function createIpcMessage(type, data) {
-  const crypto = /* @__PURE__ */ getCrypto();
-  return {
-    id: crypto.randomBytes(16).toString("hex"),
-    timestamp: Date.now(),
-    type,
-    data
-  };
-}
-function hasIpcChannel(process2) {
-  return Boolean(
-    process2 && typeof process2 === "object" && "send" in process2 && typeof process2.send === "function" && "channel" in process2 && process2.channel !== void 0
-  );
-}
-function parseIpcMessage(message) {
-  try {
-    const validated = IpcMessageSchema.parse(message);
-    return validated;
-  } catch {
-    return null;
-  }
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  IpcHandshakeSchema,
-  cleanupIpcStubs,
-  createIpcChannelId,
-  createIpcMessage,
   getIpcStubPath,
-  hasIpcChannel,
-  onIpc,
-  parseIpcMessage,
-  readIpcStub,
-  sendIpc,
-  waitForIpc,
   writeIpcStub
 });

package/dist/json/edit.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Editable JSON file manipulation with formatting preservation.
+ */
 import type { EditableJsonConstructor } from './types';
 /**
  * Get the EditableJson class for JSON file manipulation.
@@ -12,5 +15,4 @@ import type { EditableJsonConstructor } from './types';
  * await config.save({ sort: true })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getEditableJsonClass<T = Record<string, unknown>>(): EditableJsonConstructor<T>;