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

package/dist/safe-executor.js

@@ -0,0 +1,370 @@
+/**
+ * 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 { execFile, spawn } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+const execFileAsync = promisify(execFile);
+export class SafeExecutorError extends Error {
+    code;
+    command;
+    args;
+    constructor(message, code, command, args) {
+        super(message);
+        this.code = code;
+        this.command = command;
+        this.args = args;
+        this.name = 'SafeExecutorError';
+    }
+}
+/**
+ * Default blocked argument patterns.
+ * These patterns indicate potential command injection attempts.
+ */
+const DEFAULT_BLOCKED_PATTERNS = [
+    // Shell metacharacters
+    ';',
+    '&&',
+    '||',
+    '|',
+    '`',
+    '$(',
+    '${',
+    // Redirection
+    '>',
+    '<',
+    '>>',
+    // Background execution
+    '&',
+    // Newlines (command chaining)
+    '\n',
+    '\r',
+    // Null byte injection
+    '\0',
+    // Command substitution
+    '$()',
+];
+/**
+ * Commands that are inherently dangerous and should never be allowed.
+ */
+const DANGEROUS_COMMANDS = [
+    'rm',
+    'rmdir',
+    'del',
+    'format',
+    'mkfs',
+    'dd',
+    'chmod',
+    'chown',
+    'kill',
+    'killall',
+    'pkill',
+    'reboot',
+    'shutdown',
+    'init',
+    'poweroff',
+    'halt',
+];
+/**
+ * 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 class SafeExecutor {
+    config;
+    blockedPatterns;
+    constructor(config) {
+        this.config = {
+            allowedCommands: config.allowedCommands,
+            blockedPatterns: config.blockedPatterns ?? DEFAULT_BLOCKED_PATTERNS,
+            timeout: config.timeout ?? 30000,
+            maxBuffer: config.maxBuffer ?? 10 * 1024 * 1024, // 10MB
+            cwd: config.cwd ?? process.cwd(),
+            env: config.env ?? process.env,
+            allowSudo: config.allowSudo ?? false,
+        };
+        // Compile blocked patterns for performance
+        this.blockedPatterns = this.config.blockedPatterns.map(pattern => new RegExp(this.escapeRegExp(pattern), 'i'));
+        this.validateConfig();
+    }
+    /**
+     * Escapes special regex characters.
+     */
+    escapeRegExp(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * Validates executor configuration.
+     */
+    validateConfig() {
+        if (this.config.allowedCommands.length === 0) {
+            throw new SafeExecutorError('At least one allowed command must be specified', 'EMPTY_ALLOWLIST');
+        }
+        // Check for dangerous commands in allowlist
+        const dangerousAllowed = this.config.allowedCommands.filter(cmd => DANGEROUS_COMMANDS.includes(path.basename(cmd)));
+        if (dangerousAllowed.length > 0) {
+            throw new SafeExecutorError(`Dangerous commands cannot be allowed: ${dangerousAllowed.join(', ')}`, 'DANGEROUS_COMMAND_ALLOWED');
+        }
+    }
+    /**
+     * Validates a command against the allowlist.
+     *
+     * @param command - Command to validate
+     * @throws SafeExecutorError if command is not allowed
+     */
+    validateCommand(command) {
+        const basename = path.basename(command);
+        // Check if command is allowed
+        const isAllowed = this.config.allowedCommands.some(allowed => {
+            const allowedBasename = path.basename(allowed);
+            return command === allowed || basename === allowedBasename;
+        });
+        if (!isAllowed) {
+            throw new SafeExecutorError(`Command not in allowlist: ${command}`, 'COMMAND_NOT_ALLOWED', command);
+        }
+        // Check for sudo
+        if (!this.config.allowSudo && (command === 'sudo' || basename === 'sudo')) {
+            throw new SafeExecutorError('Sudo commands are not allowed', 'SUDO_NOT_ALLOWED', command);
+        }
+    }
+    /**
+     * Validates command arguments for injection patterns.
+     *
+     * @param args - Arguments to validate
+     * @throws SafeExecutorError if arguments contain dangerous patterns
+     */
+    validateArguments(args) {
+        for (const arg of args) {
+            // Check for null bytes
+            if (arg.includes('\0')) {
+                throw new SafeExecutorError('Null byte detected in argument', 'NULL_BYTE_INJECTION', undefined, args);
+            }
+            // Check against blocked patterns
+            for (const pattern of this.blockedPatterns) {
+                if (pattern.test(arg)) {
+                    throw new SafeExecutorError(`Dangerous pattern detected in argument: ${arg}`, 'DANGEROUS_PATTERN', undefined, args);
+                }
+            }
+            // Check for command chaining attempts
+            if (/^-.*[;&|]/.test(arg)) {
+                throw new SafeExecutorError(`Potential command chaining in argument: ${arg}`, 'COMMAND_CHAINING', undefined, args);
+            }
+        }
+    }
+    /**
+     * Sanitizes a single argument.
+     *
+     * @param arg - Argument to sanitize
+     * @returns Sanitized argument
+     */
+    sanitizeArgument(arg) {
+        // Remove null bytes
+        let sanitized = arg.replace(/\0/g, '');
+        // Remove shell metacharacters
+        sanitized = sanitized.replace(/[;&|`$(){}><\n\r]/g, '');
+        return sanitized;
+    }
+    /**
+     * 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
+     */
+    async execute(command, args = []) {
+        const startTime = Date.now();
+        // Validate command
+        this.validateCommand(command);
+        // Validate arguments
+        this.validateArguments(args);
+        try {
+            // Execute command WITHOUT shell
+            const { stdout, stderr } = await execFileAsync(command, args, {
+                cwd: this.config.cwd,
+                env: this.config.env,
+                timeout: this.config.timeout,
+                maxBuffer: this.config.maxBuffer,
+                shell: false, // CRITICAL: Never use shell
+                windowsHide: true,
+            });
+            return {
+                stdout: stdout.toString(),
+                stderr: stderr.toString(),
+                exitCode: 0,
+                command,
+                args,
+                duration: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            // Handle execution errors
+            if (error.killed) {
+                throw new SafeExecutorError('Command execution timed out', 'TIMEOUT', command, args);
+            }
+            if (error.code === 'ENOENT') {
+                throw new SafeExecutorError(`Command not found: ${command}`, 'COMMAND_NOT_FOUND', command, args);
+            }
+            // Return result with non-zero exit code
+            return {
+                stdout: error.stdout?.toString() ?? '',
+                stderr: error.stderr?.toString() ?? error.message,
+                exitCode: error.code ?? 1,
+                command,
+                args,
+                duration: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Executes a command with streaming output.
+     *
+     * @param command - Command to execute
+     * @param args - Command arguments
+     * @returns Streaming executor with process handles
+     */
+    executeStreaming(command, args = []) {
+        const startTime = Date.now();
+        // Validate command
+        this.validateCommand(command);
+        // Validate arguments
+        this.validateArguments(args);
+        // Spawn process WITHOUT shell
+        const childProcess = spawn(command, args, {
+            cwd: this.config.cwd,
+            env: this.config.env,
+            timeout: this.config.timeout,
+            shell: false, // CRITICAL: Never use shell
+            windowsHide: true,
+        });
+        const promise = new Promise((resolve, reject) => {
+            let stdout = '';
+            let stderr = '';
+            childProcess.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            childProcess.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            childProcess.on('close', (code) => {
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: code ?? 0,
+                    command,
+                    args,
+                    duration: Date.now() - startTime,
+                });
+            });
+            childProcess.on('error', (error) => {
+                reject(new SafeExecutorError(error.message, 'EXECUTION_ERROR', command, args));
+            });
+        });
+        return {
+            process: childProcess,
+            stdout: childProcess.stdout,
+            stderr: childProcess.stderr,
+            promise,
+        };
+    }
+    /**
+     * Adds a command to the allowlist at runtime.
+     *
+     * @param command - Command to add
+     */
+    allowCommand(command) {
+        const basename = path.basename(command);
+        if (DANGEROUS_COMMANDS.includes(basename)) {
+            throw new SafeExecutorError(`Cannot allow dangerous command: ${command}`, 'DANGEROUS_COMMAND');
+        }
+        if (!this.config.allowedCommands.includes(command)) {
+            this.config.allowedCommands.push(command);
+        }
+    }
+    /**
+     * Checks if a command is allowed.
+     *
+     * @param command - Command to check
+     * @returns True if command is allowed
+     */
+    isCommandAllowed(command) {
+        const basename = path.basename(command);
+        return this.config.allowedCommands.some(allowed => {
+            const allowedBasename = path.basename(allowed);
+            return command === allowed || basename === allowedBasename;
+        });
+    }
+    /**
+     * Returns the current allowlist.
+     */
+    getAllowedCommands() {
+        return [...this.config.allowedCommands];
+    }
+}
+/**
+ * Factory function to create a safe executor for common development tasks.
+ *
+ * @returns Configured SafeExecutor for git, npm, and node
+ */
+export function createDevelopmentExecutor() {
+    return new SafeExecutor({
+        allowedCommands: [
+            'git',
+            'npm',
+            'npx',
+            'node',
+            'tsc',
+            'vitest',
+            'eslint',
+            'prettier',
+        ],
+    });
+}
+/**
+ * Factory function to create a read-only executor.
+ * Only allows commands that read without modifying.
+ *
+ * @returns Configured SafeExecutor for read operations
+ */
+export function createReadOnlyExecutor() {
+    return new SafeExecutor({
+        allowedCommands: [
+            'git',
+            'cat',
+            'head',
+            'tail',
+            'ls',
+            'find',
+            'grep',
+            'which',
+            'echo',
+        ],
+        timeout: 10000,
+    });
+}
+//# sourceMappingURL=safe-executor.js.map

package/dist/safe-executor.js.map

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

package/dist/token-generator.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Token Generator - Secure Token Generation
+ *
+ * Provides cryptographically secure token generation for:
+ * - JWT tokens
+ * - Session tokens
+ * - CSRF tokens
+ * - API tokens
+ * - Verification codes
+ *
+ * Security Properties:
+ * - Uses crypto.randomBytes for all randomness
+ * - Configurable entropy levels
+ * - Timing-safe comparison
+ * - Token expiration handling
+ *
+ * @module v3/security/token-generator
+ */
+export interface TokenConfig {
+    /**
+     * Default token length in bytes.
+     * Default: 32 (256 bits)
+     */
+    defaultLength?: number;
+    /**
+     * Token encoding format.
+     * Default: 'base64url'
+     */
+    encoding?: 'hex' | 'base64' | 'base64url';
+    /**
+     * HMAC secret for signed tokens.
+     */
+    hmacSecret?: string;
+    /**
+     * Default expiration time in seconds.
+     * Default: 3600 (1 hour)
+     */
+    defaultExpiration?: number;
+}
+export interface Token {
+    value: string;
+    createdAt: Date;
+    expiresAt: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface SignedToken {
+    token: string;
+    signature: string;
+    combined: string;
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface VerificationCode {
+    code: string;
+    createdAt: Date;
+    expiresAt: Date;
+    attempts: number;
+    maxAttempts: number;
+}
+export declare class TokenGeneratorError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Secure token generator.
+ *
+ * @example
+ * ```typescript
+ * const generator = new TokenGenerator({ hmacSecret: 'secret' });
+ *
+ * // Generate session token
+ * const session = generator.generateSessionToken();
+ *
+ * // Generate signed token
+ * const signed = generator.generateSignedToken({ userId: '123' });
+ *
+ * // Verify signed token
+ * const isValid = generator.verifySignedToken(signed.combined);
+ * ```
+ */
+export declare class TokenGenerator {
+    private readonly config;
+    constructor(config?: TokenConfig);
+    /**
+     * Generates a random token.
+     *
+     * @param length - Token length in bytes
+     * @returns Random token string
+     */
+    generate(length?: number): string;
+    /**
+     * Generates a token with expiration.
+     *
+     * @param expirationSeconds - Expiration time in seconds
+     * @param metadata - Optional metadata to attach
+     * @returns Token with expiration
+     */
+    generateWithExpiration(expirationSeconds?: number, metadata?: Record<string, unknown>): Token;
+    /**
+     * Generates a session token (URL-safe).
+     *
+     * @param length - Token length in bytes (default: 32)
+     * @returns Session token
+     */
+    generateSessionToken(length?: number): Token;
+    /**
+     * Generates a CSRF token.
+     *
+     * @returns CSRF token (shorter expiration)
+     */
+    generateCsrfToken(): Token;
+    /**
+     * Generates an API token with prefix.
+     *
+     * @param prefix - Token prefix (e.g., 'cf_')
+     * @returns Prefixed API token
+     */
+    generateApiToken(prefix?: string): Token;
+    /**
+     * Generates a numeric verification code.
+     *
+     * @param length - Number of digits (default: 6)
+     * @param expirationMinutes - Expiration in minutes (default: 10)
+     * @param maxAttempts - Maximum verification attempts (default: 3)
+     * @returns Verification code
+     */
+    generateVerificationCode(length?: number, expirationMinutes?: number, maxAttempts?: number): VerificationCode;
+    /**
+     * Generates a signed token using HMAC.
+     *
+     * @param payload - Data to include in token
+     * @param expirationSeconds - Token expiration
+     * @returns Signed token
+     */
+    generateSignedToken(payload: Record<string, unknown>, expirationSeconds?: number): SignedToken;
+    /**
+     * Verifies a signed token.
+     *
+     * @param combined - Combined token string (token.signature)
+     * @returns Decoded payload if valid, null otherwise
+     */
+    verifySignedToken(combined: string): Record<string, unknown> | null;
+    /**
+     * Generates a refresh token pair.
+     *
+     * @returns Access and refresh tokens
+     */
+    generateTokenPair(): {
+        accessToken: Token;
+        refreshToken: Token;
+    };
+    /**
+     * Generates a password reset token.
+     *
+     * @returns Password reset token (short expiration)
+     */
+    generatePasswordResetToken(): Token;
+    /**
+     * Generates an email verification token.
+     *
+     * @returns Email verification token
+     */
+    generateEmailVerificationToken(): Token;
+    /**
+     * Generates a unique request ID.
+     *
+     * @returns Request ID (shorter, for logging)
+     */
+    generateRequestId(): string;
+    /**
+     * Generates a correlation ID for distributed tracing.
+     *
+     * @returns Correlation ID
+     */
+    generateCorrelationId(): string;
+    /**
+     * Checks if a token has expired.
+     *
+     * @param token - Token to check
+     * @returns True if expired
+     */
+    isExpired(token: Token | VerificationCode): boolean;
+    /**
+     * Compares two tokens in constant time.
+     *
+     * @param a - First token
+     * @param b - Second token
+     * @returns True if equal
+     */
+    compare(a: string, b: string): boolean;
+    /**
+     * Signs data using HMAC-SHA256.
+     */
+    private sign;
+    /**
+     * Encodes bytes according to configuration.
+     */
+    private encode;
+}
+/**
+ * Factory function to create a production token generator.
+ *
+ * @param hmacSecret - HMAC secret for signed tokens
+ * @returns Configured TokenGenerator
+ */
+export declare function createTokenGenerator(hmacSecret: string): TokenGenerator;
+/**
+ * Gets or creates the default token generator.
+ * Note: Does not support signed tokens without configuration.
+ */
+export declare function getDefaultGenerator(): TokenGenerator;
+/**
+ * Quick token generation functions.
+ */
+export declare const quickGenerate: {
+    token: (length?: number) => string;
+    sessionToken: () => Token;
+    csrfToken: () => Token;
+    apiToken: (prefix?: string) => Token;
+    verificationCode: (length?: number) => VerificationCode;
+    requestId: () => string;
+    correlationId: () => string;
+};
+//# sourceMappingURL=token-generator.d.ts.map

package/dist/token-generator.d.ts.map

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