@wlfi-agent/cli 1.4.13 → 1.4.15

package/src/lib/wallet-status.js

@@ -0,0 +1 @@
+export * from './wallet-status.ts';

package/src/lib/wallet-status.ts

@@ -0,0 +1,640 @@
+import fs from 'node:fs';
+import {
+  assertSafeRpcUrl,
+  defaultConfig,
+  defaultDaemonSocketPath,
+  defaultStateFilePath,
+  readConfig,
+  redactConfig,
+  resolveRustBinaryPath,
+  type WlfiConfig,
+} from '../../packages/config/src/index.js';
+import {
+  type BootstrapArtifactCheck,
+  listAutoGeneratedBootstrapArtifacts,
+} from './bootstrap-artifacts.js';
+import {
+  assertTrustedDaemonSocketPath,
+  assertTrustedExecutablePath,
+  assertTrustedRootPrivateFilePath,
+} from './fs-trust.js';
+import {
+  AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE,
+  assertValidAgentKeyId,
+  hasAgentAuthTokenInKeychain,
+  readAgentAuthTokenFromKeychain,
+} from './keychain.js';
+import type { RustBinaryName } from './rust.js';
+
+export interface WalletStatusBinaryCheck {
+  name: RustBinaryName;
+  path: string;
+  installed: boolean;
+  trusted: boolean;
+  error: string | null;
+}
+
+export interface WalletStatusChainProfileCheck {
+  key: string;
+  chainId: number | null;
+  chainName: string | null;
+  rpcUrlConfigured: boolean;
+  rpcUrlTrusted: boolean | null;
+  error: string | null;
+}
+
+export interface WalletStatusResult {
+  platform: NodeJS.Platform;
+  config: {
+    readable: boolean;
+    error: string | null;
+    values: Record<string, unknown>;
+  };
+  agent: {
+    agentKeyId: string | null;
+    agentKeyIdValid: boolean;
+    keychain: {
+      supported: boolean;
+      service: string | null;
+      tokenStored: boolean;
+      error: string | null;
+    };
+    legacyConfigToken: {
+      present: boolean;
+      keychainMatch: boolean | null;
+      error: string | null;
+    };
+  };
+  chain: {
+    chainId: number | null;
+    chainName: string | null;
+    rpcUrlConfigured: boolean;
+    rpcUrlTrusted: boolean | null;
+    error: string | null;
+  };
+  chainProfiles: WalletStatusChainProfileCheck[];
+  bootstrapFiles: BootstrapArtifactCheck[];
+  daemonSocket: {
+    path: string;
+    trusted: boolean;
+    error: string | null;
+  };
+  stateFile: {
+    path: string;
+    present: boolean;
+    trusted: boolean;
+    error: string | null;
+  };
+  binaries: WalletStatusBinaryCheck[];
+  security: {
+    ready: boolean;
+    warnings: string[];
+  };
+}
+
+export interface WalletStatusExitOptions {
+  strict?: boolean;
+}
+
+interface WalletStatusDeps {
+  platform?: NodeJS.Platform;
+  readConfig?: () => WlfiConfig;
+  hasAgentAuthToken?: (agentKeyId: string) => boolean;
+  readAgentAuthToken?: (agentKeyId: string) => string | null;
+  assertTrustedDaemonSocketPath?: (targetPath: string, label?: string) => string;
+  assertTrustedStateFilePath?: (targetPath: string, label?: string) => string;
+  assertTrustedExecutablePath?: (targetPath: string) => void;
+  resolveRustBinaryPath?: (binaryName: RustBinaryName, config?: WlfiConfig) => string;
+  existsSync?: (targetPath: string) => boolean;
+  listBootstrapFiles?: () => BootstrapArtifactCheck[];
+}
+
+const RUST_BINARIES: RustBinaryName[] = [
+  'wlfi-agent-daemon',
+  'wlfi-agent-admin',
+  'wlfi-agent-agent',
+];
+
+function renderError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function presentString(value: string | undefined): string | null {
+  const normalized = value?.trim();
+  return normalized ? normalized : null;
+}
+
+function presentSecret(value: string | undefined): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  return value.length > 0 ? value : null;
+}
+
+function resolveChainStatus(config: WlfiConfig): WalletStatusResult['chain'] {
+  const rpcUrl = presentString(config.rpcUrl);
+  if (!rpcUrl) {
+    return {
+      chainId: config.chainId ?? null,
+      chainName: presentString(config.chainName),
+      rpcUrlConfigured: false,
+      rpcUrlTrusted: null,
+      error: null,
+    };
+  }
+
+  try {
+    assertSafeRpcUrl(rpcUrl, 'configured rpcUrl');
+    return {
+      chainId: config.chainId ?? null,
+      chainName: presentString(config.chainName),
+      rpcUrlConfigured: true,
+      rpcUrlTrusted: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      chainId: config.chainId ?? null,
+      chainName: presentString(config.chainName),
+      rpcUrlConfigured: true,
+      rpcUrlTrusted: false,
+      error: renderError(error),
+    };
+  }
+}
+
+function resolveChainProfileStatuses(config: WlfiConfig): WalletStatusChainProfileCheck[] {
+  return Object.entries(config.chains ?? {}).map(([key, profile]) => {
+    const chainId = typeof profile?.chainId === 'number' ? profile.chainId : null;
+    const chainName = typeof profile?.name === 'string' ? presentString(profile.name) : null;
+    const rpcUrl = typeof profile?.rpcUrl === 'string' ? presentString(profile.rpcUrl) : null;
+
+    if (!rpcUrl) {
+      return {
+        key,
+        chainId,
+        chainName,
+        rpcUrlConfigured: false,
+        rpcUrlTrusted: null,
+        error: null,
+      };
+    }
+
+    try {
+      assertSafeRpcUrl(rpcUrl, `chain profile '${key}' rpcUrl`);
+      return {
+        key,
+        chainId,
+        chainName,
+        rpcUrlConfigured: true,
+        rpcUrlTrusted: true,
+        error: null,
+      };
+    } catch (error) {
+      return {
+        key,
+        chainId,
+        chainName,
+        rpcUrlConfigured: true,
+        rpcUrlTrusted: false,
+        error: renderError(error),
+      };
+    }
+  });
+}
+
+function resolveConfigSnapshot(loadConfig: () => WlfiConfig): {
+  config: WlfiConfig;
+  readable: boolean;
+  error: string | null;
+} {
+  try {
+    return {
+      config: loadConfig(),
+      readable: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      config: defaultConfig(),
+      readable: false,
+      error: renderError(error),
+    };
+  }
+}
+
+function resolveAgentStatus(
+  config: WlfiConfig,
+  platform: NodeJS.Platform,
+  hasAgentAuthToken: (agentKeyId: string) => boolean,
+  readAgentAuthToken: (agentKeyId: string) => string | null,
+): WalletStatusResult['agent'] {
+  const agentKeyId = presentString(config.agentKeyId);
+  const legacyConfigToken = presentSecret(config.agentAuthToken);
+
+  if (!agentKeyId) {
+    return {
+      agentKeyId: null,
+      agentKeyIdValid: false,
+      keychain: {
+        supported: platform === 'darwin',
+        service: platform === 'darwin' ? AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE : null,
+        tokenStored: false,
+        error: null,
+      },
+      legacyConfigToken: {
+        present: legacyConfigToken !== null,
+        keychainMatch: null,
+        error: null,
+      },
+    };
+  }
+
+  try {
+    const normalizedAgentKeyId = assertValidAgentKeyId(agentKeyId);
+    let tokenStored = false;
+    let keychainError: string | null = null;
+    let legacyConfigTokenMatch: boolean | null = null;
+    let legacyConfigTokenError: string | null = null;
+
+    try {
+      tokenStored = hasAgentAuthToken(normalizedAgentKeyId);
+    } catch (error) {
+      keychainError = renderError(error);
+    }
+
+    if (legacyConfigToken !== null && platform === 'darwin') {
+      try {
+        const keychainToken = readAgentAuthToken(normalizedAgentKeyId);
+        legacyConfigTokenMatch =
+          keychainToken === null ? null : keychainToken === legacyConfigToken;
+      } catch (error) {
+        legacyConfigTokenError = renderError(error);
+      }
+    }
+
+    return {
+      agentKeyId: normalizedAgentKeyId,
+      agentKeyIdValid: true,
+      keychain: {
+        supported: platform === 'darwin',
+        service: platform === 'darwin' ? AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE : null,
+        tokenStored,
+        error: keychainError,
+      },
+      legacyConfigToken: {
+        present: legacyConfigToken !== null,
+        keychainMatch: legacyConfigTokenMatch,
+        error: legacyConfigTokenError,
+      },
+    };
+  } catch (error) {
+    return {
+      agentKeyId,
+      agentKeyIdValid: false,
+      keychain: {
+        supported: platform === 'darwin',
+        service: platform === 'darwin' ? AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE : null,
+        tokenStored: false,
+        error: renderError(error),
+      },
+      legacyConfigToken: {
+        present: legacyConfigToken !== null,
+        keychainMatch: null,
+        error: null,
+      },
+    };
+  }
+}
+
+function resolveDaemonSocketStatus(
+  config: WlfiConfig,
+  assertTrustedSocketPath: (targetPath: string, label?: string) => string,
+): WalletStatusResult['daemonSocket'] {
+  const daemonSocketPath = config.daemonSocket ?? defaultDaemonSocketPath();
+  try {
+    return {
+      path: assertTrustedSocketPath(daemonSocketPath),
+      trusted: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      path: daemonSocketPath,
+      trusted: false,
+      error: renderError(error),
+    };
+  }
+}
+
+function resolveStateFileStatus(
+  config: WlfiConfig,
+  assertTrustedStateFilePath: (targetPath: string, label?: string) => string,
+  existsSync: (targetPath: string) => boolean,
+): WalletStatusResult['stateFile'] {
+  const stateFilePath = config.stateFile ?? defaultStateFilePath();
+  const present = existsSync(stateFilePath);
+
+  try {
+    return {
+      path: assertTrustedStateFilePath(stateFilePath),
+      present,
+      trusted: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      path: stateFilePath,
+      present,
+      trusted: false,
+      error: renderError(error),
+    };
+  }
+}
+
+function resolveBinaryStatus(
+  config: WlfiConfig,
+  binaryName: RustBinaryName,
+  deps: Required<
+    Pick<WalletStatusDeps, 'assertTrustedExecutablePath' | 'existsSync' | 'resolveRustBinaryPath'>
+  >,
+): WalletStatusBinaryCheck {
+  const binaryPath = deps.resolveRustBinaryPath(binaryName, config);
+  if (!deps.existsSync(binaryPath)) {
+    return {
+      name: binaryName,
+      path: binaryPath,
+      installed: false,
+      trusted: false,
+      error: 'binary is not installed',
+    };
+  }
+
+  try {
+    deps.assertTrustedExecutablePath(binaryPath);
+    return {
+      name: binaryName,
+      path: binaryPath,
+      installed: true,
+      trusted: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      name: binaryName,
+      path: binaryPath,
+      installed: true,
+      trusted: false,
+      error: renderError(error),
+    };
+  }
+}
+
+function buildWarnings(result: Omit<WalletStatusResult, 'security'>): string[] {
+  const warnings: string[] = [];
+
+  if (!result.config.readable) {
+    warnings.push(`config is unreadable: ${result.config.error}`);
+  }
+  if (result.config.readable && result.agent.legacyConfigToken.present) {
+    if (result.agent.legacyConfigToken.keychainMatch === true) {
+      warnings.push(
+        'legacy agentAuthToken is duplicated in config.json and macOS Keychain; run `wlfi-agent config agent-auth migrate` to scrub plaintext config storage',
+      );
+    } else if (result.agent.legacyConfigToken.keychainMatch === false) {
+      warnings.push(
+        'legacy agentAuthToken in config.json differs from the macOS Keychain token for the configured agentKeyId; avoid `--allow-legacy-agent-auth-source` until migrated',
+      );
+    } else {
+      warnings.push(
+        'legacy agentAuthToken is still present in config.json; migrate it to macOS Keychain',
+      );
+    }
+  }
+  if (result.agent.legacyConfigToken.error) {
+    warnings.push(
+      `legacy agentAuthToken could not be compared with macOS Keychain: ${result.agent.legacyConfigToken.error}`,
+    );
+  }
+  if (!result.agent.agentKeyId) {
+    warnings.push('agentKeyId is not configured');
+  } else if (!result.agent.agentKeyIdValid) {
+    warnings.push('configured agentKeyId is not a valid UUID');
+  }
+  if (result.agent.agentKeyIdValid && result.agent.keychain.error) {
+    warnings.push(`macOS Keychain status check failed: ${result.agent.keychain.error}`);
+  } else if (result.agent.agentKeyIdValid && !result.agent.keychain.supported) {
+    warnings.push('macOS Keychain integration is unavailable on this platform');
+  } else if (result.agent.agentKeyIdValid && !result.agent.keychain.tokenStored) {
+    warnings.push(
+      'macOS Keychain does not contain an agent auth token for the configured agentKeyId',
+    );
+  }
+  if (!result.daemonSocket.trusted) {
+    warnings.push(`daemon socket is not trusted: ${result.daemonSocket.error}`);
+  }
+  if (!result.stateFile.trusted) {
+    warnings.push(`state file is not trusted: ${result.stateFile.error}`);
+  }
+  for (const binary of result.binaries) {
+    if (!binary.installed) {
+      warnings.push(`${binary.name} is not installed at ${binary.path}`);
+    } else if (!binary.trusted) {
+      warnings.push(`${binary.name} is not trusted: ${binary.error}`);
+    }
+  }
+  if (result.chain.rpcUrlConfigured && result.chain.rpcUrlTrusted === false) {
+    warnings.push(`configured rpcUrl is not trusted: ${result.chain.error}`);
+  }
+  if (result.chain.chainId !== null && !result.chain.rpcUrlConfigured) {
+    warnings.push('active chain is configured without an rpcUrl');
+  }
+  for (const profile of result.chainProfiles) {
+    if (profile.rpcUrlConfigured && profile.rpcUrlTrusted === false) {
+      warnings.push(`chain profile '${profile.key}' rpcUrl is not trusted: ${profile.error}`);
+    }
+  }
+  for (const bootstrapFile of result.bootstrapFiles) {
+    if (bootstrapFile.status === 'plaintext') {
+      warnings.push(
+        `bootstrap file '${bootstrapFile.path}' still contains plaintext bootstrap secrets; delete or redact it securely`,
+      );
+    }
+    if (
+      bootstrapFile.leaseExpired &&
+      (bootstrapFile.status === 'plaintext' || bootstrapFile.status === 'redacted')
+    ) {
+      warnings.push(
+        `bootstrap file '${bootstrapFile.path}' has an expired setup lease; do not rely on it for wallet recovery or metadata backfill`,
+      );
+    } else if (bootstrapFile.status === 'invalid') {
+      warnings.push(
+        `bootstrap file '${bootstrapFile.path}' is malformed or incomplete: ${bootstrapFile.error}`,
+      );
+    } else if (bootstrapFile.status === 'untrusted') {
+      warnings.push(
+        `bootstrap file '${bootstrapFile.path}' is not trusted: ${bootstrapFile.error}`,
+      );
+    }
+  }
+
+  return warnings;
+}
+
+function summarizeAgentAuthStorage(result: WalletStatusResult): string {
+  if (!result.agent.agentKeyId) {
+    return 'not configured';
+  }
+  if (!result.agent.agentKeyIdValid) {
+    return 'configured agentKeyId is invalid';
+  }
+  if (!result.agent.keychain.supported) {
+    return 'macOS Keychain integration unavailable on this platform';
+  }
+  if (result.agent.keychain.error) {
+    return `macOS Keychain check failed: ${result.agent.keychain.error}`;
+  }
+  return result.agent.keychain.tokenStored
+    ? 'stored in macOS Keychain'
+    : 'missing from macOS Keychain';
+}
+
+function summarizeChain(result: WalletStatusResult): string {
+  if (result.chain.chainName && result.chain.chainId !== null) {
+    return `${result.chain.chainName} (${result.chain.chainId})`;
+  }
+  if (result.chain.chainName) {
+    return result.chain.chainName;
+  }
+  if (result.chain.chainId !== null) {
+    return `chainId ${result.chain.chainId}`;
+  }
+  return 'unconfigured';
+}
+
+function summarizeRpcTrust(result: WalletStatusResult): string {
+  if (!result.chain.rpcUrlConfigured) {
+    return 'not configured';
+  }
+  if (result.chain.rpcUrlTrusted === false) {
+    return `untrusted: ${result.chain.error}`;
+  }
+  return 'trusted';
+}
+
+function summarizeStateFile(result: WalletStatusResult): string {
+  const presence = result.stateFile.present ? 'present' : 'missing';
+  if (result.stateFile.trusted) {
+    return `${presence}, trusted`;
+  }
+  return `${presence}, untrusted: ${result.stateFile.error}`;
+}
+
+function summarizeDaemonSocket(result: WalletStatusResult): string {
+  if (result.daemonSocket.trusted) {
+    return 'trusted';
+  }
+  return `untrusted: ${result.daemonSocket.error}`;
+}
+
+export function formatWalletStatusText(result: WalletStatusResult): string {
+  const trustedBinaryCount = result.binaries.filter(
+    (binary) => binary.installed && binary.trusted,
+  ).length;
+  const lines = [
+    result.security.ready ? 'wallet status: ready' : 'wallet status: attention required',
+    `platform: ${result.platform}`,
+    `agent key id: ${result.agent.agentKeyId ?? '<unconfigured>'}`,
+    `agent auth token: ${summarizeAgentAuthStorage(result)}`,
+    `active chain: ${summarizeChain(result)}`,
+    `rpc url: ${summarizeRpcTrust(result)}`,
+    `daemon socket: ${result.daemonSocket.path} (${summarizeDaemonSocket(result)})`,
+    `state file: ${result.stateFile.path} (${summarizeStateFile(result)})`,
+    `bootstrap artifacts: ${result.bootstrapFiles.length === 0 ? 'none detected' : `${result.bootstrapFiles.length} detected`}`,
+    `rust binaries: ${trustedBinaryCount}/${result.binaries.length} trusted`,
+  ];
+
+  if (result.security.warnings.length === 0) {
+    lines.push('warnings: none');
+    return lines.join('\n');
+  }
+
+  lines.push(`warnings (${result.security.warnings.length}):`);
+  for (const warning of result.security.warnings) {
+    lines.push(`- ${warning}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function getWalletStatus(deps: WalletStatusDeps = {}): WalletStatusResult {
+  const platform = deps.platform ?? process.platform;
+  const loadConfig = deps.readConfig ?? readConfig;
+  const resolveBinaryPath = deps.resolveRustBinaryPath ?? resolveRustBinaryPath;
+  const trustDaemonSocketPath = deps.assertTrustedDaemonSocketPath ?? assertTrustedDaemonSocketPath;
+  const trustStateFilePath =
+    deps.assertTrustedStateFilePath ??
+    ((targetPath: string, label = 'State file') =>
+      assertTrustedRootPrivateFilePath(targetPath, label, {
+        allowMissing: true,
+      }));
+  const trustExecutablePath = deps.assertTrustedExecutablePath ?? assertTrustedExecutablePath;
+  const hasAgentAuthToken = deps.hasAgentAuthToken ?? hasAgentAuthTokenInKeychain;
+  const readAgentAuthToken = deps.readAgentAuthToken ?? readAgentAuthTokenFromKeychain;
+  const existsSync = deps.existsSync ?? fs.existsSync;
+  const listBootstrapFiles = deps.listBootstrapFiles ?? listAutoGeneratedBootstrapArtifacts;
+
+  const configSnapshot = resolveConfigSnapshot(loadConfig);
+  const agent = resolveAgentStatus(
+    configSnapshot.config,
+    platform,
+    hasAgentAuthToken,
+    readAgentAuthToken,
+  );
+  const daemonSocket = resolveDaemonSocketStatus(configSnapshot.config, trustDaemonSocketPath);
+  const stateFile = resolveStateFileStatus(configSnapshot.config, trustStateFilePath, existsSync);
+  const binaries = RUST_BINARIES.map((binaryName) =>
+    resolveBinaryStatus(configSnapshot.config, binaryName, {
+      assertTrustedExecutablePath: trustExecutablePath,
+      existsSync,
+      resolveRustBinaryPath: resolveBinaryPath,
+    }),
+  );
+
+  const resultWithoutSecurity = {
+    platform,
+    config: {
+      readable: configSnapshot.readable,
+      error: configSnapshot.error,
+      values: redactConfig(configSnapshot.config),
+    },
+    agent,
+    chain: resolveChainStatus(configSnapshot.config),
+    chainProfiles: resolveChainProfileStatuses(configSnapshot.config),
+    bootstrapFiles: listBootstrapFiles(),
+    daemonSocket,
+    stateFile,
+    binaries,
+  };
+
+  const warnings = buildWarnings(resultWithoutSecurity);
+  return {
+    ...resultWithoutSecurity,
+    security: {
+      ready: warnings.length === 0,
+      warnings,
+    },
+  };
+}
+
+export function resolveWalletStatusExitCode(
+  result: WalletStatusResult,
+  options: WalletStatusExitOptions = {},
+): number {
+  if (!options.strict) {
+    return 0;
+  }
+
+  return result.security.ready ? 0 : 1;
+}

package/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["node"],
+    "noEmit": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "include": [
+    "src/**/*.ts",
+    "tsup.config.ts"
+  ]
+}

package/tsup.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    cli: 'src/cli.ts'
+  },
+  format: ['cjs'],
+  platform: 'node',
+  target: 'node20',
+  clean: true,
+  sourcemap: true,
+  dts: false,
+  banner: {
+    js: '#!/usr/bin/env node'
+  },
+  outExtension() {
+    return { js: '.cjs' };
+  },
+  noExternal: [
+    '@wlfi-agent/config',
+    '@wlfi-agent/rpc',
+    'commander',
+    'viem'
+  ]
+});