@did-btcr2/cli 0.14.0 → 0.16.0

package/dist/esm/src/config.js

@@ -1,19 +1,27 @@
-import { createApi, Identifier } from '@did-btcr2/api';
+import { createApi, DEFAULT_BITCOIN_NETWORK_CONFIG, DEFAULT_CAS_GATEWAY, Identifier } from '@did-btcr2/api';
+import { StaticFeeEstimator } from '@did-btcr2/method';
 import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname } from 'node:path';
 import { CLIError } from './error.js';
 import { ensureDir, writeFileAtomic } from './keystore/atomic.js';
 import { FileBackedKeyManager } from './keystore/file-backed-key-manager.js';
+import { keystoreProtection } from './keystore/file-key-store.js';
 import { defaultKeystorePath } from './keystore/paths.js';
 import { acquirePassphrase } from './keystore/passphrase.js';
-import { SUPPORTED_NETWORKS } from './types.js';
+import { defaultConfigPath } from './paths.js';
+import { blankToUndef, SUPPORTED_NETWORKS } from './types.js';
+export { defaultConfigPath };
 /** Current config-file schema version, stamped on every write. */
 export const CONFIG_SCHEMA_VERSION = 1;
 /**
  * Read-modify-write a config file, preserving unknown keys. Reads the raw JSON
  * (so keys outside {@link ConfigFile} survive a rewrite), applies `mutate`,
  * stamps the schema version, and writes atomically (file 0600, dir 0700).
+ *
+ * A file that exists but cannot be parsed makes {@link readConfigFile} throw, so
+ * a write never starts from `{}` over a malformed-but-recoverable file and can
+ * never clobber the other profiles and defaults it still holds. A genuinely
+ * absent file (ENOENT) still starts from `{}`.
  */
 export function writeConfigFile(path, mutate) {
     const raw = readConfigFile(path) ?? {};
@@ -22,13 +30,37 @@ export function writeConfigFile(path, mutate) {
     ensureDir(dirname(path), 0o700);
     writeFileAtomic(path, `${JSON.stringify(raw, null, 2)}\n`, 0o600);
 }
+/**
+ * Writes a default config scaffold to `path`: schema version, a `text` output
+ * default, and one empty profile per supported network. Shared by `config init`
+ * and `btcr2 init` so the seeded config is identical. Writes atomically (file
+ * 0600, dir 0700); the caller decides whether to overwrite an existing file.
+ */
+export function writeDefaultConfigFile(path) {
+    const scaffold = {
+        schemaVersion: CONFIG_SCHEMA_VERSION,
+        defaults: { output: 'text' },
+        profiles: Object.fromEntries(SUPPORTED_NETWORKS.map(n => [n, {}])),
+    };
+    ensureDir(dirname(path), 0o700);
+    writeFileAtomic(path, `${JSON.stringify(scaffold, null, 2)}\n`, 0o600);
+}
 /** Reads the value at a dotted path (e.g. `profiles.regtest.btc.rest`). */
 export function getConfigPath(config, path) {
     return path.split('.').reduce((node, key) => node?.[key], config);
 }
+/** Dotted-path segments that would let a write reach the prototype chain. */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Rejects a path segment that would let a `config set`/`unset` reach the prototype chain. */
+function assertSafeKey(key, path) {
+    if (UNSAFE_KEYS.has(key)) {
+        throw new CLIError(`Illegal config path segment "${key}" in "${path}".`, 'INVALID_ARGUMENT_ERROR', { path, key });
+    }
+}
 /** Sets the value at a dotted path, creating intermediate objects. */
 export function setConfigPath(config, path, value) {
     const keys = path.split('.');
+    keys.forEach(key => assertSafeKey(key, path));
     const last = keys.pop();
     if (!last)
         throw new CLIError('Config path must be non-empty.', 'INVALID_ARGUMENT_ERROR');
@@ -43,6 +75,7 @@ export function setConfigPath(config, path, value) {
 /** Deletes the value at a dotted path. No-op if the path does not exist. */
 export function unsetConfigPath(config, path) {
     const keys = path.split('.');
+    keys.forEach(key => assertSafeKey(key, path));
     const last = keys.pop();
     if (!last)
         return;
@@ -65,6 +98,9 @@ export function unsetConfigPath(config, path) {
  * | `BTCR2_BTC_RPC_PASS`  | `--btc-rpc-pass`   |
  * | `BTCR2_CAS_GATEWAY`   | `--cas-gateway`    |
  * | `BTCR2_CAS_RPC_URL`   | `--cas-rpc-url`    |
+ * | `BTCR2_BTC_TIMEOUT`   | `--btc-timeout`    |
+ * | `BTCR2_CAS_TIMEOUT`   | `--cas-timeout`    |
+ * | `BTCR2_FEE_RATE`      | `--fee-rate`       |
  */
 export const ENV_VARS = {
     BTC_REST: 'BTCR2_BTC_REST',
@@ -73,6 +109,9 @@ export const ENV_VARS = {
     BTC_RPC_PASS: 'BTCR2_BTC_RPC_PASS',
     CAS_GATEWAY: 'BTCR2_CAS_GATEWAY',
     CAS_RPC_URL: 'BTCR2_CAS_RPC_URL',
+    BTC_TIMEOUT: 'BTCR2_BTC_TIMEOUT',
+    CAS_TIMEOUT: 'BTCR2_CAS_TIMEOUT',
+    FEE_RATE: 'BTCR2_FEE_RATE',
 };
 /**
  * Reads {@link ConnectionOverrides} from environment variables.
@@ -90,30 +129,58 @@ export function readEnvOverrides() {
     };
 }
 /**
- * Default config file path following the XDG Base Directory Specification.
- *
- * Resolution order:
- * 1. `$XDG_CONFIG_HOME/btcr2/config.json`
- * 2. `%APPDATA%/btcr2/config.json` (Windows)
- * 3. `~/.config/btcr2/config.json` (fallback)
+ * Reads and JSON-parses a config file without applying the schema-version
+ * ceiling check. Returns `undefined` only for a genuinely absent file (ENOENT).
+ * Any other read failure, and any JSON parse failure, throws a {@link CLIError}
+ * that names the file. Used by `config validate`, which reports a newer-than-
+ * supported `schemaVersion` as a finding rather than aborting on it.
  */
-export function defaultConfigPath() {
-    const base = process.env.XDG_CONFIG_HOME
-        ?? process.env.APPDATA
-        ?? join(homedir(), '.config');
-    return join(base, 'btcr2', 'config.json');
+export function parseConfigFileRaw(path) {
+    let content;
+    try {
+        content = readFileSync(path, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new CLIError(`Failed to read config file at ${path}: ${error.message}`, 'CONFIG_READ_ERROR', { path });
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new CLIError(`Config file at ${path} is not valid JSON: ${error.message}. `
+            + 'Fix the file by hand; the CLI will not overwrite it while it is unparseable.', 'CONFIG_PARSE_ERROR', { path });
+    }
 }
 /**
- * Reads and parses a config file. Returns `undefined` if the file does
- * not exist or cannot be parsed.
+ * Reads and parses a config file. Returns `undefined` only when the file is
+ * genuinely absent (ENOENT), so callers can safely treat "no file" as "use
+ * defaults". Any other read failure, and any JSON parse failure, throws a
+ * {@link CLIError} that names the file, rather than silently degrading to the
+ * public network defaults. A file written by a newer CLI (higher `schemaVersion`)
+ * is also refused.
  */
 export function readConfigFile(path) {
-    try {
-        const content = readFileSync(path, 'utf-8');
-        return JSON.parse(content);
-    }
-    catch {
+    const parsed = parseConfigFileRaw(path);
+    if (parsed === undefined)
         return undefined;
+    migrateConfigShape(parsed, path);
+    return parsed;
+}
+/**
+ * Validates a parsed config's `schemaVersion` against {@link CONFIG_SCHEMA_VERSION}
+ * and brings an older shape up to the current version in place. A file written by
+ * a newer CLI is refused so today's assumptions are never applied blindly to an
+ * unknown shape. An absent version is treated as the earliest and migrated
+ * forward. No structural migrations are registered yet (the schema is at version
+ * 1); future versions register their transforms here in ascending order.
+ */
+function migrateConfigShape(raw, path) {
+    const version = typeof raw.schemaVersion === 'number' ? raw.schemaVersion : 0;
+    if (version > CONFIG_SCHEMA_VERSION) {
+        throw new CLIError(`Config file at ${path} has schemaVersion ${version}, but this CLI supports up to `
+            + `${CONFIG_SCHEMA_VERSION}. Upgrade the btcr2 CLI to read it.`, 'CONFIG_SCHEMA_VERSION_ERROR', { path, fileVersion: version, supported: CONFIG_SCHEMA_VERSION });
     }
 }
 /**
@@ -133,26 +200,118 @@ export function profileToOverrides(config, profileName) {
         casRpcUrl: profile.cas?.rpcUrl,
     };
 }
+/**
+ * Resolves the active profile name and the network it targets, shared by
+ * {@link resolveDefaultNetwork} and {@link resolveConnectionConfig} so the two
+ * can never disagree about which profile is active or which network it means.
+ *
+ * The active profile name is the explicit `--profile` flag, else the config
+ * file's `defaults.profile`. The network is the profile's own `network` field
+ * when set to a supported value, else the profile name itself when it is a
+ * network name (the historical convention). A profile that declares no network
+ * and is not named after one yields `network: undefined`.
+ */
+export function resolveActiveProfile(file, overrides) {
+    const name = blankToUndef(overrides?.profile) ?? file?.defaults?.profile;
+    if (!name)
+        return { name: undefined, network: undefined };
+    const declared = file?.profiles?.[name]?.network;
+    const network = (declared && SUPPORTED_NETWORKS.includes(declared))
+        ? declared
+        : (SUPPORTED_NETWORKS.includes(name) ? name : undefined);
+    return { name, network };
+}
 /**
  * Resolves the default Bitcoin network for offline identifier creation when no
  * `--network` flag is given. Resolution order: the config file's
- * `defaults.network`, then an active profile named for a network (an explicit
- * `--profile` flag or `defaults.profile`), then `regtest` as the development
+ * `defaults.network`, then the active profile's network (its explicit `network`
+ * field, else its network-derived name), then `regtest` as the development
  * fallback. Generation itself is offline; this only fixes which network the
  * identifier encodes.
  */
 export function resolveDefaultNetwork(overrides) {
-    const configPath = overrides?.config ?? defaultConfigPath();
+    const configPath = overrides?.config ?? defaultConfigPath(overrides);
     const file = readConfigFile(configPath);
     const explicit = file?.defaults?.network;
     if (explicit && SUPPORTED_NETWORKS.includes(explicit))
         return explicit;
-    const profile = overrides?.profile ?? file?.defaults?.profile;
-    if (profile && SUPPORTED_NETWORKS.includes(profile)) {
-        return profile;
-    }
+    const { network } = resolveActiveProfile(file, overrides);
+    if (network)
+        return network;
     return 'regtest';
 }
+/**
+ * Reports a coherence conflict between the network a `create` run is about to
+ * encode and the network the active profile declares, so the CLI can warn
+ * instead of silently minting an identifier on one network while wiring
+ * endpoints for another. Returns `undefined` when the active profile declares
+ * no network or agrees with the one being encoded.
+ */
+export function profileNetworkMismatch(network, overrides) {
+    // This drives only a warning, so a malformed config must not break an otherwise
+    // offline `create`; a genuinely broken config is still surfaced loudly by any
+    // command that actually resolves a connection.
+    let file;
+    try {
+        file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
+    }
+    catch {
+        return undefined;
+    }
+    const { name, network: declared } = resolveActiveProfile(file, overrides);
+    if (name && declared && declared !== network)
+        return { profile: name, declared };
+    return undefined;
+}
+/**
+ * Resolves the effective output format: the `-o/--output` flag, then the
+ * `BTCR2_OUTPUT` environment variable, then the config file's `defaults.output`,
+ * then `'text'`. A malformed config never blocks output resolution (the command's
+ * own read path surfaces it); output format falls back to `'text'` instead.
+ */
+export function resolveOutputFormat(options) {
+    const candidates = [
+        blankToUndef(options.output),
+        process.env.BTCR2_OUTPUT || undefined,
+    ];
+    try {
+        candidates.push(readConfigFile(options.config ?? defaultConfigPath(options))?.defaults?.output);
+    }
+    catch {
+        // Output format is cosmetic; a broken config is reported by the command
+        // itself rather than aborting here (which would block a recovery command).
+    }
+    for (const candidate of candidates) {
+        if (candidate === 'json' || candidate === 'text')
+            return candidate;
+    }
+    return 'text';
+}
+/**
+ * Resolves the RPC credential unit atomically: the highest-precedence layer that
+ * supplies a url, else the highest that supplies a username or password. url,
+ * user, and pass therefore always come from one layer, so a host from one layer
+ * is never handed another layer's credentials (ADR 074). When no layer supplies a
+ * url, the credentials still resolve (so they reach the SDK's per-network default
+ * host, e.g. regtest's, without the url being restated). Returns `undefined` when
+ * no layer supplies a url or a credential.
+ */
+function resolveRpcUnit(overrides, env, fileOverrides) {
+    const layers = [
+        { src: 'flag', url: overrides?.btcRpcUrl, user: overrides?.btcRpcUser, pass: overrides?.btcRpcPass },
+        { src: 'env', url: env?.btcRpcUrl, user: env?.btcRpcUser, pass: env?.btcRpcPass },
+        { src: 'file', url: fileOverrides?.btcRpcUrl, user: fileOverrides?.btcRpcUser, pass: fileOverrides?.btcRpcPass },
+    ];
+    const withUrl = layers.find(l => blankToUndef(l.url) !== undefined);
+    if (withUrl) {
+        return { src: withUrl.src, url: blankToUndef(withUrl.url), user: blankToUndef(withUrl.user), pass: blankToUndef(withUrl.pass) };
+    }
+    const withCreds = layers.find(l => blankToUndef(l.user) !== undefined || blankToUndef(l.pass) !== undefined);
+    if (withCreds) {
+        return { src: withCreds.src, url: undefined, user: blankToUndef(withCreds.user), pass: blankToUndef(withCreds.pass) };
+    }
+    return undefined;
+}
 /**
  * Resolves the Bitcoin and CAS connection config for a network by merging,
  * in precedence order, CLI flags, environment variables, and the config-file
@@ -164,47 +323,331 @@ export function resolveDefaultNetwork(overrides) {
  * When no `--profile` is given, the network name is used as the profile key
  * (e.g. a regtest DID auto-selects the `"regtest"` profile).
  */
-function resolveConnectionConfig(network, overrides) {
+export function resolveConnectionConfig(network, overrides) {
     if (!network)
         return {};
-    // Layer 1: Config file profile (lowest precedence of the three override layers)
-    const configPath = overrides?.config ?? defaultConfigPath();
+    // Layer 1: Config file profile (lowest precedence of the three override layers).
+    // The active-profile name is resolved through the same shared helper as
+    // resolveDefaultNetwork so the two cannot disagree about which profile is live.
+    const configPath = overrides?.config ?? defaultConfigPath(overrides);
     const file = readConfigFile(configPath);
-    const profileName = overrides?.profile ?? file?.defaults?.profile ?? network;
+    const { name: activeProfile } = resolveActiveProfile(file, overrides);
+    const profileName = activeProfile ?? network;
     const fileOverrides = file ? profileToOverrides(file, profileName) : {};
     // Layer 2: Environment variables
     const env = readEnvOverrides();
-    // Merge: CLI flags -> env vars -> config file -> (network defaults handled by BitcoinConnection)
-    const merged = {
-        btcRest: overrides?.btcRest ?? env.btcRest ?? fileOverrides.btcRest,
-        btcRpcUrl: overrides?.btcRpcUrl ?? env.btcRpcUrl ?? fileOverrides.btcRpcUrl,
-        btcRpcUser: overrides?.btcRpcUser ?? env.btcRpcUser ?? fileOverrides.btcRpcUser,
-        btcRpcPass: overrides?.btcRpcPass ?? env.btcRpcPass ?? fileOverrides.btcRpcPass,
-        casGateway: overrides?.casGateway ?? env.casGateway ?? fileOverrides.casGateway,
-        casRpcUrl: overrides?.casRpcUrl ?? env.casRpcUrl ?? fileOverrides.casRpcUrl,
-    };
+    // Blank-aware precedence merge: CLI flag -> env var -> config file. A blank at
+    // any layer defers to the next instead of masking it (mirrors the env layer's
+    // `|| undefined`), so an empty flag or profile field no longer silently reverts
+    // resolution to the SDK network default.
+    const pick = (flag, envVal, fileVal) => blankToUndef(flag) ?? blankToUndef(envVal) ?? blankToUndef(fileVal);
+    const profileBtc = file?.profiles?.[profileName]?.btc;
+    const profileCas = file?.profiles?.[profileName]?.cas;
     const btc = { network };
-    if (merged.btcRest) {
-        btc.rest = { host: merged.btcRest };
+    // REST host and headers. Headers apply even without a host override, layering
+    // onto the per-network default host inside the api's config merge, so an
+    // authenticated Esplora/mempool endpoint can be reached with the default host.
+    const btcRest = pick(overrides?.btcRest, env.btcRest, fileOverrides.btcRest);
+    const restHeaders = mergeHeaders(profileBtc?.headers, parseHeaderList(overrides?.btcRestHeader, '--btc-rest-header'));
+    if (btcRest || restHeaders) {
+        btc.rest = { ...(btcRest ? { host: btcRest } : {}), ...(restHeaders ? { headers: restHeaders } : {}) };
     }
-    if (merged.btcRpcUrl) {
+    // Resolve the RPC endpoint as one atomic credential unit (url + user + pass from
+    // one layer), plus the orthogonal wallet and header augmentations.
+    const rpcUnit = resolveRpcUnit(overrides, env, fileOverrides);
+    const rpcWallet = pick(overrides?.btcRpcWallet, undefined, profileBtc?.wallet);
+    const rpcHeaders = mergeHeaders(profileBtc?.rpcHeaders, parseHeaderList(overrides?.btcRpcHeader, '--btc-rpc-header'));
+    // Build an RPC config only when a host will actually exist to talk to: either
+    // the unit supplies a url, or the network has a default RPC host (regtest).
+    // Wallet/header (or credential) knobs alone with no host would otherwise point
+    // a phantom client at the default 127.0.0.1:8332 and, on public networks, flip
+    // the connection to "has RPC" spuriously (and could leak a header credential
+    // meant for a remote proxy). The pass-file fallback is read lazily inside this
+    // block, so a set-but-unreadable BTCR2_BTC_RPC_PASS_FILE never aborts a command
+    // that uses no RPC at all.
+    const networkHasDefaultRpc = DEFAULT_BITCOIN_NETWORK_CONFIG[network].rpc !== undefined;
+    const wantsRpc = rpcUnit !== undefined || rpcWallet !== undefined || rpcHeaders !== undefined;
+    const hasRpcHost = rpcUnit?.url !== undefined || networkHasDefaultRpc;
+    if (wantsRpc && hasRpcHost) {
+        const password = resolveSecretRef(rpcUnit?.pass) ?? readRpcPassFile();
         btc.rpc = {
-            host: merged.btcRpcUrl,
-            username: merged.btcRpcUser,
-            password: merged.btcRpcPass,
+            ...(rpcUnit?.url !== undefined ? { host: rpcUnit.url } : {}),
+            ...(rpcUnit?.user !== undefined ? { username: rpcUnit.user } : {}),
+            ...(password !== undefined ? { password } : {}),
+            ...(rpcWallet ? { wallet: rpcWallet } : {}),
+            ...(rpcHeaders ? { headers: rpcHeaders } : {}),
         };
     }
+    // Bitcoin request timeout. No default: honored only when explicitly set, so
+    // callers that rely on unbounded waits are unaffected (ADR 076).
+    const btcTimeout = resolveTimeout(overrides?.btcTimeout, process.env[ENV_VARS.BTC_TIMEOUT], profileBtc?.timeoutMs, '--btc-timeout', 1);
+    if (btcTimeout !== undefined)
+        btc.timeoutMs = btcTimeout;
     // A configured RPC endpoint is writable and takes precedence over the
     // read-only gateway (matching the api's CasConfig priority: rpcUrl > gateway).
     // Both may be set; the api selects one executor from them.
+    const casGateway = pick(overrides?.casGateway, env.casGateway, fileOverrides.casGateway);
+    const casRpcUrl = pick(overrides?.casRpcUrl, env.casRpcUrl, fileOverrides.casRpcUrl);
+    const casTimeout = resolveTimeout(overrides?.casTimeout, process.env[ENV_VARS.CAS_TIMEOUT], profileCas?.timeoutMs, '--cas-timeout');
     const cas = {};
-    if (merged.casGateway)
-        cas.gateway = merged.casGateway;
-    if (merged.casRpcUrl)
-        cas.rpcUrl = merged.casRpcUrl;
-    const hasCas = merged.casGateway || merged.casRpcUrl;
+    if (casGateway)
+        cas.gateway = casGateway;
+    if (casRpcUrl)
+        cas.rpcUrl = casRpcUrl;
+    if (casTimeout !== undefined) {
+        cas.timeoutMs = casTimeout;
+        // A timeout needs an endpoint to attach to. When none is configured, fall
+        // back to the same default gateway the api would otherwise apply, so the
+        // timeout is honored rather than dropped (the api only defaults the gateway
+        // when the whole cas config is absent).
+        if (!casGateway && !casRpcUrl)
+            cas.gateway = DEFAULT_CAS_GATEWAY;
+    }
+    const hasCas = casGateway || casRpcUrl || casTimeout !== undefined;
     return { btc, ...(hasCas && { cas }) };
 }
+/**
+ * Resolves a millisecond timeout from a flag string, an env string, then a
+ * config-file number, in precedence order. Returns `undefined` when none is set
+ * (preserving unbounded behavior). Throws a {@link CLIError} for a value below
+ * `min` or not a finite number. `min` is `0` for CAS (where `0` disables the
+ * timeout) and `1` for the Bitcoin timeout (where `0` would abort every request
+ * immediately, which is never intended).
+ */
+function resolveTimeout(flag, envVal, fileVal, flagName = 'timeout', min = 0) {
+    const raw = blankToUndef(flag) ?? blankToUndef(envVal) ?? (typeof fileVal === 'number' ? String(fileVal) : undefined);
+    if (raw === undefined)
+        return undefined;
+    const ms = Number(raw);
+    if (!Number.isFinite(ms) || ms < min) {
+        throw new CLIError(`Invalid ${flagName} value "${raw}": expected a number of milliseconds >= ${min}.`, 'INVALID_ARGUMENT_ERROR', { value: raw });
+    }
+    return ms;
+}
+/**
+ * Parses repeatable `Key: Value` header flag values into a header map. Returns
+ * `undefined` for an empty list. Throws a {@link CLIError} for an entry missing a
+ * colon or with an empty key.
+ */
+export function parseHeaderList(list, flagName = '--header') {
+    if (!list || list.length === 0)
+        return undefined;
+    const headers = {};
+    for (const entry of list) {
+        const idx = entry.indexOf(':');
+        const key = idx === -1 ? '' : entry.slice(0, idx).trim();
+        if (idx === -1 || key === '') {
+            throw new CLIError(`Invalid ${flagName} "${entry}": expected "Key: Value".`, 'INVALID_ARGUMENT_ERROR', { header: entry });
+        }
+        headers[key] = entry.slice(idx + 1).trim();
+    }
+    return headers;
+}
+/**
+ * Merges a base header map (from the config-file profile) with an override map
+ * (from flags), with the override winning per key. Returns `undefined` when both
+ * are absent so callers can skip attaching an empty header map.
+ */
+function mergeHeaders(base, override) {
+    if (!base && !override)
+        return undefined;
+    return { ...base, ...override };
+}
+/** Environment variable naming a file whose contents are the Bitcoin Core RPC password. */
+export const ENV_RPC_PASS_FILE = 'BTCR2_BTC_RPC_PASS_FILE';
+/** Removes at most one trailing newline, matching the keystore-passphrase normalization. */
+function trimTrailingNewline(value) {
+    return value.replace(/\r?\n$/, '');
+}
+/** Reads a secret file, throwing a {@link CLIError} (not a raw Node error) that names the path and source. */
+function readSecretFile(path, source) {
+    try {
+        return trimTrailingNewline(readFileSync(path, 'utf-8'));
+    }
+    catch (error) {
+        throw new CLIError(`Could not read the RPC password ${source} at ${path}: ${error.message}`, 'CONFIG_READ_ERROR', { path });
+    }
+}
+/**
+ * Resolves an RPC-password secret reference to its literal value: `env:<VAR>`
+ * reads the named environment variable, `file:<path>` reads the file, and any
+ * other value is returned as-is. A trailing newline is trimmed from file/env
+ * sources so a secret written by `echo` matches an inline value (ADR 077).
+ */
+export function resolveSecretRef(value) {
+    if (value === undefined)
+        return undefined;
+    if (value.startsWith('env:')) {
+        const fromEnv = process.env[value.slice(4)];
+        return fromEnv === undefined ? undefined : trimTrailingNewline(fromEnv);
+    }
+    if (value.startsWith('file:')) {
+        return readSecretFile(value.slice(5), 'file reference');
+    }
+    return value;
+}
+/** Reads the RPC password from an {@link ENV_RPC_PASS_FILE}-named file, if set. */
+function readRpcPassFile() {
+    const path = process.env[ENV_RPC_PASS_FILE];
+    if (!path)
+        return undefined;
+    return readSecretFile(path, `file named by ${ENV_RPC_PASS_FILE}`);
+}
+/**
+ * Resolves the beacon {@link BroadcastOptions} for an update/deactivate from the
+ * fee-rate and change-address knobs, following the CLI precedence chain.
+ *
+ * - Fee rate: `--fee-rate` flag, then `BTCR2_FEE_RATE`, then profile
+ *   `btc.feeRate`. A positive sats/vByte value wrapped in a `StaticFeeEstimator`.
+ * - Change address: `--change-address` flag, then profile `btc.changeAddress`
+ *   (no env, since a change address is DID/network-specific). Validated against
+ *   the DID network by the beacon at broadcast time.
+ *
+ * Returns `undefined` when neither is set, so the SDK defaults (5 sat/vB, change
+ * back to the beacon address) still apply.
+ */
+export function resolveBroadcastOptions(network, overrides, flags) {
+    const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
+    const { name: activeProfile } = resolveActiveProfile(file, overrides);
+    const profileBtc = file?.profiles?.[activeProfile ?? network]?.btc;
+    const options = {};
+    const feeRateRaw = blankToUndef(flags.feeRate)
+        ?? blankToUndef(process.env[ENV_VARS.FEE_RATE])
+        ?? (typeof profileBtc?.feeRate === 'number' ? String(profileBtc.feeRate) : undefined);
+    if (feeRateRaw !== undefined)
+        options.feeEstimator = new StaticFeeEstimator(parseFeeRate(feeRateRaw));
+    const changeAddress = blankToUndef(flags.changeAddress) ?? blankToUndef(profileBtc?.changeAddress);
+    if (changeAddress)
+        options.changeAddress = changeAddress;
+    return options.feeEstimator || options.changeAddress ? options : undefined;
+}
+/** Parses a positive sats/vByte fee rate, throwing a {@link CLIError} otherwise. */
+function parseFeeRate(raw) {
+    const rate = Number(raw);
+    if (!Number.isFinite(rate) || rate <= 0) {
+        throw new CLIError(`Invalid --fee-rate "${raw}": expected a positive number of sats per vByte.`, 'INVALID_ARGUMENT_ERROR', { value: raw });
+    }
+    return rate;
+}
+/**
+ * Resolves the effective connection config with provenance for `config effective`.
+ * The btc values are read back from the constructed api (so SDK network defaults
+ * are reflected), the cas and timeout values from {@link resolveConnectionConfig},
+ * and each `source` is derived by the same precedence order the merge uses.
+ */
+export function resolveEffectiveConfig(network, overrides) {
+    const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
+    const { name: activeProfile } = resolveActiveProfile(file, overrides);
+    const profileName = activeProfile ?? network;
+    const fileOv = file ? profileToOverrides(file, profileName) : {};
+    const profileBtc = file?.profiles?.[profileName]?.btc;
+    const profileCas = file?.profiles?.[profileName]?.cas;
+    const env = readEnvOverrides();
+    const api = defaultApiFactory(network, overrides);
+    const restCfg = api.btc.connection.rest.config;
+    const rpcCfg = api.btc.connection.rpc?.config;
+    const conn = resolveConnectionConfig(network, overrides);
+    const src = (flag, envVal, fileVal) => blankToUndef(flag) !== undefined ? 'flag'
+        : blankToUndef(envVal) !== undefined ? 'env'
+            : (fileVal !== undefined && fileVal !== null && String(fileVal).trim() !== '') ? 'file'
+                : 'default';
+    // CAS has no client to read back from; derive its resolved endpoint from the
+    // connection resolver, defaulting the gateway the way the api would.
+    const casGatewayVal = conn.cas?.gateway ?? (conn.cas?.rpcUrl ? undefined : DEFAULT_CAS_GATEWAY);
+    // RPC url/user/pass provenance follows the atomic-credential unit, so a value's
+    // reported source is the layer the merge actually bound it to (never an
+    // independent per-field guess that could disagree with the resolver). A password
+    // taken from BTCR2_BTC_RPC_PASS_FILE when the unit supplied none is env-sourced.
+    const rpcUnit = resolveRpcUnit(overrides, env, fileOv);
+    const rpcSrc = rpcUnit?.src ?? 'default';
+    const passFromFile = rpcUnit?.pass === undefined
+        && process.env[ENV_RPC_PASS_FILE] !== undefined
+        && rpcCfg?.password !== undefined;
+    return {
+        network,
+        profile: activeProfile,
+        btc: {
+            rest: { value: restCfg.host, source: src(overrides?.btcRest, env.btcRest, fileOv.btcRest) },
+            rpcUrl: { value: rpcCfg?.host, source: rpcUnit?.url !== undefined ? rpcSrc : 'default' },
+            rpcUser: { value: rpcCfg?.username, source: rpcUnit?.user !== undefined ? rpcSrc : 'default' },
+            rpcPass: { value: rpcCfg?.password, source: rpcUnit?.pass !== undefined ? rpcSrc : (passFromFile ? 'env' : 'default') },
+            rpcWallet: { value: rpcCfg?.wallet, source: src(overrides?.btcRpcWallet, undefined, profileBtc?.wallet) },
+            timeoutMs: { value: conn.btc?.timeoutMs, source: src(overrides?.btcTimeout, process.env[ENV_VARS.BTC_TIMEOUT], profileBtc?.timeoutMs) },
+        },
+        cas: {
+            gateway: { value: casGatewayVal, source: src(overrides?.casGateway, env.casGateway, fileOv.casGateway) },
+            rpcUrl: { value: conn.cas?.rpcUrl, source: src(overrides?.casRpcUrl, env.casRpcUrl, fileOv.casRpcUrl) },
+            timeoutMs: { value: conn.cas?.timeoutMs, source: src(overrides?.casTimeout, process.env[ENV_VARS.CAS_TIMEOUT], profileCas?.timeoutMs) },
+        },
+    };
+}
+/** Default per-probe timeout (ms) for `config doctor`. */
+const DOCTOR_PROBE_TIMEOUT_MS = 5000;
+/** Fetches a URL with a bounded timeout, reporting reachability rather than throwing. */
+async function probeEndpoint(endpoint, target, url, opts) {
+    try {
+        const res = await fetch(url, {
+            method: opts?.method ?? 'GET',
+            headers: opts?.headers,
+            signal: AbortSignal.timeout(DOCTOR_PROBE_TIMEOUT_MS),
+        });
+        return res.ok
+            ? { endpoint, target, ok: true }
+            : { endpoint, target, ok: false, detail: `HTTP ${res.status}` };
+    }
+    catch (error) {
+        return { endpoint, target, ok: false, detail: error.message };
+    }
+}
+/** Races a promise against a timeout so a stalled RPC call cannot hang `doctor`. */
+function withProbeTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Probes reachability of the resolved endpoints for `config doctor`: a
+ * lightweight REST call against btc-rest, a `getblockchaininfo` against btc-rpc
+ * when configured, and a reachability check against the resolved CAS. Also
+ * surfaces the profile/network coherence warning. Reads and touches the network;
+ * never writes.
+ */
+export async function runDoctor(network, overrides) {
+    const api = defaultApiFactory(network, overrides);
+    const checks = [];
+    const restHost = api.btc.connection.rest.config.host.replace(/\/+$/, '');
+    checks.push(await probeEndpoint('btc-rest', restHost, `${restHost}/blocks/tip/height`, { headers: api.btc.connection.rest.config.headers }));
+    const rpc = api.btc.connection.rpc;
+    if (rpc) {
+        const target = rpc.config.host ?? '(default rpc)';
+        try {
+            await withProbeTimeout(rpc.getBlockchainInfo(), DOCTOR_PROBE_TIMEOUT_MS);
+            checks.push({ endpoint: 'btc-rpc', target, ok: true });
+        }
+        catch (error) {
+            checks.push({ endpoint: 'btc-rpc', target, ok: false, detail: error.message });
+        }
+    }
+    // A writable IPFS RPC (Kubo) answers only POST, so a bare GET would falsely
+    // report a healthy node as down; probe its version endpoint with POST. A
+    // read-only gateway answers a plain GET on its base URL.
+    const conn = resolveConnectionConfig(network, overrides);
+    if (conn.cas?.rpcUrl) {
+        const base = conn.cas.rpcUrl.replace(/\/+$/, '');
+        checks.push(await probeEndpoint('cas', conn.cas.rpcUrl, `${base}/api/v0/version`, { method: 'POST' }));
+    }
+    else {
+        const gateway = (conn.cas?.gateway ?? DEFAULT_CAS_GATEWAY).replace(/\/+$/, '');
+        checks.push(await probeEndpoint('cas', gateway, gateway));
+    }
+    const mismatch = profileNetworkMismatch(network, overrides);
+    return {
+        checks,
+        ...(mismatch ? { coherence: { profile: mismatch.profile, declared: mismatch.declared, encoding: network } } : {}),
+    };
+}
 /**
  * Default {@link ApiFactory} backed by network defaults from
  * `@did-btcr2/bitcoin` (mempool.space for public networks, localhost for
@@ -226,10 +669,91 @@ export function defaultApiFactory(network, overrides) {
  */
 function buildKeystoreKms(overrides) {
     return new FileBackedKeyManager({
-        path: overrides?.keystore ?? defaultKeystorePath(),
-        getPassphrase: () => acquirePassphrase({ passphraseFile: overrides?.passphraseFile }),
+        path: resolveKeystorePath(overrides),
+        // The store decides when to confirm: it passes `confirm: true` only while
+        // establishing a fresh keystore's passphrase, so a first-key typo is caught
+        // by a second entry (ADR 080). confirm is a no-op for env/file sources.
+        getPassphrase: (opts) => acquirePassphrase({ passphraseFile: overrides?.passphraseFile, confirm: opts?.confirm }),
     });
 }
+/**
+ * The protection mode of the resolved keystore, read without decrypting or
+ * prompting: `encrypted`, `dev` (plaintext), or `absent`. Used by `keystore
+ * status`, `config path`, and the mainnet guard.
+ */
+export function resolveKeystoreProtection(overrides) {
+    return keystoreProtection(resolveKeystorePath(overrides));
+}
+/**
+ * Hard-refuses using an unencrypted dev keystore for a mainnet operation (ADR
+ * 080). A plaintext key must never sign or seal a `bitcoin` did:btcr2; the check
+ * reads only the keystore's protection header, so it never decrypts or prompts.
+ * A no-op for every other network and for encrypted/absent keystores.
+ */
+export function assertKeystoreAllowedForNetwork(network, overrides) {
+    if (network !== 'bitcoin')
+        return;
+    if (resolveKeystoreProtection(overrides) !== 'dev')
+        return;
+    const path = resolveKeystorePath(overrides);
+    throw new CLIError(`Refusing a mainnet (bitcoin) operation with the unencrypted dev keystore at ${path}. `
+        + 'Dev keystores hold plaintext keys and are for testnet/regtest throwaway material only. '
+        + 'Establish an encrypted keystore (btcr2 keystore init) for mainnet keys.', 'DEV_KEYSTORE_MAINNET_ERROR', { path, network });
+}
+/**
+ * Resolves the keystore file path: the `--keystore` flag, else the active
+ * profile's `identity.keystore`, else the default `<home>/keystore.json` (ADR
+ * 079). The flag always wins over the profile default and never reads the config.
+ *
+ * A malformed config aborts loudly by default so a keystore-mutating command
+ * never silently reads or writes the wrong store. Pass `lenient: true` only for
+ * diagnostic/recovery commands (`config path`, `keystore status`) that must still
+ * report a path instead of crashing on the very config you ran them to fix; those
+ * fall back to the home default when the profile identity cannot be read.
+ */
+export function resolveKeystorePath(overrides, options) {
+    // The flag wins outright and short-circuits before any config read. A blank
+    // flag defers to the profile, and a blank profile `identity.keystore` defers to
+    // the default, so neither resolves the keystore to an empty path.
+    const fromFlag = blankToUndef(overrides?.keystore);
+    if (fromFlag)
+        return fromFlag;
+    let identity;
+    try {
+        identity = activeProfileIdentity(overrides);
+    }
+    catch (error) {
+        if (!options?.lenient)
+            throw error;
+    }
+    return blankToUndef(identity?.keystore) ?? defaultKeystorePath(overrides);
+}
+/**
+ * Reads the active profile's `identity` block (keystore + default signing key),
+ * or `undefined` when no profile is active. A profile is active only when
+ * selected by `--profile` or the config's `defaults.profile`.
+ */
+function activeProfileIdentity(overrides) {
+    // Intentionally propagates a malformed-config error rather than swallowing it.
+    // This feeds resolveKeystorePath for keystore-mutating commands (key generate/
+    // import, keystore init/change-passphrase) and the mainnet dev-keystore guard,
+    // so a broken config must abort loudly instead of silently resolving to the
+    // default keystore and stranding key material there. Diagnostic-only commands
+    // opt into a graceful fallback via resolveKeystorePath's `lenient` option; do
+    // not add a try/catch here (it would re-hide the keystore misdirection).
+    const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
+    const { name } = resolveActiveProfile(file, overrides);
+    return name ? file?.profiles?.[name]?.identity : undefined;
+}
+/**
+ * Resolves the signing-key reference for update/deactivate: the `--signing-key`
+ * flag, else the active profile's `identity.default`, else `undefined` (letting
+ * the KMS fall back to its active key). The flag always wins over the profile
+ * default, consistent with the flag -> profile precedence used elsewhere.
+ */
+export function resolveSigningKeyRef(overrides) {
+    return blankToUndef(overrides?.signingKey) ?? blankToUndef(activeProfileIdentity(overrides)?.default);
+}
 /**
  * Keystore-aware {@link ApiFactory} for commands that need a signing identity
  * (key management, update, deactivate). Identical to {@link defaultApiFactory}