@sparkleideas/security 3.0.0-alpha.22 → 3.0.0-alpha.29

package/dist/path-validator.js

@@ -0,0 +1,421 @@
+/**
+ * Path Validator - HIGH-2 Remediation
+ *
+ * Fixes path traversal vulnerabilities by:
+ * - Validating all file paths against allowed prefixes
+ * - Using path.resolve() for canonicalization
+ * - Blocking traversal patterns (../, etc.)
+ * - Enforcing path length limits
+ *
+ * Security Properties:
+ * - Path canonicalization
+ * - Prefix validation
+ * - Symlink resolution (optional)
+ * - Traversal pattern detection
+ *
+ * @module v3/security/path-validator
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+export class PathValidatorError extends Error {
+    code;
+    path;
+    constructor(message, code, path) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.name = 'PathValidatorError';
+    }
+}
+/**
+ * Dangerous path patterns that indicate traversal attempts.
+ */
+const TRAVERSAL_PATTERNS = [
+    /\.\.\//, // ../
+    /\.\.\\/, // ..\
+    /\.\./, // .. anywhere
+    /%2e%2e/i, // URL-encoded ..
+    /%252e%252e/i, // Double URL-encoded ..
+    /\.%2e/i, // Mixed encoding
+    /%2e\./i, // Mixed encoding
+    /\0/, // Null byte
+    /%00/, // URL-encoded null
+];
+/**
+ * Default blocked file extensions (sensitive files).
+ */
+const DEFAULT_BLOCKED_EXTENSIONS = [
+    '.env',
+    '.pem',
+    '.key',
+    '.crt',
+    '.pfx',
+    '.p12',
+    '.jks',
+    '.keystore',
+    '.secret',
+    '.credentials',
+];
+/**
+ * Default blocked file names (sensitive files).
+ */
+const DEFAULT_BLOCKED_NAMES = [
+    'id_rsa',
+    'id_dsa',
+    'id_ecdsa',
+    'id_ed25519',
+    '.htpasswd',
+    '.htaccess',
+    'shadow',
+    'passwd',
+    'authorized_keys',
+    'known_hosts',
+    '.git',
+    '.gitconfig',
+    '.npmrc',
+    '.docker',
+];
+/**
+ * Path validator that prevents traversal attacks.
+ *
+ * This class validates file paths to ensure they stay within
+ * allowed directories and don't access sensitive files.
+ *
+ * @example
+ * ```typescript
+ * const validator = new PathValidator({
+ *   allowedPrefixes: ['/workspaces/project']
+ * });
+ *
+ * const result = await validator.validate('/workspaces/project/src/file.ts');
+ * if (result.isValid) {
+ *   // Safe to use result.resolvedPath
+ * }
+ * ```
+ */
+export class PathValidator {
+    config;
+    resolvedPrefixes;
+    constructor(config) {
+        this.config = {
+            allowedPrefixes: config.allowedPrefixes,
+            blockedExtensions: config.blockedExtensions ?? DEFAULT_BLOCKED_EXTENSIONS,
+            blockedNames: config.blockedNames ?? DEFAULT_BLOCKED_NAMES,
+            maxPathLength: config.maxPathLength ?? 4096,
+            resolveSymlinks: config.resolveSymlinks ?? true,
+            allowNonExistent: config.allowNonExistent ?? true,
+            allowHidden: config.allowHidden ?? false,
+        };
+        if (this.config.allowedPrefixes.length === 0) {
+            throw new PathValidatorError('At least one allowed prefix must be specified', 'EMPTY_PREFIXES');
+        }
+        // Pre-resolve all prefixes
+        this.resolvedPrefixes = this.config.allowedPrefixes.map(p => path.resolve(p));
+    }
+    /**
+     * Validates a path against security rules.
+     *
+     * @param inputPath - The path to validate
+     * @returns Validation result with resolved path
+     */
+    async validate(inputPath) {
+        const errors = [];
+        // Check for empty path
+        if (!inputPath || inputPath.trim() === '') {
+            return {
+                isValid: false,
+                resolvedPath: '',
+                relativePath: '',
+                matchedPrefix: '',
+                errors: ['Path is empty'],
+            };
+        }
+        // Check path length
+        if (inputPath.length > this.config.maxPathLength) {
+            return {
+                isValid: false,
+                resolvedPath: '',
+                relativePath: '',
+                matchedPrefix: '',
+                errors: [`Path exceeds maximum length of ${this.config.maxPathLength}`],
+            };
+        }
+        // Check for traversal patterns
+        for (const pattern of TRAVERSAL_PATTERNS) {
+            if (pattern.test(inputPath)) {
+                return {
+                    isValid: false,
+                    resolvedPath: '',
+                    relativePath: '',
+                    matchedPrefix: '',
+                    errors: ['Path traversal pattern detected'],
+                };
+            }
+        }
+        // Resolve the path
+        let resolvedPath;
+        try {
+            resolvedPath = path.resolve(inputPath);
+            // Optionally resolve symlinks
+            if (this.config.resolveSymlinks) {
+                try {
+                    resolvedPath = await fs.realpath(resolvedPath);
+                }
+                catch (error) {
+                    // Path doesn't exist yet - use resolved path
+                    if (error.code !== 'ENOENT' || !this.config.allowNonExistent) {
+                        if (error.code === 'ENOENT') {
+                            errors.push('Path does not exist');
+                        }
+                        else {
+                            errors.push(`Failed to resolve path: ${error.message}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                resolvedPath: '',
+                relativePath: '',
+                matchedPrefix: '',
+                errors: [`Invalid path: ${error.message}`],
+            };
+        }
+        // Check against allowed prefixes
+        let matchedPrefix = '';
+        let relativePath = '';
+        let prefixMatched = false;
+        for (const prefix of this.resolvedPrefixes) {
+            if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
+                prefixMatched = true;
+                matchedPrefix = prefix;
+                relativePath = resolvedPath.slice(prefix.length);
+                if (relativePath.startsWith(path.sep)) {
+                    relativePath = relativePath.slice(1);
+                }
+                break;
+            }
+        }
+        if (!prefixMatched) {
+            return {
+                isValid: false,
+                resolvedPath,
+                relativePath: '',
+                matchedPrefix: '',
+                errors: ['Path is outside allowed directories'],
+            };
+        }
+        // Check for hidden files
+        const pathParts = resolvedPath.split(path.sep);
+        if (!this.config.allowHidden) {
+            for (const part of pathParts) {
+                if (part.startsWith('.') && part !== '.' && part !== '..') {
+                    errors.push('Hidden files/directories are not allowed');
+                    break;
+                }
+            }
+        }
+        // Check blocked file names
+        const basename = path.basename(resolvedPath);
+        if (this.config.blockedNames.includes(basename)) {
+            errors.push(`File name "${basename}" is blocked`);
+        }
+        // Check blocked extensions
+        const ext = path.extname(resolvedPath).toLowerCase();
+        if (this.config.blockedExtensions.includes(ext)) {
+            errors.push(`File extension "${ext}" is blocked`);
+        }
+        // Also check for double extensions (e.g., .tar.gz, .config.json)
+        const fullname = basename.toLowerCase();
+        for (const blockedExt of this.config.blockedExtensions) {
+            if (fullname.endsWith(blockedExt)) {
+                errors.push(`File extension "${blockedExt}" is blocked`);
+                break;
+            }
+        }
+        return {
+            isValid: errors.length === 0,
+            resolvedPath,
+            relativePath,
+            matchedPrefix,
+            errors,
+        };
+    }
+    /**
+     * Validates and returns resolved path, throwing on failure.
+     *
+     * @param inputPath - The path to validate
+     * @returns Resolved path if valid
+     * @throws PathValidatorError if validation fails
+     */
+    async validateOrThrow(inputPath) {
+        const result = await this.validate(inputPath);
+        if (!result.isValid) {
+            throw new PathValidatorError(result.errors.join('; '), 'VALIDATION_FAILED', inputPath);
+        }
+        return result.resolvedPath;
+    }
+    /**
+     * Synchronous validation (without symlink resolution).
+     *
+     * @param inputPath - The path to validate
+     * @returns Validation result
+     */
+    validateSync(inputPath) {
+        const errors = [];
+        if (!inputPath || inputPath.trim() === '') {
+            return {
+                isValid: false,
+                resolvedPath: '',
+                relativePath: '',
+                matchedPrefix: '',
+                errors: ['Path is empty'],
+            };
+        }
+        if (inputPath.length > this.config.maxPathLength) {
+            return {
+                isValid: false,
+                resolvedPath: '',
+                relativePath: '',
+                matchedPrefix: '',
+                errors: [`Path exceeds maximum length of ${this.config.maxPathLength}`],
+            };
+        }
+        for (const pattern of TRAVERSAL_PATTERNS) {
+            if (pattern.test(inputPath)) {
+                return {
+                    isValid: false,
+                    resolvedPath: '',
+                    relativePath: '',
+                    matchedPrefix: '',
+                    errors: ['Path traversal pattern detected'],
+                };
+            }
+        }
+        const resolvedPath = path.resolve(inputPath);
+        let matchedPrefix = '';
+        let relativePath = '';
+        let prefixMatched = false;
+        for (const prefix of this.resolvedPrefixes) {
+            if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
+                prefixMatched = true;
+                matchedPrefix = prefix;
+                relativePath = resolvedPath.slice(prefix.length);
+                if (relativePath.startsWith(path.sep)) {
+                    relativePath = relativePath.slice(1);
+                }
+                break;
+            }
+        }
+        if (!prefixMatched) {
+            return {
+                isValid: false,
+                resolvedPath,
+                relativePath: '',
+                matchedPrefix: '',
+                errors: ['Path is outside allowed directories'],
+            };
+        }
+        const pathParts = resolvedPath.split(path.sep);
+        if (!this.config.allowHidden) {
+            for (const part of pathParts) {
+                if (part.startsWith('.') && part !== '.' && part !== '..') {
+                    errors.push('Hidden files/directories are not allowed');
+                    break;
+                }
+            }
+        }
+        const basename = path.basename(resolvedPath);
+        if (this.config.blockedNames.includes(basename)) {
+            errors.push(`File name "${basename}" is blocked`);
+        }
+        const ext = path.extname(resolvedPath).toLowerCase();
+        if (this.config.blockedExtensions.includes(ext)) {
+            errors.push(`File extension "${ext}" is blocked`);
+        }
+        return {
+            isValid: errors.length === 0,
+            resolvedPath,
+            relativePath,
+            matchedPrefix,
+            errors,
+        };
+    }
+    /**
+     * Securely joins path segments within allowed directories.
+     *
+     * @param prefix - Base directory (must be in allowedPrefixes)
+     * @param segments - Path segments to join
+     * @returns Validated resolved path
+     */
+    async securePath(prefix, ...segments) {
+        // Join the segments
+        const joined = path.join(prefix, ...segments);
+        // Validate the result
+        return this.validateOrThrow(joined);
+    }
+    /**
+     * Adds a prefix to the allowed list at runtime.
+     *
+     * @param prefix - Prefix to add
+     */
+    addPrefix(prefix) {
+        const resolved = path.resolve(prefix);
+        if (!this.resolvedPrefixes.includes(resolved)) {
+            this.config.allowedPrefixes.push(prefix);
+            this.resolvedPrefixes.push(resolved);
+        }
+    }
+    /**
+     * Returns the current allowed prefixes.
+     */
+    getAllowedPrefixes() {
+        return [...this.resolvedPrefixes];
+    }
+    /**
+     * Checks if a path is within allowed prefixes (quick check).
+     */
+    isWithinAllowed(inputPath) {
+        try {
+            const resolved = path.resolve(inputPath);
+            return this.resolvedPrefixes.some(prefix => resolved === prefix || resolved.startsWith(prefix + path.sep));
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Factory function to create a path validator for a project directory.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Configured PathValidator
+ */
+export function createProjectPathValidator(projectRoot) {
+    const srcDir = path.join(projectRoot, 'src');
+    const testDir = path.join(projectRoot, 'tests');
+    const docsDir = path.join(projectRoot, 'docs');
+    return new PathValidator({
+        allowedPrefixes: [srcDir, testDir, docsDir],
+        allowHidden: false,
+    });
+}
+/**
+ * Factory function to create a path validator for the entire project.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Configured PathValidator
+ */
+export function createFullProjectPathValidator(projectRoot) {
+    return new PathValidator({
+        allowedPrefixes: [projectRoot],
+        allowHidden: true, // Allow .gitignore, etc.
+        blockedNames: [
+            ...DEFAULT_BLOCKED_NAMES,
+            'node_modules', // Block access to node_modules
+        ],
+    });
+}
+//# sourceMappingURL=path-validator.js.map

package/dist/path-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-validator.js","sourceRoot":"","sources":["../src/path-validator.ts"],"names":[],"mappings":"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"}

package/dist/safe-executor.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Safe Executor - HIGH-1 Remediation
+ *
+ * Fixes command injection vulnerabilities by:
+ * - Using execFile instead of exec with shell
+ * - Validating all command arguments
+ * - Implementing command allowlist
+ * - Sanitizing command inputs
+ *
+ * Security Properties:
+ * - No shell interpretation
+ * - Argument validation
+ * - Command allowlist enforcement
+ * - Timeout controls
+ * - Resource limits
+ *
+ * @module v3/security/safe-executor
+ */
+import { ChildProcess } from 'child_process';
+export interface ExecutorConfig {
+    /**
+     * Allowed commands (allowlist).
+     * Only commands in this list can be executed.
+     */
+    allowedCommands: string[];
+    /**
+     * Blocked argument patterns (regex strings).
+     * Arguments matching these patterns are rejected.
+     */
+    blockedPatterns?: string[];
+    /**
+     * Maximum execution timeout in milliseconds.
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Maximum buffer size for stdout/stderr.
+     * Default: 10MB
+     */
+    maxBuffer?: number;
+    /**
+     * Working directory for command execution.
+     * Default: process.cwd()
+     */
+    cwd?: string;
+    /**
+     * Environment variables to include.
+     * Default: process.env
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Whether to allow sudo commands.
+     * Default: false
+     */
+    allowSudo?: boolean;
+}
+export interface ExecutionResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    command: string;
+    args: string[];
+    duration: number;
+}
+export interface StreamingExecutor {
+    process: ChildProcess;
+    stdout: NodeJS.ReadableStream | null;
+    stderr: NodeJS.ReadableStream | null;
+    promise: Promise<ExecutionResult>;
+}
+export declare class SafeExecutorError extends Error {
+    readonly code: string;
+    readonly command?: string | undefined;
+    readonly args?: string[] | undefined;
+    constructor(message: string, code: string, command?: string | undefined, args?: string[] | undefined);
+}
+/**
+ * Safe command executor that prevents command injection.
+ *
+ * This class replaces unsafe exec() and spawn({shell: true}) calls
+ * with validated execFile() calls.
+ *
+ * @example
+ * ```typescript
+ * const executor = new SafeExecutor({
+ *   allowedCommands: ['git', 'npm', 'node']
+ * });
+ *
+ * const result = await executor.execute('git', ['status']);
+ * ```
+ */
+export declare class SafeExecutor {
+    private readonly config;
+    private readonly blockedPatterns;
+    constructor(config: ExecutorConfig);
+    /**
+     * Escapes special regex characters.
+     */
+    private escapeRegExp;
+    /**
+     * Validates executor configuration.
+     */
+    private validateConfig;
+    /**
+     * Validates a command against the allowlist.
+     *
+     * @param command - Command to validate
+     * @throws SafeExecutorError if command is not allowed
+     */
+    private validateCommand;
+    /**
+     * Validates command arguments for injection patterns.
+     *
+     * @param args - Arguments to validate
+     * @throws SafeExecutorError if arguments contain dangerous patterns
+     */
+    private validateArguments;
+    /**
+     * Sanitizes a single argument.
+     *
+     * @param arg - Argument to sanitize
+     * @returns Sanitized argument
+     */
+    sanitizeArgument(arg: string): string;
+    /**
+     * Executes a command safely.
+     *
+     * @param command - Command to execute (must be in allowlist)
+     * @param args - Command arguments
+     * @returns Execution result
+     * @throws SafeExecutorError on validation failure or execution error
+     */
+    execute(command: string, args?: string[]): Promise<ExecutionResult>;
+    /**
+     * Executes a command with streaming output.
+     *
+     * @param command - Command to execute
+     * @param args - Command arguments
+     * @returns Streaming executor with process handles
+     */
+    executeStreaming(command: string, args?: string[]): StreamingExecutor;
+    /**
+     * Adds a command to the allowlist at runtime.
+     *
+     * @param command - Command to add
+     */
+    allowCommand(command: string): void;
+    /**
+     * Checks if a command is allowed.
+     *
+     * @param command - Command to check
+     * @returns True if command is allowed
+     */
+    isCommandAllowed(command: string): boolean;
+    /**
+     * Returns the current allowlist.
+     */
+    getAllowedCommands(): readonly string[];
+}
+/**
+ * Factory function to create a safe executor for common development tasks.
+ *
+ * @returns Configured SafeExecutor for git, npm, and node
+ */
+export declare function createDevelopmentExecutor(): SafeExecutor;
+/**
+ * Factory function to create a read-only executor.
+ * Only allows commands that read without modifying.
+ *
+ * @returns Configured SafeExecutor for read operations
+ */
+export declare function createReadOnlyExecutor(): SafeExecutor;
+//# sourceMappingURL=safe-executor.d.ts.map

package/dist/safe-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-executor.d.ts","sourceRoot":"","sources":["../src/safe-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAmB,YAAY,EAAE,MAAM,eAAe,CAAC;AAM9D,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACnC;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,MAAM;aAChB,IAAI,CAAC,EAAE,MAAM,EAAE;gBAH/B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,YAAA,EAChB,IAAI,CAAC,EAAE,MAAM,EAAE,YAAA;CAKlC;AAoDD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAW;gBAE/B,MAAM,EAAE,cAAc;IAmBlC;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAqBtB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA2BvB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAoCzB;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAUrC;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IA4D7E;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,iBAAiB;IA2DzE;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAenC;;;;;OAKG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ1C;;OAEG;IACH,kBAAkB,IAAI,SAAS,MAAM,EAAE;CAGxC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,YAAY,CAaxD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,CAerD"}