@absol-labs/agent 0.7.3 → 0.9.0

package/src/wallet/autonomous-wallet.ts

@@ -1,5 +1,3 @@
-import { createPrivateKey, createPublicKey } from "node:crypto";
-
 import {
   generateAuthorizationSignature,
   generateP256KeyPair,
@@ -19,6 +17,16 @@ import {
   type AutonomousWalletProof,
   type PreparedPrivyRequest,
 } from "./autonomous-wallet-protocol.js";
+import {
+  AutonomousWalletError,
+  assertDurableCredentialStore,
+  createDefaultAutonomousWalletStore,
+  decodeBase64,
+  isRecord,
+  validateStoredRecord,
+  type AutonomousWalletCredentialStore,
+  type AutonomousWalletRecord,
+} from "./autonomous-wallet-store.js";
 
 export {
   AUTONOMOUS_WALLET_CAIP2,
@@ -29,44 +37,39 @@ export {
   type AutonomousWalletProof,
   type PreparedPrivyRequest,
 } from "./autonomous-wallet-protocol.js";
-const KEYCHAIN_SERVICE = "com.absol-labs.metrik.autonomous-wallet";
-export const METRIK_AUTONOMOUS_WALLET_BROKER_URL =
-  "https://wallet.137.23.50.249.sslip.io";
 
-export interface AutonomousWalletRecord {
-  readonly version: typeof AUTONOMOUS_WALLET_VERSION;
-  readonly appId: string;
-  readonly brokerUrl: string;
-  readonly publicKey: string;
-  /** Base64 PKCS8 P-256 key. This field must only be stored in a secure store. */
-  readonly privateKey: string;
-  readonly provisioningNonce: string;
-  readonly walletId?: string;
-  readonly address?: Address;
-  readonly policyId?: string;
-  readonly createdAt: number;
-}
+export {
+  AUTONOMOUS_WALLET_KEYCHAIN_SERVICE,
+  AutonomousWalletError,
+  InMemoryAutonomousWalletStore,
+  OsCredentialStore,
+  assertDurableCredentialStore,
+  createDefaultAutonomousWalletStore,
+  type AssertDurableCredentialStoreOptions,
+  type AutonomousWalletCredentialStore,
+  type AutonomousWalletRecord,
+  type CredentialStoreDurability,
+  type CredentialStoreDurabilityReport,
+  type OsCredentialStoreOptions,
+  type SecretEntryFactory,
+  type SecretEntryLike,
+} from "./autonomous-wallet-store.js";
 
-export interface AutonomousWalletCredentialStore {
-  load(key: string): Promise<AutonomousWalletRecord | null>;
-  save(key: string, record: AutonomousWalletRecord): Promise<void>;
-}
+export {
+  EncryptedFileCredentialStore,
+  METRIK_WALLET_ENCRYPTION_KEY_ENV,
+  METRIK_WALLET_STORE_DIR_ENV,
+  type EncryptedFileCredentialStoreOptions,
+} from "./encrypted-file-credential-store.js";
 
-export class AutonomousWalletError extends Error {
-  constructor(
-    readonly code:
-      | "invalid-config"
-      | "store-failure"
-      | "broker-failure"
-      | "proof-failure"
-      | "invalid-response",
-    message: string,
-    options?: { readonly cause?: unknown },
-  ) {
-    super(message, options);
-    this.name = "AutonomousWalletError";
-  }
-}
+export {
+  probeSecretServiceAvailable,
+  type ProbeSecretServiceOptions,
+  type SecretServiceProbeResult,
+} from "./secret-service-probe.js";
+
+export const METRIK_AUTONOMOUS_WALLET_BROKER_URL =
+  "https://wallet.137.23.50.249.sslip.io";
 
 /**
  * Wire adapter for the broker HTTP contract. The only credential sent by this
@@ -166,6 +169,13 @@ export interface ProvisionAutonomousWalletOptions {
   readonly store?: AutonomousWalletCredentialStore;
   readonly nowSeconds?: number;
   readonly nonce?: string;
+  /**
+   * Opt in to a credential store that does NOT survive a host reboot (process
+   * memory, the Linux kernel keyring). Off by default: provisioning refuses a
+   * volatile store because the owner key — and therefore any funds the wallet
+   * holds — is lost on reboot. Only set this for genuinely ephemeral runs.
+   */
+  readonly allowVolatileStore?: boolean;
 }
 
 export interface ProvisionMetrikAutonomousWalletOptions {
@@ -173,6 +183,8 @@ export interface ProvisionMetrikAutonomousWalletOptions {
   readonly brokerUrl?: string;
   readonly store?: AutonomousWalletCredentialStore;
   readonly fetchImpl?: typeof fetch;
+  /** See {@link ProvisionAutonomousWalletOptions.allowVolatileStore}. */
+  readonly allowVolatileStore?: boolean;
 }
 
 /**
@@ -223,6 +235,9 @@ export async function provisionMetrikAutonomousWallet(
     storeKey: options.storeKey,
     broker,
     ...(options.store === undefined ? {} : { store: options.store }),
+    ...(options.allowVolatileStore === undefined
+      ? {}
+      : { allowVolatileStore: options.allowVolatileStore }),
   });
 }
 
@@ -237,6 +252,11 @@ export async function provisionAutonomousWallet(
 ): Promise<AutonomousWalletRecord> {
   validateProvisionOptions(options);
   const store = options.store ?? createDefaultAutonomousWalletStore();
+  // Fail closed BEFORE a key is generated or a stored key is handed back: a
+  // volatile backend silently loses the owner key (and any funds) on reboot.
+  await assertDurableCredentialStore(store, {
+    allowVolatileStore: options.allowVolatileStore === true,
+  });
   const existingRaw = await loadRecord(store, options.storeKey);
   if (existingRaw !== null) {
     const existing = validateStoredRecord(existingRaw);
@@ -461,72 +481,6 @@ export async function createAutonomousWalletAccount(
   return createPrivyEmbeddedAccount(config);
 }
 
-export class InMemoryAutonomousWalletStore implements AutonomousWalletCredentialStore {
-  private readonly records = new Map<string, AutonomousWalletRecord>();
-
-  async load(key: string): Promise<AutonomousWalletRecord | null> {
-    return this.records.get(key) ?? null;
-  }
-
-  async save(key: string, record: AutonomousWalletRecord): Promise<void> {
-    this.records.set(key, record);
-  }
-}
-
-/**
- * Uses the host OS credential manager. There is intentionally no plaintext
- * file fallback: unsupported hosts receive an actionable error instead.
- */
-export class OsCredentialStore implements AutonomousWalletCredentialStore {
-  async load(key: string): Promise<AutonomousWalletRecord | null> {
-    const raw = await this.readSecret(key);
-    if (raw === null) return null;
-    try {
-      return validateStoredRecord(JSON.parse(raw));
-    } catch (error) {
-      throw new AutonomousWalletError(
-        "store-failure",
-        "OS credential contains invalid wallet data",
-        { cause: error },
-      );
-    }
-  }
-
-  async save(key: string, record: AutonomousWalletRecord): Promise<void> {
-    const raw = JSON.stringify(record);
-    try {
-      const { AsyncEntry } = await import("@napi-rs/keyring");
-      await new AsyncEntry(KEYCHAIN_SERVICE, key).setPassword(raw);
-      return;
-    } catch (error) {
-      throw new AutonomousWalletError(
-        "store-failure",
-        "OS credential store rejected the autonomous wallet record; no plaintext fallback is allowed",
-        { cause: error },
-      );
-    }
-  }
-
-  private async readSecret(key: string): Promise<string | null> {
-    try {
-      const { AsyncEntry } = await import("@napi-rs/keyring");
-      return (
-        (await new AsyncEntry(KEYCHAIN_SERVICE, key).getPassword()) ?? null
-      );
-    } catch (error) {
-      throw new AutonomousWalletError(
-        "store-failure",
-        "OS credential store could not read the autonomous wallet record",
-        { cause: error },
-      );
-    }
-  }
-}
-
-export function createDefaultAutonomousWalletStore(): AutonomousWalletCredentialStore {
-  return new OsCredentialStore();
-}
-
 async function loadRecord(
   store: AutonomousWalletCredentialStore,
   key: string,
@@ -612,80 +566,6 @@ function validateExistingRecord(
   }
 }
 
-function validateStoredRecord(value: unknown): AutonomousWalletRecord {
-  if (
-    !isRecord(value) ||
-    value.version !== AUTONOMOUS_WALLET_VERSION ||
-    typeof value.appId !== "string" ||
-    value.appId.trim() === "" ||
-    typeof value.brokerUrl !== "string" ||
-    typeof value.publicKey !== "string" ||
-    value.publicKey.trim() === "" ||
-    typeof value.privateKey !== "string" ||
-    value.privateKey.trim() === "" ||
-    typeof value.provisioningNonce !== "string" ||
-    value.provisioningNonce.trim() === "" ||
-    typeof value.createdAt !== "number" ||
-    !Number.isSafeInteger(value.createdAt)
-  ) {
-    throw new AutonomousWalletError(
-      "store-failure",
-      "OS credential contains an invalid autonomous wallet record",
-    );
-  }
-  if (
-    value.walletId !== undefined &&
-    (typeof value.walletId !== "string" || value.walletId.trim() === "")
-  ) {
-    throw new AutonomousWalletError(
-      "store-failure",
-      "OS credential contains an invalid wallet id",
-    );
-  }
-  if (
-    value.policyId !== undefined &&
-    (typeof value.policyId !== "string" || value.policyId.trim() === "")
-  ) {
-    throw new AutonomousWalletError(
-      "store-failure",
-      "OS credential contains an invalid policy id",
-    );
-  }
-  if (
-    value.address !== undefined &&
-    (typeof value.address !== "string" ||
-      !/^0x[0-9a-fA-F]{40}$/.test(value.address))
-  ) {
-    throw new AutonomousWalletError(
-      "store-failure",
-      "OS credential contains an invalid wallet address",
-    );
-  }
-  try {
-    validateP256KeyPair(value.publicKey, value.privateKey);
-  } catch (error) {
-    throw new AutonomousWalletError(
-      "store-failure",
-      "OS credential contains invalid P-256 key material",
-      { cause: error },
-    );
-  }
-  return {
-    version: AUTONOMOUS_WALLET_VERSION,
-    appId: value.appId,
-    brokerUrl: value.brokerUrl,
-    publicKey: value.publicKey,
-    privateKey: value.privateKey,
-    provisioningNonce: value.provisioningNonce,
-    ...(value.walletId === undefined ? {} : { walletId: value.walletId }),
-    ...(value.address === undefined
-      ? {}
-      : { address: getAddress(value.address) }),
-    ...(value.policyId === undefined ? {} : { policyId: value.policyId }),
-    createdAt: value.createdAt,
-  };
-}
-
 function normalizeBrokerUrl(value: string): string {
   const url = new URL(value);
   url.search = "";
@@ -699,49 +579,6 @@ function cryptoRandomNonce(): string {
   return Buffer.from(bytes).toString("base64url");
 }
 
-function decodeBase64(value: string): Uint8Array {
-  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 === 1) {
-    throw new AutonomousWalletError(
-      "invalid-response",
-      "broker returned invalid proof payload encoding",
-    );
-  }
-  const decoded = Buffer.from(value, "base64");
-  if (decoded.length === 0 || decoded.toString("base64") !== value) {
-    throw new AutonomousWalletError(
-      "invalid-response",
-      "broker returned an empty proof payload",
-    );
-  }
-  return new Uint8Array(decoded);
-}
-
-function validateP256KeyPair(publicKey: string, privateKey: string): void {
-  const publicObject = createPublicKey({
-    key: Buffer.from(decodeBase64(publicKey)),
-    format: "der",
-    type: "spki",
-  });
-  const privateObject = createPrivateKey({
-    key: Buffer.from(decodeBase64(privateKey)),
-    format: "der",
-    type: "pkcs8",
-  });
-  if (
-    publicObject.asymmetricKeyType !== "ec" ||
-    publicObject.asymmetricKeyDetails?.namedCurve !== "prime256v1" ||
-    privateObject.asymmetricKeyType !== "ec" ||
-    privateObject.asymmetricKeyDetails?.namedCurve !== "prime256v1"
-  ) {
-    throw new Error("key material is not P-256");
-  }
-  const derived = createPublicKey(privateObject)
-    .export({ format: "der", type: "spki" })
-    .toString("base64");
-  if (derived !== publicKey)
-    throw new Error("public key does not match private key");
-}
-
 function validateProvisionResponse(value: unknown): {
   readonly walletId: string;
   readonly address: Address;
@@ -804,10 +641,6 @@ function validatePreparedResponse(value: unknown): PreparedPrivyRequest {
   };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function bigintJson(_key: string, value: unknown): unknown {
   return typeof value === "bigint" ? `0x${value.toString(16)}` : value;
 }

package/src/wallet/cdp-sdk.ts

@@ -0,0 +1,33 @@
+/**
+ * `@coinbase/cdp-sdk` is an OPTIONAL peer dependency: only consumers that use the
+ * Coinbase CDP wallet path need it, and it carries a very large transitive graph
+ * (it was the main contributor to the 18 -> ~515 package jump a consumer saw just
+ * for hiring and invoking a service). The top-level "@absol-labs/agent" barrel
+ * DOES reach `./provider.ts`, so that module must import the SDK's TYPES only
+ * (`import type`, erased at compile time) and load the runtime module lazily
+ * through this loader at the point of first use.
+ *
+ * This is the same contract as `../zktls/reclaim-js-sdk.ts`, and it is enforced
+ * by the barrel-reachability guard in `test/flat-install.test.ts`: a static value
+ * import of an optional peer from any barrel-reachable module fails that test.
+ *
+ * Deliberately NOT a top-level `await import(...)` (the pattern used by
+ * `../frameworks/agentkit.ts`): those modules are not barrel-reachable, this one
+ * is, and a top-level await would re-introduce the hard dependency at
+ * barrel-import time — precisely the regression that issue #79 was filed for.
+ */
+
+type CdpSdkModule = typeof import("@coinbase/cdp-sdk");
+
+let modulePromise: Promise<CdpSdkModule> | undefined;
+
+/** Memoized lazy load with an actionable missing-peer error. */
+export async function loadCdpSdk(): Promise<CdpSdkModule> {
+  modulePromise ??= import("@coinbase/cdp-sdk").catch((error: unknown) => {
+    throw new Error(
+      "@absol-labs/agent CDP wallet support requires the optional peer dependency '@coinbase/cdp-sdk'. Install it with `npm install @coinbase/cdp-sdk`, or use a different wallet mode (the autonomous Privy wallet and an injected account both work without it).",
+      { cause: error },
+    );
+  });
+  return await modulePromise;
+}