@absol-labs/agent 0.7.2 → 0.8.0

package/src/wallet/autonomous-wallet-store.ts

@@ -0,0 +1,487 @@
+import { createPrivateKey, createPublicKey } from "node:crypto";
+
+import { getAddress, type Address } from "viem";
+
+import { AUTONOMOUS_WALLET_VERSION } from "./autonomous-wallet-protocol.js";
+import {
+  probeSecretServiceAvailable,
+  type SecretServiceProbeResult,
+} from "./secret-service-probe.js";
+
+export const AUTONOMOUS_WALLET_KEYCHAIN_SERVICE =
+  "com.absol-labs.metrik.autonomous-wallet";
+
+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;
+}
+
+/**
+ * Whether a credential store keeps a key across a host reboot.
+ *
+ * - `durable`: the key survives a reboot (macOS Keychain, Windows Credential
+ *   Manager, a freedesktop Secret Service provider, an encrypted file).
+ * - `volatile`: the key is lost on reboot (process memory, the Linux kernel
+ *   keyring). Provisioning a fund-controlling wallet onto one of these is
+ *   refused unless the caller explicitly opts in.
+ * - `unknown`: an injected third-party store that does not implement
+ *   `probeDurability()`. Allowed for backwards compatibility, with a warning.
+ */
+export type CredentialStoreDurability = "durable" | "volatile" | "unknown";
+
+export interface CredentialStoreDurabilityReport {
+  readonly durability: CredentialStoreDurability;
+  /** Stable identifier of the resolved backend, e.g. `linux-kernel-keyring`. */
+  readonly backend: string;
+  readonly detail: string;
+}
+
+export interface AutonomousWalletCredentialStore {
+  load(key: string): Promise<AutonomousWalletRecord | null>;
+  save(key: string, record: AutonomousWalletRecord): Promise<void>;
+  /**
+   * Optional capability probe. Implementations SHOULD round-trip a throwaway
+   * probe credential and report whether the resolved backend survives a
+   * reboot. Stores that omit it are treated as `unknown`.
+   */
+  probeDurability?(): Promise<CredentialStoreDurabilityReport>;
+}
+
+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 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);
+  }
+
+  async probeDurability(): Promise<CredentialStoreDurabilityReport> {
+    return {
+      durability: "volatile",
+      backend: "in-memory",
+      detail:
+        "records live in process memory only and are lost when the process exits",
+    };
+  }
+}
+
+/** The subset of `@napi-rs/keyring`'s `AsyncEntry` this package relies on. */
+export interface SecretEntryLike {
+  setPassword(password: string): Promise<void>;
+  getPassword(): Promise<string | undefined | null>;
+  deleteCredential?(): Promise<boolean>;
+}
+
+export type SecretEntryFactory = (
+  service: string,
+  key: string,
+) => Promise<SecretEntryLike>;
+
+export interface OsCredentialStoreOptions {
+  readonly service?: string;
+  /** Override for tests; defaults to `process.platform`. */
+  readonly platform?: string;
+  /** Override for tests; defaults to the real D-Bus Secret Service probe. */
+  readonly secretServiceProbe?: () => Promise<SecretServiceProbeResult>;
+  /** Override for tests; defaults to `@napi-rs/keyring`'s `AsyncEntry`. */
+  readonly entryFactory?: SecretEntryFactory;
+}
+
+const DURABILITY_PROBE_KEY_PREFIX = "__metrik-durability-probe__";
+
+/**
+ * Uses the host OS credential manager. There is intentionally no plaintext
+ * file fallback: unsupported hosts receive an actionable error instead.
+ *
+ * IMPORTANT: on Linux the underlying native module silently falls back from the
+ * freedesktop Secret Service to the Linux kernel keyring, which is destroyed on
+ * reboot. `probeDurability()` detects that and reports `volatile`, which makes
+ * `provisionAutonomousWallet` refuse rather than lose the key later.
+ */
+export class OsCredentialStore implements AutonomousWalletCredentialStore {
+  private readonly service: string;
+  private readonly platform: string;
+  private readonly secretServiceProbe: () => Promise<SecretServiceProbeResult>;
+  private readonly entryFactory: SecretEntryFactory;
+
+  constructor(options: OsCredentialStoreOptions = {}) {
+    this.service = options.service ?? AUTONOMOUS_WALLET_KEYCHAIN_SERVICE;
+    this.platform = options.platform ?? process.platform;
+    this.secretServiceProbe =
+      options.secretServiceProbe ?? (() => probeSecretServiceAvailable());
+    this.entryFactory =
+      options.entryFactory ??
+      (async (service, key) => {
+        const { AsyncEntry } = await import("@napi-rs/keyring");
+        return new AsyncEntry(service, key) as unknown as SecretEntryLike;
+      });
+  }
+
+  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) {
+      if (error instanceof AutonomousWalletError) throw 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 entry = await this.entryFactory(this.service, key);
+      await entry.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 },
+      );
+    }
+  }
+
+  /**
+   * Startup self-check. Round-trips a throwaway probe credential (so a broken
+   * or locked keychain is caught before a key is generated) and resolves which
+   * backend the host actually provides.
+   */
+  async probeDurability(): Promise<CredentialStoreDurabilityReport> {
+    const platformReport = await this.resolvePlatformDurability();
+    const roundTrip = await this.roundTripProbe();
+    if (roundTrip !== null) {
+      return {
+        durability: "volatile",
+        backend: platformReport.backend,
+        detail: `credential round-trip self-check failed: ${roundTrip}`,
+      };
+    }
+    return platformReport;
+  }
+
+  private async resolvePlatformDurability(): Promise<CredentialStoreDurabilityReport> {
+    if (this.platform === "darwin") {
+      return {
+        durability: "durable",
+        backend: "macos-keychain",
+        detail: "the macOS Keychain persists credentials across reboots",
+      };
+    }
+    if (this.platform === "win32") {
+      return {
+        durability: "durable",
+        backend: "windows-credential-manager",
+        detail:
+          "the Windows Credential Manager persists credentials across reboots",
+      };
+    }
+    if (this.platform === "linux") {
+      let probe: SecretServiceProbeResult;
+      try {
+        probe = await this.secretServiceProbe();
+      } catch (error) {
+        probe = {
+          available: false,
+          detail: `Secret Service probe failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+      if (probe.available) {
+        return {
+          durability: "durable",
+          backend: "linux-secret-service",
+          detail: probe.detail,
+        };
+      }
+      return {
+        durability: "volatile",
+        backend: "linux-kernel-keyring",
+        detail: `${probe.detail}; the keyring falls back to the Linux kernel keyring, which is in-memory and destroyed on reboot`,
+      };
+    }
+    return {
+      durability: "unknown",
+      backend: `os-credential-store:${this.platform}`,
+      detail: `durability of the OS credential store on "${this.platform}" could not be determined`,
+    };
+  }
+
+  /** Returns `null` on success, or a description of the failure. */
+  private async roundTripProbe(): Promise<string | null> {
+    const key = `${DURABILITY_PROBE_KEY_PREFIX}${Date.now().toString(36)}`;
+    const expected = `metrik-durability-probe:${Math.random().toString(36).slice(2)}`;
+    let entry: SecretEntryLike;
+    try {
+      entry = await this.entryFactory(this.service, key);
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+    try {
+      await entry.setPassword(expected);
+      const observed = await entry.getPassword();
+      if (observed !== expected) {
+        return "the probe credential did not read back with the value that was written";
+      }
+      return null;
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    } finally {
+      try {
+        await entry.deleteCredential?.();
+      } catch {
+        // A leftover probe credential is harmless; never fail the probe on it.
+      }
+    }
+  }
+
+  private async readSecret(key: string): Promise<string | null> {
+    try {
+      const entry = await this.entryFactory(this.service, key);
+      return (await entry.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();
+}
+
+export interface AssertDurableCredentialStoreOptions {
+  /**
+   * Opt in to a volatile credential store. Only for genuinely ephemeral flows
+   * (CI, tests, a throwaway container) where losing the key is acceptable.
+   * A wallet provisioned this way cannot be recovered after a reboot.
+   */
+  readonly allowVolatileStore?: boolean;
+  readonly logger?: { warn(...args: readonly unknown[]): void };
+}
+
+function volatileStoreMessage(report: CredentialStoreDurabilityReport): string {
+  return [
+    `autonomous wallet provisioning refused: the resolved credential store (${report.backend}) is NOT durable — ${report.detail}.`,
+    "The P-256 owner key would be lost on reboot, permanently losing control of any funds held by the wallet.",
+    "Remedies:",
+    "(1) use EncryptedFileCredentialStore with METRIK_WALLET_ENCRYPTION_KEY supplied from your secret manager — durable on any headless host;",
+    "(2) on Linux, install a freedesktop Secret Service provider (for example gnome-keyring plus dbus-user-session) and run inside a D-Bus session;",
+    "(3) inject your own durable AutonomousWalletCredentialStore;",
+    "(4) for genuinely ephemeral runs only, pass allowVolatileStore: true and accept that the wallet is unrecoverable.",
+  ].join(" ");
+}
+
+/**
+ * Fail-closed durability gate. Run before any wallet key is generated or any
+ * stored wallet is returned.
+ */
+export async function assertDurableCredentialStore(
+  store: AutonomousWalletCredentialStore,
+  options: AssertDurableCredentialStoreOptions = {},
+): Promise<CredentialStoreDurabilityReport> {
+  const logger = options.logger ?? console;
+  if (typeof store.probeDurability !== "function") {
+    const report: CredentialStoreDurabilityReport = {
+      durability: "unknown",
+      backend: "custom",
+      detail:
+        "the injected credential store does not implement probeDurability(), so durability could not be verified",
+    };
+    logger.warn(
+      `[metrik] autonomous wallet: ${report.detail}. Confirm it survives a host reboot before funding this wallet.`,
+    );
+    return report;
+  }
+
+  let report: CredentialStoreDurabilityReport;
+  try {
+    report = await store.probeDurability();
+  } catch (error) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      "credential store durability self-check failed; refusing to provision an autonomous wallet",
+      { cause: error },
+    );
+  }
+
+  if (report.durability === "durable") return report;
+
+  if (report.durability === "unknown") {
+    logger.warn(
+      `[metrik] autonomous wallet: credential store durability is unverified (${report.backend}) — ${report.detail}. Confirm it survives a host reboot before funding this wallet.`,
+    );
+    return report;
+  }
+
+  if (options.allowVolatileStore !== true) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      volatileStoreMessage(report),
+    );
+  }
+
+  logger.warn(
+    `[metrik] WARNING: autonomous wallet provisioned onto a VOLATILE credential store (${report.backend}) because allowVolatileStore was set — ${report.detail}. This wallet and any funds it holds become permanently inaccessible on reboot. Never use this for a funded wallet.`,
+  );
+  return report;
+}
+
+export 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,
+  };
+}
+
+export 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);
+}
+
+export 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");
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}