@wlfi-agent/cli 1.4.16 → 1.4.18

package/src/lib/admin-setup.ts

@@ -41,6 +41,7 @@ import {
   resolveWalletSetupCleanupAction,
   type WalletSetupPlan,
 } from './wallet-setup.js';
+import { promptHiddenTty } from './hidden-tty-prompt.js';
 
 const DEFAULT_LAUNCH_DAEMON_LABEL = 'com.wlfi.agent.daemon';
 const DEFAULT_SIGNER_BACKEND = 'software';
@@ -69,6 +70,7 @@ interface AdminSetupOptions {
   nonInteractive?: boolean;
   plan?: boolean;
   yes?: boolean;
+  reuseExistingWallet?: boolean;
   printAgentAuthToken?: boolean;
   daemonSocket?: string;
   perTxMaxWei?: string;
@@ -170,6 +172,12 @@ export interface ExistingWalletSetupTarget {
   hasLegacyAgentAuthToken: boolean;
 }
 
+interface ReusableWalletSetupTarget {
+  address?: string;
+  existingVaultKeyId: string;
+  existingVaultPublicKey: string;
+}
+
 interface ConfirmAdminSetupOverwriteDeps {
   prompt?: (query: string) => Promise<string>;
   stderr?: Pick<NodeJS.WriteStream, 'write'>;
@@ -203,34 +211,13 @@ async function readTrimmedStdin(label: string): Promise<string> {
   return validateSecret(raw.replace(/[\r\n]+$/u, ''), label);
 }
 
-async function promptHidden(query: string): Promise<string> {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new Error('vault password is required; use --vault-password-stdin or a local TTY prompt');
-  }
-
-  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, 'vault password');
+async function promptHidden(
+  query: string,
+  label = 'vault password',
+  nonInteractiveError = 'vault password is required; use --vault-password-stdin or a local TTY prompt',
+): Promise<string> {
+  const answer = await promptHiddenTty(query, nonInteractiveError);
+  return validateSecret(answer, label);
 }
 
 async function promptVisible(query: string, nonInteractiveError: string): Promise<string> {
@@ -260,6 +247,7 @@ function deriveWalletAddress(vaultPublicKey: string | undefined): string | undef
     return publicKeyToAddress(
       (normalized.startsWith('0x') ? normalized : `0x${normalized}`) as Hex,
     );
+    /* c8 ignore next 2 -- viem currently normalizes malformed public-key strings instead of throwing; catch is defensive */
   } catch {
     return undefined;
   }
@@ -284,8 +272,33 @@ export function resolveExistingWalletSetupTarget(
   };
 }
 
+function resolveReusableWalletSetupTarget(config: WlfiConfig): ReusableWalletSetupTarget {
+  let walletProfile: ReturnType<typeof resolveWalletProfile>;
+  try {
+    walletProfile = resolveWalletProfile(config);
+  } catch (error) {
+    throw new Error(
+      `--reuse-existing-wallet requires a local wallet to reuse; ${renderError(error)}`,
+    );
+  }
+
+  const existingVaultKeyId = walletProfile.vaultKeyId?.trim();
+  const existingVaultPublicKey = walletProfile.vaultPublicKey?.trim();
+  if (!existingVaultKeyId || !existingVaultPublicKey) {
+    throw new Error(
+      '--reuse-existing-wallet requires wallet.vaultKeyId and wallet.vaultPublicKey in the local wallet profile',
+    );
+  }
+
+  return {
+    address: walletProfile.address?.trim() || deriveWalletAddress(existingVaultPublicKey),
+    existingVaultKeyId,
+    existingVaultPublicKey,
+  };
+}
+
 export async function confirmAdminSetupOverwrite(
-  options: Pick<AdminSetupOptions, 'yes' | 'nonInteractive'>,
+  options: Pick<AdminSetupOptions, 'yes' | 'nonInteractive' | 'reuseExistingWallet'>,
   config: WlfiConfig,
   deps: ConfirmAdminSetupOverwriteDeps = {},
 ): Promise<void> {
@@ -295,13 +308,17 @@ export async function confirmAdminSetupOverwrite(
   }
   if (options.nonInteractive) {
     throw new Error(
-      '`wlfi-agent admin setup` would overwrite the existing wallet; rerun with --yes in non-interactive mode',
+      options.reuseExistingWallet
+        ? '`wlfi-agent admin setup --reuse-existing-wallet` would refresh the existing local wallet metadata and agent credentials; rerun with --yes in non-interactive mode'
+        : '`wlfi-agent admin setup` would overwrite the existing wallet; rerun with --yes in non-interactive mode',
     );
   }
 
   const stderr = deps.stderr ?? process.stderr;
   stderr.write(
-    'warning: admin setup will overwrite the current local wallet metadata and agent credentials.\n',
+    options.reuseExistingWallet
+      ? 'warning: admin setup will reuse the current vault and refresh the local wallet metadata and agent credentials.\n'
+      : 'warning: admin setup will overwrite the current local wallet metadata and agent credentials.\n',
   );
   if (existing.address) {
     stderr.write(`current address: ${existing.address}\n`);
@@ -313,15 +330,21 @@ export async function confirmAdminSetupOverwrite(
     stderr.write('legacy agent auth token is still present in config.json\n');
   }
 
+  const confirmationToken = options.reuseExistingWallet ? 'REUSE' : 'OVERWRITE';
+  const confirmationPrompt = options.reuseExistingWallet
+    ? 'Type REUSE to reattach the current local vault: '
+    : 'Type OVERWRITE to replace the current local wallet: ';
   const confirmation = await (
     deps.prompt ??
     ((query: string) =>
       promptVisible(
         query,
-        '`wlfi-agent admin setup` requires --yes in non-interactive environments when overwriting an existing wallet',
+        options.reuseExistingWallet
+          ? '`wlfi-agent admin setup --reuse-existing-wallet` requires --yes in non-interactive environments when reusing an existing wallet'
+          : '`wlfi-agent admin setup` requires --yes in non-interactive environments when overwriting an existing wallet',
       ))
-  )('Type OVERWRITE to replace the current local wallet: ');
-  if (confirmation !== 'OVERWRITE') {
+  )(confirmationPrompt);
+  if (confirmation !== confirmationToken) {
     throw new Error('admin setup aborted');
   }
 }
@@ -357,7 +380,9 @@ export async function resolveAdminSetupVaultPassword(
       'vault password is required in non-interactive mode; use --vault-password-stdin',
     );
   }
-  return promptForVaultPassword('Vault password (input hidden; nothing will be echoed): ');
+  return promptForVaultPassword(
+    'Vault password (input hidden; this unlocks the wallet, not sudo): ',
+  );
 }
 
 function resolveDaemonSocket(optionValue: string | undefined): string {
@@ -398,6 +423,9 @@ export function createAdminSetupPlan(
   }
 
   const existingWallet = resolveExistingWalletSetupTarget(config);
+  const reusableWallet = options.reuseExistingWallet
+    ? resolveReusableWalletSetupTarget(config)
+    : null;
 
   return {
     command: 'setup',
@@ -442,6 +470,8 @@ export function createAdminSetupPlan(
         recipient: options.recipient,
         attachPolicyId: options.attachPolicyId,
         attachBootstrapPolicies: options.attachBootstrapPolicies,
+        existingVaultKeyId: reusableWallet?.existingVaultKeyId,
+        existingVaultPublicKey: reusableWallet?.existingVaultPublicKey,
         bootstrapOutputPath: options.bootstrapOutput,
         deleteBootstrapOutput: options.deleteBootstrapOutput,
       },
@@ -851,7 +881,9 @@ async function daemonAcceptsVaultPassword(
 const sudoSession = createSudoSession({
   promptPassword: async () =>
     await promptHidden(
-      'Root password (input hidden; required to install or recover the root daemon): ',
+      'macOS admin password for sudo (input hidden; required to install or recover the root daemon): ',
+      'macOS admin password for sudo',
+      'macOS admin password for sudo is required; rerun on a local TTY',
     ),
 });
 
@@ -873,6 +905,158 @@ async function managedStateFileExists(stateFile: string): Promise<boolean> {
   );
 }
 
+async function inspectManagedState(
+  stateFile: string,
+  showProgress: boolean,
+  message = 'Inspecting managed daemon state',
+): Promise<boolean> {
+  await sudoSession.prime();
+  const stateProbeProgress = createProgress(message, showProgress);
+  let stateExists: boolean;
+  try {
+    stateExists = await managedStateFileExists(stateFile);
+    stateProbeProgress.succeed(
+      stateExists ? 'Managed daemon state already exists' : 'No managed daemon state found',
+    );
+  } catch (error) {
+    stateProbeProgress.fail();
+    throw error;
+  }
+  return stateExists;
+}
+
+function createManagedStatePasswordMismatchError(stateFile: string): Error {
+  return new Error(
+    `managed daemon state already exists at ${stateFile} and is encrypted with a different vault password. Re-run setup with the original vault password, or remove/reset the managed daemon state before initializing a fresh wallet.`,
+  );
+}
+
+function isManagedStatePasswordMismatch(output: string): boolean {
+  return /failed to decrypt state|wrong password or tampered file|authentication failed/iu.test(
+    output,
+  );
+}
+
+async function managedStateAcceptsRequestedVaultPassword(
+  config: WlfiConfig,
+  daemonSocket: string,
+  stateFile: string,
+  vaultPassword: string,
+): Promise<boolean> {
+  const installPreconditions = assertManagedDaemonInstallPreconditions(
+    config,
+    daemonSocket,
+    stateFile,
+  );
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'wlfi-managed-state-probe-'));
+  const tempSocket = path.join(tempRoot, 'daemon.sock');
+  const allowedUid = String(process.getuid?.() ?? process.geteuid?.() ?? 0);
+  const probeScript = [
+    'set -euo pipefail',
+    'vault_password="$(cat)"',
+    'daemon_bin="$1"',
+    'state_file="$2"',
+    'daemon_socket="$3"',
+    'admin_uid="$4"',
+    'agent_uid="$5"',
+    'signer_backend="$6"',
+    '"$daemon_bin" \\',
+    '  --non-interactive \\',
+    '  --vault-password-stdin \\',
+    '  --state-file "$state_file" \\',
+    '  --daemon-socket "$daemon_socket" \\',
+    '  --signer-backend "$signer_backend" \\',
+    '  --allow-admin-euid "$admin_uid" \\',
+    '  --allow-agent-euid "$agent_uid" <<<"$vault_password" &',
+    'child="$!"',
+    'for _ in $(seq 1 20); do',
+    '  if ! kill -0 "$child" 2>/dev/null; then',
+    '    wait "$child"',
+    '    exit $?',
+    '  fi',
+    '  sleep 0.25',
+    'done',
+    'kill "$child" >/dev/null 2>&1 || true',
+    'wait "$child" >/dev/null 2>&1 || true',
+    'exit 0',
+  ].join('\n');
+
+  try {
+    const result = await sudoSession.run(
+      [
+        '/bin/bash',
+        '-lc',
+        probeScript,
+        '--',
+        installPreconditions.daemonBin,
+        stateFile,
+        tempSocket,
+        allowedUid,
+        allowedUid,
+        DEFAULT_SIGNER_BACKEND,
+      ],
+      {
+        stdin: `${vaultPassword}\n`,
+      },
+    );
+    if (result.code === 0) {
+      return true;
+    }
+
+    const combinedOutput = `${result.stderr}\n${result.stdout}`.trim();
+    if (isManagedStatePasswordMismatch(combinedOutput)) {
+      return false;
+    }
+    throw new Error(
+      combinedOutput ||
+        `failed to validate the managed daemon state with the requested vault password (exit code ${result.code})`,
+    );
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function assertManagedStateMatchesRequestedVaultPasswordBeforeInstall(
+  config: WlfiConfig,
+  daemonSocket: string,
+  stateFile: string,
+  vaultPassword: string,
+  showProgress: boolean,
+): Promise<void> {
+  const stateExists = await inspectManagedState(
+    stateFile,
+    showProgress,
+    'Inspecting managed daemon state before install',
+  );
+  if (!stateExists) {
+    return;
+  }
+
+  const verifyProgress = createProgress(
+    'Verifying the requested vault password against the managed daemon state',
+    showProgress,
+  );
+  let accepted: boolean;
+  try {
+    accepted = await managedStateAcceptsRequestedVaultPassword(
+      config,
+      daemonSocket,
+      stateFile,
+      vaultPassword,
+    );
+  } catch (error) {
+    verifyProgress.fail();
+    throw error;
+  }
+
+  if (!accepted) {
+    verifyProgress.fail('Existing daemon password does not unlock the stored daemon state');
+    throw createManagedStatePasswordMismatchError(stateFile);
+  }
+
+  verifyProgress.succeed('Requested vault password unlocks the existing managed daemon state');
+}
+
 async function waitForTrustedDaemonSocket(targetPath: string, timeoutMs = 15_000): Promise<void> {
   async function canConnect(socketPath: string): Promise<boolean> {
     return new Promise<boolean>((resolve) => {
@@ -1109,6 +1293,9 @@ async function runAdminSetup(options: AdminSetupOptions): Promise<void> {
   const config = readConfig();
   const daemonSocket = resolveDaemonSocket(options.daemonSocket);
   const stateFile = resolveStateFile();
+  const reusableWallet = options.reuseExistingWallet
+    ? resolveReusableWalletSetupTarget(config)
+    : null;
   assertManagedDaemonInstallPreconditions(config, daemonSocket, stateFile);
   await confirmAdminSetupOverwrite(options, config);
   const vaultPassword = await resolveAdminSetupVaultPassword(options);
@@ -1176,10 +1363,17 @@ async function runAdminSetup(options: AdminSetupOptions): Promise<void> {
       }
       if (!options.json && typeof process.geteuid === 'function' && process.geteuid() !== 0) {
         process.stderr.write(
-          'Root password required: setup must install or recover the root LaunchDaemon and store the daemon password in System Keychain.\n',
+          'macOS admin password required: setup uses sudo to install or recover the root LaunchDaemon and store the daemon password in System Keychain.\n',
         );
       }
       await sudoSession.prime();
+      await assertManagedStateMatchesRequestedVaultPasswordBeforeInstall(
+        config,
+        daemonSocket,
+        stateFile,
+        vaultPassword,
+        showProgress,
+      );
       const installProgress = createProgress('Installing and restarting daemon', showProgress);
       try {
         daemon = await installLaunchDaemon(config, daemonSocket, stateFile, vaultPassword);
@@ -1212,29 +1406,15 @@ async function runAdminSetup(options: AdminSetupOptions): Promise<void> {
   if (!daemonAcceptedPassword) {
     if (existingDaemonRejectedPassword) {
       authProgress.fail('Existing daemon password does not unlock the stored daemon state');
-      throw new Error(
-        `managed daemon state already exists at ${stateFile} and is encrypted with a different vault password. Re-run setup with the original vault password, or remove/reset the managed daemon state before initializing a fresh wallet.`,
-      );
+      throw createManagedStatePasswordMismatchError(stateFile);
     }
 
     authProgress.info('Daemon rejected the requested vault password; inspecting managed state');
-    const stateProbeProgress = createProgress('Inspecting managed daemon state', showProgress);
-    let stateExists: boolean;
-    try {
-      stateExists = await managedStateFileExists(stateFile);
-      stateProbeProgress.succeed(
-        stateExists ? 'Managed daemon state already exists' : 'No managed daemon state found',
-      );
-    } catch (error) {
-      stateProbeProgress.fail();
-      throw error;
-    }
+    const stateExists = await inspectManagedState(stateFile, showProgress);
 
     if (stateExists) {
       authProgress.fail('Existing daemon password does not unlock the stored daemon state');
-      throw new Error(
-        `managed daemon state already exists at ${stateFile} and is encrypted with a different vault password. Re-run setup with the original vault password, or remove/reset the managed daemon state before initializing a fresh wallet.`,
-      );
+      throw createManagedStatePasswordMismatchError(stateFile);
     }
 
     authProgress.fail(
@@ -1243,7 +1423,7 @@ async function runAdminSetup(options: AdminSetupOptions): Promise<void> {
 
     if (!options.json && typeof process.geteuid === 'function' && process.geteuid() !== 0) {
       process.stderr.write(
-        'Root password required: setup must reinstall the root LaunchDaemon to rotate the managed daemon password.\n',
+        'macOS admin password required: setup uses sudo to reinstall the root LaunchDaemon and rotate the managed daemon password.\n',
       );
     }
     await sudoSession.prime();
@@ -1333,6 +1513,8 @@ async function runAdminSetup(options: AdminSetupOptions): Promise<void> {
     recipient: options.recipient,
     attachPolicyId: options.attachPolicyId,
     attachBootstrapPolicies: options.attachBootstrapPolicies,
+    existingVaultKeyId: reusableWallet?.existingVaultKeyId,
+    existingVaultPublicKey: reusableWallet?.existingVaultPublicKey,
     bootstrapOutputPath: bootstrapOutput.path,
   });
 
@@ -1460,6 +1642,8 @@ export function buildAdminSetupBootstrapInvocation(input: {
   recipient?: string;
   attachPolicyId?: string[];
   attachBootstrapPolicies?: boolean;
+  existingVaultKeyId?: string;
+  existingVaultPublicKey?: string;
   bootstrapOutputPath: string;
 }): { args: string[]; stdin: string } {
   return {
@@ -1481,6 +1665,8 @@ export function buildAdminSetupBootstrapInvocation(input: {
       recipient: input.recipient,
       attachPolicyId: input.attachPolicyId,
       attachBootstrapPolicies: input.attachBootstrapPolicies,
+      existingVaultKeyId: input.existingVaultKeyId,
+      existingVaultPublicKey: input.existingVaultPublicKey,
       bootstrapOutputPath: input.bootstrapOutputPath,
     }),
     stdin: `${validateSecret(input.vaultPassword, 'vault password')}\n`,
@@ -1552,6 +1738,11 @@ export async function runAdminSetupCli(argv: string[]): Promise<void> {
     .option('--vault-password-stdin', 'Read vault password from stdin', false)
     .option('--non-interactive', 'Disable password prompts', false)
     .option('-y, --yes', 'Skip the overwrite confirmation prompt', false)
+    .option(
+      '--reuse-existing-wallet',
+      'Reuse the current local vault instead of generating a fresh wallet',
+      false,
+    )
     .option('--daemon-socket <path>', 'Daemon unix socket path')
     .option('--per-tx-max-wei <wei>', 'Per-transaction max spend in wei')
     .option('--daily-max-wei <wei>', 'Daily max spend in wei')

package/src/lib/agent-auth-migrate.ts

@@ -62,8 +62,12 @@ function resolveConfiguredAgentKeyId(
     if (explicitAgentKeyId) {
       return undefined;
     }
+    const renderedError =
+      error instanceof Error
+        ? error.message
+        : /* c8 ignore next -- assertValidAgentKeyId throws Error objects */ String(error);
     throw new Error(
-      (error instanceof Error ? error.message : String(error)) +
+      renderedError +
         '; pass --agent-key-id to migrate the legacy config secret explicitly'
     );
   }

package/src/lib/asset-broadcast.ts

@@ -94,6 +94,16 @@ export interface WaitForOnchainReceiptDeps {
   sleep?: (ms: number) => Promise<void>;
 }
 
+export function resolveEstimatedPriorityFeePerGasWei(fees: BroadcastFeeEstimate): bigint {
+  const resolved = fees.maxPriorityFeePerGas ?? fees.gasPrice;
+  if (resolved === null || resolved <= 0n) {
+    throw new Error(
+      'Could not determine maxPriorityFeePerGas; pass --max-priority-fee-per-gas-wei',
+    );
+  }
+  return resolved;
+}
+
 export function encodeErc20TransferData(recipient: Address, amountWei: bigint): Hex {
   return encodeFunctionData({
     abi: erc20Abi,
@@ -128,14 +138,15 @@ export async function resolveAssetBroadcastPlan(
   const fees = await deps.estimateFees(input.rpcUrl);
   const resolvedFees = fees as BroadcastFeeEstimate;
   const maxFeePerGasWei = input.maxFeePerGasWei ?? (resolvedFees.maxFeePerGas ?? resolvedFees.gasPrice);
-  const maxPriorityFeePerGasWei =
-    input.maxPriorityFeePerGasWei
-    ?? (resolvedFees.maxPriorityFeePerGas ?? resolvedFees.gasPrice ?? 0n);
 
   if (maxFeePerGasWei === null || maxFeePerGasWei <= 0n) {
     throw new Error('Could not determine maxFeePerGas; pass --max-fee-per-gas-wei');
   }
 
+  const maxPriorityFeePerGasWei =
+    input.maxPriorityFeePerGasWei
+    ?? resolveEstimatedPriorityFeePerGasWei(resolvedFees);
+
   return {
     rpcUrl: input.rpcUrl,
     chainId: input.chainId,
@@ -166,7 +177,7 @@ export async function completeAssetBroadcast(
     to: plan.to,
     chainId: plan.chainId,
     nonce: plan.nonce,
-    allowHigherNonce: true,
+    allowHigherNonce: false,
     value: plan.valueWei,
     data: plan.dataHex,
     gasLimit: plan.gasLimit,

package/src/lib/config-amounts.ts

@@ -181,9 +181,11 @@ export function rewriteAmountPolicyErrorMessage(
         minAmountLiteral: string,
         minAmountWei: string | undefined,
         maxAmountWei: string,
-      ) =>
-        `requires manual approval for requested amount ${formatAmount(requestedAmountWei)} within range ${
-          minAmountLiteral === 'None' ? 'None' : `Some(${formatAmount(minAmountWei ?? '0')})`
-        }..=${formatAmount(maxAmountWei)}`,
+      ) => {
+        const minAmountDisplay =
+          /* c8 ignore next -- both None and Some(...) paths are exercised, but c8 misattributes this ternary under --experimental-strip-types */
+          minAmountLiteral === 'None' ? 'None' : `Some(${formatAmount(minAmountWei ?? '0')})`;
+        return `requires manual approval for requested amount ${formatAmount(requestedAmountWei)} within range ${minAmountDisplay}..=${formatAmount(maxAmountWei)}`;
+      },
     );
 }

package/src/lib/hidden-tty-prompt.js

@@ -0,0 +1 @@
+export * from './hidden-tty-prompt.ts';

package/src/lib/hidden-tty-prompt.ts

@@ -0,0 +1,105 @@
+interface HiddenPromptInput {
+  isRaw?: boolean;
+  isTTY?: boolean;
+  on(event: 'data', listener: (chunk: Buffer | string) => void): this;
+  on(event: 'error', listener: (error: Error) => void): this;
+  removeListener(event: 'data', listener: (chunk: Buffer | string) => void): this;
+  removeListener(event: 'error', listener: (error: Error) => void): this;
+  pause?(): void;
+  resume?(): void;
+  setRawMode?(mode: boolean): void;
+}
+
+interface HiddenPromptOutput {
+  isTTY?: boolean;
+  write(chunk: string): boolean;
+}
+
+interface HiddenPromptDeps {
+  input?: HiddenPromptInput;
+  output?: HiddenPromptOutput;
+}
+
+export async function promptHiddenTty(
+  query: string,
+  nonInteractiveError: string,
+  deps: HiddenPromptDeps = {},
+): Promise<string> {
+  const input = deps.input ?? (process.stdin as unknown as HiddenPromptInput);
+  const output = deps.output ?? (process.stderr as unknown as HiddenPromptOutput);
+
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
+    throw new Error(nonInteractiveError);
+  }
+
+  output.write('\r\u001b[2K');
+  output.write(query);
+  const wasRaw = Boolean(input.isRaw);
+  if (!wasRaw) {
+    input.setRawMode(true);
+  }
+  input.resume?.();
+
+  return await new Promise<string>((resolve, reject) => {
+    let answer = '';
+    let settled = false;
+
+    const cleanup = () => {
+      input.removeListener('data', onData);
+      input.removeListener('error', onError);
+      if (!wasRaw) {
+        input.setRawMode?.(false);
+      }
+      input.pause?.();
+      output.write('\n');
+    };
+
+    const finish = (callback: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      callback();
+    };
+
+    const onError = (error: Error) => {
+      finish(() => reject(error));
+    };
+
+    const onData = (chunk: Buffer | string) => {
+      const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      if (text.includes('\u001b')) {
+        return;
+      }
+
+      for (const char of text) {
+        if (char === '\r' || char === '\n') {
+          finish(() => resolve(answer));
+          return;
+        }
+        if (char === '\u0003') {
+          finish(() => reject(new Error('prompt canceled')));
+          return;
+        }
+        if (char === '\u007f' || char === '\b') {
+          const chars = Array.from(answer);
+          chars.pop();
+          answer = chars.join('');
+          continue;
+        }
+        if (char === '\u0015') {
+          answer = '';
+          continue;
+        }
+        if (/[\u0000-\u001f\u007f]/u.test(char)) {
+          continue;
+        }
+        answer += char;
+      }
+    };
+
+    input.on('data', onData);
+    input.on('error', onError);
+  });
+}

package/src/lib/keychain.ts

@@ -89,6 +89,7 @@ function assertValidKeychainAccount(account: string): string {
 
 function assertValidKeychainService(service: string): string {
   const normalized = service.trim();
+  /* c8 ignore next 6 -- public APIs use fixed non-empty service identifiers, so these guards are unreachable through exported entry points */
   if (!normalized) {
     throw new Error('keychain service is required');
   }