@agirails/sdk 2.4.2 → 2.5.0

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/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;
     }

package/src/wallet/keystore.ts

@@ -1,14 +1,16 @@
 /**
  * Keystore auto-resolution for ACTP wallets.
  *
- * Resolution order:
- *   1. ACTP_PRIVATE_KEY env var (backward compat, highest priority)
- *   2. .actp/keystore.json decrypted with ACTP_KEY_PASSWORD
- *   3. undefined (caller decides what to do)
+ * Resolution order (AIP-13):
+ *   1. ACTP_PRIVATE_KEY env var (policy-gated: mainnet/unknown = hard fail)
+ *   2. ACTP_KEYSTORE_BASE64 + ACTP_KEY_PASSWORD (deployment-safe, preferred)
+ *   3. .actp/keystore.json decrypted with ACTP_KEY_PASSWORD
+ *   4. undefined (caller decides what to do)
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { Wallet } from 'ethers';
+import { sdkLogger } from '../utils/Logger';
 
 /** 30-minute TTL for cached private keys */
 const CACHE_TTL_MS = 30 * 60 * 1000;
@@ -19,12 +21,20 @@ interface CacheEntry {
   expiresAt: number;
 }
 
+export interface ResolvePrivateKeyOptions {
+  /** Network mode: 'mainnet', 'testnet', or 'mock'. Controls ACTP_PRIVATE_KEY policy. */
+  network?: string;
+}
+
 // Cache keyed by resolved keystorePath to support multiple stateDirectories
 const _cache = new Map<string, CacheEntry>();
 
 // Separate cache for env-var-resolved key (no path dependency)
 let _envCache: CacheEntry | null = null;
 
+// Separate cache for base64-resolved key (no path dependency)
+let _base64Cache: CacheEntry | null = null;
+
 function isExpired(entry: CacheEntry): boolean {
   return Date.now() >= entry.expiresAt;
 }
@@ -59,14 +69,58 @@ function validateRawKey(raw: string, source: string): string {
 }
 
 /**
- * Auto-resolve private key: env var → keystore → undefined.
+ * Determine the effective network for ACTP_PRIVATE_KEY policy.
+ * Falls back to ACTP_NETWORK env var. Null means unknown (fail-closed).
+ */
+function getEffectiveNetwork(options?: ResolvePrivateKeyOptions): string | null {
+  return options?.network ?? process.env.ACTP_NETWORK ?? null;
+}
+
+/**
+ * Enforce ACTP_PRIVATE_KEY policy based on network (AIP-13).
+ * - mainnet/unknown: hard fail
+ * - testnet: warn once (on first resolution, not cache hits)
+ * - mock: silent
+ */
+function enforcePrivateKeyPolicy(network: string | null): void {
+  if (network === 'mock') return;
+
+  if (network === 'testnet') {
+    // Warn once (only on first resolution — _envCache is null)
+    if (_envCache === null) {
+      sdkLogger.warn(
+        'ACTP_PRIVATE_KEY is deprecated. Use ACTP_KEYSTORE_BASE64 instead.\n' +
+        'Run: actp deploy:env'
+      );
+    }
+    return;
+  }
+
+  // mainnet or unknown (null) — fail-closed
+  const networkLabel = network === 'mainnet' ? 'production' : 'unknown network (fail-closed)';
+  throw new Error(
+    `ACTP_PRIVATE_KEY is not allowed in ${networkLabel}. Use ACTP_KEYSTORE_BASE64 instead.\n` +
+    'Run: actp deploy:env\n' +
+    'If this is testnet, set ACTP_NETWORK=testnet'
+  );
+}
+
+/**
+ * Auto-resolve private key: env var → base64 keystore → file keystore → undefined.
  * Never logs or prints the key itself.
+ *
+ * @param stateDirectory - Directory containing .actp/ (defaults to cwd)
+ * @param options - Options including network for ACTP_PRIVATE_KEY policy
  */
 export async function resolvePrivateKey(
-  stateDirectory?: string
+  stateDirectory?: string,
+  options?: ResolvePrivateKeyOptions
 ): Promise<string | undefined> {
-  // 1. Env var (highest priority, backward compat)
+  // 1. ACTP_PRIVATE_KEY (highest priority, policy-gated)
   if (process.env.ACTP_PRIVATE_KEY) {
+    const network = getEffectiveNetwork(options);
+    enforcePrivateKeyPolicy(network);
+
     if (_envCache && !isExpired(_envCache)) return _envCache.key;
 
     const key = validateRawKey(process.env.ACTP_PRIVATE_KEY, 'ACTP_PRIVATE_KEY env var');
@@ -75,7 +129,54 @@ export async function resolvePrivateKey(
     return key;
   }
 
-  // 2. Resolve keystore path
+  // 2. ACTP_KEYSTORE_BASE64 (deployment-safe, preferred for production)
+  if (process.env.ACTP_KEYSTORE_BASE64) {
+    if (_base64Cache && !isExpired(_base64Cache)) return _base64Cache.key;
+
+    const raw = process.env.ACTP_KEYSTORE_BASE64.replace(/\s/g, '');
+    let decoded: string;
+    try {
+      decoded = Buffer.from(raw, 'base64').toString('utf-8');
+    } catch {
+      throw new Error(
+        'ACTP_KEYSTORE_BASE64 is not valid base64.\n' +
+        'Run: actp deploy:env'
+      );
+    }
+
+    try {
+      JSON.parse(decoded);
+    } catch {
+      throw new Error(
+        'ACTP_KEYSTORE_BASE64 is not valid encrypted keystore JSON.\n' +
+        'Run: actp deploy:env'
+      );
+    }
+
+    const password = process.env.ACTP_KEY_PASSWORD;
+    if (!password) {
+      throw new Error(
+        'ACTP_KEYSTORE_BASE64 is set but ACTP_KEY_PASSWORD is not set.\n' +
+        'Set it: export ACTP_KEY_PASSWORD="your-password"'
+      );
+    }
+
+    let wallet: Wallet;
+    try {
+      wallet = (await Wallet.fromEncryptedJson(decoded, password)) as Wallet;
+    } catch (err) {
+      // Sanitize: do not leak keystore content in error messages
+      const message = err instanceof Error ? err.message : 'unknown error';
+      throw new Error(
+        `Failed to decrypt ACTP_KEYSTORE_BASE64: ${message}`
+      );
+    }
+
+    _base64Cache = { key: wallet.privateKey, address: wallet.address, expiresAt: Date.now() + CACHE_TTL_MS };
+    return wallet.privateKey;
+  }
+
+  // 3. Resolve keystore path
   if (stateDirectory) {
     validateStateDirectory(stateDirectory);
   }
@@ -84,12 +185,12 @@ export async function resolvePrivateKey(
     : path.join(process.cwd(), '.actp');
   const keystorePath = path.resolve(actpDir, 'keystore.json');
 
-  // 3. Cache hit (keyed by resolved path, with TTL)
+  // 4. Cache hit (keyed by resolved path, with TTL)
   const cached = _cache.get(keystorePath);
   if (cached && !isExpired(cached)) return cached.key;
   if (cached) _cache.delete(keystorePath); // expired
 
-  // 4. Keystore file
+  // 5. Keystore file
   if (!fs.existsSync(keystorePath)) return undefined;
 
   const password = process.env.ACTP_KEY_PASSWORD;
@@ -109,12 +210,15 @@ export async function resolvePrivateKey(
 
 /**
  * Get cached address from last resolvePrivateKey() call.
- * Works for both env-var and keystore resolution paths.
+ * Works for env-var, base64, and keystore resolution paths.
  */
 export function getCachedAddress(stateDirectory?: string): string | undefined {
   // Env var path
   if (_envCache && !isExpired(_envCache)) return _envCache.address;
 
+  // Base64 path
+  if (_base64Cache && !isExpired(_base64Cache)) return _base64Cache.address;
+
   // Keystore path — look up by resolved path
   const actpDir = stateDirectory
     ? path.join(stateDirectory, '.actp')
@@ -132,4 +236,5 @@ export function getCachedAddress(stateDirectory?: string): string | undefined {
 export function _clearCache(): void {
   _cache.clear();
   _envCache = null;
+  _base64Cache = null;
 }