@wlfi-agent/cli 1.4.13 → 1.4.14

package/src/lib/keychain.ts

@@ -0,0 +1,225 @@
+import { spawnSync } from 'node:child_process';
+import { assertValidAgentAuthToken } from './agent-auth-token.js';
+
+export const AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE = 'wlfi-agent-agent-auth-token';
+export const DAEMON_PASSWORD_KEYCHAIN_SERVICE = 'wlfi-agent-daemon-password';
+const SECURITY_NOT_FOUND_EXIT_CODE = 44;
+const AGENT_KEY_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+const MAX_KEYCHAIN_SECRET_BYTES = 16 * 1024;
+const KEYCHAIN_IDENTIFIER_CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/u;
+
+export interface SecurityCommandInvocation {
+  args: string[];
+  input?: string;
+}
+
+export type SecurityCommandRunner = (command: SecurityCommandInvocation) => string;
+
+export function assertValidAgentKeyId(agentKeyId: string): string {
+  const normalized = agentKeyId.trim();
+  if (!AGENT_KEY_ID_PATTERN.test(normalized)) {
+    throw new Error('agentKeyId must be a valid UUID');
+  }
+  return normalized;
+}
+
+function defaultSecurityRunner(command: SecurityCommandInvocation): string {
+  const result = spawnSync('security', command.args, {
+    encoding: 'utf8',
+    input: command.input,
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const error = new Error(result.stderr.trim() || result.stdout.trim() || `security ${command.args[0]} failed`);
+    Object.assign(error, {
+      status: result.status,
+      stdout: result.stdout,
+      stderr: result.stderr
+    });
+    throw error;
+  }
+
+  return result.stdout.trim();
+}
+
+function renderSecurityError(error: unknown): string | null {
+  if (!(error instanceof Error)) {
+    return null;
+  }
+
+  const stderr = 'stderr' in error && typeof error.stderr === 'string' ? error.stderr.trim() : '';
+  const stdout = 'stdout' in error && typeof error.stdout === 'string' ? error.stdout.trim() : '';
+  return stderr || stdout || error.message || null;
+}
+
+function isMissingSecurityItem(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const status = 'status' in error && typeof error.status === 'number' ? error.status : null;
+  const message = renderSecurityError(error)?.toLowerCase() ?? '';
+  return status === SECURITY_NOT_FOUND_EXIT_CODE || message.includes('could not be found');
+}
+
+function assertMacOsKeychainAvailable(): void {
+  if (process.platform !== 'darwin') {
+    throw new Error('macOS Keychain integration is available only on macOS');
+  }
+}
+
+function withDefaultRunner(runner: SecurityCommandRunner): boolean {
+  return runner === defaultSecurityRunner;
+}
+
+function assertValidKeychainAccount(account: string): string {
+  const normalized = account.trim();
+  if (!normalized) {
+    throw new Error('keychain account is required');
+  }
+  if (KEYCHAIN_IDENTIFIER_CONTROL_CHAR_PATTERN.test(normalized)) {
+    throw new Error('keychain account must not contain control characters');
+  }
+  return normalized;
+}
+
+function assertValidKeychainService(service: string): string {
+  const normalized = service.trim();
+  if (!normalized) {
+    throw new Error('keychain service is required');
+  }
+  if (KEYCHAIN_IDENTIFIER_CONTROL_CHAR_PATTERN.test(normalized)) {
+    throw new Error('keychain service must not contain control characters');
+  }
+  return normalized;
+}
+
+function assertValidKeychainSecret(secret: string, label: string): string {
+  if (Buffer.byteLength(secret, 'utf8') > MAX_KEYCHAIN_SECRET_BYTES) {
+    throw new Error(`${label} must not exceed ${MAX_KEYCHAIN_SECRET_BYTES} bytes`);
+  }
+  if (!secret.trim()) {
+    throw new Error(`${label} must not be empty or whitespace`);
+  }
+  return secret;
+}
+
+function storeGenericPasswordInKeychain(
+  service: string,
+  account: string,
+  secret: string,
+  runner: SecurityCommandRunner = defaultSecurityRunner
+): void {
+  if (withDefaultRunner(runner)) {
+    assertMacOsKeychainAvailable();
+  }
+
+  const normalizedService = assertValidKeychainService(service);
+  const normalizedAccount = assertValidKeychainAccount(account);
+  const normalizedSecret = assertValidKeychainSecret(secret, 'keychain secret');
+
+  runner({
+    args: [
+      'add-generic-password',
+      '-U',
+      '-s',
+      normalizedService,
+      '-a',
+      normalizedAccount,
+      '-X',
+      Buffer.from(normalizedSecret, 'utf8').toString('hex'),
+    ],
+  });
+}
+
+export function storeAgentAuthTokenInKeychain(
+  agentKeyId: string,
+  token: string,
+  runner: SecurityCommandRunner = defaultSecurityRunner
+): void {
+  const normalizedAgentKeyId = assertValidAgentKeyId(agentKeyId);
+  const normalizedToken = assertValidAgentAuthToken(token, 'agentAuthToken');
+  storeGenericPasswordInKeychain(
+    AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE,
+    normalizedAgentKeyId,
+    normalizedToken,
+    runner
+  );
+}
+
+export function storeDaemonPasswordInKeychain(
+  account: string,
+  password: string,
+  runner: SecurityCommandRunner = defaultSecurityRunner
+): void {
+  storeGenericPasswordInKeychain(DAEMON_PASSWORD_KEYCHAIN_SERVICE, account, password, runner);
+}
+
+export function readAgentAuthTokenFromKeychain(
+  agentKeyId: string,
+  runner: SecurityCommandRunner = defaultSecurityRunner
+): string | null {
+  if (process.platform !== 'darwin' && withDefaultRunner(runner)) {
+    return null;
+  }
+
+  const normalizedAgentKeyId = assertValidAgentKeyId(agentKeyId);
+
+  try {
+    return runner({
+      args: [
+        'find-generic-password',
+        '-w',
+        '-s',
+        AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE,
+        '-a',
+        normalizedAgentKeyId
+      ]
+    });
+  } catch (error) {
+    if (isMissingSecurityItem(error)) {
+      return null;
+    }
+    throw new Error(renderSecurityError(error) ?? 'failed to read agent auth token from Keychain');
+  }
+}
+
+export function deleteAgentAuthTokenFromKeychain(
+  agentKeyId: string,
+  runner: SecurityCommandRunner = defaultSecurityRunner
+): boolean {
+  if (process.platform !== 'darwin' && withDefaultRunner(runner)) {
+    return false;
+  }
+
+  const normalizedAgentKeyId = assertValidAgentKeyId(agentKeyId);
+
+  try {
+    runner({
+      args: [
+        'delete-generic-password',
+        '-s',
+        AGENT_AUTH_TOKEN_KEYCHAIN_SERVICE,
+        '-a',
+        normalizedAgentKeyId
+      ]
+    });
+    return true;
+  } catch (error) {
+    if (isMissingSecurityItem(error)) {
+      return false;
+    }
+    throw new Error(renderSecurityError(error) ?? 'failed to delete agent auth token from Keychain');
+  }
+}
+
+export function hasAgentAuthTokenInKeychain(
+  agentKeyId: string,
+  runner: SecurityCommandRunner = defaultSecurityRunner
+): boolean {
+  return readAgentAuthTokenFromKeychain(agentKeyId, runner) !== null;
+}

package/src/lib/local-admin-access.ts

@@ -0,0 +1,106 @@
+import readline from 'node:readline';
+import { createSudoSession } from './sudo.js';
+
+const MAX_SECRET_STDIN_BYTES = 16 * 1024;
+
+export interface LocalAdminMutationAccessDeps {
+  isRoot?: () => boolean;
+  ensureRootAccess?: () => Promise<void>;
+}
+
+function renderError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function validateSecret(value: string, label: string): string {
+  if (Buffer.byteLength(value, 'utf8') > MAX_SECRET_STDIN_BYTES) {
+    throw new Error(`${label} must not exceed ${MAX_SECRET_STDIN_BYTES} bytes`);
+  }
+  if (!value.trim()) {
+    throw new Error(`${label} must not be empty or whitespace`);
+  }
+  return value;
+}
+
+function currentProcessIsRoot(): boolean {
+  return typeof process.geteuid === 'function' && process.geteuid() === 0;
+}
+
+async function promptHidden(query: string, label: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(`${label} is required; rerun on a local TTY`);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  }) as readline.Interface & { stdoutMuted?: boolean; _writeToOutput?: (value: string) => void };
+
+  rl.stdoutMuted = true;
+  rl._writeToOutput = (value: string) => {
+    if (value.includes(query)) {
+      (rl as unknown as { output: NodeJS.WritableStream }).output.write(value);
+      return;
+    }
+    if (!rl.stdoutMuted) {
+      (rl as unknown as { output: NodeJS.WritableStream }).output.write(value);
+    }
+  };
+
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(query, resolve);
+  });
+  rl.close();
+  process.stdout.write('\n');
+  return validateSecret(answer, label);
+}
+
+const sudoSession = createSudoSession({
+  promptPassword: async () =>
+    await promptHidden(
+      'Root password (input hidden; required to change local admin chain and token configuration): ',
+      'root password',
+    ),
+});
+
+export async function requireLocalAdminMutationAccess(
+  commandLabel: string,
+  deps: LocalAdminMutationAccessDeps = {},
+): Promise<void> {
+  const isRoot = deps.isRoot ?? currentProcessIsRoot;
+  if (isRoot()) {
+    return;
+  }
+
+  const ensureRootAccess = deps.ensureRootAccess ?? (() => sudoSession.prime());
+  try {
+    await ensureRootAccess();
+  } catch (error) {
+    throw new Error(
+      `${commandLabel} requires verified root access before local admin configuration can change: ${renderError(error)}`,
+    );
+  }
+}
+
+export function withLocalAdminMutationAccess<TArgs extends unknown[], TReturn>(
+  commandLabel: string,
+  action: (...args: TArgs) => TReturn | Promise<TReturn>,
+  deps: LocalAdminMutationAccessDeps = {},
+): (...args: TArgs) => Promise<TReturn> {
+  return async (...args: TArgs): Promise<TReturn> => {
+    await requireLocalAdminMutationAccess(commandLabel, deps);
+    return await action(...args);
+  };
+}
+
+export function withDynamicLocalAdminMutationAccess<TArgs extends unknown[], TReturn>(
+  resolveCommandLabel: (...args: TArgs) => string,
+  action: (...args: TArgs) => TReturn | Promise<TReturn>,
+  deps: LocalAdminMutationAccessDeps = {},
+): (...args: TArgs) => Promise<TReturn> {
+  return async (...args: TArgs): Promise<TReturn> => {
+    await requireLocalAdminMutationAccess(resolveCommandLabel(...args), deps);
+    return await action(...args);
+  };
+}

package/src/lib/network-selection.js

@@ -0,0 +1 @@
+export * from './network-selection.ts';

package/src/lib/network-selection.ts

@@ -0,0 +1,71 @@
+import {
+  assertSafeRpcUrl,
+  resolveChainProfile,
+  type WlfiConfig,
+} from '../../packages/config/src/index.js';
+
+function presentString(value: string | undefined | null): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+
+function isNumericSelector(value: string): boolean {
+  return /^[0-9]+$/u.test(value);
+}
+
+function resolveActiveNetworkSelector(config: WlfiConfig): string | undefined {
+  const activeName = presentString(config.chainName);
+  if (activeName) {
+    return activeName;
+  }
+  if (config.chainId !== undefined) {
+    return String(config.chainId);
+  }
+  return undefined;
+}
+
+export function resolveCliNetworkProfile(
+  selector: string | undefined,
+  config: WlfiConfig,
+  label = 'network',
+) {
+  const explicitSelector = presentString(selector);
+  if (explicitSelector && isNumericSelector(explicitSelector)) {
+    throw new Error(`${label} must be a chain name, not a chain id`);
+  }
+
+  const resolvedSelector = explicitSelector ?? resolveActiveNetworkSelector(config);
+  if (!resolvedSelector) {
+    throw new Error(`${label} is required`);
+  }
+
+  const profile = resolveChainProfile(resolvedSelector, config);
+  if (!profile) {
+    throw new Error(`${label} '${resolvedSelector}' is not a configured or builtin chain name`);
+  }
+
+  return profile;
+}
+
+export function resolveCliRpcUrl(
+  rpcUrl: string | undefined,
+  selector: string | undefined,
+  config: WlfiConfig,
+): string {
+  const explicitRpcUrl = presentString(rpcUrl);
+  if (explicitRpcUrl) {
+    return assertSafeRpcUrl(explicitRpcUrl, 'rpcUrl');
+  }
+
+  const profileRpcUrl = presentString(resolveCliNetworkProfile(selector, config).rpcUrl);
+  if (profileRpcUrl) {
+    return assertSafeRpcUrl(profileRpcUrl, 'rpcUrl');
+  }
+
+  const configuredRpcUrl = presentString(config.rpcUrl);
+  if (configuredRpcUrl) {
+    return assertSafeRpcUrl(configuredRpcUrl, 'rpcUrl');
+  }
+
+  throw new Error('rpcUrl is required');
+}

package/src/lib/passthrough-security.js

@@ -0,0 +1 @@
+export * from './passthrough-security.ts';

package/src/lib/passthrough-security.ts

@@ -0,0 +1,114 @@
+import { defaultDaemonSocketPath, type WlfiConfig } from '../../packages/config/src/index.js';
+import { assertTrustedAdminDaemonSocketPath, assertTrustedDaemonSocketPath } from './fs-trust.js';
+import type { RustBinaryName } from './rust.js';
+
+const HELP_FLAGS = new Set(['-h', '--help', '-V', '--version']);
+
+function forwardedArgsPrefix(args: string[]): string[] {
+  const terminatorIndex = args.indexOf('--');
+  return terminatorIndex >= 0 ? args.slice(0, terminatorIndex) : args;
+}
+
+interface ResolvePassthroughDaemonSocketDeps {
+  env?: NodeJS.ProcessEnv;
+  assertTrustedDaemonSocketPath?: (targetPath: string, label?: string) => string;
+}
+
+interface ForwardedOptionValue {
+  present: boolean;
+  value: string | undefined;
+}
+
+function findForwardedOptionOccurrences(args: string[], optionName: string): ForwardedOptionValue[] {
+  const matches: ForwardedOptionValue[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const current = args[index];
+    if (current === '--') {
+      break;
+    }
+
+    if (current === optionName) {
+      const value = args[index + 1];
+      if (value === undefined || value === '--' || value.startsWith('-')) {
+        throw new Error(
+          `${optionName} requires a path; use ${optionName}=<path> if the path starts with -`
+        );
+      }
+      matches.push({
+        present: true,
+        value
+      });
+      index += 1;
+      continue;
+    }
+
+    if (current.startsWith(`${optionName}=`)) {
+      matches.push({
+        present: true,
+        value: current.slice(optionName.length + 1)
+      });
+    }
+  }
+
+  return matches;
+}
+
+function presentString(value: string | undefined): string | null {
+  const normalized = value?.trim();
+  return normalized ? normalized : null;
+}
+
+export function forwardedArgsSkipDaemonSocketValidation(args: string[]): boolean {
+  const forwarded = forwardedArgsPrefix(args);
+  return forwarded[0] === 'help' || forwarded.some((arg) => HELP_FLAGS.has(arg));
+}
+
+export function readForwardedLongOptionValue(
+  args: string[],
+  optionName: string
+): ForwardedOptionValue {
+  const matches = findForwardedOptionOccurrences(args, optionName);
+  if (matches.length > 1) {
+    throw new Error(`${optionName} may only be provided once`);
+  }
+
+  if (matches.length === 1) {
+    return matches[0];
+  }
+
+  return {
+    present: false,
+    value: undefined
+  };
+}
+
+export function resolveValidatedPassthroughDaemonSocket(
+  binaryName: RustBinaryName,
+  args: string[],
+  config: WlfiConfig,
+  deps: ResolvePassthroughDaemonSocketDeps = {}
+): string | null {
+  if (binaryName === 'wlfi-agent-daemon' || forwardedArgsSkipDaemonSocketValidation(args)) {
+    return null;
+  }
+
+  const env = deps.env ?? process.env;
+  const trustDaemonSocketPath = deps.assertTrustedDaemonSocketPath
+    ?? (binaryName === 'wlfi-agent-admin'
+      ? assertTrustedAdminDaemonSocketPath
+      : assertTrustedDaemonSocketPath);
+  const forwardedValue = readForwardedLongOptionValue(args, '--daemon-socket');
+
+  if (forwardedValue.present && !presentString(forwardedValue.value)) {
+    throw new Error('--daemon-socket requires a path');
+  }
+
+  const daemonSocket =
+    presentString(forwardedValue.value) ??
+    presentString(env.WLFI_DAEMON_SOCKET) ??
+    presentString(config.daemonSocket) ??
+    defaultDaemonSocketPath();
+
+  return trustDaemonSocketPath(daemonSocket);
+}

package/src/lib/rpc-guard.js

@@ -0,0 +1 @@
+export * from './rpc-guard.ts';

package/src/lib/rpc-guard.ts

@@ -0,0 +1,7 @@
+export function assertRpcChainIdMatches(expectedChainId: number, actualChainId: number): void {
+  if (actualChainId !== expectedChainId) {
+    throw new Error(
+      `RPC endpoint chainId ${actualChainId} does not match expected chainId ${expectedChainId}`
+    );
+  }
+}

package/src/lib/rust-spawn-options.js

@@ -0,0 +1 @@
+export * from './rust-spawn-options.ts';

package/src/lib/rust-spawn-options.ts

@@ -0,0 +1,98 @@
+import { assertAdminAccessPreconditions } from './admin-guard.js';
+import { prepareAgentAuthRelay } from './agent-auth-forwarding.js';
+import { prepareVaultPasswordRelay } from './vault-password-forwarding.js';
+
+export interface RunRustBinaryOptions {
+  stdin?: string;
+  scrubSensitiveEnv?: boolean;
+  preSuppliedSecretStdin?: 'vaultPassword' | 'agentAuthToken';
+}
+
+const SENSITIVE_ENV_KEYS = ['WLFI_AGENT_AUTH_TOKEN', 'WLFI_VAULT_PASSWORD'] as const;
+
+function buildChildEnv(scrubSensitiveEnv: boolean): NodeJS.ProcessEnv {
+  if (!scrubSensitiveEnv) {
+    return process.env;
+  }
+
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  for (const key of SENSITIVE_ENV_KEYS) {
+    delete env[key];
+  }
+  return env;
+}
+
+function supportsVaultPasswordRelay(binaryName: string): boolean {
+  return binaryName === 'wlfi-agent-admin' || binaryName === 'wlfi-agent-daemon';
+}
+
+function supportsAgentAuthRelay(binaryName: string): boolean {
+  return binaryName === 'wlfi-agent-agent';
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+export async function prepareSpawnOptions(
+  binaryName: 'wlfi-agent-daemon' | 'wlfi-agent-admin' | 'wlfi-agent-agent',
+  args: string[],
+  options: RunRustBinaryOptions
+): Promise<{
+  args: string[];
+  stdin?: string;
+  env: NodeJS.ProcessEnv;
+}> {
+  let stdin = options.stdin;
+  let scrubSensitiveEnv = options.scrubSensitiveEnv ?? false;
+  let preparedArgs = [...args];
+  const preSuppliedSecretStdin = options.preSuppliedSecretStdin;
+
+  if (preSuppliedSecretStdin && stdin === undefined) {
+    throw new Error('preSuppliedSecretStdin requires an explicit stdin payload');
+  }
+
+  if (supportsVaultPasswordRelay(binaryName)) {
+    if (preSuppliedSecretStdin === 'vaultPassword') {
+      if (!hasFlag(preparedArgs, '--vault-password-stdin')) {
+        throw new Error('preSuppliedSecretStdin=vaultPassword requires --vault-password-stdin in args');
+      }
+      scrubSensitiveEnv = true;
+    } else {
+      const relay = await prepareVaultPasswordRelay(preparedArgs);
+      if (stdin !== undefined && relay.stdin !== undefined) {
+        throw new Error('vault password relay conflicts with explicit stdin payload');
+      }
+
+      preparedArgs = relay.args;
+      stdin = relay.stdin ?? stdin;
+      scrubSensitiveEnv = scrubSensitiveEnv || relay.scrubSensitiveEnv;
+    }
+  }
+
+  if (supportsAgentAuthRelay(binaryName)) {
+    if (preSuppliedSecretStdin === 'agentAuthToken') {
+      if (!hasFlag(preparedArgs, '--agent-auth-token-stdin')) {
+        throw new Error('preSuppliedSecretStdin=agentAuthToken requires --agent-auth-token-stdin in args');
+      }
+      scrubSensitiveEnv = true;
+    } else {
+      const relay = await prepareAgentAuthRelay(preparedArgs);
+      if (stdin !== undefined && relay.stdin !== undefined) {
+        throw new Error('agent auth token relay conflicts with explicit stdin payload');
+      }
+
+      preparedArgs = relay.args;
+      stdin = relay.stdin ?? stdin;
+      scrubSensitiveEnv = scrubSensitiveEnv || relay.scrubSensitiveEnv;
+    }
+  }
+
+  assertAdminAccessPreconditions(binaryName, preparedArgs);
+
+  return {
+    args: preparedArgs,
+    stdin,
+    env: buildChildEnv(scrubSensitiveEnv)
+  };
+}

package/src/lib/rust.js

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