@agirails/sdk 2.4.2 → 2.5.2

package/src/cli/commands/deploy-check.ts

@@ -0,0 +1,364 @@
+/**
+ * Deploy:check Command - Pre-deploy security audit (AIP-13)
+ *
+ * Scans the project for common deployment security issues:
+ * - Missing ignore files
+ * - Raw private keys in env files, Dockerfiles, CI configs
+ * - Symlinked keystore
+ * - Incorrect file permissions
+ *
+ * Exit code 0: all checks pass (warnings allowed)
+ * Exit code 1: at least one FAIL check
+ *
+ * @module cli/commands/deploy-check
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { getActpDir } from '../utils/config';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+type CheckSeverity = 'FAIL' | 'WARN';
+type CheckResult = 'PASS' | 'FAIL' | 'WARN' | 'SKIP';
+
+interface CheckOutput {
+  name: string;
+  result: CheckResult;
+  message?: string;
+}
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createDeployCheckCommand(): Command {
+  const cmd = new Command('deploy:check')
+    .description('Pre-deploy security audit (AIP-13)')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Only show failures')
+    .action(async (options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        const exitCode = runDeployCheck(options, output);
+        process.exit(exitCode);
+      } catch (error) {
+        output.errorResult({
+          code: 'DEPLOY_CHECK_FAILED',
+          message: (error as Error).message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/** Regex matching a raw private key pattern */
+const RAW_KEY_PATTERN = /0x[0-9a-fA-F]{64}/;
+const RAW_KEY_ENV_PATTERN = /ACTP_PRIVATE_KEY\s*=\s*0x/;
+
+interface DeployCheckOptions {
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export function runDeployCheck(options: DeployCheckOptions, output: Output): number {
+  const projectRoot = process.cwd();
+  const actpDir = getActpDir(projectRoot);
+  const results: CheckOutput[] = [];
+  let failCount = 0;
+  let warnCount = 0;
+  let passCount = 0;
+
+  // ── FAIL checks ──────────────────────────────────────────────────────
+
+  // 1. .actp/ in .gitignore
+  results.push(checkIgnoreFile(projectRoot, '.gitignore', '.actp', 'FAIL'));
+
+  // 2. .actp/ in .dockerignore
+  results.push(checkIgnoreFile(projectRoot, '.dockerignore', '.actp', 'FAIL'));
+
+  // 3. No ACTP_PRIVATE_KEY in .env* files
+  results.push(checkNoRawKeysInEnvFiles(projectRoot));
+
+  // 4. No raw keys in Dockerfiles
+  results.push(checkNoRawKeysInFiles(
+    projectRoot,
+    ['Dockerfile', 'Dockerfile.*', 'docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml'],
+    'No raw keys in Dockerfiles'
+  ));
+
+  // 5. No raw keys in CI/workflow files
+  results.push(checkNoRawKeysInCIFiles(projectRoot));
+
+  // 6. Keystore is not a symlink
+  results.push(checkKeystoreNotSymlink(actpDir));
+
+  // ── WARN checks ──────────────────────────────────────────────────────
+
+  // 7. ACTP_KEYSTORE_BASE64 or keystore.json exists
+  results.push(checkKeystoreAvailable(actpDir));
+
+  // 8. Keystore file permissions (POSIX only)
+  results.push(checkKeystorePermissions(actpDir));
+
+  // ── Output ───────────────────────────────────────────────────────────
+
+  for (const check of results) {
+    if (check.result === 'FAIL') failCount++;
+    else if (check.result === 'WARN') warnCount++;
+    else if (check.result === 'PASS') passCount++;
+  }
+
+  if (options.json) {
+    output.result({
+      checks: results,
+      summary: { passed: passCount, warnings: warnCount, failed: failCount },
+    });
+  } else {
+    output.print('actp deploy:check');
+    for (const check of results) {
+      if (options.quiet && check.result !== 'FAIL') continue;
+      const tag = `[${check.result}]`;
+      const msg = check.message ? ` ${check.message}` : '';
+      output.print(`  ${tag} ${check.name}${msg}`);
+    }
+    output.print('');
+    output.print(`  ${passCount} passed, ${warnCount} warnings, ${failCount} failed`);
+  }
+
+  return failCount > 0 ? ExitCode.ERROR : ExitCode.SUCCESS;
+}
+
+// ============================================================================
+// Individual Checks
+// ============================================================================
+
+function checkIgnoreFile(
+  projectRoot: string,
+  fileName: string,
+  entry: string,
+  _severity: CheckSeverity
+): CheckOutput {
+  const filePath = path.join(projectRoot, fileName);
+  const name = `${entry} in ${fileName}`;
+
+  if (!fs.existsSync(filePath)) {
+    return { name, result: 'FAIL', message: `${fileName} does not exist` };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  if (content.includes(entry)) {
+    return { name, result: 'PASS' };
+  }
+
+  return { name, result: 'FAIL', message: `${entry} not found in ${fileName}` };
+}
+
+function checkNoRawKeysInEnvFiles(projectRoot: string): CheckOutput {
+  const name = 'No raw keys in .env files';
+  const envFiles = findMatchingFiles(projectRoot, ['.env', '.env.*', '.env.local', '.env.production']);
+
+  for (const file of envFiles) {
+    const content = safeReadFile(file);
+    if (content && (RAW_KEY_PATTERN.test(content) || RAW_KEY_ENV_PATTERN.test(content))) {
+      return { name, result: 'FAIL', message: `Raw key found in ${path.basename(file)}` };
+    }
+  }
+
+  return { name, result: 'PASS' };
+}
+
+function checkNoRawKeysInFiles(
+  projectRoot: string,
+  patterns: string[],
+  name: string
+): CheckOutput {
+  const files = findMatchingFiles(projectRoot, patterns);
+
+  for (const file of files) {
+    const content = safeReadFile(file);
+    if (content && RAW_KEY_PATTERN.test(content)) {
+      return { name, result: 'FAIL', message: `Raw key found in ${path.basename(file)}` };
+    }
+  }
+
+  return { name, result: 'PASS' };
+}
+
+function checkNoRawKeysInCIFiles(projectRoot: string): CheckOutput {
+  const name = 'No raw keys in CI/workflow files';
+
+  // Collect all CI-related files
+  const files: string[] = [];
+
+  // GitHub workflows
+  const workflowDir = path.join(projectRoot, '.github', 'workflows');
+  if (fs.existsSync(workflowDir)) {
+    try {
+      const entries = fs.readdirSync(workflowDir);
+      for (const entry of entries) {
+        if (entry.endsWith('.yml') || entry.endsWith('.yaml')) {
+          files.push(path.join(workflowDir, entry));
+        }
+      }
+    } catch { /* ignore read errors */ }
+  }
+
+  // Platform config files
+  const platformFiles = [
+    'railway.json', 'fly.toml', 'vercel.json',
+    'pm2.config.js', 'pm2.config.cjs', 'ecosystem.config.js', 'ecosystem.config.cjs',
+  ];
+  for (const pf of platformFiles) {
+    const fp = path.join(projectRoot, pf);
+    if (fs.existsSync(fp)) files.push(fp);
+  }
+
+  for (const file of files) {
+    const content = safeReadFile(file);
+    if (content && (RAW_KEY_PATTERN.test(content) || RAW_KEY_ENV_PATTERN.test(content))) {
+      return { name, result: 'FAIL', message: `Raw key found in ${path.relative(projectRoot, file)}` };
+    }
+  }
+
+  return { name, result: 'PASS' };
+}
+
+function checkKeystoreNotSymlink(actpDir: string): CheckOutput {
+  const name = 'Keystore is not a symlink';
+  const keystorePath = path.join(actpDir, 'keystore.json');
+
+  if (!fs.existsSync(keystorePath)) {
+    return { name, result: 'PASS' };
+  }
+
+  try {
+    const stat = fs.lstatSync(keystorePath);
+    if (stat.isSymbolicLink()) {
+      return { name, result: 'FAIL', message: 'keystore.json is a symlink (security risk)' };
+    }
+  } catch { /* ignore */ }
+
+  return { name, result: 'PASS' };
+}
+
+function checkKeystoreAvailable(actpDir: string): CheckOutput {
+  const name = 'Keystore available';
+  const keystorePath = path.join(actpDir, 'keystore.json');
+
+  if (process.env.ACTP_KEYSTORE_BASE64) {
+    return { name, result: 'PASS' };
+  }
+
+  if (fs.existsSync(keystorePath)) {
+    return { name, result: 'PASS' };
+  }
+
+  return { name, result: 'WARN', message: 'ACTP_KEYSTORE_BASE64 not set (OK for local dev)' };
+}
+
+function checkKeystorePermissions(actpDir: string): CheckOutput {
+  const name = 'Keystore file permissions';
+  const keystorePath = path.join(actpDir, 'keystore.json');
+
+  // Skip on Windows
+  if (process.platform === 'win32') {
+    return { name, result: 'SKIP', message: 'Permission check skipped on Windows' };
+  }
+
+  if (!fs.existsSync(keystorePath)) {
+    return { name, result: 'PASS' };
+  }
+
+  try {
+    const stat = fs.statSync(keystorePath);
+    const mode = stat.mode & 0o777;
+    if (mode === 0o600) {
+      return { name, result: 'PASS' };
+    }
+    return { name, result: 'WARN', message: `Permissions are 0o${mode.toString(8)} (expected 0o600)` };
+  } catch {
+    return { name, result: 'WARN', message: 'Could not check file permissions' };
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Directories to skip during recursive scan */
+const SKIP_DIRS = new Set(['node_modules', '.git', '.actp', 'dist', 'build', '.next', 'coverage']);
+
+/** Max recursion depth to prevent runaway scans */
+const MAX_SCAN_DEPTH = 5;
+
+function findMatchingFiles(projectRoot: string, patterns: string[], maxDepth = MAX_SCAN_DEPTH): string[] {
+  const files: string[] = [];
+  walkDir(projectRoot, patterns, files, 0, maxDepth);
+  return files;
+}
+
+function walkDir(dir: string, patterns: string[], files: string[], depth: number, maxDepth: number): void {
+  if (depth > maxDepth) return;
+
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch { return; }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+
+    // Match files against patterns
+    for (const pattern of patterns) {
+      if (matchPattern(entry, pattern)) {
+        try {
+          if (fs.statSync(fullPath).isFile()) {
+            files.push(fullPath);
+          }
+        } catch { /* ignore */ }
+        break;
+      }
+    }
+
+    // Recurse into subdirectories (skip noise dirs)
+    if (!SKIP_DIRS.has(entry)) {
+      try {
+        if (fs.statSync(fullPath).isDirectory()) {
+          walkDir(fullPath, patterns, files, depth + 1, maxDepth);
+        }
+      } catch { /* ignore */ }
+    }
+  }
+}
+
+function matchPattern(filename: string, pattern: string): boolean {
+  // Simple glob: support * and exact match
+  if (pattern === filename) return true;
+  if (pattern.includes('*')) {
+    const regex = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+    return regex.test(filename);
+  }
+  return false;
+}
+
+function safeReadFile(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}

package/src/cli/commands/deploy-env.ts

@@ -0,0 +1,120 @@
+/**
+ * Deploy:env Command - Generate deployment environment variables (AIP-13)
+ *
+ * Reads .actp/keystore.json, base64-encodes it, and outputs env vars
+ * ready for any deployment platform (Railway, Vercel, Fly.io, Hetzner, etc.).
+ *
+ * @module cli/commands/deploy-env
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { getActpDir } from '../utils/config';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createDeployEnvCommand(): Command {
+  const cmd = new Command('deploy:env')
+    .description('Generate deployment env vars from keystore (AIP-13)')
+    .option('--format <format>', 'Output format: shell (default), docker, json', 'shell')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Output only the base64 string (for piping)')
+    .action(async (options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        runDeployEnv(options, output);
+      } catch (error) {
+        output.errorResult({
+          code: 'DEPLOY_ENV_FAILED',
+          message: (error as Error).message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface DeployEnvOptions {
+  format: string;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+export function runDeployEnv(options: DeployEnvOptions, output: Output): void {
+  const projectRoot = process.cwd();
+  const actpDir = getActpDir(projectRoot);
+  const keystorePath = path.join(actpDir, 'keystore.json');
+
+  if (!fs.existsSync(keystorePath)) {
+    throw new Error(
+      'No keystore found at ' + keystorePath + '\n' +
+      'Run "actp init" first to generate a wallet.'
+    );
+  }
+
+  const keystoreContent = fs.readFileSync(keystorePath, 'utf-8');
+
+  // Validate it's valid JSON
+  try {
+    JSON.parse(keystoreContent);
+  } catch {
+    throw new Error('Keystore file is corrupted (not valid JSON).');
+  }
+
+  const base64 = Buffer.from(keystoreContent).toString('base64');
+
+  // Quiet mode: just the base64 string (for piping)
+  if (options.quiet) {
+    output.result({ keystoreBase64: base64 }, { quietKey: 'keystoreBase64' });
+    return;
+  }
+
+  // JSON mode
+  if (options.json || options.format === 'json') {
+    output.result({
+      keystoreBase64: base64,
+      passwordVar: 'ACTP_KEY_PASSWORD',
+    });
+    return;
+  }
+
+  // Docker format
+  if (options.format === 'docker') {
+    output.print('# Add to your Dockerfile:');
+    output.print(`ENV ACTP_KEYSTORE_BASE64="${base64}"`);
+    output.print('ENV ACTP_KEY_PASSWORD="<your keystore password>"');
+    output.print('');
+    output.print('# WARNING: Prefer build args or secrets over ENV for sensitive values.');
+    return;
+  }
+
+  // Shell format (default)
+  output.print('# Set these environment variables on your deployment platform:');
+  output.print(`ACTP_KEYSTORE_BASE64=${base64}`);
+  output.print('ACTP_KEY_PASSWORD=<your keystore password>');
+  output.print('');
+  output.print('# SECURITY BEST PRACTICE:');
+  output.print('# Store ACTP_KEYSTORE_BASE64 and ACTP_KEY_PASSWORD in SEPARATE secret scopes');
+  output.print('# where your platform supports it (e.g., different secret groups, vaults, or teams).');
+  output.print('# This preserves the two-factor security model.');
+  output.print('#');
+  output.print('# WARNING: Never echo these values in CI/CD logs or commit them to git.');
+  output.print('');
+  output.print('# Platform-specific examples:');
+  output.print(`# Railway:  railway variables set ACTP_KEYSTORE_BASE64="${base64}"`);
+  output.print('# Vercel:   vercel env add ACTP_KEYSTORE_BASE64');
+  output.print(`# Fly.io:   fly secrets set ACTP_KEYSTORE_BASE64="${base64}"`);
+  output.print('# Hetzner:  Add to your .env on the server (ensure .env is in .gitignore)');
+}

package/src/cli/commands/init.ts

@@ -14,6 +14,8 @@ import { Command } from 'commander';
 import {
   saveConfig,
   addToGitignore,
+  addToDockerignore,
+  addToRailwayignore,
   isInitialized,
   getActpDir,
   CLIConfig,
@@ -236,13 +238,25 @@ async function runInit(options: InitOptions, output: Output, cmd?: Command): Pro
     output.info('Minted 10,000 USDC to your address');
   }
 
-  // Add to gitignore
+  // Add to ignore files (AIP-13: gitignore + dockerignore + railwayignore)
   try {
     addToGitignore(projectRoot);
     output.success('Added .actp/ to .gitignore');
   } catch {
     output.warning('Could not update .gitignore (may not exist)');
   }
+  try {
+    addToDockerignore(projectRoot);
+    output.success('Added .actp/ to .dockerignore');
+  } catch {
+    output.warning('Could not update .dockerignore');
+  }
+  try {
+    addToRailwayignore(projectRoot);
+    output.success('Added .actp/ to .railwayignore');
+  } catch {
+    output.warning('Could not update .railwayignore');
+  }
 
   // Output result
   output.blank();

package/src/cli/commands/publish.ts

@@ -394,7 +394,7 @@ async function activateOnTestnet(
   const { buildActivationBatch, buildTestnetMintBatch } = await import('../../wallet/aa/TransactionBatcher');
   const { getOnChainAgentState, detectLazyPublishScenario } = await import('../../ACTPClient');
 
-  const privateKey = await resolvePrivateKey(projectRoot);
+  const privateKey = await resolvePrivateKey(projectRoot, { network: 'testnet' });
   if (!privateKey) {
     throw new Error('No wallet found. Cannot activate on testnet.');
   }

package/src/cli/commands/register.ts

@@ -85,7 +85,7 @@ async function runRegister(
   }
 
   // Resolve private key
-  const privateKey = await resolvePrivateKey(projectRoot);
+  const privateKey = await resolvePrivateKey(projectRoot, { network: config.mode });
   if (!privateKey) {
     throw new Error(
       'No wallet found. Run "actp init" first to generate a wallet.'

package/src/cli/index.ts

@@ -52,6 +52,8 @@ import { createPublishCommand } from './commands/publish';
 import { createPullCommand } from './commands/pull';
 import { createDiffCommand } from './commands/diff';
 import { createRegisterCommand } from './commands/register';
+import { createDeployEnvCommand } from './commands/deploy-env';
+import { createDeployCheckCommand } from './commands/deploy-check';
 
 // ============================================================================
 // Program Setup
@@ -104,6 +106,10 @@ program.addCommand(createDiffCommand());
 // AIP-12: Gas-free registration
 program.addCommand(createRegisterCommand());
 
+// AIP-13: Deployment security
+program.addCommand(createDeployEnvCommand());
+program.addCommand(createDeployCheckCommand());
+
 // ============================================================================
 // Error Handling
 // ============================================================================

package/src/cli/utils/client.ts

@@ -11,7 +11,7 @@
 
 import * as os from 'os';
 import { ACTPClient, ACTPClientConfig } from '../../ACTPClient';
-import { loadConfig, validateConfigForMode } from './config';
+import { loadConfig } from './config';
 
 // ============================================================================
 // Security: Path Sanitization
@@ -54,8 +54,10 @@ export async function createClient(
   // Load configuration
   const config = loadConfig(projectRoot);
 
-  // Validate config for the mode
-  validateConfigForMode(config);
+  // NOTE: We intentionally do NOT call validateConfigForMode() here.
+  // ACTPClient.create() handles keystore resolution (AIP-13) and provides
+  // proper error messages if no credentials are found. Premature validation
+  // would block keystore/env-var-based auth flows.
 
   // Build client config
   const clientConfig: ACTPClientConfig = {

package/src/cli/utils/config.ts

@@ -319,3 +319,71 @@ export function addToGitignore(projectRoot: string = process.cwd()): void {
 
   fs.writeFileSync(gitignorePath, newContent, 'utf-8');
 }
+
+// ============================================================================
+// Ignore File Management (AIP-13)
+// ============================================================================
+
+const IGNORE_ENTRIES = ['.actp/', '.env', '.env.*', 'node_modules/'];
+const IGNORE_HEADER = '# ACTP deployment security (AIP-13)';
+
+/**
+ * Validate that a file path is not a symlink.
+ * Throws if the path exists and is a symlink (security: prevents symlink attacks).
+ */
+function assertNotSymlink(filePath: string): void {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `Refusing to write ${path.basename(filePath)}: path is a symlink. Remove the symlink and retry.`
+      );
+    }
+  } catch (err) {
+    // Re-throw symlink errors; ENOENT (file doesn't exist) is fine
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Add standard ignore entries to a file (idempotent).
+ * Creates the file if it doesn't exist.
+ */
+function addIgnoreEntries(filePath: string): void {
+  assertNotSymlink(filePath);
+
+  let content = '';
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf-8');
+  }
+
+  // Only add entries that are missing (check each individually)
+  const missingEntries = IGNORE_ENTRIES.filter(entry => !content.includes(entry));
+  if (missingEntries.length === 0) return;
+
+  const newContent =
+    content +
+    (content.length > 0 && !content.endsWith('\n') ? '\n' : '') +
+    IGNORE_HEADER + '\n' +
+    missingEntries.join('\n') + '\n';
+
+  fs.writeFileSync(filePath, newContent, 'utf-8');
+}
+
+/**
+ * Add .actp/ and related entries to .dockerignore (AIP-13).
+ * Creates the file if it doesn't exist. Idempotent.
+ * Throws if .dockerignore is a symlink.
+ */
+export function addToDockerignore(projectRoot: string = process.cwd()): void {
+  addIgnoreEntries(path.join(projectRoot, '.dockerignore'));
+}
+
+/**
+ * Add .actp/ and related entries to .railwayignore (AIP-13).
+ * Creates the file if it doesn't exist. Idempotent.
+ * Throws if .railwayignore is a symlink.
+ */
+export function addToRailwayignore(projectRoot: string = process.cwd()): void {
+  addIgnoreEntries(path.join(projectRoot, '.railwayignore'));
+}

package/src/level0/request.ts

@@ -320,7 +320,7 @@ async function resolveKeyIfNeeded(
 ): Promise<string | undefined> {
   if (wallet && wallet !== 'auto') return undefined; // explicit wallet, skip auto-detect
   if (network !== 'testnet' && network !== 'mainnet') return undefined;
-  return resolvePrivateKey(stateDirectory);
+  return resolvePrivateKey(stateDirectory, { network });
 }
 
 /**

package/src/level1/Agent.ts

@@ -1391,7 +1391,7 @@ export class Agent extends EventEmitter {
   private async getPrivateKey(): Promise<string | undefined> {
     if (!this.config.wallet || this.config.wallet === 'auto') {
       if (this.network === 'testnet' || this.network === 'mainnet') {
-        return resolvePrivateKey(this.config.stateDirectory);
+        return resolvePrivateKey(this.config.stateDirectory, { network: this.network });
       }
       return undefined;
     }