@wlfi-agent/cli 1.4.12 → 1.4.14

package/src/lib/wallet-setup.ts

@@ -0,0 +1,1466 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isAddress } from 'viem';
+import {
+  assertSafeRpcUrl,
+  defaultDaemonSocketPath,
+  deleteConfigKey,
+  ensureWlfiHome,
+  listBuiltinChains,
+  readConfig,
+  redactConfig,
+  resolveWlfiHome,
+  type WlfiConfig,
+  writeConfig,
+} from '../../packages/config/src/index.js';
+import {
+  type AdminAccessGuardDeps,
+  type AdminAccessMode,
+  resolveAdminAccess,
+} from './admin-guard.js';
+import {
+  assertBootstrapSetupSummaryLeaseIsActive,
+  type BootstrapSetupSummary,
+  cleanupBootstrapAgentCredentialsFile,
+  readBootstrapSetupFile,
+} from './bootstrap-credentials.js';
+import {
+  assertPrivateFileStats,
+  assertTrustedAdminDaemonSocketPath,
+  assertTrustedDirectoryPath,
+  assertTrustedOwner,
+} from './fs-trust.js';
+import { AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE, storeAgentAuthTokenInKeychain } from './keychain.js';
+import { walletProfileFromBootstrapSummary } from './wallet-profile.js';
+
+const PRIVATE_DIR_MODE = 0o700;
+const GROUP_OTHER_WRITE_MODE_MASK = 0o022;
+const STICKY_BIT_MODE = 0o1000;
+const RUST_DEFAULT_VALUE = 'rust-default';
+const AUTO_GENERATED_BOOTSTRAP_FILENAME = 'bootstrap-<pid>-<timestamp>.json';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+type BootstrapCleanupAction = 'deleted' | 'redacted';
+
+export interface WalletSetupAdminArgsInput {
+  vaultPassword?: string;
+  vaultPasswordStdin?: boolean;
+  nonInteractive?: boolean;
+  daemonSocket?: string;
+  perTxMaxWei?: string;
+  dailyMaxWei?: string;
+  weeklyMaxWei?: string;
+  maxGasPerChainWei?: string;
+  dailyMaxTxCount?: string;
+  perTxMaxFeePerGasWei?: string;
+  perTxMaxPriorityFeePerGasWei?: string;
+  perTxMaxCalldataBytes?: string;
+  token?: string[];
+  allowNativeEth?: boolean;
+  network?: string;
+  recipient?: string;
+  attachPolicyId?: string[];
+  attachBootstrapPolicies?: boolean;
+  fromSharedConfig?: boolean;
+  bootstrapOutputPath: string;
+}
+
+export interface WalletSetupBootstrapOutput {
+  path: string;
+  autoGenerated: boolean;
+}
+
+export interface CompleteWalletSetupOptions {
+  bootstrapOutputPath: string;
+  cleanupAction: BootstrapCleanupAction;
+  daemonSocket?: string;
+  perTxMaxWei?: string;
+  dailyMaxWei?: string;
+  weeklyMaxWei?: string;
+  maxGasPerChainWei?: string;
+  dailyMaxTxCount?: string;
+  perTxMaxFeePerGasWei?: string;
+  perTxMaxPriorityFeePerGasWei?: string;
+  perTxMaxCalldataBytes?: string;
+  token?: string[];
+  allowNativeEth?: boolean;
+  network?: number;
+  recipient?: string;
+  attachPolicyId?: string[];
+  attachBootstrapPolicies?: boolean;
+  rpcUrl?: string;
+  chainName?: string;
+}
+
+export interface CompleteWalletSetupResult extends BootstrapSetupSummary {
+  agentAuthToken: string;
+  sourceCleanup: BootstrapCleanupAction;
+  keychain: {
+    stored: true;
+    service: string;
+  };
+  config: Record<string, unknown>;
+}
+
+export interface WalletSetupPlanOptions
+  extends Omit<WalletSetupAdminArgsInput, 'bootstrapOutputPath'> {
+  bootstrapOutputPath?: string;
+  deleteBootstrapOutput?: boolean;
+  rpcUrl?: string;
+  chainName?: string;
+}
+
+export interface WalletSetupPlan {
+  adminAccess: {
+    permitted: boolean;
+    mode: AdminAccessMode;
+    reason: string;
+    nonInteractive: boolean;
+  };
+  rustCommand: {
+    binary: 'wlfi-agent-admin';
+    args: string[];
+  };
+  bootstrapOutput: {
+    path: string;
+    autoGenerated: boolean;
+    cleanupAction: BootstrapCleanupAction;
+  };
+  daemonSocket: string;
+  policyLimits: {
+    perTxMaxWei: string;
+    dailyMaxWei: string;
+    weeklyMaxWei: string;
+    maxGasPerChainWei: string;
+    dailyMaxTxCount: string | null;
+    perTxMaxFeePerGasWei: string | null;
+    perTxMaxPriorityFeePerGasWei: string | null;
+    perTxMaxCalldataBytes: string | null;
+  };
+  policyScope: {
+    network: number | null;
+    chainName: string | null;
+    recipient: string | null;
+    assets: {
+      mode: 'daemon-default' | 'native-only' | 'erc20-only' | 'mixed';
+      allowNativeEth: boolean;
+      erc20Tokens: string[];
+    };
+  };
+  policyAttachment: {
+    mode: 'none' | 'bootstrap-only' | 'explicit-only' | 'bootstrap-and-explicit';
+    attachBootstrapPolicies: boolean;
+    explicitPolicyIds: string[];
+  };
+  configAfterSetup: {
+    agentKeyId: '<issued during bootstrap>';
+    daemonSocket: string;
+    chainId: number | null;
+    chainName: string | null;
+    rpcUrl: string | null;
+  };
+  preflight: {
+    daemonSocketTrusted: boolean;
+    daemonSocketError: string | null;
+    rpcUrlTrusted: boolean | null;
+    rpcUrlError: string | null;
+    bootstrapOutputReady: boolean;
+    bootstrapOutputError: string | null;
+  };
+  security: {
+    rustPasswordTransport: 'interactive-prompt' | 'stdin-relay' | 'not-available';
+    childArgvContainsVaultPassword: false;
+    childEnvContainsVaultPassword: false;
+    keyMaterialStorage: 'macOS Keychain';
+    bootstrapCredentialCleanup: BootstrapCleanupAction;
+    notes: string[];
+  };
+}
+
+interface CompleteWalletSetupDeps {
+  platform?: NodeJS.Platform;
+  storeAgentAuthToken?: (agentKeyId: string, token: string) => void;
+  readConfig?: () => WlfiConfig;
+  writeConfig?: (nextConfig: WlfiConfig) => WlfiConfig;
+  deleteConfigKey?: (key: keyof WlfiConfig) => WlfiConfig;
+  assertTrustedDaemonSocketPath?: (targetPath: string, label?: string) => string;
+}
+
+interface CreateWalletSetupPlanDeps extends AdminAccessGuardDeps {
+  readConfig?: () => WlfiConfig;
+  assertTrustedDaemonSocketPath?: (targetPath: string, label?: string) => string;
+}
+
+function presentString(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+
+function renderError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function tryChmod(targetPath: string, mode: number): void {
+  try {
+    fs.chmodSync(targetPath, mode);
+  } catch {}
+}
+
+function assertWritableDirectoryAccess(targetPath: string, label: string): void {
+  try {
+    fs.accessSync(targetPath, fs.constants.W_OK | fs.constants.X_OK);
+  } catch {
+    throw new Error(`${label} '${targetPath}' must be writable by the current process`);
+  }
+}
+
+function assertWritableFileAccess(targetPath: string, label: string): void {
+  try {
+    fs.accessSync(targetPath, fs.constants.W_OK);
+  } catch {
+    throw new Error(`${label} '${targetPath}' must be writable by the current process`);
+  }
+}
+
+function readLstat(targetPath: string): fs.Stats | null {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function assertNoSymlinkAncestorDirectories(targetPath: string, label: string): void {
+  const resolvedPath = path.resolve(targetPath);
+  const parentPath = path.dirname(resolvedPath);
+  if (parentPath === resolvedPath) {
+    return;
+  }
+
+  const { root } = path.parse(parentPath);
+  const relativeParent = parentPath.slice(root.length);
+  if (!relativeParent) {
+    return;
+  }
+
+  let currentPath = root;
+  for (const segment of relativeParent.split(path.sep).filter(Boolean)) {
+    currentPath = path.join(currentPath, segment);
+    const stats = readLstat(currentPath);
+    if (!stats) {
+      break;
+    }
+    if (stats.isSymbolicLink()) {
+      if (isStableRootOwnedSymlink(stats, currentPath)) {
+        continue;
+      }
+      throw new Error(
+        `${label} '${resolvedPath}' must not traverse symlinked ancestor directories`,
+      );
+    }
+  }
+}
+
+function isStableRootOwnedSymlink(stats: fs.Stats, targetPath: string): boolean {
+  if (process.platform === 'win32' || typeof stats.uid !== 'number' || stats.uid !== 0) {
+    return false;
+  }
+
+  const parentPath = path.dirname(targetPath);
+  const parentStats = readLstat(parentPath);
+  return Boolean(
+    parentStats?.isDirectory() &&
+      typeof parentStats.uid === 'number' &&
+      parentStats.uid === 0 &&
+      (parentStats.mode & GROUP_OTHER_WRITE_MODE_MASK) === 0,
+  );
+}
+
+function currentEffectiveUid(): number | null {
+  if (typeof process.geteuid === 'function') {
+    return process.geteuid();
+  }
+  if (typeof process.getuid === 'function') {
+    return process.getuid();
+  }
+  return null;
+}
+
+function canCurrentProcessTightenDirectoryMode(stats: fs.Stats): boolean {
+  if (process.platform === 'win32' || typeof stats.uid !== 'number') {
+    return true;
+  }
+
+  const effectiveUid = currentEffectiveUid();
+  return effectiveUid === 0 || effectiveUid === stats.uid;
+}
+
+function isStickyDirectory(stats: fs.Stats): boolean {
+  return process.platform !== 'win32' && (stats.mode & STICKY_BIT_MODE) !== 0;
+}
+
+function assertSecureExistingPreviewDirectory(
+  targetPath: string,
+  stats: fs.Stats,
+  label: string,
+): void {
+  if (stats.isSymbolicLink()) {
+    throw new Error(`${label} '${targetPath}' must not be a symlink`);
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`${label} '${targetPath}' must be a directory`);
+  }
+
+  assertTrustedOwner(stats, targetPath, label);
+  if (
+    process.platform !== 'win32' &&
+    (stats.mode & GROUP_OTHER_WRITE_MODE_MASK) !== 0 &&
+    !canCurrentProcessTightenDirectoryMode(stats)
+  ) {
+    throw new Error(`${label} '${targetPath}' must not be writable by group/other`);
+  }
+
+  assertWritableDirectoryAccess(targetPath, label);
+}
+
+function assertTrustedAncestorDirectories(targetPath: string, label: string): void {
+  let currentPath = fs.realpathSync.native(path.resolve(targetPath));
+
+  while (true) {
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      break;
+    }
+
+    const stats = fs.lstatSync(parentPath);
+    if (!stats.isDirectory()) {
+      throw new Error(`${label} '${parentPath}' must be a directory`);
+    }
+
+    assertTrustedOwner(stats, parentPath, label);
+    if (process.platform !== 'win32' && (stats.mode & GROUP_OTHER_WRITE_MODE_MASK) !== 0) {
+      if (!isStickyDirectory(stats)) {
+        throw new Error(`${label} '${parentPath}' must not be writable by group/other`);
+      }
+    }
+
+    currentPath = parentPath;
+  }
+}
+
+function findNearestExistingPath(targetPath: string): string {
+  let currentPath = path.resolve(targetPath);
+
+  while (true) {
+    if (readLstat(currentPath)) {
+      return currentPath;
+    }
+
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      return currentPath;
+    }
+
+    currentPath = parentPath;
+  }
+}
+
+function assertPreviewBootstrapOutputDirectory(targetPath: string, label: string): void {
+  const resolvedPath = path.resolve(targetPath);
+  assertNoSymlinkAncestorDirectories(resolvedPath, label);
+  const existingPath = findNearestExistingPath(resolvedPath);
+  const stats = fs.lstatSync(existingPath);
+
+  assertSecureExistingPreviewDirectory(existingPath, stats, label);
+  assertTrustedAncestorDirectories(existingPath, label);
+}
+
+function resolveBootstrapOutputPreflight(targetPath: string): {
+  bootstrapOutputReady: boolean;
+  bootstrapOutputError: string | null;
+} {
+  try {
+    assertPreviewBootstrapOutputDirectory(path.dirname(targetPath), 'bootstrap output directory');
+    assertSecureBootstrapOutputTarget(targetPath);
+    return {
+      bootstrapOutputReady: true,
+      bootstrapOutputError: null,
+    };
+  } catch (error) {
+    return {
+      bootstrapOutputReady: false,
+      bootstrapOutputError: renderError(error),
+    };
+  }
+}
+
+function ensurePrivateOutputDirectory(targetPath: string, label: string): string {
+  const resolvedPath = path.resolve(targetPath);
+  assertNoSymlinkAncestorDirectories(resolvedPath, label);
+  const stats = readLstat(resolvedPath);
+  if (stats?.isSymbolicLink()) {
+    throw new Error(`${label} '${resolvedPath}' must not be a symlink`);
+  }
+
+  if (stats) {
+    if (!stats.isDirectory()) {
+      throw new Error(`${label} '${resolvedPath}' must be a directory`);
+    }
+    tryChmod(resolvedPath, PRIVATE_DIR_MODE);
+    assertTrustedDirectoryPath(resolvedPath, label);
+    assertWritableDirectoryAccess(resolvedPath, label);
+    return resolvedPath;
+  }
+
+  const parentPath = path.dirname(resolvedPath);
+  if (parentPath !== resolvedPath) {
+    ensurePrivateOutputDirectory(parentPath, `${label} parent`);
+  }
+
+  fs.mkdirSync(resolvedPath, { mode: PRIVATE_DIR_MODE });
+  tryChmod(resolvedPath, PRIVATE_DIR_MODE);
+  assertTrustedDirectoryPath(resolvedPath, label);
+  assertWritableDirectoryAccess(resolvedPath, label);
+  return resolvedPath;
+}
+
+function assertSecureBootstrapOutputTarget(targetPath: string): void {
+  const resolvedPath = path.resolve(targetPath);
+  const stats = readLstat(resolvedPath);
+  if (!stats) {
+    return;
+  }
+  if (stats.isSymbolicLink()) {
+    throw new Error(`bootstrap output file '${resolvedPath}' must not be a symlink`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`bootstrap output file '${resolvedPath}' must be a regular file`);
+  }
+
+  assertPrivateFileStats(stats, resolvedPath, 'bootstrap output file');
+  assertWritableFileAccess(resolvedPath, 'bootstrap output file');
+}
+
+function configuredChainName(chainId: number, currentConfig: WlfiConfig): string | null {
+  for (const profile of Object.values(currentConfig.chains ?? {})) {
+    if (profile.chainId === chainId && profile.name.trim().length > 0) {
+      return profile.name.trim();
+    }
+  }
+
+  const builtin = listBuiltinChains().find((profile) => profile.chainId === chainId);
+  return builtin?.name ?? null;
+}
+
+function configuredRpcUrl(chainId: number, currentConfig: WlfiConfig): string | undefined {
+  if (currentConfig.chainId === chainId) {
+    const currentRpcUrl = presentString(currentConfig.rpcUrl);
+    if (currentRpcUrl) {
+      return currentRpcUrl;
+    }
+  }
+
+  for (const profile of Object.values(currentConfig.chains ?? {})) {
+    if (profile.chainId === chainId) {
+      const candidate = presentString(profile.rpcUrl);
+      if (candidate) {
+        return candidate;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function resolvePlannedRpcUrl(
+  chainId: number | null,
+  rpcUrl: string | undefined,
+  currentConfig: WlfiConfig,
+): string | null {
+  if (chainId === null) {
+    return null;
+  }
+
+  return presentString(rpcUrl) ?? configuredRpcUrl(chainId, currentConfig) ?? null;
+}
+
+function resolveWalletSetupPreflight(
+  daemonSocket: string,
+  rpcUrl: string | null,
+  bootstrapOutputPath: string,
+  trustDaemonSocketPath: (targetPath: string, label?: string) => string,
+): WalletSetupPlan['preflight'] {
+  let daemonSocketTrusted = true;
+  let daemonSocketError: string | null = null;
+  try {
+    trustDaemonSocketPath(daemonSocket);
+  } catch (error) {
+    daemonSocketTrusted = false;
+    daemonSocketError = renderError(error);
+  }
+
+  const bootstrapOutput = resolveBootstrapOutputPreflight(bootstrapOutputPath);
+
+  if (rpcUrl === null) {
+    return {
+      daemonSocketTrusted,
+      daemonSocketError,
+      rpcUrlTrusted: null,
+      rpcUrlError: null,
+      ...bootstrapOutput,
+    };
+  }
+
+  try {
+    assertSafeRpcUrl(rpcUrl, 'rpcUrl');
+    return {
+      daemonSocketTrusted,
+      daemonSocketError,
+      rpcUrlTrusted: true,
+      rpcUrlError: null,
+      ...bootstrapOutput,
+    };
+  } catch (error) {
+    return {
+      daemonSocketTrusted,
+      daemonSocketError,
+      rpcUrlTrusted: false,
+      rpcUrlError: renderError(error),
+      ...bootstrapOutput,
+    };
+  }
+}
+
+export function assertWalletSetupExecutionPreconditions(
+  options: Pick<CompleteWalletSetupOptions, 'daemonSocket' | 'network' | 'rpcUrl'>,
+  currentConfig: WlfiConfig,
+  deps: Pick<CompleteWalletSetupDeps, 'assertTrustedDaemonSocketPath'> = {},
+): void {
+  const trustDaemonSocketPath =
+    deps.assertTrustedDaemonSocketPath ?? assertTrustedAdminDaemonSocketPath;
+
+  const daemonSocket =
+    presentString(options.daemonSocket) ?? presentString(currentConfig.daemonSocket);
+  if (options.network === undefined) {
+    if (daemonSocket) {
+      trustDaemonSocketPath(daemonSocket);
+    }
+    return;
+  }
+
+  const plannedRpcUrl = resolvePlannedRpcUrl(
+    assertPositiveChainId(options.network),
+    presentString(options.rpcUrl),
+    currentConfig,
+  );
+  if (plannedRpcUrl !== null) {
+    assertSafeRpcUrl(plannedRpcUrl, 'rpcUrl');
+  }
+
+  if (daemonSocket) {
+    trustDaemonSocketPath(daemonSocket);
+  }
+}
+
+function assertPositiveChainId(value: number): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error('network must be a positive safe integer');
+  }
+
+  return value;
+}
+
+function parsePositiveChainIdString(value: string): number {
+  const normalized = value.trim();
+  if (!/^[1-9][0-9]*$/u.test(normalized)) {
+    throw new Error('network must be a positive safe integer');
+  }
+
+  return assertPositiveChainId(Number(normalized));
+}
+
+function normalizedList(values: string[] | undefined): string[] {
+  return (values ?? []).map((value) => value.trim()).filter((value) => value.length > 0);
+}
+
+function dedupeCanonicalList(values: string[]): string[] {
+  const deduped: string[] = [];
+  const seen = new Set<string>();
+
+  for (const value of values) {
+    const canonical = value.toLowerCase();
+    if (seen.has(canonical)) {
+      continue;
+    }
+
+    seen.add(canonical);
+    deduped.push(canonical);
+  }
+
+  return deduped;
+}
+
+function assertWalletSetupAddress(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!isAddress(normalized)) {
+    throw new Error(`${label} must be a valid EVM address`);
+  }
+  return normalized;
+}
+
+function assertWalletSetupUuid(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!UUID_PATTERN.test(normalized)) {
+    throw new Error(`${label} must be a valid UUID`);
+  }
+  return normalized;
+}
+
+function resolveValidatedWalletSetupRecipient(value: string | undefined): string | undefined {
+  const normalized = presentString(value);
+  return normalized ? assertWalletSetupAddress(normalized, 'recipient') : undefined;
+}
+
+function resolveValidatedWalletSetupTokenList(values: string[] | undefined): string[] {
+  return dedupeCanonicalList(
+    normalizedList(values).map((value) => assertWalletSetupAddress(value, 'token')),
+  );
+}
+
+function resolveValidatedWalletSetupPolicyIds(values: string[] | undefined): string[] {
+  return dedupeCanonicalList(
+    normalizedList(values).map((value) => assertWalletSetupUuid(value, 'attachPolicyId')),
+  );
+}
+
+function previewBootstrapOutputPath(inputPath?: string): WalletSetupBootstrapOutput {
+  const explicitPath = presentString(inputPath);
+  if (explicitPath) {
+    return {
+      path: path.resolve(explicitPath),
+      autoGenerated: false,
+    };
+  }
+
+  return {
+    path: path.join(resolveWlfiHome(), AUTO_GENERATED_BOOTSTRAP_FILENAME),
+    autoGenerated: true,
+  };
+}
+
+function resolvePreviewDaemonSocket(input: string | undefined, currentConfig: WlfiConfig): string {
+  return path.resolve(
+    presentString(input) ?? presentString(currentConfig.daemonSocket) ?? defaultDaemonSocketPath(),
+  );
+}
+
+function resolveOptionalLimit(value: string | undefined): string | null {
+  return presentString(value) ?? null;
+}
+
+function resolveRequiredLimit(value: string | undefined): string {
+  return presentString(value) ?? RUST_DEFAULT_VALUE;
+}
+
+function resolveAssetMode(
+  tokens: string[],
+  allowNativeEth: boolean,
+): WalletSetupPlan['policyScope']['assets']['mode'] {
+  if (tokens.length > 0 && allowNativeEth) {
+    return 'mixed';
+  }
+  if (tokens.length > 0) {
+    return 'erc20-only';
+  }
+  if (allowNativeEth) {
+    return 'native-only';
+  }
+  return 'daemon-default';
+}
+
+function resolveAttachmentMode(
+  _attachBootstrapPolicies: boolean,
+  explicitPolicyIds: string[],
+): WalletSetupPlan['policyAttachment']['mode'] {
+  if (explicitPolicyIds.length > 0) {
+    return 'bootstrap-and-explicit';
+  }
+  return 'bootstrap-only';
+}
+
+function shouldBootstrapFromSharedConfig(
+  input: Pick<
+    WalletSetupAdminArgsInput,
+    | 'fromSharedConfig'
+    | 'perTxMaxWei'
+    | 'dailyMaxWei'
+    | 'weeklyMaxWei'
+    | 'maxGasPerChainWei'
+    | 'dailyMaxTxCount'
+    | 'perTxMaxFeePerGasWei'
+    | 'perTxMaxPriorityFeePerGasWei'
+    | 'perTxMaxCalldataBytes'
+    | 'token'
+    | 'allowNativeEth'
+    | 'recipient'
+  >,
+): boolean {
+  if (typeof input.fromSharedConfig === 'boolean') {
+    return input.fromSharedConfig;
+  }
+
+  const hasExplicitLegacyPolicyScope = Boolean(
+    presentString(input.perTxMaxWei) ||
+      presentString(input.dailyMaxWei) ||
+      presentString(input.weeklyMaxWei) ||
+      presentString(input.maxGasPerChainWei) ||
+      presentString(input.dailyMaxTxCount) ||
+      presentString(input.perTxMaxFeePerGasWei) ||
+      presentString(input.perTxMaxPriorityFeePerGasWei) ||
+      presentString(input.perTxMaxCalldataBytes) ||
+      resolveValidatedWalletSetupTokenList(input.token).length > 0 ||
+      input.allowNativeEth ||
+      resolveValidatedWalletSetupRecipient(input.recipient),
+  );
+
+  return !hasExplicitLegacyPolicyScope;
+}
+
+function normalizePositiveIntegerString(value: string | undefined, label: string): string | null {
+  const normalized = presentString(value);
+  if (!normalized) {
+    return null;
+  }
+  if (!/^[1-9][0-9]*$/u.test(normalized)) {
+    throw new Error(`${label} must be a positive integer string`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalPositiveIntegerString(
+  value: string | undefined,
+  label: string,
+): string | null {
+  const normalized = presentString(value);
+  if (!normalized) {
+    return null;
+  }
+  if (!/^(0|[1-9][0-9]*)$/u.test(normalized)) {
+    throw new Error(`${label} must be a non-negative integer string`);
+  }
+  return normalized === '0' ? null : normalized;
+}
+
+function expectedWalletSetupNetworkScope(network: number | undefined): string {
+  return network === undefined ? 'all networks' : String(assertPositiveChainId(network));
+}
+
+function expectedWalletSetupAssetScope(
+  tokens: string[] | undefined,
+  allowNativeEth: boolean,
+): string {
+  const normalizedTokens = resolveValidatedWalletSetupTokenList(tokens)
+    .map((token) => token.toLowerCase())
+    .sort((left, right) => left.localeCompare(right));
+
+  if (normalizedTokens.length === 0 && !allowNativeEth) {
+    return 'all assets';
+  }
+
+  const assets = [
+    ...(allowNativeEth ? ['native_eth'] : []),
+    ...normalizedTokens.map((token) => `erc20:${token}`),
+  ];
+  return assets.join(',');
+}
+
+function expectedWalletSetupRecipientScope(recipient: string | undefined): string {
+  const normalizedRecipient = resolveValidatedWalletSetupRecipient(recipient);
+  return normalizedRecipient ? normalizedRecipient.toLowerCase() : 'all recipients';
+}
+
+function createdBootstrapPolicyIds(summary: BootstrapSetupSummary): string[] {
+  const ids = [
+    summary.perTxPolicyId,
+    summary.dailyPolicyId,
+    summary.weeklyPolicyId,
+    summary.gasPolicyId,
+    summary.dailyTxCountPolicyId,
+    summary.perTxMaxFeePerGasPolicyId,
+    summary.perTxMaxPriorityFeePerGasPolicyId,
+    summary.perTxMaxCalldataBytesPolicyId,
+  ].filter((value): value is string => typeof value === 'string' && value.length > 0);
+
+  for (const destinationOverride of summary.destinationOverrides ?? []) {
+    ids.push(
+      destinationOverride.perTxPolicyId,
+      destinationOverride.dailyPolicyId,
+      destinationOverride.weeklyPolicyId,
+    );
+    if (destinationOverride.gasPolicyId) {
+      ids.push(destinationOverride.gasPolicyId);
+    }
+    if (destinationOverride.dailyTxCountPolicyId) {
+      ids.push(destinationOverride.dailyTxCountPolicyId);
+    }
+    if (destinationOverride.perTxMaxFeePerGasPolicyId) {
+      ids.push(destinationOverride.perTxMaxFeePerGasPolicyId);
+    }
+    if (destinationOverride.perTxMaxPriorityFeePerGasPolicyId) {
+      ids.push(destinationOverride.perTxMaxPriorityFeePerGasPolicyId);
+    }
+    if (destinationOverride.perTxMaxCalldataBytesPolicyId) {
+      ids.push(destinationOverride.perTxMaxCalldataBytesPolicyId);
+    }
+  }
+
+  for (const tokenPolicy of summary.tokenPolicies ?? []) {
+    ids.push(tokenPolicy.perTxPolicyId, tokenPolicy.dailyPolicyId, tokenPolicy.weeklyPolicyId);
+    if (tokenPolicy.gasPolicyId) {
+      ids.push(tokenPolicy.gasPolicyId);
+    }
+    if (tokenPolicy.dailyTxCountPolicyId) {
+      ids.push(tokenPolicy.dailyTxCountPolicyId);
+    }
+    if (tokenPolicy.perTxMaxFeePerGasPolicyId) {
+      ids.push(tokenPolicy.perTxMaxFeePerGasPolicyId);
+    }
+    if (tokenPolicy.perTxMaxPriorityFeePerGasPolicyId) {
+      ids.push(tokenPolicy.perTxMaxPriorityFeePerGasPolicyId);
+    }
+    if (tokenPolicy.perTxMaxCalldataBytesPolicyId) {
+      ids.push(tokenPolicy.perTxMaxCalldataBytesPolicyId);
+    }
+  }
+
+  for (const destinationOverride of summary.tokenDestinationOverrides ?? []) {
+    ids.push(
+      destinationOverride.perTxPolicyId,
+      destinationOverride.dailyPolicyId,
+      destinationOverride.weeklyPolicyId,
+    );
+    if (destinationOverride.gasPolicyId) {
+      ids.push(destinationOverride.gasPolicyId);
+    }
+    if (destinationOverride.dailyTxCountPolicyId) {
+      ids.push(destinationOverride.dailyTxCountPolicyId);
+    }
+    if (destinationOverride.perTxMaxFeePerGasPolicyId) {
+      ids.push(destinationOverride.perTxMaxFeePerGasPolicyId);
+    }
+    if (destinationOverride.perTxMaxPriorityFeePerGasPolicyId) {
+      ids.push(destinationOverride.perTxMaxPriorityFeePerGasPolicyId);
+    }
+    if (destinationOverride.perTxMaxCalldataBytesPolicyId) {
+      ids.push(destinationOverride.perTxMaxCalldataBytesPolicyId);
+    }
+  }
+
+  for (const manualApproval of summary.tokenManualApprovalPolicies ?? []) {
+    ids.push(manualApproval.policyId);
+  }
+
+  return ids;
+}
+
+function normalizeStringSet(values: string[]): Set<string> {
+  return new Set(values.map((value) => value.toLowerCase()));
+}
+
+function assertRequestedRequiredLimit(
+  requestedValue: string | undefined,
+  summaryValue: string | null,
+  label: string,
+): void {
+  const normalizedRequested = normalizePositiveIntegerString(requestedValue, label);
+  if (normalizedRequested !== null && normalizedRequested !== summaryValue) {
+    throw new Error(`bootstrap summary ${label} does not match the requested wallet setup limit`);
+  }
+}
+
+function assertRequestedOptionalLimit(
+  requestedValue: string | undefined,
+  summaryValue: string | null,
+  summaryPolicyId: string | null,
+  label: string,
+): void {
+  const normalizedRequested = normalizeOptionalPositiveIntegerString(requestedValue, label);
+
+  if (normalizedRequested === null) {
+    if (summaryValue !== null || summaryPolicyId !== null) {
+      throw new Error(`bootstrap summary ${label} was enabled unexpectedly`);
+    }
+    return;
+  }
+
+  if (summaryValue !== normalizedRequested) {
+    throw new Error(`bootstrap summary ${label} does not match the requested wallet setup limit`);
+  }
+  if (summaryPolicyId === null) {
+    throw new Error(`bootstrap summary ${label} is missing its policy id`);
+  }
+}
+
+function assertWalletSetupSummaryMatchesRequest(
+  summary: BootstrapSetupSummary,
+  options: CompleteWalletSetupOptions,
+): void {
+  const usesPerTokenBootstrap =
+    summary.tokenPolicies.length > 0 ||
+    summary.tokenDestinationOverrides.length > 0 ||
+    summary.tokenManualApprovalPolicies.length > 0;
+
+  if (
+    !usesPerTokenBootstrap &&
+    summary.networkScope !== expectedWalletSetupNetworkScope(options.network)
+  ) {
+    throw new Error(
+      'bootstrap summary network_scope does not match the requested wallet setup scope',
+    );
+  }
+
+  if (
+    !usesPerTokenBootstrap &&
+    summary.assetScope !==
+      expectedWalletSetupAssetScope(options.token, Boolean(options.allowNativeEth))
+  ) {
+    throw new Error(
+      'bootstrap summary asset_scope does not match the requested wallet setup scope',
+    );
+  }
+
+  if (
+    !usesPerTokenBootstrap &&
+    summary.recipientScope !== expectedWalletSetupRecipientScope(options.recipient)
+  ) {
+    throw new Error(
+      'bootstrap summary recipient_scope does not match the requested wallet setup scope',
+    );
+  }
+
+  if (!usesPerTokenBootstrap) {
+    assertRequestedRequiredLimit(options.perTxMaxWei, summary.perTxMaxWei, 'perTxMaxWei');
+    assertRequestedRequiredLimit(options.dailyMaxWei, summary.dailyMaxWei, 'dailyMaxWei');
+    assertRequestedRequiredLimit(options.weeklyMaxWei, summary.weeklyMaxWei, 'weeklyMaxWei');
+    assertRequestedRequiredLimit(
+      options.maxGasPerChainWei,
+      summary.maxGasPerChainWei,
+      'maxGasPerChainWei',
+    );
+
+    assertRequestedOptionalLimit(
+      options.dailyMaxTxCount,
+      summary.dailyMaxTxCount,
+      summary.dailyTxCountPolicyId,
+      'dailyMaxTxCount',
+    );
+    assertRequestedOptionalLimit(
+      options.perTxMaxFeePerGasWei,
+      summary.perTxMaxFeePerGasWei,
+      summary.perTxMaxFeePerGasPolicyId,
+      'perTxMaxFeePerGasWei',
+    );
+    assertRequestedOptionalLimit(
+      options.perTxMaxPriorityFeePerGasWei,
+      summary.perTxMaxPriorityFeePerGasWei,
+      summary.perTxMaxPriorityFeePerGasPolicyId,
+      'perTxMaxPriorityFeePerGasWei',
+    );
+    assertRequestedOptionalLimit(
+      options.perTxMaxCalldataBytes,
+      summary.perTxMaxCalldataBytes,
+      summary.perTxMaxCalldataBytesPolicyId,
+      'perTxMaxCalldataBytes',
+    );
+  }
+
+  const explicitPolicyIds = normalizeStringSet(
+    resolveValidatedWalletSetupPolicyIds(options.attachPolicyId),
+  );
+  const expectedAttachment = 'policy_set';
+  if (summary.policyAttachment !== expectedAttachment) {
+    throw new Error(
+      'bootstrap summary policy_attachment does not match the requested wallet setup attachment',
+    );
+  }
+
+  const actualAttachedPolicyIds = normalizeStringSet(summary.attachedPolicyIds);
+  const expectedAttachedPolicyIds = new Set(
+    createdBootstrapPolicyIds(summary).map((policyId) => policyId.toLowerCase()),
+  );
+  for (const policyId of explicitPolicyIds) {
+    expectedAttachedPolicyIds.add(policyId);
+  }
+
+  if (actualAttachedPolicyIds.size !== expectedAttachedPolicyIds.size) {
+    throw new Error(
+      'bootstrap summary attached_policy_ids do not match the requested wallet setup attachment',
+    );
+  }
+  for (const policyId of expectedAttachedPolicyIds) {
+    if (!actualAttachedPolicyIds.has(policyId)) {
+      throw new Error(
+        'bootstrap summary attached_policy_ids do not match the requested wallet setup attachment',
+      );
+    }
+  }
+}
+
+function previewWalletSetupRustArgs(
+  input: Omit<WalletSetupAdminArgsInput, 'bootstrapOutputPath'> & { bootstrapOutputPath?: string },
+  _adminAccessMode: AdminAccessMode,
+  bootstrapOutputPath: string,
+): string[] {
+  return buildWalletSetupAdminArgs({
+    ...input,
+    bootstrapOutputPath,
+  });
+}
+
+export function createWalletSetupPlan(
+  input: WalletSetupPlanOptions,
+  deps: CreateWalletSetupPlanDeps = {},
+): WalletSetupPlan {
+  const loadConfig = deps.readConfig ?? readConfig;
+  const trustDaemonSocketPath =
+    deps.assertTrustedDaemonSocketPath ?? assertTrustedAdminDaemonSocketPath;
+  const currentConfig = loadConfig();
+  const network = presentString(input.network);
+  const rpcUrl = presentString(input.rpcUrl);
+  const chainName = presentString(input.chainName);
+
+  if (rpcUrl && !network) {
+    throw new Error('--rpc-url requires --network');
+  }
+  if (chainName && !network) {
+    throw new Error('--chain-name requires --network');
+  }
+
+  const chainId = network ? parsePositiveChainIdString(network) : null;
+  const resolvedRpcUrl = resolvePlannedRpcUrl(chainId, rpcUrl, currentConfig);
+  const resolvedChainName =
+    chainId === null
+      ? null
+      : chainName
+        ? chainName
+        : (configuredChainName(chainId, currentConfig) ?? `chain-${chainId}`);
+
+  const bootstrapOutput = previewBootstrapOutputPath(input.bootstrapOutputPath);
+  const cleanupAction = resolveWalletSetupCleanupAction(
+    bootstrapOutput.autoGenerated,
+    Boolean(input.deleteBootstrapOutput),
+  );
+  const explicitPolicyIds = resolveValidatedWalletSetupPolicyIds(input.attachPolicyId);
+  const erc20Tokens = resolveValidatedWalletSetupTokenList(input.token);
+  const recipient = resolveValidatedWalletSetupRecipient(input.recipient) ?? null;
+  const daemonSocket = resolvePreviewDaemonSocket(input.daemonSocket, currentConfig);
+  const preflight = resolveWalletSetupPreflight(
+    daemonSocket,
+    resolvedRpcUrl,
+    bootstrapOutput.path,
+    trustDaemonSocketPath,
+  );
+  const rustArgs = previewWalletSetupRustArgs(input, 'blocked', bootstrapOutput.path);
+  const adminAccess = resolveAdminAccess('wlfi-agent-admin', rustArgs, deps);
+
+  const notes = [
+    'Rust still performs the real password check and policy creation.',
+    'TypeScript imports the emitted agent auth token into macOS Keychain after bootstrap.',
+    'TypeScript re-checks the emitted bootstrap summary against the requested setup scope before importing credentials.',
+    cleanupAction === 'deleted'
+      ? 'The bootstrap JSON is deleted after Keychain import.'
+      : 'The bootstrap JSON is redacted after Keychain import so the plaintext token is removed.',
+  ];
+
+  if (chainId !== null && resolvedRpcUrl === null) {
+    notes.push(
+      'No rpcUrl is persisted for this network unless you pass --rpc-url or configure one already.',
+    );
+  } else if (preflight.rpcUrlTrusted === false) {
+    notes.push(
+      'The rpcUrl that would be persisted for this setup is not trusted and wallet setup would fail until it is fixed.',
+    );
+  }
+  if (adminAccess.mode === 'vault-password-stdin') {
+    notes.push(
+      'The vault password is passed to Rust through stdin and scrubbed from child argv/env.',
+    );
+  } else if (adminAccess.mode === 'interactive-prompt') {
+    notes.push(
+      'A local tty is expected so a human can enter the vault password securely during bootstrap.',
+    );
+  } else if (!adminAccess.permitted) {
+    notes.push(
+      'This environment would not be allowed to run wallet setup until a vault password source is provided or a local tty prompt is available.',
+    );
+  }
+  if (!preflight.daemonSocketTrusted) {
+    notes.push(
+      'The daemon socket is not currently trusted or reachable, so wallet setup would fail until it is fixed.',
+    );
+  }
+  if (!preflight.bootstrapOutputReady) {
+    notes.push(
+      'The bootstrap output path is not currently safe or writable, so wallet setup would fail before bootstrap starts.',
+    );
+  }
+
+  const rustPasswordTransport =
+    adminAccess.mode === 'interactive-prompt'
+      ? 'interactive-prompt'
+      : adminAccess.mode === 'blocked'
+        ? 'not-available'
+        : 'stdin-relay';
+
+  return {
+    adminAccess: {
+      permitted: adminAccess.permitted,
+      mode: adminAccess.mode,
+      reason: adminAccess.reason,
+      nonInteractive: adminAccess.nonInteractive,
+    },
+    rustCommand: {
+      binary: 'wlfi-agent-admin',
+      args: previewWalletSetupRustArgs(input, adminAccess.mode, bootstrapOutput.path),
+    },
+    bootstrapOutput: {
+      path: bootstrapOutput.path,
+      autoGenerated: bootstrapOutput.autoGenerated,
+      cleanupAction,
+    },
+    daemonSocket,
+    policyLimits: {
+      perTxMaxWei: resolveRequiredLimit(input.perTxMaxWei),
+      dailyMaxWei: resolveRequiredLimit(input.dailyMaxWei),
+      weeklyMaxWei: resolveRequiredLimit(input.weeklyMaxWei),
+      maxGasPerChainWei: resolveRequiredLimit(input.maxGasPerChainWei),
+      dailyMaxTxCount: resolveOptionalLimit(input.dailyMaxTxCount),
+      perTxMaxFeePerGasWei: resolveOptionalLimit(input.perTxMaxFeePerGasWei),
+      perTxMaxPriorityFeePerGasWei: resolveOptionalLimit(input.perTxMaxPriorityFeePerGasWei),
+      perTxMaxCalldataBytes: resolveOptionalLimit(input.perTxMaxCalldataBytes),
+    },
+    policyScope: {
+      network: chainId,
+      chainName: resolvedChainName,
+      recipient,
+      assets: {
+        mode: resolveAssetMode(erc20Tokens, Boolean(input.allowNativeEth)),
+        allowNativeEth: Boolean(input.allowNativeEth),
+        erc20Tokens,
+      },
+    },
+    policyAttachment: {
+      mode: resolveAttachmentMode(Boolean(input.attachBootstrapPolicies), explicitPolicyIds),
+      attachBootstrapPolicies: Boolean(input.attachBootstrapPolicies),
+      explicitPolicyIds,
+    },
+    configAfterSetup: {
+      agentKeyId: '<issued during bootstrap>',
+      daemonSocket,
+      chainId,
+      chainName: resolvedChainName,
+      rpcUrl: resolvedRpcUrl,
+    },
+    preflight,
+    security: {
+      rustPasswordTransport,
+      childArgvContainsVaultPassword: false,
+      childEnvContainsVaultPassword: false,
+      keyMaterialStorage: 'macOS Keychain',
+      bootstrapCredentialCleanup: cleanupAction,
+      notes,
+    },
+  };
+}
+
+function formatOptionalPlanValue(value: string | null, fallback = 'none'): string {
+  return value ?? fallback;
+}
+
+function formatBooleanPlanValue(value: boolean): string {
+  return value ? 'yes' : 'no';
+}
+
+function formatWalletSetupScope(plan: WalletSetupPlan): string[] {
+  return [
+    `- Network: ${plan.policyScope.network === null ? 'daemon default' : String(plan.policyScope.network)}`,
+    `- Chain Name: ${plan.policyScope.chainName ?? 'daemon default'}`,
+    `- Recipient: ${plan.policyScope.recipient ?? 'all recipients'}`,
+    `- Asset Mode: ${plan.policyScope.assets.mode}`,
+    `- Native Transfers Allowed: ${formatBooleanPlanValue(plan.policyScope.assets.allowNativeEth)}`,
+    `- ERC20 Tokens: ${
+      plan.policyScope.assets.erc20Tokens.length > 0
+        ? plan.policyScope.assets.erc20Tokens.join(', ')
+        : 'daemon default'
+    }`,
+  ];
+}
+
+function formatWalletSetupLimits(plan: WalletSetupPlan): string[] {
+  return [
+    `- Per Tx Max Wei: ${plan.policyLimits.perTxMaxWei}`,
+    `- Daily Max Wei: ${plan.policyLimits.dailyMaxWei}`,
+    `- Weekly Max Wei: ${plan.policyLimits.weeklyMaxWei}`,
+    `- Max Gas Per Chain Wei: ${plan.policyLimits.maxGasPerChainWei}`,
+    `- Daily Max Tx Count: ${formatOptionalPlanValue(plan.policyLimits.dailyMaxTxCount)}`,
+    `- Per Tx Max Fee Per Gas Wei: ${formatOptionalPlanValue(plan.policyLimits.perTxMaxFeePerGasWei)}`,
+    `- Per Tx Max Priority Fee Per Gas Wei: ${formatOptionalPlanValue(
+      plan.policyLimits.perTxMaxPriorityFeePerGasWei,
+    )}`,
+    `- Per Tx Max Calldata Bytes: ${formatOptionalPlanValue(plan.policyLimits.perTxMaxCalldataBytes)}`,
+  ];
+}
+
+function formatWalletSetupPreflight(plan: WalletSetupPlan): string[] {
+  return [
+    `- Daemon Socket Trusted: ${formatBooleanPlanValue(plan.preflight.daemonSocketTrusted)}`,
+    plan.preflight.daemonSocketError ? `  ${plan.preflight.daemonSocketError}` : null,
+    `- RPC URL Trusted: ${
+      plan.preflight.rpcUrlTrusted === null
+        ? 'not applicable'
+        : formatBooleanPlanValue(plan.preflight.rpcUrlTrusted)
+    }`,
+    plan.preflight.rpcUrlError ? `  ${plan.preflight.rpcUrlError}` : null,
+    `- Bootstrap Output Ready: ${formatBooleanPlanValue(plan.preflight.bootstrapOutputReady)}`,
+    plan.preflight.bootstrapOutputError ? `  ${plan.preflight.bootstrapOutputError}` : null,
+  ].filter((line): line is string => Boolean(line));
+}
+
+export function formatWalletSetupPlanText(plan: WalletSetupPlan): string {
+  const bootstrapOutputLabel = `${plan.bootstrapOutput.path} (${plan.bootstrapOutput.autoGenerated ? 'auto-generated' : 'explicit'}, ${plan.bootstrapOutput.cleanupAction} after import)`;
+
+  const lines = [
+    'Wallet Setup Preview',
+    `Admin Access: ${plan.adminAccess.permitted ? 'allowed' : 'blocked'} (${plan.adminAccess.mode})`,
+    `Admin Access Reason: ${plan.adminAccess.reason}`,
+    `Daemon Socket: ${plan.daemonSocket}`,
+    `Bootstrap Output: ${bootstrapOutputLabel}`,
+    `Rust Command: ${plan.rustCommand.binary} ${plan.rustCommand.args.join(' ')}`,
+    '',
+    'Policy Scope',
+    ...formatWalletSetupScope(plan),
+    '',
+    'Policy Limits',
+    ...formatWalletSetupLimits(plan),
+    '',
+    'Policy Attachment',
+    `- Mode: ${plan.policyAttachment.mode}`,
+    `- Attach Bootstrap Policies: ${formatBooleanPlanValue(
+      plan.policyAttachment.attachBootstrapPolicies,
+    )}`,
+    `- Explicit Policy IDs: ${
+      plan.policyAttachment.explicitPolicyIds.length > 0
+        ? plan.policyAttachment.explicitPolicyIds.join(', ')
+        : 'none'
+    }`,
+    '',
+    'Config After Setup',
+    `- Agent Key ID: ${plan.configAfterSetup.agentKeyId}`,
+    `- Daemon Socket: ${plan.configAfterSetup.daemonSocket}`,
+    `- Chain ID: ${plan.configAfterSetup.chainId === null ? 'unchanged' : String(plan.configAfterSetup.chainId)}`,
+    `- Chain Name: ${plan.configAfterSetup.chainName ?? 'unchanged'}`,
+    `- RPC URL: ${plan.configAfterSetup.rpcUrl ?? 'unchanged'}`,
+    '',
+    'Preflight',
+    ...formatWalletSetupPreflight(plan),
+    '',
+    'Security',
+    `- Rust Password Transport: ${plan.security.rustPasswordTransport}`,
+    `- Child Argv Contains Vault Password: ${formatBooleanPlanValue(
+      plan.security.childArgvContainsVaultPassword,
+    )}`,
+    `- Child Env Contains Vault Password: ${formatBooleanPlanValue(
+      plan.security.childEnvContainsVaultPassword,
+    )}`,
+    `- Key Material Storage: ${plan.security.keyMaterialStorage}`,
+    `- Bootstrap Cleanup: ${plan.security.bootstrapCredentialCleanup}`,
+    'Notes:',
+    ...plan.security.notes.map((note) => `- ${note}`),
+  ];
+
+  return lines.join('\n');
+}
+
+export function resolveWalletSetupBootstrapOutputPath(
+  inputPath?: string,
+): WalletSetupBootstrapOutput {
+  const explicitPath = presentString(inputPath);
+  if (!explicitPath) {
+    const wlfiHome = ensureWlfiHome();
+    return {
+      path: path.join(wlfiHome, `bootstrap-${process.pid}-${Date.now()}.json`),
+      autoGenerated: true,
+    };
+  }
+
+  const resolvedPath = path.resolve(explicitPath);
+  ensurePrivateOutputDirectory(path.dirname(resolvedPath), 'bootstrap output directory');
+  assertSecureBootstrapOutputTarget(resolvedPath);
+  return {
+    path: resolvedPath,
+    autoGenerated: false,
+  };
+}
+
+export function resolveWalletSetupCleanupAction(
+  autoGeneratedOutput: boolean,
+  deleteBootstrapOutput: boolean,
+): BootstrapCleanupAction {
+  return autoGeneratedOutput || deleteBootstrapOutput ? 'deleted' : 'redacted';
+}
+
+export function buildWalletSetupAdminArgs(input: WalletSetupAdminArgsInput): string[] {
+  const args = ['--json', '--quiet', '--output', input.bootstrapOutputPath];
+  const recipient = resolveValidatedWalletSetupRecipient(input.recipient);
+  const tokens = resolveValidatedWalletSetupTokenList(input.token);
+  const policyIds = resolveValidatedWalletSetupPolicyIds(input.attachPolicyId);
+  const fromSharedConfig = shouldBootstrapFromSharedConfig(input);
+
+  if (input.vaultPassword) {
+    throw new Error(
+      'insecure vaultPassword is disabled; use vaultPasswordStdin or an interactive prompt',
+    );
+  }
+  if (input.vaultPasswordStdin) {
+    args.push('--vault-password-stdin');
+  }
+  if (input.nonInteractive) {
+    args.push('--non-interactive');
+  }
+  if (input.daemonSocket) {
+    args.push('--daemon-socket', input.daemonSocket);
+  }
+
+  args.push('bootstrap', '--print-agent-auth-token');
+  if (fromSharedConfig) {
+    args.push('--from-shared-config');
+  }
+
+  const appendValue = (flag: string, value: string | undefined) => {
+    if (value) {
+      args.push(flag, value);
+    }
+  };
+
+  if (!fromSharedConfig) {
+    appendValue('--per-tx-max-wei', input.perTxMaxWei);
+    appendValue('--daily-max-wei', input.dailyMaxWei);
+    appendValue('--weekly-max-wei', input.weeklyMaxWei);
+    appendValue('--max-gas-per-chain-wei', input.maxGasPerChainWei);
+    appendValue('--daily-max-tx-count', input.dailyMaxTxCount);
+    appendValue('--per-tx-max-fee-per-gas-wei', input.perTxMaxFeePerGasWei);
+    appendValue('--per-tx-max-priority-fee-per-gas-wei', input.perTxMaxPriorityFeePerGasWei);
+    appendValue('--per-tx-max-calldata-bytes', input.perTxMaxCalldataBytes);
+    appendValue('--network', input.network);
+    appendValue('--recipient', recipient);
+
+    for (const token of tokens) {
+      appendValue('--token', token);
+    }
+    if (input.allowNativeEth) {
+      args.push('--allow-native-eth');
+    }
+  }
+  for (const policyId of policyIds) {
+    appendValue('--attach-policy-id', policyId);
+  }
+  args.push('--attach-bootstrap-policies');
+
+  return args;
+}
+
+export function completeWalletSetup(
+  options: CompleteWalletSetupOptions,
+  deps: CompleteWalletSetupDeps = {},
+): CompleteWalletSetupResult {
+  const platform = deps.platform ?? process.platform;
+  if (platform !== 'darwin') {
+    throw new Error(
+      'wallet setup requires macOS because agent auth tokens are imported into macOS Keychain',
+    );
+  }
+
+  const normalizedRpcUrl = presentString(options.rpcUrl);
+  const normalizedChainName = presentString(options.chainName);
+  if (normalizedRpcUrl && options.network === undefined) {
+    throw new Error('--rpc-url requires --network');
+  }
+  if (normalizedChainName && options.network === undefined) {
+    throw new Error('--chain-name requires --network');
+  }
+
+  const storeAgentAuthToken = deps.storeAgentAuthToken ?? storeAgentAuthTokenInKeychain;
+  const loadConfig = deps.readConfig ?? readConfig;
+  const persistConfig = deps.writeConfig ?? writeConfig;
+  const clearLegacyConfigKey = deps.deleteConfigKey ?? deleteConfigKey;
+  const trustDaemonSocketPath =
+    deps.assertTrustedDaemonSocketPath ?? assertTrustedAdminDaemonSocketPath;
+
+  const currentConfig = loadConfig();
+  assertWalletSetupExecutionPreconditions(
+    {
+      daemonSocket: options.daemonSocket,
+      network: options.network,
+      rpcUrl: normalizedRpcUrl,
+    },
+    currentConfig,
+    {
+      assertTrustedDaemonSocketPath: trustDaemonSocketPath,
+    },
+  );
+
+  try {
+    const { summary, credentials } = readBootstrapSetupFile(options.bootstrapOutputPath);
+    assertBootstrapSetupSummaryLeaseIsActive(summary);
+
+    if (summary.agentKeyId !== credentials.agentKeyId) {
+      throw new Error(
+        'bootstrap credentials file agent_key_id does not match setup summary agent_key_id',
+      );
+    }
+
+    assertWalletSetupSummaryMatchesRequest(summary, options);
+
+    const nextConfig: WlfiConfig = {
+      agentKeyId: credentials.agentKeyId,
+      wallet: walletProfileFromBootstrapSummary(summary),
+    };
+
+    const daemonSocket = presentString(options.daemonSocket);
+    if (daemonSocket) {
+      nextConfig.daemonSocket = trustDaemonSocketPath(daemonSocket);
+    }
+
+    if (options.network !== undefined) {
+      nextConfig.chainId = assertPositiveChainId(options.network);
+      nextConfig.chainName =
+        normalizedChainName ??
+        configuredChainName(nextConfig.chainId, currentConfig) ??
+        `chain-${nextConfig.chainId}`;
+      nextConfig.rpcUrl = normalizedRpcUrl ?? configuredRpcUrl(nextConfig.chainId, currentConfig);
+    }
+
+    storeAgentAuthToken(credentials.agentKeyId, credentials.agentAuthToken);
+
+    let updated = persistConfig(nextConfig);
+    if (updated.agentAuthToken !== undefined) {
+      updated = clearLegacyConfigKey('agentAuthToken');
+    }
+
+    return {
+      ...summary,
+      agentAuthToken: credentials.agentAuthToken,
+      sourceCleanup: options.cleanupAction,
+      keychain: {
+        stored: true,
+        service: AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE,
+      },
+      config: redactConfig(updated),
+    };
+  } finally {
+    cleanupBootstrapAgentCredentialsFile(options.bootstrapOutputPath, options.cleanupAction);
+  }
+}