@agirails/sdk 2.4.2 → 2.5.0

package/dist/wallet/keystore.js

@@ -27,20 +27,24 @@ exports._clearCache = exports.getCachedAddress = exports.resolvePrivateKey = voi
 /**
  * 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)
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const ethers_1 = require("ethers");
+const Logger_1 = require("../utils/Logger");
 /** 30-minute TTL for cached private keys */
 const CACHE_TTL_MS = 30 * 60 * 1000;
 // Cache keyed by resolved keystorePath to support multiple stateDirectories
 const _cache = new Map();
 // Separate cache for env-var-resolved key (no path dependency)
 let _envCache = null;
+// Separate cache for base64-resolved key (no path dependency)
+let _base64Cache = null;
 function isExpired(entry) {
     return Date.now() >= entry.expiresAt;
 }
@@ -70,12 +74,47 @@ function validateRawKey(raw, source) {
     return trimmed;
 }
 /**
- * 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) {
+    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) {
+    if (network === 'mock')
+        return;
+    if (network === 'testnet') {
+        // Warn once (only on first resolution — _envCache is null)
+        if (_envCache === null) {
+            Logger_1.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
  */
-async function resolvePrivateKey(stateDirectory) {
-    // 1. Env var (highest priority, backward compat)
+async function resolvePrivateKey(stateDirectory, options) {
+    // 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');
@@ -83,7 +122,44 @@ async function resolvePrivateKey(stateDirectory) {
         _envCache = { key, address, expiresAt: Date.now() + CACHE_TTL_MS };
         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;
+        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;
+        try {
+            wallet = (await ethers_1.Wallet.fromEncryptedJson(decoded, password));
+        }
+        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);
     }
@@ -91,13 +167,13 @@ async function resolvePrivateKey(stateDirectory) {
         ? path.join(stateDirectory, '.actp')
         : 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;
@@ -113,12 +189,15 @@ async function resolvePrivateKey(stateDirectory) {
 exports.resolvePrivateKey = 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.
  */
 function getCachedAddress(stateDirectory) {
     // 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')
@@ -137,6 +216,7 @@ exports.getCachedAddress = getCachedAddress;
 function _clearCache() {
     _cache.clear();
     _envCache = null;
+    _base64Cache = null;
 }
 exports._clearCache = _clearCache;
 //# sourceMappingURL=keystore.js.map

package/dist/wallet/keystore.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agirails/sdk",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "AGIRAILS SDK for the ACTP (Agent Commerce Transaction Protocol) - Unified mock + blockchain support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/ACTPClient.ts

@@ -736,7 +736,7 @@ export class ACTPClient {
           // Auto-detect private key from keystore / env var if not provided
           if (!config.privateKey) {
             const { resolvePrivateKey } = await import('./wallet/keystore');
-            const resolved = await resolvePrivateKey(config.stateDirectory);
+            const resolved = await resolvePrivateKey(config.stateDirectory, { network: config.mode });
             if (resolved) {
               config = { ...config, privateKey: resolved };
             } else {

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)');
+}