@agirails/sdk 2.4.1 → 2.5.0

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