@did-btcr2/cli 0.14.0 → 0.15.0

package/dist/cjs/index.js

@@ -23,18 +23,26 @@ __export(index_exports, {
   CLIError: () => CLIError,
   CONFIG_SCHEMA_VERSION: () => CONFIG_SCHEMA_VERSION,
   DidBtcr2Cli: () => DidBtcr2Cli,
+  ENV_RPC_PASS_FILE: () => ENV_RPC_PASS_FILE,
   ENV_VARS: () => ENV_VARS,
+  REDACTED: () => REDACTED,
   SUPPORTED_NETWORKS: () => SUPPORTED_NETWORKS,
   VERSION: () => VERSION,
+  blankToUndef: () => blankToUndef,
   defaultApiFactory: () => defaultApiFactory,
   defaultConfigPath: () => defaultConfigPath,
   deriveNetwork: () => deriveNetwork,
   formatResult: () => formatResult,
   getConfigPath: () => getConfigPath,
+  isSecretKey: () => isSecretKey,
   keystoreApiFactory: () => keystoreApiFactory,
+  parseConfigFileRaw: () => parseConfigFileRaw,
+  parseHeaderList: () => parseHeaderList,
+  profileNetworkMismatch: () => profileNetworkMismatch,
   profileToOverrides: () => profileToOverrides,
   readConfigFile: () => readConfigFile,
   readEnvOverrides: () => readEnvOverrides,
+  redactSecrets: () => redactSecrets,
   registerCompletionCommand: () => registerCompletionCommand,
   registerConfigCommand: () => registerConfigCommand,
   registerCreateCommand: () => registerCreateCommand,
@@ -43,7 +51,17 @@ __export(index_exports, {
   registerProfileCommand: () => registerProfileCommand,
   registerResolveCommand: () => registerResolveCommand,
   registerUpdateCommand: () => registerUpdateCommand,
+  resolveActiveProfile: () => resolveActiveProfile,
+  resolveBroadcastOptions: () => resolveBroadcastOptions,
+  resolveConnectionConfig: () => resolveConnectionConfig,
   resolveDefaultNetwork: () => resolveDefaultNetwork,
+  resolveEffectiveConfig: () => resolveEffectiveConfig,
+  resolveKeystorePath: () => resolveKeystorePath,
+  resolveOutputFormat: () => resolveOutputFormat,
+  resolveSecretRef: () => resolveSecretRef,
+  resolveSigningKeyRef: () => resolveSigningKeyRef,
+  runDoctor: () => runDoctor,
+  scrubUrlUserinfo: () => scrubUrlUserinfo,
   setConfigPath: () => setConfigPath,
   unsetConfigPath: () => unsetConfigPath,
   writeConfigFile: () => writeConfigFile
@@ -63,6 +81,7 @@ var import_utils2 = require("@noble/hashes/utils.js");
 
 // src/config.ts
 var import_api = require("@did-btcr2/api");
+var import_method = require("@did-btcr2/method");
 var import_node_fs5 = require("fs");
 var import_node_os2 = require("os");
 var import_node_path4 = require("path");
@@ -317,8 +336,24 @@ function withFileLock(lockPath, fn, options = {}) {
 // src/keystore/paths.ts
 var import_node_os = require("os");
 var import_node_path2 = require("path");
+
+// src/types.ts
+var SUPPORTED_NETWORKS = [
+  "bitcoin",
+  "testnet3",
+  "testnet4",
+  "signet",
+  "mutinynet",
+  "regtest"
+];
+function blankToUndef(value) {
+  if (value === void 0) return void 0;
+  return value.trim() === "" ? void 0 : value;
+}
+
+// src/keystore/paths.ts
 function defaultKeystorePath() {
-  const base = process.env.XDG_DATA_HOME ?? process.env.LOCALAPPDATA ?? (0, import_node_path2.join)((0, import_node_os.homedir)(), ".local", "share");
+  const base = blankToUndef(process.env.XDG_DATA_HOME) ?? blankToUndef(process.env.LOCALAPPDATA) ?? (0, import_node_path2.join)((0, import_node_os.homedir)(), ".local", "share");
   return (0, import_node_path2.join)(base, "btcr2", "keystore.json");
 }
 
@@ -657,16 +692,6 @@ function promptHidden(label) {
   return Buffer.from(bytes).toString("utf-8");
 }
 
-// src/types.ts
-var SUPPORTED_NETWORKS = [
-  "bitcoin",
-  "testnet3",
-  "testnet4",
-  "signet",
-  "mutinynet",
-  "regtest"
-];
-
 // src/config.ts
 var CONFIG_SCHEMA_VERSION = 1;
 function writeConfigFile(path, mutate) {
@@ -683,8 +708,15 @@ function getConfigPath(config, path) {
     config
   );
 }
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function assertSafeKey(key, path) {
+  if (UNSAFE_KEYS.has(key)) {
+    throw new CLIError(`Illegal config path segment "${key}" in "${path}".`, "INVALID_ARGUMENT_ERROR", { path, key });
+  }
+}
 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");
   let node = config;
@@ -696,6 +728,7 @@ function setConfigPath(config, path, value) {
 }
 function unsetConfigPath(config, path) {
   const keys = path.split(".");
+  keys.forEach((key) => assertSafeKey(key, path));
   const last = keys.pop();
   if (!last) return;
   let node = config;
@@ -711,7 +744,10 @@ var ENV_VARS = {
   BTC_RPC_USER: "BTCR2_BTC_RPC_USER",
   BTC_RPC_PASS: "BTCR2_BTC_RPC_PASS",
   CAS_GATEWAY: "BTCR2_CAS_GATEWAY",
-  CAS_RPC_URL: "BTCR2_CAS_RPC_URL"
+  CAS_RPC_URL: "BTCR2_CAS_RPC_URL",
+  BTC_TIMEOUT: "BTCR2_BTC_TIMEOUT",
+  CAS_TIMEOUT: "BTCR2_CAS_TIMEOUT",
+  FEE_RATE: "BTCR2_FEE_RATE"
 };
 function readEnvOverrides() {
   const env = (key) => process.env[key] || void 0;
@@ -725,15 +761,45 @@ function readEnvOverrides() {
   };
 }
 function defaultConfigPath() {
-  const base = process.env.XDG_CONFIG_HOME ?? process.env.APPDATA ?? (0, import_node_path4.join)((0, import_node_os2.homedir)(), ".config");
+  const base = blankToUndef(process.env.XDG_CONFIG_HOME) ?? blankToUndef(process.env.APPDATA) ?? (0, import_node_path4.join)((0, import_node_os2.homedir)(), ".config");
   return (0, import_node_path4.join)(base, "btcr2", "config.json");
 }
-function readConfigFile(path) {
+function parseConfigFileRaw(path) {
+  let content;
+  try {
+    content = (0, import_node_fs5.readFileSync)(path, "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw new CLIError(
+      `Failed to read config file at ${path}: ${error.message}`,
+      "CONFIG_READ_ERROR",
+      { path }
+    );
+  }
   try {
-    const content = (0, import_node_fs5.readFileSync)(path, "utf-8");
     return JSON.parse(content);
-  } catch {
-    return void 0;
+  } 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 }
+    );
+  }
+}
+function readConfigFile(path) {
+  const parsed = parseConfigFileRaw(path);
+  if (parsed === void 0) return void 0;
+  migrateConfigShape(parsed, path);
+  return parsed;
+}
+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 }
+    );
   }
 }
 function profileToOverrides(config, profileName) {
@@ -748,58 +814,302 @@ function profileToOverrides(config, profileName) {
     casRpcUrl: profile.cas?.rpcUrl
   };
 }
+function resolveActiveProfile(file, overrides) {
+  const name = blankToUndef(overrides?.profile) ?? file?.defaults?.profile;
+  if (!name) return { name: void 0, network: void 0 };
+  const declared = file?.profiles?.[name]?.network;
+  const network = declared && SUPPORTED_NETWORKS.includes(declared) ? declared : SUPPORTED_NETWORKS.includes(name) ? name : void 0;
+  return { name, network };
+}
 function resolveDefaultNetwork(overrides) {
   const configPath = overrides?.config ?? defaultConfigPath();
   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";
 }
+function profileNetworkMismatch(network, overrides) {
+  let file;
+  try {
+    file = readConfigFile(overrides?.config ?? defaultConfigPath());
+  } catch {
+    return void 0;
+  }
+  const { name, network: declared } = resolveActiveProfile(file, overrides);
+  if (name && declared && declared !== network) return { profile: name, declared };
+  return void 0;
+}
+function resolveOutputFormat(options) {
+  const candidates = [
+    blankToUndef(options.output),
+    process.env.BTCR2_OUTPUT || void 0
+  ];
+  try {
+    candidates.push(readConfigFile(options.config ?? defaultConfigPath())?.defaults?.output);
+  } catch {
+  }
+  for (const candidate of candidates) {
+    if (candidate === "json" || candidate === "text") return candidate;
+  }
+  return "text";
+}
+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) !== void 0);
+  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) !== void 0 || blankToUndef(l.pass) !== void 0);
+  if (withCreds) {
+    return { src: withCreds.src, url: void 0, user: blankToUndef(withCreds.user), pass: blankToUndef(withCreds.pass) };
+  }
+  return void 0;
+}
 function resolveConnectionConfig(network, overrides) {
   if (!network) return {};
   const configPath = overrides?.config ?? defaultConfigPath();
   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) : {};
   const env = readEnvOverrides();
-  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
-  };
+  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 };
-  }
-  if (merged.btcRpcUrl) {
+  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 } : {} };
+  }
+  const rpcUnit = resolveRpcUnit(overrides, env, fileOverrides);
+  const rpcWallet = pick(overrides?.btcRpcWallet, void 0, profileBtc?.wallet);
+  const rpcHeaders = mergeHeaders(profileBtc?.rpcHeaders, parseHeaderList(overrides?.btcRpcHeader, "--btc-rpc-header"));
+  const networkHasDefaultRpc = import_api.DEFAULT_BITCOIN_NETWORK_CONFIG[network].rpc !== void 0;
+  const wantsRpc = rpcUnit !== void 0 || rpcWallet !== void 0 || rpcHeaders !== void 0;
+  const hasRpcHost = rpcUnit?.url !== void 0 || networkHasDefaultRpc;
+  if (wantsRpc && hasRpcHost) {
+    const password = resolveSecretRef(rpcUnit?.pass) ?? readRpcPassFile();
     btc.rpc = {
-      host: merged.btcRpcUrl,
-      username: merged.btcRpcUser,
-      password: merged.btcRpcPass
+      ...rpcUnit?.url !== void 0 ? { host: rpcUnit.url } : {},
+      ...rpcUnit?.user !== void 0 ? { username: rpcUnit.user } : {},
+      ...password !== void 0 ? { password } : {},
+      ...rpcWallet ? { wallet: rpcWallet } : {},
+      ...rpcHeaders ? { headers: rpcHeaders } : {}
     };
   }
+  const btcTimeout = resolveTimeout(overrides?.btcTimeout, process.env[ENV_VARS.BTC_TIMEOUT], profileBtc?.timeoutMs, "--btc-timeout", 1);
+  if (btcTimeout !== void 0) btc.timeoutMs = btcTimeout;
+  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 !== void 0) {
+    cas.timeoutMs = casTimeout;
+    if (!casGateway && !casRpcUrl) cas.gateway = import_api.DEFAULT_CAS_GATEWAY;
+  }
+  const hasCas = casGateway || casRpcUrl || casTimeout !== void 0;
   return { btc, ...hasCas && { cas } };
 }
+function resolveTimeout(flag, envVal, fileVal, flagName = "timeout", min = 0) {
+  const raw = blankToUndef(flag) ?? blankToUndef(envVal) ?? (typeof fileVal === "number" ? String(fileVal) : void 0);
+  if (raw === void 0) return void 0;
+  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;
+}
+function parseHeaderList(list, flagName = "--header") {
+  if (!list || list.length === 0) return void 0;
+  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;
+}
+function mergeHeaders(base, override) {
+  if (!base && !override) return void 0;
+  return { ...base, ...override };
+}
+var ENV_RPC_PASS_FILE = "BTCR2_BTC_RPC_PASS_FILE";
+function trimTrailingNewline(value) {
+  return value.replace(/\r?\n$/, "");
+}
+function readSecretFile(path, source) {
+  try {
+    return trimTrailingNewline((0, import_node_fs5.readFileSync)(path, "utf-8"));
+  } catch (error) {
+    throw new CLIError(
+      `Could not read the RPC password ${source} at ${path}: ${error.message}`,
+      "CONFIG_READ_ERROR",
+      { path }
+    );
+  }
+}
+function resolveSecretRef(value) {
+  if (value === void 0) return void 0;
+  if (value.startsWith("env:")) {
+    const fromEnv = process.env[value.slice(4)];
+    return fromEnv === void 0 ? void 0 : trimTrailingNewline(fromEnv);
+  }
+  if (value.startsWith("file:")) {
+    return readSecretFile(value.slice(5), "file reference");
+  }
+  return value;
+}
+function readRpcPassFile() {
+  const path = process.env[ENV_RPC_PASS_FILE];
+  if (!path) return void 0;
+  return readSecretFile(path, `file named by ${ENV_RPC_PASS_FILE}`);
+}
+function resolveBroadcastOptions(network, overrides, flags) {
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath());
+  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) : void 0);
+  if (feeRateRaw !== void 0) options.feeEstimator = new import_method.StaticFeeEstimator(parseFeeRate(feeRateRaw));
+  const changeAddress = blankToUndef(flags.changeAddress) ?? blankToUndef(profileBtc?.changeAddress);
+  if (changeAddress) options.changeAddress = changeAddress;
+  return options.feeEstimator || options.changeAddress ? options : void 0;
+}
+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;
+}
+function resolveEffectiveConfig(network, overrides) {
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath());
+  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) !== void 0 ? "flag" : blankToUndef(envVal) !== void 0 ? "env" : fileVal !== void 0 && fileVal !== null && String(fileVal).trim() !== "" ? "file" : "default";
+  const casGatewayVal = conn.cas?.gateway ?? (conn.cas?.rpcUrl ? void 0 : import_api.DEFAULT_CAS_GATEWAY);
+  const rpcUnit = resolveRpcUnit(overrides, env, fileOv);
+  const rpcSrc = rpcUnit?.src ?? "default";
+  const passFromFile = rpcUnit?.pass === void 0 && process.env[ENV_RPC_PASS_FILE] !== void 0 && rpcCfg?.password !== void 0;
+  return {
+    network,
+    profile: activeProfile,
+    btc: {
+      rest: { value: restCfg.host, source: src(overrides?.btcRest, env.btcRest, fileOv.btcRest) },
+      rpcUrl: { value: rpcCfg?.host, source: rpcUnit?.url !== void 0 ? rpcSrc : "default" },
+      rpcUser: { value: rpcCfg?.username, source: rpcUnit?.user !== void 0 ? rpcSrc : "default" },
+      rpcPass: { value: rpcCfg?.password, source: rpcUnit?.pass !== void 0 ? rpcSrc : passFromFile ? "env" : "default" },
+      rpcWallet: { value: rpcCfg?.wallet, source: src(overrides?.btcRpcWallet, void 0, 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) }
+    }
+  };
+}
+var DOCTOR_PROBE_TIMEOUT_MS = 5e3;
+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 };
+  }
+}
+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));
+}
+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 });
+    }
+  }
+  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 ?? import_api.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 } } : {}
+  };
+}
 function defaultApiFactory(network, overrides) {
   return (0, import_api.createApi)(resolveConnectionConfig(network, overrides));
 }
 function buildKeystoreKms(overrides) {
   return new FileBackedKeyManager({
-    path: overrides?.keystore ?? defaultKeystorePath(),
+    path: resolveKeystorePath(overrides),
     getPassphrase: () => acquirePassphrase({ passphraseFile: overrides?.passphraseFile })
   });
 }
+function resolveKeystorePath(overrides) {
+  return overrides?.keystore ?? activeProfileIdentity(overrides)?.keystore ?? defaultKeystorePath();
+}
+function activeProfileIdentity(overrides) {
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath());
+  const { name } = resolveActiveProfile(file, overrides);
+  return name ? file?.profiles?.[name]?.identity : void 0;
+}
+function resolveSigningKeyRef(overrides) {
+  return blankToUndef(overrides?.signingKey) ?? blankToUndef(activeProfileIdentity(overrides)?.default);
+}
 function keystoreApiFactory(network, overrides) {
   return (0, import_api.createApi)({
     ...resolveConnectionConfig(network, overrides),
@@ -857,6 +1167,31 @@ function resolveKeyRef(kms, ref) {
 }
 
 // src/output.ts
+var REDACTED = "********";
+var SECRET_KEY = /(pass|secret|token|auth|api[-_]?key|credential|bearer)/i;
+function isSecretKey(key) {
+  return SECRET_KEY.test(key);
+}
+function scrubUrlUserinfo(value) {
+  if (value === void 0) return void 0;
+  return value.replace(/^([a-z][a-z0-9+.-]*:\/\/[^/@:]+):[^/@]*@/i, `$1:${REDACTED}@`);
+}
+function redactSecrets(value, keyName) {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSecrets(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = redactSecrets(val, key);
+    }
+    return out;
+  }
+  if (keyName !== void 0 && isSecretKey(keyName)) {
+    return value === void 0 ? void 0 : REDACTED;
+  }
+  return typeof value === "string" ? scrubUrlUserinfo(value) : value;
+}
 function formatResult(result, options) {
   if (options.output === "json") {
     return JSON.stringify(result, null, 2);
@@ -885,6 +1220,13 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
     const overrides = overridesFromGlobals(g);
     const network = resolveNetwork(options.network, overrides);
     const signingKey = g.signingKey;
+    const mismatch = profileNetworkMismatch(network, overrides);
+    if (mismatch && !g.quiet) {
+      process.stderr.write(
+        `Warning: creating a "${network}" identifier while the active profile "${mismatch.profile}" declares network "${mismatch.declared}". The identifier's network and the profile's endpoints may not match.
+`
+      );
+    }
     const print = (result, note) => {
       console.log(formatResult(result, g));
       if (note && g.output !== "json") process.stderr.write(`${note}
@@ -1048,6 +1390,12 @@ function registerUpdateCommand(program, factory, globals) {
     "Publish update artifacts to a writable CAS before broadcast: auto|always|never. CAS publication is optional; the default distributes the returned artifacts via sidecar.",
     parsePublishToCasMode,
     "never"
+  ).option(
+    "--fee-rate <satsPerVByte>",
+    "Fee rate in sats/vByte for the beacon transaction (default: 5). Raise it under congestion so the transaction confirms."
+  ).option(
+    "--change-address <address>",
+    "Send transaction change to this address instead of the beacon address, so a DID's announcements are not linked on-chain (ADR 044)."
   ).action(async (options) => {
     if (!/^\d+$/.test(options.sourceVersionId)) {
       throw new CLIError(
@@ -1073,8 +1421,12 @@ function registerUpdateCommand(program, factory, globals) {
     }
     const network = deriveNetwork(did);
     const api = factory(network, globals());
-    const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+    const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
     const signer = new import_key_manager2.KeyManagerSigner(api.kms.kms, keyId);
+    const broadcastOptions = resolveBroadcastOptions(network, globals(), {
+      feeRate: options.feeRate,
+      changeAddress: options.changeAddress
+    });
     const data = await api.btcr2.update({
       sourceDocument: parsed.sourceDocument,
       patches: parsed.patches,
@@ -1082,7 +1434,8 @@ function registerUpdateCommand(program, factory, globals) {
       verificationMethodId: parsed.verificationMethodId,
       beaconId: parsed.beaconId,
       signer,
-      publishToCas: options.publishToCas
+      publishToCas: options.publishToCas,
+      ...broadcastOptions ? { broadcastOptions } : {}
     });
     console.log(formatResult({ action: "update", data }, globals()));
   });
@@ -1134,6 +1487,12 @@ function registerDeactivateCommand(program, factory, globals) {
     "Publish update artifacts to a writable CAS before broadcast: auto|always|never. CAS publication is optional; the default distributes the returned artifacts via sidecar.",
     parsePublishToCasMode2,
     "never"
+  ).option(
+    "--fee-rate <satsPerVByte>",
+    "Fee rate in sats/vByte for the beacon transaction (default: 5). Raise it under congestion so the transaction confirms."
+  ).option(
+    "--change-address <address>",
+    "Send transaction change to this address instead of the beacon address, so a DID's announcements are not linked on-chain (ADR 044)."
   ).action(async (options) => {
     if (!/^\d+$/.test(options.sourceVersionId)) {
       throw new CLIError(
@@ -1159,8 +1518,12 @@ function registerDeactivateCommand(program, factory, globals) {
     }
     const network = deriveNetwork(did);
     const api = factory(network, globals());
-    const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+    const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
     const signer = new import_key_manager3.KeyManagerSigner(api.kms.kms, keyId);
+    const broadcastOptions = resolveBroadcastOptions(network, globals(), {
+      feeRate: options.feeRate,
+      changeAddress: options.changeAddress
+    });
     const data = await api.btcr2.update({
       sourceDocument: parsed.sourceDocument,
       patches: parsed.patches,
@@ -1168,7 +1531,8 @@ function registerDeactivateCommand(program, factory, globals) {
       verificationMethodId: parsed.verificationMethodId,
       beaconId: parsed.beaconId,
       signer,
-      publishToCas: options.publishToCas
+      publishToCas: options.publishToCas,
+      ...broadcastOptions ? { broadcastOptions } : {}
     });
     console.log(formatResult({ action: "deactivate", data }, globals()));
   });
@@ -1324,6 +1688,128 @@ function writeSecretFile(path, contents) {
 // src/commands/config.ts
 var import_node_fs7 = require("fs");
 var import_node_path5 = require("path");
+
+// src/config-schema.ts
+var CONFIG_SCHEMA = {
+  schemaVersion: "number",
+  defaults: {
+    profile: "string",
+    network: "enum:network",
+    output: "enum:output"
+  },
+  profiles: {
+    "*": {
+      network: "enum:network",
+      btc: {
+        rest: "string",
+        rpcUrl: "string",
+        rpcUser: "string",
+        rpcPass: "string",
+        feeRate: "number",
+        changeAddress: "string",
+        timeoutMs: "number",
+        headers: "object",
+        wallet: "string",
+        rpcHeaders: "object"
+      },
+      cas: {
+        gateway: "string",
+        rpcUrl: "string",
+        timeoutMs: "number"
+      },
+      identity: {
+        keystore: "string",
+        default: "string"
+      }
+    }
+  }
+};
+function lookupSchemaNode(dotted) {
+  let node = CONFIG_SCHEMA;
+  for (const segment of dotted.split(".")) {
+    if (typeof node !== "object") return void 0;
+    if (Object.hasOwn(node, segment)) {
+      node = node[segment];
+    } else if (Object.hasOwn(node, "*")) {
+      node = node["*"];
+    } else {
+      return void 0;
+    }
+  }
+  return node;
+}
+function assertLeafValue(kind, dotted, value) {
+  if (kind === "enum:network" && !SUPPORTED_NETWORKS.includes(value)) {
+    throw new CLIError(
+      `Invalid value for ${dotted}: "${String(value)}". Expected one of ${SUPPORTED_NETWORKS.join(", ")}.`,
+      "INVALID_ARGUMENT_ERROR",
+      { path: dotted, value }
+    );
+  }
+  if (kind === "enum:output" && value !== "json" && value !== "text") {
+    throw new CLIError(
+      `Invalid value for ${dotted}: "${String(value)}". Expected "json" or "text".`,
+      "INVALID_ARGUMENT_ERROR",
+      { path: dotted, value }
+    );
+  }
+  if (kind === "number" && typeof value !== "number") {
+    throw new CLIError(
+      `Invalid value for ${dotted}: expected a number, got ${typeof value}. Pass a bare number (e.g. \`config set ` + dotted + " 5`).",
+      "INVALID_ARGUMENT_ERROR",
+      { path: dotted, value }
+    );
+  }
+  if (kind === "object" && (typeof value !== "object" || value === null || Array.isArray(value))) {
+    throw new CLIError(
+      `Invalid value for ${dotted}: expected a JSON object (e.g. \`config set ${dotted} '{"Key":"Value"}'\`).`,
+      "INVALID_ARGUMENT_ERROR",
+      { path: dotted, value }
+    );
+  }
+}
+function validateConfigSet(dotted, value) {
+  const node = lookupSchemaNode(dotted);
+  if (node === void 0) return { unknownPath: true };
+  if (typeof node === "string") {
+    assertLeafValue(node, dotted, value);
+  }
+  return { unknownPath: false };
+}
+function findConfigIssues(config, supportedSchemaVersion) {
+  const issues = [];
+  const version = config.schemaVersion;
+  if (typeof version === "number" && version > supportedSchemaVersion) {
+    issues.push({
+      path: "schemaVersion",
+      issue: `newer than supported (${version} > ${supportedSchemaVersion}); upgrade the CLI to use this file`
+    });
+  }
+  walk(config, [], issues);
+  return issues;
+}
+function walk(obj, prefix, issues) {
+  for (const [key, value] of Object.entries(obj)) {
+    const path = [...prefix, key];
+    const dotted = path.join(".");
+    const node = lookupSchemaNode(dotted);
+    if (node === void 0) {
+      issues.push({ path: dotted, issue: "unknown key" });
+      continue;
+    }
+    if (typeof node === "string") {
+      try {
+        assertLeafValue(node, dotted, value);
+      } catch (error) {
+        issues.push({ path: dotted, issue: error.message });
+      }
+    } else if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      walk(value, path, issues);
+    }
+  }
+}
+
+// src/commands/config.ts
 function registerConfigCommand(program, globals) {
   const config = program.command("config").description("Read and write CLI configuration.");
   const path = () => globals().config ?? defaultConfigPath();
@@ -1343,29 +1829,100 @@ function registerConfigCommand(program, globals) {
 `, 384);
     print({ action: "config-init", data: { path: p } });
   });
-  config.command("get [path]").description("Print a value at a dotted path, or the whole config.").action((dotted) => {
+  config.command("get [path]").description("Print a value at a dotted path, or the whole config.").option("--show-secrets", "Reveal secret values (RPC password, etc.) instead of redacting them.", false).action((dotted, opts) => {
     const file = readConfigFile(path()) ?? {};
-    print({ action: "config-get", data: (dotted ? getConfigPath(file, dotted) : file) ?? null });
+    const raw = (dotted ? getConfigPath(file, dotted) : file) ?? null;
+    const leaf = dotted ? dotted.split(".").pop() : void 0;
+    print({ action: "config-get", data: opts.showSecrets ? raw : redactSecrets(raw, leaf) });
   });
   config.command("set <path> <value>").description("Set a value at a dotted path. The value is parsed as JSON when valid, else stored as a string.").action((dotted, value) => {
-    writeConfigFile(path(), (raw) => setConfigPath(raw, dotted, parseValue(value)));
+    const parsed = parseValue(dotted, value);
+    const { unknownPath } = validateConfigSet(dotted, parsed);
+    if (unknownPath && !globals().quiet) {
+      console.error(`Warning: "${dotted}" is not a known config path; writing it anyway.`);
+    }
+    writeConfigFile(path(), (raw) => setConfigPath(raw, dotted, parsed));
     print({ action: "config-set", data: { path: dotted } });
   });
   config.command("unset <path>").description("Delete a value at a dotted path.").action((dotted) => {
     writeConfigFile(path(), (raw) => unsetConfigPath(raw, dotted));
     print({ action: "config-unset", data: { path: dotted } });
   });
-  config.command("list").alias("ls").description("Print the entire config file.").action(() => {
-    print({ action: "config-list", data: readConfigFile(path()) ?? {} });
+  config.command("list").alias("ls").description("Print the entire config file.").option("--show-secrets", "Reveal secret values (RPC password, etc.) instead of redacting them.", false).action((opts) => {
+    const file = readConfigFile(path()) ?? {};
+    print({ action: "config-list", data: opts.showSecrets ? file : redactSecrets(file) });
+  });
+  config.command("validate").description("Check the config for unknown keys, invalid enum values, and an unsupported schema version.").action(() => {
+    const file = parseConfigFileRaw(path()) ?? {};
+    const issues = findConfigIssues(file, CONFIG_SCHEMA_VERSION);
+    if (issues.length > 0) process.exitCode ??= 1;
+    print({ action: "config-validate", data: { ok: issues.length === 0, issues } });
+  });
+  config.command("effective").description("Print the resolved connection config with per-value provenance (flag|env|file|default).").option("-n, --network <network>", "Network to resolve for (default: config default network)").option("--show-secrets", "Reveal secret values (RPC password) instead of redacting them.", false).action((opts) => {
+    const network = resolveIntrospectionNetwork(opts.network, globals());
+    const data = resolveEffectiveConfig(network, globals());
+    if (!opts.showSecrets) {
+      if (data.btc.rpcPass.value !== void 0) {
+        data.btc.rpcPass = { ...data.btc.rpcPass, value: REDACTED };
+      }
+      for (const entry of [data.btc.rest, data.btc.rpcUrl, data.cas.gateway, data.cas.rpcUrl]) {
+        if (typeof entry.value === "string") entry.value = scrubUrlUserinfo(entry.value);
+      }
+    }
+    print({ action: "config-effective", data });
+  });
+  config.command("path").description("Print the resolved config-file and keystore paths.").action(() => {
+    const data = {
+      config: globals().config ?? defaultConfigPath(),
+      keystore: globals().keystore ?? defaultKeystorePath()
+    };
+    print({ action: "config-path", data });
+  });
+  config.command("doctor").description("Probe reachability of the resolved endpoints (read-only; touches the network).").option("-n, --network <network>", "Network to resolve for (default: config default network)").action(async (opts) => {
+    const network = resolveIntrospectionNetwork(opts.network, globals());
+    const report = await runDoctor(network, globals());
+    if (report.checks.some((check) => !check.ok)) process.exitCode ??= 1;
+    print({ action: "config-doctor", data: report });
   });
 }
-function parseValue(value) {
+function resolveIntrospectionNetwork(explicit, globals) {
+  if (explicit) {
+    if (!SUPPORTED_NETWORKS.includes(explicit)) {
+      throw new CLIError(
+        `Invalid network "${explicit}". Must be one of ${SUPPORTED_NETWORKS.join(", ")}.`,
+        "INVALID_ARGUMENT_ERROR",
+        { network: explicit }
+      );
+    }
+    return explicit;
+  }
+  return resolveDefaultNetwork(globals);
+}
+function parseValue(dotted, value) {
+  if (isStringScalarPath(dotted)) return value;
   try {
     return JSON.parse(value);
   } catch {
     return value;
   }
 }
+function isStringScalarPath(dotted) {
+  const segments = dotted.split(".");
+  if (segments.length === 2 && segments[0] === "defaults") {
+    return ["profile", "network", "output"].includes(segments[1]);
+  }
+  if (segments.length === 3 && segments[0] === "profiles" && segments[2] === "network") {
+    return true;
+  }
+  if (segments.length === 4 && segments[0] === "profiles") {
+    const group = segments[2];
+    const leaf = segments[3];
+    if (group === "btc") return ["rest", "rpcUrl", "rpcUser", "rpcPass", "changeAddress", "wallet"].includes(leaf);
+    if (group === "cas") return ["gateway", "rpcUrl"].includes(leaf);
+    if (group === "identity") return ["keystore", "default"].includes(leaf);
+  }
+  return false;
+}
 
 // src/commands/profile.ts
 function registerProfileCommand(program, globals) {
@@ -1388,7 +1945,7 @@ function registerProfileCommand(program, globals) {
     });
     print({ action: "profile-use", data: { profile: name } });
   });
-  profile.command("show [name]").description("Show a profile (defaults to the active profile).").action((name) => {
+  profile.command("show [name]").description("Show a profile (defaults to the active profile).").option("--show-secrets", "Reveal secret values (RPC password, etc.) instead of redacting them.", false).action((name, opts) => {
     const file = readConfigFile(path()) ?? {};
     const target = name ?? file.defaults?.profile;
     if (!target) {
@@ -1398,7 +1955,8 @@ function registerProfileCommand(program, globals) {
     if (!data) {
       throw new CLIError(`Profile "${target}" not found.`, "INVALID_ARGUMENT_ERROR", { profile: target });
     }
-    print({ action: "profile-show", data: { profile: target, ...data } });
+    const payload = { profile: target, ...data };
+    print({ action: "profile-show", data: opts.showSecrets ? payload : redactSecrets(payload) });
   });
   profile.command("remove <name>").alias("rm").description("Remove a profile.").action((name) => {
     writeConfigFile(path(), (raw) => {
@@ -1477,8 +2035,12 @@ var DidBtcr2Cli = class {
    *   {@link keystoreApiFactory}.
    */
   constructor(factory = defaultApiFactory, keystoreFactory = keystoreApiFactory) {
-    this.program = new import_commander.Command("btcr2").version(`btcr2 ${VERSION}`, "-v, --version", "Output the current version").description("CLI tool for the did:btcr2 method").option("-o, --output <format>", "Output format <json|text>", "text").option("--verbose", "Verbose output", false).option("--quiet", "Suppress non-essential output", false).option("-c, --config <path>", "Path to config file (default: $XDG_CONFIG_HOME/btcr2/config.json)").option("--profile <name>", "Config profile name (default: auto-detected from network)").option("--btc-rest <url>", "Override Bitcoin REST endpoint (Esplora API)").option("--btc-rpc-url <url>", "Override Bitcoin Core RPC endpoint").option("--btc-rpc-user <user>", "Bitcoin Core RPC username").option("--btc-rpc-pass <pass>", "Bitcoin Core RPC password").option("--cas-gateway <url>", "IPFS HTTP gateway for CAS reads (read-only)").option("--cas-rpc-url <url>", "IPFS HTTP RPC endpoint for a writable CAS (reads + writes; enables --publish-to-cas)").option("--keystore <path>", "Path to the keystore file (default: $XDG_DATA_HOME/btcr2/keystore.json)").option("--passphrase-file <path>", "Read the keystore passphrase from a file (unattended use)").option("--signing-key <ref>", "Key for create/update/deactivate signing: a URN, fingerprint prefix, or name");
+    this.program = new import_commander.Command("btcr2").version(`btcr2 ${VERSION}`, "-v, --version", "Output the current version").description("CLI tool for the did:btcr2 method").option("-o, --output <format>", "Output format <json|text> (default: config defaults.output, else text)").option("--verbose", "Verbose output", false).option("--quiet", "Suppress non-essential output", false).option("-c, --config <path>", "Path to config file (default: $XDG_CONFIG_HOME/btcr2/config.json)").option("--profile <name>", "Config profile name (default: auto-detected from network)").option("--btc-rest <url>", "Override Bitcoin REST endpoint (Esplora API)").option("--btc-rpc-url <url>", "Override Bitcoin Core RPC endpoint").option("--btc-rpc-user <user>", "Bitcoin Core RPC username").option("--btc-rpc-pass <pass>", "Bitcoin Core RPC password").option("--cas-gateway <url>", "IPFS HTTP gateway for CAS reads (read-only)").option("--cas-rpc-url <url>", "IPFS HTTP RPC endpoint for a writable CAS (reads + writes; enables --publish-to-cas)").option("--btc-timeout <ms>", "Bitcoin REST/RPC request timeout in milliseconds (default: unbounded)").option("--cas-timeout <ms>", "CAS request timeout in milliseconds (default: 30000; 0 disables)").option("--btc-rest-header <header>", 'Extra Bitcoin REST header "Key: Value" (repeatable)', collectHeader, []).option("--btc-rpc-wallet <name>", "Bitcoin Core wallet name for wallet-scoped RPCs").option("--btc-rpc-header <header>", 'Extra Bitcoin Core RPC header "Key: Value" (repeatable)', collectHeader, []).option("--keystore <path>", "Path to the keystore file (default: $XDG_DATA_HOME/btcr2/keystore.json)").option("--passphrase-file <path>", "Read the keystore passphrase from a file (unattended use)").option("--signing-key <ref>", "Key for create/update/deactivate signing: a URN, fingerprint prefix, or name");
     const globals = () => this.program.opts();
+    this.program.hook("preAction", () => {
+      const opts = this.program.opts();
+      opts.output = resolveOutputFormat({ output: opts.output, config: opts.config });
+    });
     registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
     registerUpdateCommand(this.program, keystoreFactory, globals);
@@ -1503,6 +2065,9 @@ var DidBtcr2Cli = class {
     }
   }
 };
+function collectHeader(value, previous) {
+  return [...previous, value];
+}
 function normalizeArgv(argv) {
   if (argv.length >= 2) return argv;
   if (argv.length === 1) return ["node", argv[0]];
@@ -1525,18 +2090,26 @@ function handleError(error, verbose) {
   CLIError,
   CONFIG_SCHEMA_VERSION,
   DidBtcr2Cli,
+  ENV_RPC_PASS_FILE,
   ENV_VARS,
+  REDACTED,
   SUPPORTED_NETWORKS,
   VERSION,
+  blankToUndef,
   defaultApiFactory,
   defaultConfigPath,
   deriveNetwork,
   formatResult,
   getConfigPath,
+  isSecretKey,
   keystoreApiFactory,
+  parseConfigFileRaw,
+  parseHeaderList,
+  profileNetworkMismatch,
   profileToOverrides,
   readConfigFile,
   readEnvOverrides,
+  redactSecrets,
   registerCompletionCommand,
   registerConfigCommand,
   registerCreateCommand,
@@ -1545,7 +2118,17 @@ function handleError(error, verbose) {
   registerProfileCommand,
   registerResolveCommand,
   registerUpdateCommand,
+  resolveActiveProfile,
+  resolveBroadcastOptions,
+  resolveConnectionConfig,
   resolveDefaultNetwork,
+  resolveEffectiveConfig,
+  resolveKeystorePath,
+  resolveOutputFormat,
+  resolveSecretRef,
+  resolveSigningKeyRef,
+  runDoctor,
+  scrubUrlUserinfo,
   setConfigPath,
   unsetConfigPath,
   writeConfigFile