@agirails/sdk 2.0.1-beta → 2.0.2

package/src/cli/commands/batch.ts

@@ -0,0 +1,487 @@
+/**
+ * Batch Command - Execute multiple commands from a file
+ *
+ * Agent-first feature: Process commands in bulk.
+ * Perfect for:
+ * - Scripted workflows
+ * - Replaying transaction sequences
+ * - Automated testing
+ *
+ * Security: Commands are validated against an allowlist and arguments
+ * are passed as an array to avoid shell injection attacks.
+ *
+ * @module cli/commands/batch
+ */
+
+import * as fs from 'fs';
+import * as readline from 'readline';
+import { Command } from 'commander';
+import { Output, ExitCode, fmt } from '../utils/output';
+import { mapError } from '../utils/client';
+
+// ============================================================================
+// Security: Command Allowlist and Argument Parsing
+// ============================================================================
+
+/**
+ * Allowlist of valid ACTP subcommands.
+ * Only these commands can be executed through batch mode.
+ * This prevents command injection attacks.
+ */
+const VALID_SUBCOMMANDS = new Set([
+  'init', 'pay', 'tx', 'balance', 'mint', 'config',
+  'watch', 'simulate', 'time',
+]);
+
+/**
+ * Allowlist of valid 'tx' subcommands.
+ */
+const VALID_TX_SUBCOMMANDS = new Set([
+  'create', 'status', 'list', 'deliver', 'settle', 'cancel',
+]);
+
+/**
+ * Characters that are not allowed in command arguments.
+ * These could be used for shell injection attacks.
+ */
+const DANGEROUS_CHARS_PATTERN = /[;&|`$(){}[\]<>!\\'"]/;
+
+/**
+ * Parse a command string into an array of arguments safely.
+ * Does NOT use shell for parsing - handles quotes manually.
+ *
+ * @param command - Raw command string
+ * @returns Array of parsed arguments
+ * @throws Error if command contains dangerous characters
+ */
+function parseCommandArgs(command: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let inQuotes = false;
+  let quoteChar = '';
+
+  // Check for dangerous characters outside quotes
+  const cleanCommand = command.replace(/"[^"]*"|'[^']*'/g, ''); // Remove quoted strings
+  if (DANGEROUS_CHARS_PATTERN.test(cleanCommand)) {
+    throw new Error(
+      'Command contains potentially dangerous characters. ' +
+      'Shell metacharacters are not allowed for security reasons.'
+    );
+  }
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+
+    if (inQuotes) {
+      if (char === quoteChar) {
+        inQuotes = false;
+        quoteChar = '';
+      } else {
+        current += char;
+      }
+    } else if (char === '"' || char === "'") {
+      inQuotes = true;
+      quoteChar = char;
+    } else if (char === ' ' || char === '\t') {
+      if (current) {
+        args.push(current);
+        current = '';
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) {
+    args.push(current);
+  }
+
+  if (inQuotes) {
+    throw new Error('Unclosed quote in command');
+  }
+
+  return args;
+}
+
+/**
+ * Validate that a command only uses allowed subcommands.
+ *
+ * @param args - Parsed command arguments
+ * @returns true if command is valid
+ * @throws Error if command is not in allowlist
+ */
+function validateCommand(args: string[]): boolean {
+  if (args.length === 0) {
+    throw new Error('Empty command');
+  }
+
+  const subcommand = args[0];
+
+  if (subcommand === 'tx') {
+    if (args.length < 2) {
+      throw new Error('tx command requires a subcommand');
+    }
+    if (!VALID_TX_SUBCOMMANDS.has(args[1])) {
+      throw new Error(`Unknown tx subcommand: ${args[1]}. Allowed: ${Array.from(VALID_TX_SUBCOMMANDS).join(', ')}`);
+    }
+    return true;
+  }
+
+  if (!VALID_SUBCOMMANDS.has(subcommand)) {
+    throw new Error(`Unknown command: ${subcommand}. Allowed: ${Array.from(VALID_SUBCOMMANDS).join(', ')}`);
+  }
+
+  return true;
+}
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createBatchCommand(): Command {
+  const cmd = new Command('batch')
+    .description('Execute multiple commands from a file (agent-first feature)')
+    .argument('[file]', 'File containing commands (one per line), or - for stdin')
+    .option('--dry-run', 'Parse and validate commands without executing')
+    .option('--stop-on-error', 'Stop execution on first error', false)
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (file, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runBatch(file, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface BatchOptions {
+  dryRun?: boolean;
+  stopOnError?: boolean;
+}
+
+interface BatchResult {
+  line: number;
+  command: string;
+  status: 'success' | 'error' | 'skipped';
+  output?: string;
+  error?: string;
+  duration?: number;
+}
+
+async function runBatch(
+  file: string | undefined,
+  options: BatchOptions,
+  output: Output
+): Promise<void> {
+  // Read commands
+  let commands: string[];
+
+  if (!file || file === '-') {
+    // Read from stdin
+    commands = await readStdin();
+  } else {
+    // Read from file
+    if (!fs.existsSync(file)) {
+      throw new Error(`File not found: ${file}`);
+    }
+    commands = fs.readFileSync(file, 'utf-8').split('\n');
+  }
+
+  // Filter empty lines and comments
+  const commandsWithLine = commands
+    .map((line, index) => ({ line: index + 1, command: line.trim() }))
+    .filter(({ command }) => command && !command.startsWith('#'));
+
+  if (commandsWithLine.length === 0) {
+    output.warning('No commands to execute.');
+    return;
+  }
+
+  output.info(`Processing ${commandsWithLine.length} command(s)...`);
+  output.blank();
+
+  const results: BatchResult[] = [];
+  let successCount = 0;
+  let errorCount = 0;
+  let skippedCount = 0;
+
+  for (const { line, command } of commandsWithLine) {
+    const startTime = Date.now();
+
+    if (options.dryRun) {
+      // Dry run: just parse and validate
+      const parseResult = parseCommand(command);
+
+      if (parseResult.valid) {
+        results.push({
+          line,
+          command,
+          status: 'success',
+          output: `Would execute: ${parseResult.parsed}`,
+        });
+        successCount++;
+        outputDryRunResult(output, line, command, true, parseResult.parsed);
+      } else {
+        results.push({
+          line,
+          command,
+          status: 'error',
+          error: parseResult.error,
+        });
+        errorCount++;
+        outputDryRunResult(output, line, command, false, parseResult.error);
+
+        if (options.stopOnError) {
+          output.error('Stopping on error (--stop-on-error)');
+          break;
+        }
+      }
+    } else {
+      // Execute command
+      try {
+        const result = await executeCommand(command);
+        const duration = Date.now() - startTime;
+
+        results.push({
+          line,
+          command,
+          status: 'success',
+          output: result,
+          duration,
+        });
+        successCount++;
+        outputExecutionResult(output, line, command, true, result, duration);
+      } catch (error) {
+        const duration = Date.now() - startTime;
+        const errorMessage = (error as Error).message;
+
+        results.push({
+          line,
+          command,
+          status: 'error',
+          error: errorMessage,
+          duration,
+        });
+        errorCount++;
+        outputExecutionResult(output, line, command, false, errorMessage, duration);
+
+        if (options.stopOnError) {
+          output.error('Stopping on error (--stop-on-error)');
+          skippedCount = commandsWithLine.length - successCount - errorCount;
+          break;
+        }
+      }
+    }
+  }
+
+  // Summary
+  output.blank();
+  output.section('Batch Summary');
+  output.keyValue('Total Commands', commandsWithLine.length);
+  output.keyValue('Succeeded', successCount);
+  output.keyValue('Failed', errorCount);
+  if (skippedCount > 0) {
+    output.keyValue('Skipped', skippedCount);
+  }
+
+  // Exit with appropriate code
+  if (errorCount > 0) {
+    process.exit(ExitCode.ERROR);
+  }
+}
+
+/**
+ * Read commands from stdin
+ */
+async function readStdin(): Promise<string[]> {
+  return new Promise((resolve) => {
+    const lines: string[] = [];
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
+
+    rl.on('line', (line) => {
+      lines.push(line);
+    });
+
+    rl.on('close', () => {
+      resolve(lines);
+    });
+  });
+}
+
+/**
+ * Parse and validate a command (for dry-run)
+ *
+ * Security: Uses parseCommandArgs for safe argument parsing
+ * and validates against allowlist.
+ */
+function parseCommand(command: string): {
+  valid: boolean;
+  parsed?: string;
+  args?: string[];
+  error?: string;
+} {
+  try {
+    // Parse command safely (no shell interpretation)
+    const args = parseCommandArgs(command);
+
+    if (args.length === 0) {
+      return { valid: false, error: 'Empty command' };
+    }
+
+    // Validate against allowlist
+    validateCommand(args);
+
+    return {
+      valid: true,
+      parsed: `actp ${args.join(' ')}`,
+      args,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+/**
+ * Execute a command (by spawning a child process)
+ *
+ * SECURITY FIX: No longer uses shell interpolation.
+ * Arguments are passed as an array directly to the actp binary.
+ * This prevents command injection attacks.
+ */
+async function executeCommand(command: string): Promise<string> {
+  const { spawn } = await import('child_process');
+
+  return new Promise((resolve, reject) => {
+    // Parse command safely - no shell interpretation
+    let args: string[];
+    try {
+      args = parseCommandArgs(command);
+      validateCommand(args);
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    // Add --json flag for structured output
+    args.push('--json');
+
+    // SECURITY: Use shell: false and pass arguments as array
+    // This prevents any shell interpretation of the arguments
+    const child = spawn('actp', args, {
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env: { ...process.env },
+      shell: false, // CRITICAL: Do not use shell
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout.trim() || 'OK');
+      } else {
+        // Try to parse error from JSON output
+        try {
+          const errorObj = JSON.parse(stderr || stdout);
+          reject(new Error(errorObj.error?.message || 'Command failed'));
+        } catch {
+          reject(new Error(stderr.trim() || stdout.trim() || `Exit code: ${code}`));
+        }
+      }
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Output dry-run result
+ */
+function outputDryRunResult(
+  output: Output,
+  line: number,
+  command: string,
+  success: boolean,
+  message?: string
+): void {
+  if (output['mode'] === 'json') {
+    return; // JSON output is aggregated at the end
+  }
+
+  if (output['mode'] === 'quiet') {
+    console.log(success ? 'OK' : 'ERROR');
+    return;
+  }
+
+  const lineStr = `[${line}]`.padEnd(5);
+  const status = success ? fmt.green('VALID') : fmt.red('INVALID');
+  console.log(`${fmt.dim(lineStr)} ${status} ${fmt.dim(command)}`);
+  if (message && !success) {
+    console.log(`      ${fmt.red(message)}`);
+  }
+}
+
+/**
+ * Output execution result
+ */
+function outputExecutionResult(
+  output: Output,
+  line: number,
+  command: string,
+  success: boolean,
+  message: string,
+  durationMs: number
+): void {
+  if (output['mode'] === 'json') {
+    return; // JSON output is aggregated at the end
+  }
+
+  if (output['mode'] === 'quiet') {
+    console.log(success ? 'OK' : 'ERROR');
+    return;
+  }
+
+  const lineStr = `[${line}]`.padEnd(5);
+  const status = success ? fmt.green('OK') : fmt.red('FAIL');
+  const duration = fmt.dim(`(${durationMs}ms)`);
+  console.log(`${fmt.dim(lineStr)} ${status} ${command} ${duration}`);
+  if (!success) {
+    console.log(`      ${fmt.red(message)}`);
+  }
+}
+
+export { runBatch };

package/src/cli/commands/config.ts

@@ -0,0 +1,231 @@
+/**
+ * Config Command - View and modify CLI configuration
+ *
+ * Commands:
+ * - config show: Display current configuration
+ * - config set <key> <value>: Set a configuration value
+ * - config get <key>: Get a specific configuration value
+ *
+ * @module cli/commands/config
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import {
+  loadConfig,
+  updateConfig,
+  CLIConfig,
+  CLIMode,
+  validateAddress,
+  validatePrivateKey,
+} from '../utils/config';
+import { mapError } from '../utils/client';
+
+// ============================================================================
+// Main config Command
+// ============================================================================
+
+export function createConfigCommand(): Command {
+  const cmd = new Command('config')
+    .description('View and modify configuration');
+
+  cmd.addCommand(createConfigShowCommand());
+  cmd.addCommand(createConfigSetCommand());
+  cmd.addCommand(createConfigGetCommand());
+
+  return cmd;
+}
+
+// ============================================================================
+// config show
+// ============================================================================
+
+function createConfigShowCommand(): Command {
+  return new Command('show')
+    .description('Display current configuration')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      const output = new Output(options.json ? 'json' : 'human');
+
+      try {
+        const config = loadConfig();
+
+        // SECURITY FIX (C-1): Mask private key - show only last 4 chars
+        // Previous code showed 14 chars which reduces keyspace significantly
+        const displayConfig = {
+          ...config,
+          privateKey: config.privateKey
+            ? '****' + config.privateKey.slice(-4)
+            : undefined,
+        };
+
+        if (options.json) {
+          output.result(displayConfig);
+        } else {
+          output.section('ACTP Configuration');
+          output.keyValue('Mode', config.mode);
+          output.keyValue('Address', config.address);
+          output.keyValue('Version', config.version);
+          if (config.privateKey) {
+            output.keyValue('Private Key', '****' + config.privateKey.slice(-4));
+          }
+          if (config.rpcUrl) {
+            output.keyValue('RPC URL', config.rpcUrl);
+          }
+        }
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// config set
+// ============================================================================
+
+function createConfigSetCommand(): Command {
+  return new Command('set')
+    .description('Set a configuration value')
+    .argument('<key>', 'Configuration key (mode, address, privateKey, rpcUrl)')
+    .argument('<value>', 'Value to set')
+    .option('--json', 'Output as JSON')
+    .action(async (key, value, options) => {
+      const output = new Output(options.json ? 'json' : 'human');
+
+      try {
+        // Validate key
+        const validKeys = ['mode', 'address', 'privateKey', 'rpcUrl'];
+        if (!validKeys.includes(key)) {
+          throw new Error(
+            `Invalid config key: "${key}"\n` +
+              `Valid keys: ${validKeys.join(', ')}`
+          );
+        }
+
+        // Validate value based on key
+        switch (key) {
+          case 'mode': {
+            const validModes: CLIMode[] = ['mock', 'testnet', 'mainnet'];
+            if (!validModes.includes(value as CLIMode)) {
+              throw new Error(
+                `Invalid mode: "${value}"\n` +
+                  `Valid modes: ${validModes.join(', ')}`
+              );
+            }
+            break;
+          }
+
+          case 'address':
+            if (!validateAddress(value)) {
+              throw new Error(
+                `Invalid address: "${value}"\n` +
+                  'Expected 0x-prefixed 40-character hex string.'
+              );
+            }
+            break;
+
+          case 'privateKey':
+            if (!validatePrivateKey(value)) {
+              throw new Error(
+                `Invalid private key format.\n` +
+                  'Expected 64-character hex string (with or without 0x prefix).'
+              );
+            }
+            // Normalize: ensure no 0x prefix for storage
+            value = value.startsWith('0x') ? value.slice(2) : value;
+            break;
+
+          case 'rpcUrl':
+            if (!value.startsWith('http://') && !value.startsWith('https://')) {
+              throw new Error(
+                `Invalid RPC URL: "${value}"\n` +
+                  'Expected URL starting with http:// or https://'
+              );
+            }
+            break;
+        }
+
+        // Update config
+        const updates: Partial<CLIConfig> = { [key]: value };
+        if (key === 'address') {
+          updates.address = value.toLowerCase();
+        }
+
+        const newConfig = updateConfig(updates);
+
+        output.result({
+          [key]: key === 'privateKey' ? '****' + value.slice(-4) : value,
+          updated: true,
+        });
+
+        output.success(`Configuration updated: ${key}`);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// config get
+// ============================================================================
+
+function createConfigGetCommand(): Command {
+  return new Command('get')
+    .description('Get a specific configuration value')
+    .argument('<key>', 'Configuration key')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the value')
+    .action(async (key, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        const config = loadConfig();
+
+        const validKeys = ['mode', 'address', 'privateKey', 'rpcUrl', 'version'];
+        if (!validKeys.includes(key)) {
+          throw new Error(
+            `Invalid config key: "${key}"\n` +
+              `Valid keys: ${validKeys.join(', ')}`
+          );
+        }
+
+        const value = config[key as keyof CLIConfig];
+
+        // Mask private key
+        let displayValue = value;
+        if (key === 'privateKey' && value) {
+          displayValue = '****' + (value as string).slice(-4);
+        }
+
+        if (options.quiet) {
+          if (value !== undefined) {
+            console.log(key === 'privateKey' ? displayValue : value);
+          }
+        } else {
+          output.result({
+            key,
+            value: displayValue ?? null,
+          });
+        }
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}