@defai.digital/ax-cli 3.5.4 → 3.6.1

package/dist/utils/command-security.js

@@ -0,0 +1,200 @@
+/**
+ * Command Security Utilities
+ *
+ * Provides secure command execution with whitelisting and validation.
+ * Prevents command injection vulnerabilities (REQ-SEC-001).
+ *
+ * @module command-security
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+/**
+ * Whitelist of safe commands allowed for execution.
+ * Only these commands can be executed via the BashTool.
+ *
+ * CRITICAL: Do not add arbitrary commands without security review.
+ */
+export const SAFE_COMMANDS = [
+    'ls',
+    'grep',
+    'find',
+    'cat',
+    'head',
+    'tail',
+    'wc',
+    'sort',
+    'uniq',
+    'cut',
+    'awk',
+    'sed',
+    'pwd',
+    'echo',
+    'date',
+    'whoami',
+    'hostname',
+    'git',
+    'rg',
+    'fd',
+    'rm', // File deletion (safe with validation)
+    'mkdir', // Directory creation
+    'touch', // File creation
+    'cp', // File copy
+    'mv', // File move/rename
+];
+/**
+ * Environment variables safe to pass to child processes.
+ * Only these will be included in the child process environment.
+ */
+const SAFE_ENV_VARS = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LANG',
+    'LC_ALL',
+    'TERM',
+    'TMPDIR',
+    'PWD',
+];
+/**
+ * Shell metacharacters that are forbidden in command arguments.
+ * These could enable command injection if not properly validated.
+ */
+const SHELL_METACHARACTERS = /[;&|`$(){}[\]<>'"\\*?~!#]/;
+/**
+ * Sanitize environment variables for child process.
+ * Only includes safe environment variables to prevent injection.
+ *
+ * @param env - Original process environment
+ * @returns Sanitized environment object
+ */
+export function sanitizeEnv(env) {
+    const sanitized = {};
+    for (const key of SAFE_ENV_VARS) {
+        if (env[key]) {
+            sanitized[key] = env[key];
+        }
+    }
+    return sanitized;
+}
+/**
+ * Parse a command string into command and arguments.
+ * Validates that the command is in the whitelist.
+ *
+ * @param commandString - Full command string (e.g., "ls -la /tmp")
+ * @returns Parsed command structure
+ * @throws Error if command is not whitelisted
+ */
+export function parseCommand(commandString) {
+    const trimmed = commandString.trim();
+    if (!trimmed) {
+        throw new Error('Empty command string');
+    }
+    // Simple split by whitespace
+    const parts = trimmed.split(/\s+/);
+    const command = parts[0];
+    const args = parts.slice(1);
+    // Validate command is in whitelist
+    if (!SAFE_COMMANDS.includes(command)) {
+        throw new Error(`Command '${command}' not in whitelist. Allowed commands: ${SAFE_COMMANDS.join(', ')}`);
+    }
+    return {
+        command: command,
+        args,
+    };
+}
+/**
+ * Validate command arguments for shell metacharacters.
+ * Prevents command injection via argument injection.
+ *
+ * @param args - Command arguments to validate
+ * @returns Validation result
+ */
+export function validateArguments(args) {
+    const errors = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        // Check for shell metacharacters
+        if (SHELL_METACHARACTERS.test(arg)) {
+            errors.push(`Argument ${i} contains forbidden shell metacharacters: "${arg}"`);
+        }
+        // Check for null bytes
+        if (arg.includes('\0')) {
+            errors.push(`Argument ${i} contains null byte`);
+        }
+        // Check length (prevent buffer overflow)
+        if (arg.length > 10000) {
+            errors.push(`Argument ${i} exceeds maximum length (10000 chars)`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Execute a safe command with validation.
+ * Uses execFile to avoid shell invocation and command injection.
+ *
+ * SECURITY: This function uses execFile instead of spawn('bash', ['-c'])
+ * to prevent command injection attacks.
+ *
+ * @param commandString - Command to execute
+ * @param options - Execution options
+ * @returns Tool result with output or error
+ */
+export async function executeSafeCommand(commandString, options = {}) {
+    try {
+        // 1. Parse command into command + args
+        const parsed = parseCommand(commandString);
+        // 2. Validate arguments
+        const validation = validateArguments(parsed.args);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: `Command validation failed:\n${validation.errors.join('\n')}`,
+            };
+        }
+        // 3. Prepare execution options
+        const execOptions = {
+            cwd: options.cwd || process.cwd(),
+            env: sanitizeEnv(process.env),
+            timeout: options.timeout || 30000, // 30 second default
+            maxBuffer: options.maxBuffer || 1024 * 1024, // 1MB default
+        };
+        // 4. Execute using execFile (no shell invocation)
+        const { stdout, stderr } = await execFileAsync(parsed.command, parsed.args, execOptions);
+        // 5. Return successful result
+        return {
+            success: true,
+            output: stdout || stderr || 'Command completed successfully',
+        };
+    }
+    catch (error) {
+        // Handle execution errors
+        const errorMessage = error.message || String(error);
+        const exitCode = error.code || 'unknown';
+        return {
+            success: false,
+            error: `Command execution failed (exit code: ${exitCode}): ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Check if a command is safe to execute.
+ *
+ * @param command - Command name to check
+ * @returns True if command is in whitelist
+ */
+export function isSafeCommand(command) {
+    return SAFE_COMMANDS.includes(command);
+}
+/**
+ * Get list of safe commands (for documentation/help).
+ *
+ * @returns Array of safe command names
+ */
+export function getSafeCommands() {
+    return SAFE_COMMANDS;
+}
+//# sourceMappingURL=command-security.js.map

package/dist/utils/command-security.js.map

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

package/dist/utils/config-loader.js

@@ -16,9 +16,9 @@ const configCache = new Map();
  * Get the config directory path
  */
 function getConfigDir() {
-    // In development: src/utils -> ../../config
-    // In production: dist/utils -> ../../config
-    return join(__dirname, '../../config');
+    // In development: src/utils -> ../../config-defaults
+    // In production: dist/utils -> ../../config-defaults
+    return join(__dirname, '../../config-defaults');
 }
 /**
  * Load a YAML configuration file with optional schema validation

package/dist/utils/config-loader.js.map

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

package/dist/utils/encryption.d.ts

@@ -0,0 +1,78 @@
+/**
+ * API Key Encryption Utilities
+ *
+ * Provides secure encryption/decryption for API keys stored in configuration
+ * files (REQ-SEC-003).
+ *
+ * Uses Node.js crypto module with:
+ * - AES-256-GCM for encryption (authenticated encryption)
+ * - PBKDF2 for key derivation from machine-specific identifier
+ * - Random IV for each encryption
+ * - Authentication tag verification
+ *
+ * @module encryption
+ */
+/**
+ * Encrypted value format
+ */
+export interface EncryptedValue {
+    encrypted: string;
+    iv: string;
+    tag: string;
+    version: number;
+}
+/**
+ * Encrypt a string value (typically an API key).
+ *
+ * @param plaintext - The value to encrypt
+ * @returns Encrypted value object with iv, tag, and encrypted data
+ */
+export declare function encrypt(plaintext: string): EncryptedValue;
+/**
+ * Decrypt an encrypted value.
+ *
+ * @param encryptedValue - The encrypted value object
+ * @returns Decrypted plaintext
+ * @throws Error if decryption fails (wrong machine, corrupted data, etc.)
+ */
+export declare function decrypt(encryptedValue: EncryptedValue): string;
+/**
+ * Check if a value is encrypted (has the expected structure).
+ *
+ * @param value - Value to check
+ * @returns True if value appears to be encrypted
+ */
+export declare function isEncrypted(value: unknown): value is EncryptedValue;
+/**
+ * Encrypt an object's sensitive fields.
+ *
+ * @param obj - Object containing sensitive fields
+ * @param fieldsToEncrypt - Array of field names to encrypt
+ * @returns New object with encrypted fields
+ */
+export declare function encryptFields<T extends Record<string, any>>(obj: T, fieldsToEncrypt: string[]): T;
+/**
+ * Decrypt an object's encrypted fields.
+ *
+ * @param obj - Object containing encrypted fields
+ * @param fieldsToDecrypt - Array of field names to decrypt
+ * @returns New object with decrypted fields
+ */
+export declare function decryptFields<T extends Record<string, any>>(obj: T, fieldsToDecrypt: string[]): T;
+/**
+ * Test if encryption is working (for diagnostics).
+ *
+ * @returns True if encryption/decryption round-trip works
+ */
+export declare function testEncryption(): boolean;
+/**
+ * Get encryption info for diagnostics.
+ */
+export declare function getEncryptionInfo(): {
+    algorithm: string;
+    keyLength: number;
+    ivLength: number;
+    pbkdf2Iterations: number;
+    version: number;
+    machineId: string;
+};

package/dist/utils/encryption.js

@@ -0,0 +1,216 @@
+/**
+ * API Key Encryption Utilities
+ *
+ * Provides secure encryption/decryption for API keys stored in configuration
+ * files (REQ-SEC-003).
+ *
+ * Uses Node.js crypto module with:
+ * - AES-256-GCM for encryption (authenticated encryption)
+ * - PBKDF2 for key derivation from machine-specific identifier
+ * - Random IV for each encryption
+ * - Authentication tag verification
+ *
+ * @module encryption
+ */
+import crypto from 'crypto';
+import os from 'os';
+/**
+ * Encryption configuration
+ */
+const ENCRYPTION_CONFIG = {
+    algorithm: 'aes-256-gcm',
+    keyLength: 32, // 256 bits
+    ivLength: 16, // 128 bits
+    saltLength: 32, // 256 bits
+    tagLength: 16, // 128 bits
+    pbkdf2Iterations: 100000, // OWASP recommendation
+    version: 1,
+};
+/**
+ * Get a machine-specific identifier for key derivation.
+ * Uses hostname + platform + arch to create a unique-per-machine string.
+ *
+ * Note: This is not cryptographically strong protection (attacker with file
+ * access can derive the key), but it prevents casual browsing of config files
+ * and provides defense in depth.
+ */
+function getMachineIdentifier() {
+    const hostname = os.hostname();
+    const platform = os.platform();
+    const arch = os.arch();
+    // Combine machine-specific data
+    return `${hostname}-${platform}-${arch}`;
+}
+/**
+ * Derive an encryption key from machine identifier and salt using PBKDF2.
+ *
+ * @param salt - Salt for key derivation
+ * @returns Derived encryption key
+ */
+function deriveKey(salt) {
+    const machineId = getMachineIdentifier();
+    return crypto.pbkdf2Sync(machineId, salt, ENCRYPTION_CONFIG.pbkdf2Iterations, ENCRYPTION_CONFIG.keyLength, 'sha256');
+}
+/**
+ * Encrypt a string value (typically an API key).
+ *
+ * @param plaintext - The value to encrypt
+ * @returns Encrypted value object with iv, tag, and encrypted data
+ */
+export function encrypt(plaintext) {
+    // Generate random salt and IV
+    const salt = crypto.randomBytes(ENCRYPTION_CONFIG.saltLength);
+    const iv = crypto.randomBytes(ENCRYPTION_CONFIG.ivLength);
+    // Derive key from machine identifier
+    const key = deriveKey(salt);
+    // Create cipher
+    const cipher = crypto.createCipheriv(ENCRYPTION_CONFIG.algorithm, key, iv);
+    // Encrypt the plaintext
+    let encrypted = cipher.update(plaintext, 'utf8', 'base64');
+    encrypted += cipher.final('base64');
+    // Get authentication tag
+    const tag = cipher.getAuthTag();
+    // Return encrypted value with metadata
+    // Store salt in the IV field for simplicity (both are public)
+    const saltAndIv = Buffer.concat([salt, iv]);
+    return {
+        encrypted,
+        iv: saltAndIv.toString('base64'),
+        tag: tag.toString('base64'),
+        version: ENCRYPTION_CONFIG.version,
+    };
+}
+/**
+ * Decrypt an encrypted value.
+ *
+ * @param encryptedValue - The encrypted value object
+ * @returns Decrypted plaintext
+ * @throws Error if decryption fails (wrong machine, corrupted data, etc.)
+ */
+export function decrypt(encryptedValue) {
+    try {
+        // Check version
+        if (encryptedValue.version !== ENCRYPTION_CONFIG.version) {
+            throw new Error(`Unsupported encryption version: ${encryptedValue.version}`);
+        }
+        // Extract salt and IV
+        const saltAndIv = Buffer.from(encryptedValue.iv, 'base64');
+        if (saltAndIv.length !== ENCRYPTION_CONFIG.saltLength + ENCRYPTION_CONFIG.ivLength) {
+            throw new Error('Invalid encrypted data: incorrect salt/IV length');
+        }
+        const salt = saltAndIv.subarray(0, ENCRYPTION_CONFIG.saltLength);
+        const iv = saltAndIv.subarray(ENCRYPTION_CONFIG.saltLength);
+        // Derive key from machine identifier
+        const key = deriveKey(salt);
+        // Create decipher
+        const decipher = crypto.createDecipheriv(ENCRYPTION_CONFIG.algorithm, key, iv);
+        // Set authentication tag
+        const tag = Buffer.from(encryptedValue.tag, 'base64');
+        decipher.setAuthTag(tag);
+        // Decrypt
+        let decrypted = decipher.update(encryptedValue.encrypted, 'base64', 'utf8');
+        decrypted += decipher.final('utf8');
+        return decrypted;
+    }
+    catch (error) {
+        // Provide a user-friendly error message
+        if (error instanceof Error) {
+            if (error.message.includes('Unsupported state or unable to authenticate data')) {
+                throw new Error('Failed to decrypt API key. This may be due to: ' +
+                    '(1) moving config to a different machine, ' +
+                    '(2) corrupted config file, or ' +
+                    '(3) config file was manually edited. ' +
+                    'Please re-enter your API key.');
+            }
+            throw new Error(`Decryption failed: ${error.message}`);
+        }
+        throw new Error('Decryption failed: Unknown error');
+    }
+}
+/**
+ * Check if a value is encrypted (has the expected structure).
+ *
+ * @param value - Value to check
+ * @returns True if value appears to be encrypted
+ */
+export function isEncrypted(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.encrypted === 'string' &&
+        typeof obj.iv === 'string' &&
+        typeof obj.tag === 'string' &&
+        typeof obj.version === 'number');
+}
+/**
+ * Encrypt an object's sensitive fields.
+ *
+ * @param obj - Object containing sensitive fields
+ * @param fieldsToEncrypt - Array of field names to encrypt
+ * @returns New object with encrypted fields
+ */
+export function encryptFields(obj, fieldsToEncrypt) {
+    const result = { ...obj };
+    for (const field of fieldsToEncrypt) {
+        if (field in result && typeof result[field] === 'string') {
+            // Don't re-encrypt already encrypted values
+            if (!isEncrypted(result[field])) {
+                result[field] = encrypt(result[field]);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Decrypt an object's encrypted fields.
+ *
+ * @param obj - Object containing encrypted fields
+ * @param fieldsToDecrypt - Array of field names to decrypt
+ * @returns New object with decrypted fields
+ */
+export function decryptFields(obj, fieldsToDecrypt) {
+    const result = { ...obj };
+    for (const field of fieldsToDecrypt) {
+        if (field in result && isEncrypted(result[field])) {
+            try {
+                result[field] = decrypt(result[field]);
+            }
+            catch (error) {
+                // If decryption fails, leave the field as-is and let caller handle it
+                console.error(`Failed to decrypt field "${field}":`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Test if encryption is working (for diagnostics).
+ *
+ * @returns True if encryption/decryption round-trip works
+ */
+export function testEncryption() {
+    try {
+        const testValue = 'test-api-key-12345';
+        const encrypted = encrypt(testValue);
+        const decrypted = decrypt(encrypted);
+        return decrypted === testValue;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get encryption info for diagnostics.
+ */
+export function getEncryptionInfo() {
+    return {
+        algorithm: ENCRYPTION_CONFIG.algorithm,
+        keyLength: ENCRYPTION_CONFIG.keyLength,
+        ivLength: ENCRYPTION_CONFIG.ivLength,
+        pbkdf2Iterations: ENCRYPTION_CONFIG.pbkdf2Iterations,
+        version: ENCRYPTION_CONFIG.version,
+        machineId: getMachineIdentifier(),
+    };
+}
+//# sourceMappingURL=encryption.js.map

package/dist/utils/encryption.js.map

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

package/dist/utils/error-sanitizer.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Error Message Sanitization (REQ-SEC-010)
+ *
+ * Sanitizes error messages to prevent information disclosure
+ * Removes:
+ * - File system paths
+ * - API keys and secrets
+ * - Stack traces (for user-facing errors)
+ * - Internal implementation details
+ *
+ * Security: CVSS 6.5 (Medium Priority)
+ */
+/**
+ * Sanitized error structure
+ */
+export interface SanitizedError {
+    /**
+     * Sanitized error message (safe for user display)
+     */
+    message: string;
+    /**
+     * Error code (for documentation lookup)
+     */
+    code?: string;
+    /**
+     * Generic error category
+     */
+    category: string;
+    /**
+     * Suggested action for user
+     */
+    suggestion?: string;
+    /**
+     * Original error (for internal logging only)
+     */
+    originalError?: Error;
+}
+/**
+ * Error categories for user-friendly messages
+ */
+export declare enum ErrorCategory {
+    NETWORK = "NETWORK",
+    FILE_SYSTEM = "FILE_SYSTEM",
+    VALIDATION = "VALIDATION",
+    AUTHENTICATION = "AUTHENTICATION",
+    RATE_LIMIT = "RATE_LIMIT",
+    API_ERROR = "API_ERROR",
+    INTERNAL = "INTERNAL",
+    USER_INPUT = "USER_INPUT"
+}
+/**
+ * Sanitize error message by removing sensitive information
+ *
+ * @param message - Raw error message
+ * @returns Sanitized message safe for user display
+ */
+export declare function sanitizeErrorMessage(message: string): string;
+/**
+ * Sanitize stack trace by removing sensitive paths
+ *
+ * @param stack - Raw stack trace
+ * @returns Sanitized stack trace
+ */
+export declare function sanitizeStackTrace(stack: string): string;
+/**
+ * Remove stack trace entirely (for user-facing errors)
+ *
+ * @param message - Error message with potential stack trace
+ * @returns Message without stack trace
+ */
+export declare function removeStackTrace(message: string): string;
+/**
+ * Categorize error and create user-friendly message
+ *
+ * @param error - Error object
+ * @returns Sanitized error with category and suggestion
+ */
+export declare function sanitizeError(error: Error | unknown): SanitizedError;
+/**
+ * Format sanitized error for user display
+ *
+ * @param sanitizedError - Sanitized error object
+ * @returns Formatted error message
+ */
+export declare function formatUserError(sanitizedError: SanitizedError): string;
+/**
+ * Create internal log message with full details (not sanitized)
+ *
+ * @param error - Original error
+ * @param context - Additional context
+ * @returns Detailed log message
+ */
+export declare function createInternalLogMessage(error: Error | unknown, context?: Record<string, unknown>): string;
+/**
+ * Safe error wrapper for user-facing operations
+ *
+ * @param operation - Async operation to execute
+ * @param errorHandler - Optional custom error handler
+ * @returns Result or sanitized error
+ *
+ * @example
+ * ```typescript
+ * const result = await safeExecute(
+ *   () => riskyOperation(),
+ *   (error) => console.error('Internal error:', error)
+ * );
+ *
+ * if (!result.success) {
+ *   console.log(formatUserError(result.error));
+ * }
+ * ```
+ */
+export declare function safeExecute<T>(operation: () => Promise<T>, errorHandler?: (error: Error, sanitized: SanitizedError) => void): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: SanitizedError;
+}>;