@did-btcr2/cli 0.14.0 → 0.16.0

package/src/keystore/passphrase.ts

@@ -12,6 +12,13 @@ export type PassphraseOptions = {
   prompt?: string;
   /** When true, prompt twice and require the entries to match (for a new keystore). */
   confirm?: boolean;
+  /**
+   * When true, skip the environment variable and passphrase file and require a
+   * fresh terminal entry. Used for the *new* passphrase in `change-passphrase`,
+   * where the env var / file holds the *current* passphrase and must not silently
+   * satisfy the new one (which would make the change a no-op).
+   */
+  forcePrompt?: boolean;
 };
 
 /**
@@ -19,16 +26,19 @@ export type PassphraseOptions = {
  * (which would leak into process listings and shell history). Resolution order:
  * the {@link ENV_KEYSTORE_PASSPHRASE} environment variable, a passphrase file,
  * then a non-echoing terminal prompt. Throws if none is available and standard
- * input is not a terminal.
+ * input is not a terminal. When `forcePrompt` is set, the env var and file are
+ * skipped and a terminal entry is required.
  */
 export function acquirePassphrase(options: PassphraseOptions = {}): string {
   // All sources are normalized identically (at most one trailing newline
   // removed) so the KDF input is source-independent.
-  const fromEnv = process.env[ENV_KEYSTORE_PASSPHRASE];
-  if (fromEnv) return assertNonEmpty(fromEnv.replace(/\r?\n$/, ''));
+  if (!options.forcePrompt) {
+    const fromEnv = process.env[ENV_KEYSTORE_PASSPHRASE];
+    if (fromEnv) return assertNonEmpty(fromEnv.replace(/\r?\n$/, ''));
 
-  if (options.passphraseFile) {
-    return assertNonEmpty(readFileSync(options.passphraseFile, 'utf-8').replace(/\r?\n$/, ''));
+    if (options.passphraseFile) {
+      return assertNonEmpty(readFileSync(options.passphraseFile, 'utf-8').replace(/\r?\n$/, ''));
+    }
   }
 
   if (!process.stdin.isTTY) {
@@ -56,9 +66,34 @@ function assertNonEmpty(passphrase: string): string {
   return passphrase;
 }
 
+/**
+ * A 4-byte shared buffer used only as an {@link Atomics.wait} target. It lets
+ * {@link promptHidden} block briefly on an empty non-blocking TTY instead of
+ * busy-spinning. It is never written to, so the wait always times out.
+ */
+const IDLE_WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+/**
+ * Milliseconds to block on each empty read. Imperceptible to a typist yet long
+ * enough that an open prompt sits idle rather than pegging a CPU core.
+ */
+const IDLE_POLL_MS = 20;
+
+/**
+ * Removes the last whole UTF-8 character from an accumulating byte array in
+ * place: pops any trailing continuation bytes (0b10xxxxxx) then the leading
+ * byte. Exported for testing; a backspace mid-entry must not strand a fragment
+ * that later decodes to U+FFFD.
+ */
+export function dropLastUtf8Char(bytes: number[]): void {
+  while (bytes.length > 0 && (bytes[bytes.length - 1] & 0xc0) === 0x80) bytes.pop();
+  bytes.pop();
+}
+
 /**
  * Reads a line from the terminal synchronously without echoing keystrokes.
- * Bytes are accumulated and decoded as UTF-8 so multibyte passphrases survive.
+ * Bytes are accumulated and decoded as UTF-8 so multibyte passphrases survive,
+ * including a backspace that spans a whole multibyte character.
  * This path runs only when standard input is a terminal.
  */
 function promptHidden(label: string): string {
@@ -75,7 +110,12 @@ function promptHidden(label: string): string {
         read = readSync(stdin.fd, byte, 0, 1, null);
       } catch (error) {
         const code = (error as { code?: string }).code;
-        if (code === 'EAGAIN') continue; // no byte ready yet on a non-blocking TTY
+        if (code === 'EAGAIN') {
+          // No byte ready yet on a non-blocking TTY. Block briefly instead of
+          // spinning so an open prompt does not peg a CPU core while it waits.
+          Atomics.wait(IDLE_WAIT, 0, 0, IDLE_POLL_MS);
+          continue;
+        }
         if (code === 'EOF') break;
         throw error;
       }
@@ -86,7 +126,7 @@ function promptHidden(label: string): string {
         throw new KeyStoreError('Passphrase entry aborted.', 'PASSPHRASE_REQUIRED_ERROR');
       }
       if (ch === 0x7f || ch === 0x08) { // DEL or backspace
-        bytes.pop();
+        dropLastUtf8Char(bytes);
         continue;
       }
       bytes.push(ch);

package/src/keystore/paths.ts

@@ -1,20 +1,8 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
 /**
- * Default keystore file path, following the XDG Base Directory Specification's
- * data directory. Secret key material is data a user accumulates, so it lives
- * under the data directory, kept separate from the configuration directory used
- * for portable settings.
- *
- * Resolution order:
- * 1. `$XDG_DATA_HOME/btcr2/keystore.json`
- * 2. `%LOCALAPPDATA%/btcr2/keystore.json` (Windows)
- * 3. `~/.local/share/btcr2/keystore.json` (fallback)
+ * The default keystore path now lives alongside the config file under a single
+ * CLI home root (`<home>/keystore.json`, ADR 079). The implementation lives in
+ * `../paths.ts` (the single source of truth for on-disk state locations); it is
+ * re-exported here so existing `./paths.js` importers in the keystore layer keep
+ * their import surface.
  */
-export function defaultKeystorePath(): string {
-  const base = process.env.XDG_DATA_HOME
-    ?? process.env.LOCALAPPDATA
-    ?? join(homedir(), '.local', 'share');
-  return join(base, 'btcr2', 'keystore.json');
-}
+export { defaultKeystorePath } from '../paths.js';

package/src/output.ts

@@ -1,5 +1,58 @@
 import type { CommandResult, GlobalOptions } from './types.js';
 
+/** Placeholder printed in place of a redacted secret value. */
+export const REDACTED = '********';
+
+/**
+ * Key names whose (scalar) values are treated as secrets and redacted in printed
+ * output. Covers RPC passwords plus header credentials (`Authorization`, API
+ * keys, bearer tokens) that a profile can now carry in `btc.headers`/`rpcHeaders`.
+ */
+const SECRET_KEY = /(pass|secret|token|auth|api[-_]?key|credential|bearer)/i;
+
+/** Whether a config key name looks like a secret (so its scalar value should be redacted). */
+export function isSecretKey(key: string): boolean {
+  return SECRET_KEY.test(key);
+}
+
+/**
+ * Masks the password in a `scheme://user:pass@host` URL, leaving the rest of the
+ * value verbatim. A credential embedded in an endpoint URL (e.g. `rpcUrl`) is not
+ * caught by key-name matching, so it is scrubbed here regardless of the key.
+ */
+export function scrubUrlUserinfo(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return value.replace(/^([a-z][a-z0-9+.-]*:\/\/[^/@:]+):[^/@]*@/i, `$1:${REDACTED}@`);
+}
+
+/**
+ * Returns a deep copy of `value` with secret scalar values replaced by
+ * {@link REDACTED}, so routine introspection (`config get`/`list`/`effective`)
+ * does not print RPC passwords or other secrets into terminal scrollback and CI
+ * logs. A secret-named key redacts only a scalar value (an object under such a
+ * key, e.g. a profile named `access-token`, is still traversed, not wholesale
+ * masked). Passwords embedded in URL values are scrubbed regardless of key name.
+ * When `keyName` is a secret name, a directly-passed scalar value is redacted
+ * (used when a single leaf value is printed). Display-only: the stored config and
+ * the value used to connect are untouched.
+ */
+export function redactSecrets(value: unknown, keyName?: string): unknown {
+  if (Array.isArray(value)) {
+    return value.map(item => redactSecrets(item));
+  }
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [ key, val ] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = redactSecrets(val, key);
+    }
+    return out;
+  }
+  if (keyName !== undefined && isSecretKey(keyName)) {
+    return value === undefined ? undefined : REDACTED;
+  }
+  return typeof value === 'string' ? scrubUrlUserinfo(value) : value;
+}
+
 /**
  * Formats a CommandResult for console output.
  * In 'json' mode, the full result is serialized.

package/src/paths.ts

@@ -0,0 +1,79 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { blankToUndef } from './types.js';
+
+/**
+ * State-location overrides that influence where the CLI keeps its home
+ * directory and its two state files. A subset of the broader
+ * `ConnectionOverrides`, restated here so this module (the single source of
+ * truth for on-disk locations) has no runtime dependency on `config.ts`.
+ */
+export interface PathOverrides {
+  /** Explicit home root from the `--home` flag. Wins over `$BTCR2_HOME`. */
+  home?     : string;
+  /** Explicit config-file path from the `--config` flag. Overrides the home default. */
+  config?   : string;
+  /** Explicit keystore path from the `--keystore` flag. Overrides the home default. */
+  keystore? : string;
+}
+
+/** Environment variable naming the CLI home directory (all state colocated). */
+export const ENV_HOME = 'BTCR2_HOME';
+
+/** The config and keystore file names, kept side by side under the home root. */
+export const CONFIG_FILENAME = 'config.json';
+export const KEYSTORE_FILENAME = 'keystore.json';
+
+/**
+ * Resolves the CLI home directory: the single root that holds `config.json` and
+ * `keystore.json` side by side (ADR 079). Resolution order, highest wins:
+ *
+ * 1. `--home <dir>` (the {@link PathOverrides.home} flag)
+ * 2. `$BTCR2_HOME`
+ * 3. the platform default (see {@link platformDefaultHome})
+ *
+ * A blank value at any layer defers to the next, mirroring the `blankToUndef`
+ * treatment every other precedence layer uses, so an exported-but-empty
+ * `BTCR2_HOME` does not resolve the home to a bare relative path.
+ */
+export function resolveHome(overrides?: PathOverrides): string {
+  return blankToUndef(overrides?.home)
+    ?? blankToUndef(process.env[ENV_HOME])
+    ?? platformDefaultHome();
+}
+
+/**
+ * The default home when no `--home` / `$BTCR2_HOME` override is present, chosen
+ * per OS so the location is idiomatic while staying a single colocated dir:
+ *
+ * - Windows: `%LOCALAPPDATA%\btcr2` (fallback `%APPDATA%\btcr2`, then the user
+ *   profile), the native place for per-user application state.
+ * - Linux / macOS: `~/.btcr2`, the short, teachable dot-directory in the same
+ *   family as `~/.ssh`, `~/.aws`, and `~/.gnupg`.
+ */
+export function platformDefaultHome(): string {
+  if (process.platform === 'win32') {
+    const base = blankToUndef(process.env.LOCALAPPDATA)
+      ?? blankToUndef(process.env.APPDATA)
+      ?? homedir();
+    return join(base, 'btcr2');
+  }
+  return join(homedir(), '.btcr2');
+}
+
+/**
+ * Default config-file path: `<home>/config.json`. The `--config` flag, when
+ * present, overrides it wholesale (it names a specific file, not a home).
+ */
+export function defaultConfigPath(overrides?: PathOverrides): string {
+  return join(resolveHome(overrides), CONFIG_FILENAME);
+}
+
+/**
+ * Default keystore path: `<home>/keystore.json`. The `--keystore` flag and a
+ * profile's `identity.keystore` (resolved in `config.ts`) override it; this
+ * function is the final fallback in that chain.
+ */
+export function defaultKeystorePath(overrides?: PathOverrides): string {
+  return join(resolveHome(overrides), KEYSTORE_FILENAME);
+}

package/src/types.ts

@@ -2,14 +2,34 @@ import type { DidUpdateResult } from '@did-btcr2/api';
 import type { PatchOperation } from '@did-btcr2/common';
 import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
+import type { DoctorReport, EffectiveConfig } from './config.js';
+import type { ConfigIssue } from './config-schema.js';
 
 export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
 export type OutputFormat = 'json' | 'text';
 
+/**
+ * How a keystore protects its secrets, as reported by `keystore status` and
+ * `btcr2 init`: `encrypted` (passphrase-sealed), `dev` (plaintext, testnet-only),
+ * or `absent` (no keystore file yet).
+ */
+export type KeystoreProtectionLabel = 'encrypted' | 'dev' | 'absent';
+
 export const SUPPORTED_NETWORKS: NetworkOption[] = [
   'bitcoin', 'testnet3', 'testnet4', 'signet', 'mutinynet', 'regtest'
 ];
 
+/**
+ * Normalizes a blank value (empty or whitespace-only) to `undefined`, so a
+ * blank at any precedence layer defers to the next layer instead of masking it.
+ * A non-blank value is returned unchanged. This mirrors the `|| undefined`
+ * treatment the environment layer already applies in `readEnvOverrides`.
+ */
+export function blankToUndef(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return value.trim() === '' ? undefined : value;
+}
+
 export interface ResolveCommandOptions {
   identifier : string;
   options?   : ResolutionOptions;
@@ -35,11 +55,19 @@ export type CommandResult =
   | { action: 'key-export'; data: { keyId: string; publicKey?: string; secretWrittenTo?: string } }
   | { action: 'key-delete'; data: { keyId: string; deleted: true } }
   | { action: 'key-use'; data: { keyId: string; active: true } }
+  | { action: 'init'; data: { home: string; config: string; keystore: string; created: string[]; protection: KeystoreProtectionLabel } }
   | { action: 'config-init'; data: { path: string } }
   | { action: 'config-get'; data: unknown }
   | { action: 'config-set'; data: { path: string } }
   | { action: 'config-unset'; data: { path: string } }
   | { action: 'config-list'; data: unknown }
+  | { action: 'config-validate'; data: { ok: boolean; issues: ConfigIssue[] } }
+  | { action: 'config-effective'; data: EffectiveConfig }
+  | { action: 'config-path'; data: { home: string; config: string; keystore: string } }
+  | { action: 'config-doctor'; data: DoctorReport }
+  | { action: 'keystore-init'; data: { path: string; protection: 'encrypted' | 'dev' } }
+  | { action: 'keystore-status'; data: { path: string; protection: KeystoreProtectionLabel; established: boolean; keyCount: number; active: string | undefined } }
+  | { action: 'keystore-change-passphrase'; data: { path: string; rekeyed: number } }
   | { action: 'profile-add'; data: { profile: string } }
   | { action: 'profile-use'; data: { profile: string } }
   | { action: 'profile-show'; data: unknown }
@@ -49,6 +77,7 @@ export interface GlobalOptions {
   output         : OutputFormat;
   verbose        : boolean;
   quiet          : boolean;
+  home?          : string;
   config?        : string;
   profile?       : string;
   btcRest?       : string;
@@ -57,6 +86,11 @@ export interface GlobalOptions {
   btcRpcPass?    : string;
   casGateway?    : string;
   casRpcUrl?     : string;
+  btcTimeout?    : string;
+  casTimeout?    : string;
+  btcRestHeader? : string[];
+  btcRpcWallet?  : string;
+  btcRpcHeader?  : string[];
   keystore?      : string;
   passphraseFile?: string;
   signingKey?    : string;