@absol-labs/agent 0.7.3 → 0.9.0

package/src/wallet/encrypted-file-credential-store.ts

@@ -0,0 +1,341 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+  scrypt,
+} from "node:crypto";
+import {
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import {
+  AutonomousWalletError,
+  isRecord,
+  validateStoredRecord,
+  type AutonomousWalletCredentialStore,
+  type AutonomousWalletRecord,
+  type CredentialStoreDurabilityReport,
+} from "./autonomous-wallet-store.js";
+
+const scryptAsync = promisify(scrypt) as (
+  secret: string | Buffer,
+  salt: Buffer,
+  keylen: number,
+  options: { readonly N: number; readonly r: number; readonly p: number },
+) => Promise<Buffer>;
+
+/** Environment variable holding the externally-managed encryption secret. */
+export const METRIK_WALLET_ENCRYPTION_KEY_ENV = "METRIK_WALLET_ENCRYPTION_KEY";
+/** Environment variable overriding where encrypted wallet files are written. */
+export const METRIK_WALLET_STORE_DIR_ENV = "METRIK_WALLET_STORE_DIR";
+
+const ENVELOPE_VERSION = 1;
+const CIPHER = "aes-256-gcm";
+const KEY_LENGTH = 32;
+const IV_LENGTH = 12;
+const SALT_LENGTH = 16;
+const SCRYPT_PARAMETERS = Object.freeze({ N: 16_384, r: 8, p: 1 });
+const MINIMUM_SECRET_LENGTH = 16;
+const FILE_MODE = 0o600;
+const DIRECTORY_MODE = 0o700;
+
+export interface EncryptedFileCredentialStoreOptions {
+  /**
+   * Directory holding one encrypted file per store key. Defaults to
+   * `$METRIK_WALLET_STORE_DIR`, else `~/.metrik/autonomous-wallets`.
+   */
+  readonly directory?: string;
+  /**
+   * Encryption secret. Defaults to `$METRIK_WALLET_ENCRYPTION_KEY`. Supply it
+   * from a platform secret manager (AWS/GCP Secrets Manager, Vault, a
+   * Docker/Kubernetes secret) — never commit it next to the encrypted file.
+   */
+  readonly encryptionKey?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+interface Envelope {
+  readonly v: number;
+  readonly cipher: string;
+  readonly kdf: {
+    readonly name: "scrypt";
+    readonly N: number;
+    readonly r: number;
+    readonly p: number;
+    readonly saltBase64: string;
+  };
+  readonly ivBase64: string;
+  readonly tagBase64: string;
+  readonly ciphertextBase64: string;
+  readonly keyDigest: string;
+}
+
+/**
+ * Durable credential store for headless hosts (servers, containers, VMs, CI
+ * runners) that have no OS credential manager.
+ *
+ * The wallet record is encrypted at rest with AES-256-GCM under a key derived
+ * with scrypt from an externally-supplied secret and a fresh random salt per
+ * write; the IV is fresh per write and the ciphertext is authenticated against
+ * the store key. The secret is never written to disk, so the "no plaintext key
+ * on disk" guarantee still holds — but unlike the Linux kernel keyring the file
+ * survives a reboot, which is what a fund-controlling key requires.
+ */
+export class EncryptedFileCredentialStore implements AutonomousWalletCredentialStore {
+  private readonly directory: string;
+  private readonly secret: string;
+
+  constructor(options: EncryptedFileCredentialStoreOptions = {}) {
+    const env = options.env ?? process.env;
+    const secret =
+      options.encryptionKey ?? env[METRIK_WALLET_ENCRYPTION_KEY_ENV];
+    if (typeof secret !== "string" || secret.trim() === "") {
+      throw new AutonomousWalletError(
+        "invalid-config",
+        `EncryptedFileCredentialStore requires an encryption secret: set ${METRIK_WALLET_ENCRYPTION_KEY_ENV} (from your secret manager) or pass encryptionKey. Without it the stored wallet key cannot be decrypted.`,
+      );
+    }
+    if (secret.trim().length < MINIMUM_SECRET_LENGTH) {
+      throw new AutonomousWalletError(
+        "invalid-config",
+        `the autonomous wallet encryption secret must be at least ${MINIMUM_SECRET_LENGTH} characters; generate one with "openssl rand -base64 32"`,
+      );
+    }
+    this.secret = secret.trim();
+    this.directory =
+      options.directory ??
+      env[METRIK_WALLET_STORE_DIR_ENV] ??
+      join(homedir(), ".metrik", "autonomous-wallets");
+  }
+
+  async load(key: string): Promise<AutonomousWalletRecord | null> {
+    const path = this.pathFor(key);
+    let raw: string;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch (error) {
+      if (isNotFound(error)) return null;
+      throw new AutonomousWalletError(
+        "store-failure",
+        `encrypted wallet file at ${path} could not be read`,
+        { cause: error },
+      );
+    }
+    const envelope = parseEnvelope(raw, path);
+    const digest = digestOf(key);
+    if (envelope.keyDigest !== digest) {
+      throw new AutonomousWalletError(
+        "store-failure",
+        `encrypted wallet file at ${path} belongs to a different store key`,
+      );
+    }
+    const derived = await scryptAsync(
+      this.secret,
+      Buffer.from(envelope.kdf.saltBase64, "base64"),
+      KEY_LENGTH,
+      { N: envelope.kdf.N, r: envelope.kdf.r, p: envelope.kdf.p },
+    );
+    let plaintext: string;
+    try {
+      const decipher = createDecipheriv(
+        CIPHER,
+        derived,
+        Buffer.from(envelope.ivBase64, "base64"),
+      );
+      decipher.setAAD(additionalData(digest));
+      decipher.setAuthTag(Buffer.from(envelope.tagBase64, "base64"));
+      plaintext = Buffer.concat([
+        decipher.update(Buffer.from(envelope.ciphertextBase64, "base64")),
+        decipher.final(),
+      ]).toString("utf8");
+    } catch (error) {
+      throw new AutonomousWalletError(
+        "store-failure",
+        `encrypted wallet file at ${path} failed authenticated decryption: the ${METRIK_WALLET_ENCRYPTION_KEY_ENV} secret does not match the one used to write it, or the file was modified. Restore the original secret; the wallet key cannot be recovered without it.`,
+        { cause: error },
+      );
+    }
+    try {
+      return validateStoredRecord(JSON.parse(plaintext));
+    } catch (error) {
+      if (error instanceof AutonomousWalletError) throw error;
+      throw new AutonomousWalletError(
+        "store-failure",
+        `encrypted wallet file at ${path} contains invalid wallet data`,
+        { cause: error },
+      );
+    }
+  }
+
+  async save(key: string, record: AutonomousWalletRecord): Promise<void> {
+    const path = this.pathFor(key);
+    const digest = digestOf(key);
+    try {
+      await mkdir(this.directory, { recursive: true, mode: DIRECTORY_MODE });
+      const salt = randomBytes(SALT_LENGTH);
+      const iv = randomBytes(IV_LENGTH);
+      const derived = await scryptAsync(
+        this.secret,
+        salt,
+        KEY_LENGTH,
+        SCRYPT_PARAMETERS,
+      );
+      const cipher = createCipheriv(CIPHER, derived, iv);
+      cipher.setAAD(additionalData(digest));
+      const ciphertext = Buffer.concat([
+        cipher.update(Buffer.from(JSON.stringify(record), "utf8")),
+        cipher.final(),
+      ]);
+      const envelope: Envelope = {
+        v: ENVELOPE_VERSION,
+        cipher: CIPHER,
+        kdf: {
+          name: "scrypt",
+          ...SCRYPT_PARAMETERS,
+          saltBase64: salt.toString("base64"),
+        },
+        ivBase64: iv.toString("base64"),
+        tagBase64: cipher.getAuthTag().toString("base64"),
+        ciphertextBase64: ciphertext.toString("base64"),
+        keyDigest: digest,
+      };
+      const temporaryPath = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+      await writeFile(temporaryPath, JSON.stringify(envelope), {
+        mode: FILE_MODE,
+      });
+      // writeFile's mode is subject to the process umask; force 0600.
+      await chmod(temporaryPath, FILE_MODE);
+      await rename(temporaryPath, path);
+      await chmod(path, FILE_MODE);
+    } catch (error) {
+      throw new AutonomousWalletError(
+        "store-failure",
+        `encrypted wallet file at ${path} could not be written`,
+        { cause: error },
+      );
+    }
+  }
+
+  async probeDurability(): Promise<CredentialStoreDurabilityReport> {
+    const probePath = join(
+      this.directory,
+      `.durability-probe-${randomBytes(6).toString("hex")}`,
+    );
+    try {
+      await mkdir(this.directory, { recursive: true, mode: DIRECTORY_MODE });
+      await writeFile(probePath, "metrik-durability-probe", {
+        mode: FILE_MODE,
+      });
+      const observed = await readFile(probePath, "utf8");
+      if (observed !== "metrik-durability-probe") {
+        return {
+          durability: "volatile",
+          backend: "encrypted-file",
+          detail: `the probe file at ${this.directory} did not read back with the value written`,
+        };
+      }
+      return {
+        durability: "durable",
+        backend: "encrypted-file",
+        detail: `AES-256-GCM encrypted files under ${this.directory} persist across reboots; the key is derived from ${METRIK_WALLET_ENCRYPTION_KEY_ENV}, which you must keep in your secret manager`,
+      };
+    } catch (error) {
+      return {
+        durability: "volatile",
+        backend: "encrypted-file",
+        detail: `${this.directory} is not writable: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    } finally {
+      await rm(probePath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  /** Absolute path of the encrypted file backing `key`. */
+  pathFor(key: string): string {
+    if (key.trim() === "") {
+      throw new AutonomousWalletError(
+        "invalid-config",
+        "secure store key is required",
+      );
+    }
+    // Hash the key so an arbitrary store key can never traverse the directory.
+    return join(this.directory, `${digestOf(key)}.metrik-wallet.json`);
+  }
+}
+
+function additionalData(keyDigest: string): Buffer {
+  return Buffer.from(
+    `metrik-autonomous-wallet-v${ENVELOPE_VERSION}:${keyDigest}`,
+    "utf8",
+  );
+}
+
+function digestOf(key: string): string {
+  return createHash("sha256").update(key, "utf8").digest("hex");
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { readonly code?: unknown }).code === "ENOENT"
+  );
+}
+
+function parseEnvelope(raw: string, path: string): Envelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      `encrypted wallet file at ${path} is not valid JSON`,
+      { cause: error },
+    );
+  }
+  const kdf = isRecord(parsed) ? parsed.kdf : undefined;
+  if (
+    !isRecord(parsed) ||
+    parsed.v !== ENVELOPE_VERSION ||
+    parsed.cipher !== CIPHER ||
+    typeof parsed.ivBase64 !== "string" ||
+    typeof parsed.tagBase64 !== "string" ||
+    typeof parsed.ciphertextBase64 !== "string" ||
+    typeof parsed.keyDigest !== "string" ||
+    !isRecord(kdf) ||
+    kdf.name !== "scrypt" ||
+    typeof kdf.N !== "number" ||
+    typeof kdf.r !== "number" ||
+    typeof kdf.p !== "number" ||
+    typeof kdf.saltBase64 !== "string"
+  ) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      `encrypted wallet file at ${path} has an unsupported envelope`,
+    );
+  }
+  return {
+    v: ENVELOPE_VERSION,
+    cipher: CIPHER,
+    kdf: {
+      name: "scrypt",
+      N: kdf.N,
+      r: kdf.r,
+      p: kdf.p,
+      saltBase64: kdf.saltBase64,
+    },
+    ivBase64: parsed.ivBase64,
+    tagBase64: parsed.tagBase64,
+    ciphertextBase64: parsed.ciphertextBase64,
+    keyDigest: parsed.keyDigest,
+  };
+}

package/src/wallet/provider.ts

@@ -1,9 +1,10 @@
 import { type StreamProofClientConfig } from "@absol-labs/sdk";
-import {
-  CdpClient,
-  type EvmServerAccount,
-  type EvmSmartAccount,
-} from "@coinbase/cdp-sdk";
+// `@coinbase/cdp-sdk` is an OPTIONAL peer dependency: TYPES only here (erased at
+// compile time), the runtime module via `loadCdpSdk()` at the point of first use.
+// This module IS reachable from the package barrel, so a value import here would
+// re-introduce the hard dependency for every consumer. See ./cdp-sdk.ts.
+import type { EvmServerAccount, EvmSmartAccount } from "@coinbase/cdp-sdk";
+import { loadCdpSdk } from "./cdp-sdk.js";
 import {
   custom,
   toHex,
@@ -173,9 +174,12 @@ export async function resolveAgentWallet(
     };
   }
 
-  const cdpClient = (options.createCdpClient ?? defaultCdpClientFactory)(
-    input.cdp,
-  );
+  // An injected factory keeps its synchronous public signature; only the DEFAULT
+  // path is async, because it lazily loads the optional @coinbase/cdp-sdk peer.
+  const cdpClient =
+    options.createCdpClient === undefined
+      ? await defaultCdpClientFactory(input.cdp)
+      : options.createCdpClient(input.cdp);
   const owner = await cdpClient.evm.getOrCreateAccount({
     name: input.cdp.ownerName,
   });
@@ -338,7 +342,10 @@ export function parseAgentWalletEnv(
   };
 }
 
-function defaultCdpClientFactory(config: CdpWalletConfig): CdpClientLike {
+async function defaultCdpClientFactory(
+  config: CdpWalletConfig,
+): Promise<CdpClientLike> {
+  const { CdpClient } = await loadCdpSdk();
   return new CdpClient({
     ...(config.apiKeyId === undefined ? {} : { apiKeyId: config.apiKeyId }),
     ...(config.apiKeySecret === undefined