@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/spawn.d.ts

@@ -1,454 +0,0 @@
-/**
- * @fileoverview Child process spawning utilities with cross-platform support.
- * Provides enhanced spawn functionality with stdio handling and error management.
- *
- * SECURITY: Array-Based Arguments Prevent Command Injection
- *
- * This module uses array-based arguments for all command execution, which is the
- * PRIMARY DEFENSE against command injection attacks. When you pass arguments as
- * an array to spawn():
- *
- *   spawn('npx', ['sfw', tool, ...args], { shell: true })
- *
- * Node.js handles escaping automatically. Each argument is passed directly to the
- * OS without shell interpretation. Shell metacharacters like ; | & $ ( ) ` are
- * treated as LITERAL STRINGS, not as commands. This approach is secure even when
- * shell: true is used on Windows for .cmd/.bat file resolution.
- *
- * UNSAFE ALTERNATIVE (not used in this codebase):
- *   spawn(`npx sfw ${tool} ${args.join(' ')}`, { shell: true })  // ✖ VULNERABLE
- *
- * String concatenation allows injection. For example, if tool = "foo; rm -rf /",
- * the shell would execute both commands. Array-based arguments prevent this.
- *
- * References:
- * - https://nodejs.org/api/child_process.html#child_processspawncommand-args-options
- * - https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html
- */
-import type { SendHandle, Serializable, StdioOptions } from 'node:child_process';
-import type { EventEmitter } from 'node:events';
-type BufferEncoding = globalThis.BufferEncoding;
-/**
- * Options for spawning a child process with promise-based completion.
- *
- * @property {string | undefined} cwd - Current working directory for the process
- * @property {NodeJS.ProcessEnv | undefined} env - Environment variables for the process
- * @property {number | undefined} gid - Group identity of the process (POSIX only)
- * @property {boolean | string | undefined} shell - Whether to run command in shell, or path to shell
- * @property {AbortSignal | undefined} signal - Signal to abort the process
- * @property {StdioType | undefined} stdio - Stdio configuration (`'pipe'`, `'ignore'`, `'inherit'`, or array)
- * @property {boolean | undefined} stdioString - Convert stdio output to strings (default: `true`)
- * @property {number | undefined} timeout - Maximum time in milliseconds before killing the process
- * @property {number | undefined} uid - User identity of the process (POSIX only)
- * @property {boolean | undefined} windowsVerbatimArguments - Don't quote or escape arguments on Windows (requires shell: true). Use when you need exact argument control. Default: false
- */
-export type PromiseSpawnOptions = {
-    cwd?: string | undefined;
-    env?: NodeJS.ProcessEnv | undefined;
-    gid?: number | undefined;
-    shell?: boolean | string | undefined;
-    signal?: AbortSignal | undefined;
-    stdio?: StdioType | undefined;
-    stdioString?: boolean | undefined;
-    timeout?: number | undefined;
-    uid?: number | undefined;
-    windowsVerbatimArguments?: boolean | undefined;
-};
-/**
- * Result returned by {@link spawn} when the child process completes.
- * This is a Promise that resolves with process exit information and output,
- * with additional properties for accessing the running process and stdin stream.
- *
- * @property {ChildProcess} process - The running child process instance
- * @property {WritableStreamType | null} stdin - Writable stream for process stdin, or `null` if not piped
- *
- * @example
- * const result = spawn('echo', ['hello'])
- * result.stdin?.write('additional input\n')
- * const { code, stdout } = await result
- * console.log(stdout) // 'hello'
- */
-export type PromiseSpawnResult = Promise<{
-    cmd: string;
-    args: string[] | readonly string[];
-    code: number;
-    signal: NodeJS.Signals | null;
-    stdout: string | Buffer;
-    stderr: string | Buffer;
-}> & {
-    process: ChildProcess;
-    stdin: WritableStreamType | null;
-};
-/**
- * Error object thrown when a spawned process fails.
- * Extends the standard Error with process-specific information including exit code,
- * signal, command details, and captured output.
- *
- * @property {string[]} args - Arguments passed to the command
- * @property {string} cmd - Command that was executed
- * @property {number} code - Process exit code
- * @property {string} name - Error name (typically `'Error'`)
- * @property {string} message - Error message describing the failure
- * @property {NodeJS.Signals | null} signal - Signal that terminated the process, if any
- * @property {string} stack - Stack trace of the error
- * @property {string | Buffer} stderr - Standard error output from the process
- * @property {string | Buffer} stdout - Standard output from the process
- *
- * @example
- * try {
- *   await spawn('exit', ['1'])
- * } catch (e) {
- *   if (isSpawnError(e)) {
- *     console.error(`Command failed with code ${e.code}`)
- *     console.error(`stderr: ${e.stderr}`)
- *   }
- * }
- */
-export type SpawnError = {
-    args: string[];
-    cmd: string;
-    code: number;
-    name: string;
-    message: string;
-    signal: NodeJS.Signals | null;
-    stack: string;
-    stderr: string | Buffer;
-    stdout: string | Buffer;
-};
-/**
- * Spawn error variant where stdout and stderr are guaranteed to be strings.
- * This type is used when `stdioString: true` is set in spawn options.
- *
- * @property {string} stdout - Standard output as a string
- * @property {string} stderr - Standard error as a string
- */
-export type SpawnErrorWithOutputString = SpawnError & {
-    stdout: string;
-    stderr: string;
-};
-/**
- * Spawn error variant where stdout and stderr are guaranteed to be Buffers.
- * This type is used when `stdioString: false` is set in spawn options.
- *
- * @property {Buffer} stdout - Standard output as a Buffer
- * @property {Buffer} stderr - Standard error as a Buffer
- */
-export type SpawnErrorWithOutputBuffer = SpawnError & {
-    stdout: Buffer;
-    stderr: Buffer;
-};
-/**
- * Extra options passed to the underlying promise-spawn implementation.
- * This is an open-ended object for passing additional metadata or configuration.
- */
-export type SpawnExtra = Record<string, unknown>;
-/**
- * Valid values for individual stdio streams.
- * - `'pipe'` - Creates a pipe between child and parent (default)
- * - `'ignore'` - Ignores the stream
- * - `'inherit'` - Uses parent's stream
- * - `'overlapped'` - Windows-specific overlapped I/O
- */
-export type IOType = 'pipe' | 'ignore' | 'inherit' | 'overlapped';
-/**
- * Configuration for process stdio (stdin, stdout, stderr) streams.
- * Can be a single value applied to all streams, or an array specifying each stream individually.
- * - `'ipc'` - Creates an IPC channel for communication with the parent
- *
- * @example
- * // All streams piped
- * stdio: 'pipe'
- *
- * @example
- * // Custom configuration per stream: [stdin, stdout, stderr]
- * stdio: ['ignore', 'pipe', 'pipe']
- */
-export type StdioType = IOType | 'ipc' | Array<IOType | 'ipc'>;
-/**
- * Result object returned by {@link spawnSync} when the child process completes synchronously.
- *
- * @template T - Type of stdout/stderr (string or Buffer)
- * @property {number} pid - Process ID of the spawned child
- * @property {Array<T | null>} output - Array containing stdout/stderr values
- * @property {T} stdout - Standard output from the process
- * @property {T} stderr - Standard error from the process
- * @property {number | null} status - Exit code, or `null` if killed by signal
- * @property {NodeJS.Signals | null} signal - Signal that terminated the process, or `null`
- * @property {Error | undefined} error - Error object if the spawn failed
- */
-export interface SpawnSyncReturns<T> {
-    pid: number;
-    output: Array<T | null>;
-    stdout: T;
-    stderr: T;
-    status: number | null;
-    signal: NodeJS.Signals | null;
-    error?: Error | undefined;
-}
-interface NodeSpawnOptions {
-    cwd?: string | URL | undefined;
-    env?: NodeJS.ProcessEnv | undefined;
-    argv0?: string | undefined;
-    stdio?: StdioOptions | undefined;
-    detached?: boolean | undefined;
-    uid?: number | undefined;
-    gid?: number | undefined;
-    serialization?: 'json' | 'advanced' | undefined;
-    shell?: boolean | string | undefined;
-    windowsVerbatimArguments?: boolean | undefined;
-    windowsHide?: boolean | undefined;
-    signal?: AbortSignal | undefined;
-    timeout?: number | undefined;
-    killSignal?: NodeJS.Signals | number | undefined;
-}
-interface ChildProcess extends EventEmitter {
-    stdin: NodeJS.WritableStream | null;
-    stdout: NodeJS.ReadableStream | null;
-    stderr: NodeJS.ReadableStream | null;
-    readonly channel?: unknown;
-    readonly stdio: [
-        NodeJS.WritableStream | null,
-        NodeJS.ReadableStream | null,
-        NodeJS.ReadableStream | null,
-        NodeJS.ReadableStream | NodeJS.WritableStream | null | undefined,
-        NodeJS.ReadableStream | NodeJS.WritableStream | null | undefined
-    ];
-    readonly killed: boolean;
-    readonly pid?: number | undefined;
-    readonly connected: boolean;
-    readonly exitCode: number | null;
-    readonly signalCode: NodeJS.Signals | null;
-    readonly spawnargs: string[];
-    readonly spawnfile: string;
-    kill(signal?: NodeJS.Signals | number): boolean;
-    send(message: Serializable, callback?: (error: Error | null) => void): boolean;
-    send(message: Serializable, sendHandle?: SendHandle | undefined, callback?: (error: Error | null) => void): boolean;
-    send(message: Serializable, sendHandle?: SendHandle | undefined, options?: {
-        keepOpen?: boolean | undefined;
-    } | undefined, callback?: (error: Error | null) => void): boolean;
-    disconnect(): void;
-    unref(): void;
-    ref(): void;
-}
-interface WritableStreamType {
-    writable: boolean;
-    writableEnded: boolean;
-    writableFinished: boolean;
-    writableHighWaterMark: number;
-    writableLength: number;
-    writableObjectMode: boolean;
-    writableCorked: number;
-    destroyed: boolean;
-    write(chunk: unknown, encoding?: BufferEncoding | undefined, callback?: (error?: Error | null) => void): boolean;
-    write(chunk: unknown, callback?: (error?: Error | null) => void): boolean;
-    end(cb?: () => void): this;
-    end(chunk: unknown, cb?: () => void): this;
-    end(chunk: unknown, encoding?: BufferEncoding | undefined, cb?: () => void): this;
-    cork(): void;
-    uncork(): void;
-    destroy(error?: Error | undefined): this;
-}
-/**
- * Options for spawning a child process with {@link spawn}.
- * Extends Node.js spawn options with additional Socket-specific functionality.
- *
- * @property {string | URL | undefined} cwd - Current working directory
- * @property {NodeJS.ProcessEnv | undefined} env - Environment variables
- * @property {number | undefined} gid - Group identity (POSIX)
- * @property {boolean | string | undefined} shell - Run command in shell
- * @property {AbortSignal | undefined} signal - Abort signal
- * @property {import('./spinner').Spinner | undefined} spinner - Spinner instance to pause during execution
- * @property {StdioType | undefined} stdio - Stdio configuration
- * @property {boolean | undefined} stdioString - Convert output to strings (default: `true`)
- * @property {boolean | undefined} stripAnsi - Remove ANSI codes from output (default: `true`)
- * @property {number | undefined} timeout - Timeout in milliseconds
- * @property {number | undefined} uid - User identity (POSIX)
- * @property {boolean | undefined} windowsVerbatimArguments - Don't quote or escape arguments on Windows (requires shell: true). Use when you need exact argument control. Default: false
- */
-export type SpawnOptions = import('./objects').Remap<NodeSpawnOptions & {
-    spinner?: import('./spinner').Spinner | undefined;
-    stdioString?: boolean;
-    stripAnsi?: boolean;
-}>;
-export type SpawnResult = PromiseSpawnResult;
-/**
- * Result object returned when a spawned process completes.
- *
- * @property {string} cmd - Command that was executed
- * @property {string[] | readonly string[]} args - Arguments passed to the command
- * @property {number} code - Process exit code
- * @property {NodeJS.Signals | null} signal - Signal that terminated the process, if any
- * @property {string | Buffer} stdout - Standard output (string if `stdioString: true`, Buffer otherwise)
- * @property {string | Buffer} stderr - Standard error (string if `stdioString: true`, Buffer otherwise)
- */
-export type SpawnStdioResult = {
-    cmd: string;
-    args: string[] | readonly string[];
-    code: number;
-    signal: NodeJS.Signals | null;
-    stdout: string | Buffer;
-    stderr: string | Buffer;
-};
-/**
- * Options for synchronously spawning a child process with {@link spawnSync}.
- * Same as {@link SpawnOptions} but excludes the `spinner` property (not applicable for synchronous execution).
- */
-export type SpawnSyncOptions = Omit<SpawnOptions, 'spinner'>;
-/**
- * Enhances spawn error with better context.
- * Converts generic "command failed" to detailed error with command, exit code, and stderr.
- *
- * @example
- * ```typescript
- * try {
- *   await spawn('git', ['status'])
- * } catch (e) {
- *   throw enhanceSpawnError(e)
- * }
- * ```
- */
-export declare function enhanceSpawnError(error: unknown): unknown;
-/**
- * Check if a value is a spawn error with expected error properties.
- * Tests for common error properties from child process failures.
- *
- * @param {unknown} value - Value to check
- * @returns {boolean} `true` if the value has spawn error properties
- *
- * @example
- * try {
- *   await spawn('nonexistent-command')
- * } catch (e) {
- *   if (isSpawnError(e)) {
- *     console.error(`Spawn failed: ${e.code}`)
- *   }
- * }
- */
-export declare function isSpawnError(value: unknown): value is SpawnError;
-/**
- * Check if stdio configuration matches a specific type.
- * When called with one argument, validates if it's a valid stdio type.
- * When called with two arguments, checks if the stdio config matches the specified type.
- *
- * @param {string | string[]} stdio - Stdio configuration to check
- * @param {StdioType | undefined} type - Expected stdio type (optional)
- * @returns {boolean} `true` if stdio matches the type or is valid
- *
- * @example
- * // Check if valid stdio type
- * isStdioType('pipe') // true
- * isStdioType('invalid') // false
- *
- * @example
- * // Check if stdio matches specific type
- * isStdioType('pipe', 'pipe') // true
- * isStdioType(['pipe', 'pipe', 'pipe'], 'pipe') // true
- * isStdioType('ignore', 'pipe') // false
- */
-export declare function isStdioType(stdio: string | string[], type?: StdioType | undefined): boolean;
-/**
- * Spawn a child process and return a promise that resolves when it completes.
- * Provides enhanced error handling, output capture, and cross-platform support.
- *
- * SECURITY: This function uses array-based arguments which prevent command injection.
- * Arguments in the `args` array are passed directly to the OS without shell
- * interpretation. Shell metacharacters (;|&$()`) are treated as literal strings,
- * not as commands or operators. This is the PRIMARY SECURITY DEFENSE.
- *
- * Even when shell: true is used (on Windows for .cmd/.bat execution), the array-based
- * approach remains secure because Node.js properly escapes each argument before passing
- * to the shell.
- *
- * @param {string} cmd - Command to execute (not user-controlled)
- * @param {string[] | readonly string[] | undefined} args - Array of arguments (safe even with user input)
- * @param {SpawnOptions | undefined} options - Spawn options for process configuration
- * @param {SpawnExtra | undefined} extra - Extra options for promise-spawn
- * @returns {SpawnResult} Promise that resolves with process exit information
- *
- * @throws {SpawnError} When the process exits with non-zero code or is terminated by signal
- *
- * @example
- * // Basic usage - spawn and wait for completion
- * const result = await spawn('git', ['status'])
- * console.log(result.stdout)
- *
- * @example
- * // With options - set working directory and environment
- * const result = await spawn('npm', ['install'], {
- *   cwd: '/path/to/project',
- *   env: { NODE_ENV: 'production' }
- * })
- *
- * @example
- * // ✔ DO THIS - Array-based arguments (safe)
- * spawn('git', ['commit', '-m', userMessage])
- * // Each argument is properly escaped, even if userMessage = "foo; rm -rf /"
- *
- * @example
- * // ✖ NEVER DO THIS - String concatenation (vulnerable)
- * spawn(`git commit -m "${userMessage}"`, { shell: true })
- * // Vulnerable to injection if userMessage = '"; rm -rf / #'
- *
- * @example
- * // Access stdin for interactive processes
- * const result = spawn('cat', [])
- * result.stdin?.write('Hello\n')
- * result.stdin?.end()
- * const { stdout } = await result
- * console.log(stdout) // 'Hello'
- *
- * @example
- * // Handle errors with exit codes
- * try {
- *   await spawn('exit', ['1'])
- * } catch (e) {
- *   if (isSpawnError(e)) {
- *     console.error(`Failed with code ${e.code}`)
- *     console.error(e.stderr)
- *   }
- * }
- */
-export declare function spawn(cmd: string, args?: string[] | readonly string[], options?: SpawnOptions | undefined, extra?: SpawnExtra | undefined): SpawnResult;
-/**
- * Synchronously spawn a child process and wait for it to complete.
- * Blocks execution until the process exits, returning all output and exit information.
- *
- * WARNING: This function blocks the event loop. Use {@link spawn} for async operations.
- *
- * @param {string} cmd - Command to execute
- * @param {string[] | readonly string[] | undefined} args - Array of arguments
- * @param {SpawnSyncOptions | undefined} options - Spawn options for process configuration
- * @returns {SpawnSyncReturns<string | Buffer>} Process result with exit code and captured output
- *
- * @example
- * // Basic synchronous spawn
- * const result = spawnSync('git', ['status'])
- * console.log(result.stdout)
- * console.log(result.status) // exit code
- *
- * @example
- * // With options
- * const result = spawnSync('npm', ['install'], {
- *   cwd: '/path/to/project',
- *   stdioString: true
- * })
- * if (result.status !== 0) {
- *   console.error(result.stderr)
- * }
- *
- * @example
- * // Get raw buffer output
- * const result = spawnSync('cat', ['binary-file'], {
- *   stdioString: false
- * })
- * console.log(result.stdout) // Buffer
- *
- * @example
- * // Handle process errors
- * const result = spawnSync('nonexistent-command')
- * if (result.error) {
- *   console.error('Failed to spawn:', result.error)
- * }
- */
-export declare function spawnSync(cmd: string, args?: string[] | readonly string[], options?: SpawnSyncOptions | undefined): SpawnSyncReturns<string | Buffer>;
-export {};