@agirails/sdk 2.2.3 → 2.3.0

package/src/wallet/keystore.ts

@@ -0,0 +1,119 @@
+/**
+ * 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)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { Wallet } from 'ethers';
+
+// Cache keyed by resolved keystorePath to support multiple stateDirectories
+const _cache = new Map<string, { key: string; address: string }>();
+
+// Separate cache for env-var-resolved key (no path dependency)
+let _envCache: { key: string; address: string } | null = null;
+
+/**
+ * Validate that stateDirectory doesn't escape expected boundaries.
+ * Guards against path traversal when stateDirectory comes from user input.
+ */
+function validateStateDirectory(stateDirectory: string): void {
+  if (stateDirectory.includes('\0')) {
+    throw new Error('Invalid stateDirectory: null byte detected');
+  }
+  // Reject raw '..' in the input (before normalization resolves it)
+  // Catches both relative traversal (../../etc) and embedded traversal (/tmp/../../etc)
+  if (stateDirectory.includes('..')) {
+    throw new Error('Invalid stateDirectory: path traversal detected (..)');
+  }
+}
+
+/**
+ * Validate and normalize a raw private key string.
+ * Trims whitespace and verifies 0x-prefixed 64-char hex format.
+ */
+function validateRawKey(raw: string, source: string): string {
+  const trimmed = raw.trim();
+  if (!/^0x[0-9a-fA-F]{64}$/.test(trimmed)) {
+    throw new Error(
+      `Invalid private key from ${source}: expected 0x-prefixed 64-char hex string`
+    );
+  }
+  return trimmed;
+}
+
+/**
+ * Auto-resolve private key: env var → keystore → undefined.
+ * Never logs or prints the key itself.
+ */
+export async function resolvePrivateKey(
+  stateDirectory?: string
+): Promise<string | undefined> {
+  // 1. Env var (highest priority, backward compat)
+  if (process.env.ACTP_PRIVATE_KEY) {
+    if (_envCache) return _envCache.key;
+
+    const key = validateRawKey(process.env.ACTP_PRIVATE_KEY, 'ACTP_PRIVATE_KEY env var');
+    const address = new Wallet(key).address;
+    _envCache = { key, address };
+    return key;
+  }
+
+  // 2. Resolve keystore path
+  if (stateDirectory) {
+    validateStateDirectory(stateDirectory);
+  }
+  const actpDir = stateDirectory
+    ? path.join(stateDirectory, '.actp')
+    : path.join(process.cwd(), '.actp');
+  const keystorePath = path.resolve(actpDir, 'keystore.json');
+
+  // 3. Cache hit (keyed by resolved path)
+  const cached = _cache.get(keystorePath);
+  if (cached) return cached.key;
+
+  // 4. Keystore file
+  if (!fs.existsSync(keystorePath)) return undefined;
+
+  const password = process.env.ACTP_KEY_PASSWORD;
+  if (!password) {
+    throw new Error(
+      'Keystore found at ' + keystorePath + ' but ACTP_KEY_PASSWORD is not set.\n' +
+      'Set it: export ACTP_KEY_PASSWORD="your-password"'
+    );
+  }
+
+  const keystore = fs.readFileSync(keystorePath, 'utf-8');
+  const wallet = await Wallet.fromEncryptedJson(keystore, password);
+
+  _cache.set(keystorePath, { key: wallet.privateKey, address: wallet.address });
+  return wallet.privateKey;
+}
+
+/**
+ * Get cached address from last resolvePrivateKey() call.
+ * Works for both env-var and keystore resolution paths.
+ */
+export function getCachedAddress(stateDirectory?: string): string | undefined {
+  // Env var path
+  if (_envCache) return _envCache.address;
+
+  // Keystore path — look up by resolved path
+  const actpDir = stateDirectory
+    ? path.join(stateDirectory, '.actp')
+    : path.join(process.cwd(), '.actp');
+  const keystorePath = path.resolve(actpDir, 'keystore.json');
+  return _cache.get(keystorePath)?.address;
+}
+
+/**
+ * Clear all cached keys and addresses (for testing).
+ * @internal
+ */
+export function _clearCache(): void {
+  _cache.clear();
+  _envCache = null;
+}