@did-btcr2/cli 0.14.0 → 0.16.0

package/dist/cjs/index.js

@@ -23,30 +23,53 @@ __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,
+  assertKeystoreAllowedForNetwork: () => assertKeystoreAllowedForNetwork,
+  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,
   registerDeactivateCommand: () => registerDeactivateCommand,
+  registerInitCommand: () => registerInitCommand,
   registerKeyCommand: () => registerKeyCommand,
+  registerKeystoreCommand: () => registerKeystoreCommand,
   registerProfileCommand: () => registerProfileCommand,
   registerResolveCommand: () => registerResolveCommand,
   registerUpdateCommand: () => registerUpdateCommand,
+  resolveActiveProfile: () => resolveActiveProfile,
+  resolveBroadcastOptions: () => resolveBroadcastOptions,
+  resolveConnectionConfig: () => resolveConnectionConfig,
   resolveDefaultNetwork: () => resolveDefaultNetwork,
+  resolveEffectiveConfig: () => resolveEffectiveConfig,
+  resolveKeystorePath: () => resolveKeystorePath,
+  resolveKeystoreProtection: () => resolveKeystoreProtection,
+  resolveOutputFormat: () => resolveOutputFormat,
+  resolveSecretRef: () => resolveSecretRef,
+  resolveSigningKeyRef: () => resolveSigningKeyRef,
+  runDoctor: () => runDoctor,
+  scrubUrlUserinfo: () => scrubUrlUserinfo,
   setConfigPath: () => setConfigPath,
   unsetConfigPath: () => unsetConfigPath,
-  writeConfigFile: () => writeConfigFile
+  writeConfigFile: () => writeConfigFile,
+  writeDefaultConfigFile: () => writeDefaultConfigFile
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -58,13 +81,13 @@ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 var import_common3 = require("@did-btcr2/common");
 var import_commander = require("commander");
 
-// src/commands/create.ts
-var import_utils2 = require("@noble/hashes/utils.js");
+// src/commands/init.ts
+var import_node_fs6 = require("fs");
 
 // 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");
 
 // src/error.ts
@@ -144,6 +167,7 @@ var import_key_manager = require("@did-btcr2/key-manager");
 // src/keystore/file-key-store.ts
 var import_node_fs3 = require("fs");
 var import_node_path3 = require("path");
+var import_utils2 = require("@noble/hashes/utils.js");
 var import_base2 = require("@scure/base");
 
 // src/keystore/envelope.ts
@@ -314,16 +338,57 @@ function withFileLock(lockPath, fn, options = {}) {
   }
 }
 
-// src/keystore/paths.ts
+// src/paths.ts
 var import_node_os = require("os");
 var import_node_path2 = require("path");
-function defaultKeystorePath() {
-  const base = process.env.XDG_DATA_HOME ?? 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");
+
+// 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/paths.ts
+var ENV_HOME = "BTCR2_HOME";
+var CONFIG_FILENAME = "config.json";
+var KEYSTORE_FILENAME = "keystore.json";
+function resolveHome(overrides) {
+  return blankToUndef(overrides?.home) ?? blankToUndef(process.env[ENV_HOME]) ?? platformDefaultHome();
+}
+function platformDefaultHome() {
+  if (process.platform === "win32") {
+    const base = blankToUndef(process.env.LOCALAPPDATA) ?? blankToUndef(process.env.APPDATA) ?? (0, import_node_os.homedir)();
+    return (0, import_node_path2.join)(base, "btcr2");
+  }
+  return (0, import_node_path2.join)((0, import_node_os.homedir)(), ".btcr2");
+}
+function defaultConfigPath(overrides) {
+  return (0, import_node_path2.join)(resolveHome(overrides), CONFIG_FILENAME);
+}
+function defaultKeystorePath(overrides) {
+  return (0, import_node_path2.join)(resolveHome(overrides), KEYSTORE_FILENAME);
 }
 
 // src/keystore/file-key-store.ts
 var KEYSTORE_VERSION = 1;
+var VERIFIER_PLAINTEXT = (0, import_utils2.utf8ToBytes)("did-btcr2-keystore-verifier-v1");
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+function sameEnvelope(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
 var FileKeyStore = class {
   #path;
   #lockPath;
@@ -332,12 +397,15 @@ var FileKeyStore = class {
   #argonParams;
   #cache = /* @__PURE__ */ new Map();
   #active;
+  #protection;
+  #verifier;
   constructor(options) {
     this.#path = options.path ?? defaultKeystorePath();
     this.#lockPath = `${this.#path}.lock`;
     this.#lockOptions = options.lock ?? {};
     this.#getPassphrase = options.getPassphrase;
     this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
+    this.#protection = options.protection ?? "passphrase";
     ensureDir((0, import_node_path3.dirname)(this.#path), 448);
     this.#loadFromDisk();
   }
@@ -361,7 +429,26 @@ var FileKeyStore = class {
         { version: parsed.v }
       );
     }
+    if (parsed.protection !== "none" && parsed.protection !== "passphrase") {
+      throw new KeyStoreError(
+        `Keystore at ${this.#path} has no recognized protection header; it was not written by this CLI.`,
+        "KEYSTORE_CORRUPT_ERROR",
+        { path: this.#path }
+      );
+    }
+    this.#protection = parsed.protection;
+    this.#verifier = parsed.verifier;
     this.#active = parsed.active;
+    const sealedPresent = Object.values(parsed.keys ?? {}).some(
+      (k) => k && typeof k === "object" && k.secret !== void 0
+    );
+    if (this.#protection === "passphrase" && sealedPresent && this.#verifier === void 0) {
+      throw new KeyStoreError(
+        `Keystore at ${this.#path} holds sealed keys but no passphrase verifier; it is corrupt or was tampered with.`,
+        "KEYSTORE_CORRUPT_ERROR",
+        { path: this.#path }
+      );
+    }
     for (const [id, stored] of Object.entries(parsed.keys ?? {})) {
       let publicKey;
       try {
@@ -381,24 +468,67 @@ var FileKeyStore = class {
           { path: this.#path, keyId: id }
         );
       }
-      this.#cache.set(id, {
-        publicKey,
-        ...stored.tags && { tags: stored.tags },
-        ...stored.secret && { secret: stored.secret }
-      });
+      const entry = { publicKey, ...stored.tags && { tags: stored.tags } };
+      if (stored.plainSecret !== void 0) {
+        if (this.#protection !== "none") {
+          throw new KeyStoreError(
+            `Keystore entry ${id} holds a plaintext secret in an encrypted keystore at ${this.#path}.`,
+            "KEYSTORE_CORRUPT_ERROR",
+            { path: this.#path, keyId: id }
+          );
+        }
+        entry.plaintext = true;
+        entry.decrypted = this.#decodePlainSecret(stored.plainSecret, id);
+      } else if (stored.secret) {
+        if (this.#protection !== "passphrase") {
+          throw new KeyStoreError(
+            `Keystore entry ${id} holds a sealed secret in a dev keystore at ${this.#path}.`,
+            "KEYSTORE_CORRUPT_ERROR",
+            { path: this.#path, keyId: id }
+          );
+        }
+        entry.secret = stored.secret;
+      }
+      this.#cache.set(id, entry);
+    }
+  }
+  /** Decodes and length-checks a dev-keystore plaintext secret. */
+  #decodePlainSecret(encoded, id) {
+    let secret;
+    try {
+      secret = import_base2.base64urlnopad.decode(encoded);
+    } catch {
+      throw new KeyStoreError(
+        `Keystore entry ${id} has a malformed plaintext secret.`,
+        "KEYSTORE_CORRUPT_ERROR",
+        { path: this.#path, keyId: id }
+      );
+    }
+    if (secret.length !== 32) {
+      throw new KeyStoreError(
+        `Keystore entry ${id} has a ${secret.length}-byte secret; expected 32.`,
+        "KEYSTORE_CORRUPT_ERROR",
+        { path: this.#path, keyId: id }
+      );
     }
+    return secret;
   }
   #flush() {
     const keys = {};
     for (const [id, entry] of this.#cache) {
-      keys[id] = {
-        publicKey: import_base2.base64urlnopad.encode(entry.publicKey),
-        ...entry.tags && { tags: entry.tags },
-        ...entry.secret && { secret: entry.secret }
-      };
+      const stored = { publicKey: import_base2.base64urlnopad.encode(entry.publicKey) };
+      if (entry.tags) stored.tags = entry.tags;
+      if (entry.plaintext && entry.decrypted) {
+        stored.plainSecret = import_base2.base64urlnopad.encode(entry.decrypted);
+      } else if (entry.secret) {
+        stored.secret = entry.secret;
+      }
+      keys[id] = stored;
     }
     const file = {
       v: KEYSTORE_VERSION,
+      protection: this.#protection,
+      ...this.#verifier && { verifier: this.#verifier },
       ...this.#active && { active: this.#active },
       keys
     };
@@ -410,7 +540,8 @@ var FileKeyStore = class {
    * mutation applies on top of whatever other processes have written. Secrets
    * already decrypted this session are carried over for entries whose sealed
    * envelope is byte-identical on disk, so a mid-session write does not force a
-   * re-prompt for keys it did not touch.
+   * re-prompt for keys it did not touch. (Dev-keystore plaintext secrets are
+   * reloaded from disk, so they need no carry.)
    */
   #reload() {
     const carried = /* @__PURE__ */ new Map();
@@ -441,6 +572,53 @@ var FileKeyStore = class {
       this.#flush();
     }, this.#lockOptions);
   }
+  /**
+   * Verifies a candidate passphrase against the keystore verifier, throwing when
+   * it does not open the sentinel. A no-op only on a fresh keystore whose
+   * passphrase has not been established yet (no verifier to check against).
+   */
+  #assertPassphrase(passphrase) {
+    if (!this.#verifier) return;
+    let plain;
+    try {
+      plain = decryptSecret(this.#verifier, passphrase);
+    } catch {
+      throw new KeyStoreError(
+        `Incorrect passphrase for the keystore at ${this.#path}.`,
+        "DECRYPT_ERROR",
+        { path: this.#path }
+      );
+    }
+    if (!bytesEqual(plain, VERIFIER_PLAINTEXT)) {
+      throw new KeyStoreError(
+        `Keystore verifier at ${this.#path} did not match; the file may be corrupt.`,
+        "KEYSTORE_CORRUPT_ERROR",
+        { path: this.#path }
+      );
+    }
+  }
+  /** Passphrase for opening an existing secret: verified when a verifier exists. */
+  #openPassphrase() {
+    const passphrase = this.#getPassphrase();
+    this.#assertPassphrase(passphrase);
+    return passphrase;
+  }
+  /**
+   * Passphrase for sealing a secret. When the keystore's passphrase is already
+   * established (a verifier exists), prompt once and verify it. Otherwise this is
+   * establishment on a fresh keystore: prompt with confirm and mint a verifier for
+   * the caller to persist alongside the first sealed key.
+   */
+  #sealPassphrase() {
+    if (this.#verifier) {
+      const passphrase2 = this.#getPassphrase();
+      this.#assertPassphrase(passphrase2);
+      return { passphrase: passphrase2 };
+    }
+    const passphrase = this.#getPassphrase({ confirm: true });
+    const newVerifier = encryptSecret(VERIFIER_PLAINTEXT, passphrase, this.#argonParams);
+    return { passphrase, newVerifier };
+  }
   get(id) {
     const entry = this.#cache.get(id);
     if (!entry) return void 0;
@@ -448,13 +626,20 @@ var FileKeyStore = class {
       publicKey: entry.publicKey,
       ...entry.tags && { tags: entry.tags }
     };
-    if (entry.secret) {
+    if (entry.plaintext && entry.decrypted) {
+      const secret = entry.decrypted;
+      Object.defineProperty(result, "secretKey", {
+        configurable: true,
+        enumerable: false,
+        get: () => secret
+      });
+    } else if (entry.secret) {
       const sealed = entry.secret;
       Object.defineProperty(result, "secretKey", {
         configurable: true,
         enumerable: false,
         get: () => {
-          entry.decrypted ??= decryptSecret(sealed, this.#getPassphrase());
+          entry.decrypted ??= decryptSecret(sealed, this.#openPassphrase());
           return entry.decrypted;
         }
       });
@@ -465,12 +650,45 @@ var FileKeyStore = class {
     return this.#cache.has(id);
   }
   set(id, value) {
-    const secret = value.secretKey ? encryptSecret(value.secretKey, this.#getPassphrase(), this.#argonParams) : void 0;
+    if (this.#protection === "none") {
+      this.#mutate(() => {
+        this.#cache.set(id, {
+          publicKey: value.publicKey,
+          ...value.tags && { tags: value.tags },
+          ...value.secretKey && { plaintext: true, decrypted: value.secretKey }
+        });
+      });
+      return;
+    }
+    const verifierAtSeal = this.#verifier;
+    let sealed;
+    let newVerifier;
+    let passphrase;
+    if (value.secretKey) {
+      const resolved = this.#sealPassphrase();
+      passphrase = resolved.passphrase;
+      newVerifier = resolved.newVerifier;
+      sealed = encryptSecret(value.secretKey, passphrase, this.#argonParams);
+    }
     this.#mutate(() => {
+      if (value.secretKey) {
+        if (this.#verifier === void 0 && newVerifier !== void 0) {
+          this.#verifier = newVerifier;
+        } else if (this.#verifier !== void 0 && passphrase !== void 0) {
+          if (verifierAtSeal !== void 0 && !sameEnvelope(this.#verifier, verifierAtSeal)) {
+            throw new KeyStoreError(
+              `The keystore passphrase at ${this.#path} changed concurrently; re-run the command.`,
+              "KEYSTORE_CONCURRENT_CHANGE_ERROR",
+              { path: this.#path }
+            );
+          }
+          this.#assertPassphrase(passphrase);
+        }
+      }
       this.#cache.set(id, {
         publicKey: value.publicKey,
         ...value.tags && { tags: value.tags },
-        ...secret && { secret },
+        ...sealed && { secret: sealed },
         ...value.secretKey && { decrypted: value.secretKey }
       });
     });
@@ -533,7 +751,112 @@ var FileKeyStore = class {
       this.#active = id;
     });
   }
+  /** The keystore's protection mode. */
+  get protection() {
+    return this.#protection;
+  }
+  /**
+   * Re-seals every sealed secret and the verifier under a new passphrase (ADR
+   * 080), returning the number of secrets re-sealed. Verifies the current
+   * passphrase against the verifier first. Refused on a dev keystore, which has
+   * no passphrase.
+   */
+  changePassphrase(oldPassphrase, newPassphrase) {
+    if (this.#protection === "none") {
+      throw new KeyStoreError(
+        `The keystore at ${this.#path} is an unencrypted dev keystore; it has no passphrase to change.`,
+        "KEYSTORE_PROTECTION_ERROR",
+        { path: this.#path }
+      );
+    }
+    if (this.#verifier) this.#assertPassphrase(oldPassphrase);
+    const resealed = /* @__PURE__ */ new Map();
+    for (const [id, entry] of this.#cache) {
+      if (!entry.secret) continue;
+      let plain;
+      try {
+        plain = decryptSecret(entry.secret, oldPassphrase);
+      } catch {
+        throw new KeyStoreError(
+          `Incorrect current passphrase for the keystore at ${this.#path}.`,
+          "DECRYPT_ERROR",
+          { path: this.#path }
+        );
+      }
+      resealed.set(id, { from: entry.secret, to: encryptSecret(plain, newPassphrase, this.#argonParams), plain });
+    }
+    const newVerifier = encryptSecret(VERIFIER_PLAINTEXT, newPassphrase, this.#argonParams);
+    let rekeyed = 0;
+    this.#mutate(() => {
+      for (const [id, entry] of this.#cache) {
+        if (!entry.secret) continue;
+        const pre = resealed.get(id);
+        if (!pre || !sameEnvelope(pre.from, entry.secret)) {
+          throw new KeyStoreError(
+            `The keystore at ${this.#path} changed while its passphrase was being changed; re-run the command.`,
+            "KEYSTORE_CONCURRENT_CHANGE_ERROR",
+            { path: this.#path }
+          );
+        }
+        entry.secret = pre.to;
+        entry.decrypted = pre.plain;
+        rekeyed++;
+      }
+      this.#verifier = newVerifier;
+    });
+    return rekeyed;
+  }
 };
+function keystoreSummary(path) {
+  const absent = { protection: "absent", established: false, keyCount: 0, active: void 0 };
+  if (!(0, import_node_fs3.existsSync)(path)) return absent;
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs3.readFileSync)(path, "utf-8"));
+  } catch {
+    return absent;
+  }
+  const keys = parsed.keys && typeof parsed.keys === "object" ? parsed.keys : {};
+  const keyCount = Object.keys(keys).length;
+  const active = typeof parsed.active === "string" ? parsed.active : void 0;
+  if (parsed.protection === "none") {
+    return { protection: "dev", established: true, keyCount, active };
+  }
+  if (parsed.protection === "passphrase") {
+    return { protection: "encrypted", established: parsed.verifier !== void 0, keyCount, active };
+  }
+  return absent;
+}
+function keystoreProtection(path) {
+  return keystoreSummary(path).protection;
+}
+function initKeystore(path, options) {
+  ensureDir((0, import_node_path3.dirname)(path), 448);
+  let file;
+  if (options.protection === "none") {
+    file = { v: KEYSTORE_VERSION, protection: "none", keys: {} };
+  } else {
+    const passphrase = options.getPassphrase({ confirm: true });
+    const verifier = encryptSecret(VERIFIER_PLAINTEXT, passphrase, options.argonParams ?? DEFAULT_ARGON_PARAMS);
+    file = { v: KEYSTORE_VERSION, protection: "passphrase", verifier, keys: {} };
+  }
+  writeFileAtomic(path, `${JSON.stringify(file, null, 2)}
+`, 384);
+}
+function changeKeystorePassphrase(path, oldPassphrase, newPassphrase, argonParams) {
+  const store = new FileKeyStore({
+    path,
+    ...argonParams && { argonParams },
+    getPassphrase: () => {
+      throw new KeyStoreError(
+        `Unexpected passphrase prompt while changing the passphrase for ${path}.`,
+        "KEYSTORE_INTERNAL_ERROR",
+        { path }
+      );
+    }
+  });
+  return store.changePassphrase(oldPassphrase, newPassphrase);
+}
 
 // src/keystore/file-backed-key-manager.ts
 var FileBackedKeyManager = class {
@@ -594,10 +917,12 @@ var FileBackedKeyManager = class {
 var import_node_fs4 = require("fs");
 var ENV_KEYSTORE_PASSPHRASE = "BTCR2_KEYSTORE_PASSPHRASE";
 function acquirePassphrase(options = {}) {
-  const fromEnv = process.env[ENV_KEYSTORE_PASSPHRASE];
-  if (fromEnv) return assertNonEmpty(fromEnv.replace(/\r?\n$/, ""));
-  if (options.passphraseFile) {
-    return assertNonEmpty((0, import_node_fs4.readFileSync)(options.passphraseFile, "utf-8").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((0, import_node_fs4.readFileSync)(options.passphraseFile, "utf-8").replace(/\r?\n$/, ""));
+    }
   }
   if (!process.stdin.isTTY) {
     throw new KeyStoreError(
@@ -620,6 +945,12 @@ function assertNonEmpty(passphrase) {
   }
   return passphrase;
 }
+var IDLE_WAIT = new Int32Array(new SharedArrayBuffer(4));
+var IDLE_POLL_MS = 20;
+function dropLastUtf8Char(bytes) {
+  while (bytes.length > 0 && (bytes[bytes.length - 1] & 192) === 128) bytes.pop();
+  bytes.pop();
+}
 function promptHidden(label) {
   process.stderr.write(label);
   const stdin = process.stdin;
@@ -634,7 +965,10 @@ function promptHidden(label) {
         read = (0, import_node_fs4.readSync)(stdin.fd, byte, 0, 1, null);
       } catch (error) {
         const code = error.code;
-        if (code === "EAGAIN") continue;
+        if (code === "EAGAIN") {
+          Atomics.wait(IDLE_WAIT, 0, 0, IDLE_POLL_MS);
+          continue;
+        }
         if (code === "EOF") break;
         throw error;
       }
@@ -645,7 +979,7 @@ function promptHidden(label) {
         throw new KeyStoreError("Passphrase entry aborted.", "PASSPHRASE_REQUIRED_ERROR");
       }
       if (ch === 127 || ch === 8) {
-        bytes.pop();
+        dropLastUtf8Char(bytes);
         continue;
       }
       bytes.push(ch);
@@ -657,16 +991,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) {
@@ -677,14 +1001,31 @@ function writeConfigFile(path, mutate) {
   writeFileAtomic(path, `${JSON.stringify(raw, null, 2)}
 `, 384);
 }
+function writeDefaultConfigFile(path) {
+  const scaffold = {
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    defaults: { output: "text" },
+    profiles: Object.fromEntries(SUPPORTED_NETWORKS.map((n) => [n, {}]))
+  };
+  ensureDir((0, import_node_path4.dirname)(path), 448);
+  writeFileAtomic(path, `${JSON.stringify(scaffold, null, 2)}
+`, 384);
+}
 function getConfigPath(config, path) {
   return path.split(".").reduce(
     (node, key) => node?.[key],
     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 +1037,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 +1053,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;
@@ -724,16 +1069,42 @@ function readEnvOverrides() {
     casRpcUrl: env(ENV_VARS.CAS_RPC_URL)
   };
 }
-function defaultConfigPath() {
-  const base = process.env.XDG_CONFIG_HOME ?? 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 +1119,326 @@ 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 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";
 }
+function profileNetworkMismatch(network, overrides) {
+  let file;
+  try {
+    file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
+  } 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(options))?.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 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) : {};
   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(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) : 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(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) !== 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(),
-    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 })
   });
 }
+function resolveKeystoreProtection(overrides) {
+  return keystoreProtection(resolveKeystorePath(overrides));
+}
+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 }
+  );
+}
+function resolveKeystorePath(overrides, options) {
+  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);
+}
+function activeProfileIdentity(overrides) {
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
+  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),
@@ -818,6 +1457,85 @@ function deriveNetwork(did) {
   return network;
 }
 
+// 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);
+  }
+  const { data } = result;
+  return typeof data === "string" ? data : JSON.stringify(data, null, 2);
+}
+
+// src/commands/init.ts
+function registerInitCommand(program, globals) {
+  const print = (result) => console.log(formatResult(result, globals()));
+  program.command("init").description("Set up the btcr2 home: create the directory, a default config, and establish the keystore.").option("--dev", "Establish an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only.", false).option("--force", "Re-create the config and keystore even if they already exist.", false).action((options) => {
+    const g = globals();
+    const home = resolveHome(g);
+    const configPath = g.config ?? defaultConfigPath(g);
+    const keystorePath = resolveKeystorePath(g);
+    ensureDir(home, 448);
+    const created = [];
+    if (!(0, import_node_fs6.existsSync)(configPath) || options.force) {
+      writeDefaultConfigFile(configPath);
+      created.push("config");
+    }
+    const keystoreExists = (0, import_node_fs6.existsSync)(keystorePath);
+    if (keystoreExists && options.force && !g.quiet) {
+      process.stderr.write(
+        `note: a keystore already exists at ${keystorePath} and was left intact. To re-establish it (discarding its keys), run "btcr2 keystore init --force".
+`
+      );
+    }
+    if (!keystoreExists) {
+      if (options.dev && !g.quiet) {
+        process.stderr.write(
+          "warning: establishing an UNENCRYPTED dev keystore. Keys are stored in plaintext. Use it only for disposable testnet material; mainnet operations will be refused.\n"
+        );
+      }
+      initKeystore(keystorePath, {
+        protection: options.dev ? "none" : "passphrase",
+        getPassphrase: (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: "New keystore passphrase: " })
+      });
+      created.push("keystore");
+    }
+    const protection = keystoreSummary(keystorePath).protection;
+    print({ action: "init", data: { home, config: configPath, keystore: keystorePath, created, protection } });
+    if (!g.quiet && g.output !== "json") {
+      process.stderr.write(`btcr2 home ready at ${home}. Next: btcr2 key generate --set-active
+`);
+    }
+  });
+}
+
+// src/commands/create.ts
+var import_utils3 = require("@noble/hashes/utils.js");
+
 // src/keystore/resolve-key-ref.ts
 function fingerprintOf(id) {
   return /^urn:kms:secp256k1:([0-9a-f]{32})$/.exec(id)?.[1];
@@ -856,15 +1574,6 @@ function resolveKeyRef(kms, ref) {
   throw new CLIError(`No key matches reference "${ref}".`, "KEY_NOT_FOUND_ERROR", { ref });
 }
 
-// src/output.ts
-function formatResult(result, options) {
-  if (options.output === "json") {
-    return JSON.stringify(result, null, 2);
-  }
-  const { data } = result;
-  return typeof data === "string" ? data : JSON.stringify(data, null, 2);
-}
-
 // src/commands/create.ts
 var EXPECTED_BYTES = {
   k: { length: 33, label: "secp256k1 compressed public key (33 bytes)" },
@@ -885,6 +1594,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}
@@ -926,14 +1642,15 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
       const publicKey2 = api2.kms.getPublicKey(keyId2);
       const did2 = api2.createDid("deterministic", publicKey2, { network });
       print(
-        { action: "create", data: did2, keyId: keyId2, publicKey: (0, import_utils2.bytesToHex)(publicKey2) },
+        { action: "create", data: did2, keyId: keyId2, publicKey: (0, import_utils3.bytesToHex)(publicKey2) },
         `Using stored key ${keyId2}.`
       );
       return;
     }
+    assertKeystoreAllowedForNetwork(network, overrides);
     const api = keystoreFactory(void 0, overrides);
     const { did, keyId } = api.generateDid({ network, setActive: true });
-    const publicKey = (0, import_utils2.bytesToHex)(api.kms.getPublicKey(keyId));
+    const publicKey = (0, import_utils3.bytesToHex)(api.kms.getPublicKey(keyId));
     print(
       { action: "create", data: did, keyId, publicKey },
       `Generated and stored key ${keyId} (now the active key).`
@@ -942,6 +1659,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
 }
 function overridesFromGlobals(g) {
   return {
+    home: g.home,
     config: g.config,
     profile: g.profile,
     keystore: g.keystore,
@@ -963,7 +1681,7 @@ function parseGenesisBytes(hex, type) {
   const expected = EXPECTED_BYTES[type];
   let bytes;
   try {
-    bytes = (0, import_utils2.hexToBytes)(hex.trim());
+    bytes = (0, import_utils3.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(
       `Invalid bytes: not valid hex. Expected ${expected.label}.`,
@@ -1048,6 +1766,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(
@@ -1072,9 +1796,14 @@ function registerUpdateCommand(program, factory, globals) {
       );
     }
     const network = deriveNetwork(did);
+    assertKeystoreAllowedForNetwork(network, globals());
     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 +1811,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 +1864,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(
@@ -1158,9 +1894,14 @@ function registerDeactivateCommand(program, factory, globals) {
       );
     }
     const network = deriveNetwork(did);
+    assertKeystoreAllowedForNetwork(network, globals());
     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 +1909,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()));
   });
@@ -1199,8 +1941,8 @@ function parseJsonArg2(flagName) {
 
 // src/commands/key.ts
 var import_keypair = require("@did-btcr2/keypair");
-var import_utils3 = require("@noble/hashes/utils.js");
-var import_node_fs6 = require("fs");
+var import_utils4 = require("@noble/hashes/utils.js");
+var import_node_fs7 = require("fs");
 function registerKeyCommand(program, factory, globals) {
   const key = program.command("key").description("Manage keypairs in the encrypted keystore.");
   const print = (result) => console.log(formatResult(result, globals()));
@@ -1209,7 +1951,7 @@ function registerKeyCommand(program, factory, globals) {
     assertNameAvailable(api.kms.kms, options.name);
     const setActive = options.setActive ?? false;
     const id = api.kms.generateKey({ ...options.name && { tags: { name: options.name } }, setActive });
-    print({ action: "key-generate", data: { keyId: id, publicKey: (0, import_utils3.bytesToHex)(api.kms.getPublicKey(id)), active: setActive } });
+    print({ action: "key-generate", data: { keyId: id, publicKey: (0, import_utils4.bytesToHex)(api.kms.getPublicKey(id)), active: setActive } });
   });
   key.command("list").alias("ls").description("List stored keys.").action(() => {
     const kms = factory(void 0, globals()).kms.kms;
@@ -1229,7 +1971,7 @@ function registerKeyCommand(program, factory, globals) {
     const kms = factory(void 0, globals()).kms.kms;
     const id = resolveKeyRef(kms, ref);
     const entry = kms.getEntry(id);
-    print({ action: "key-show", data: { keyId: id, publicKey: (0, import_utils3.bytesToHex)(entry.publicKey), ...entry.tags && { tags: entry.tags } } });
+    print({ action: "key-show", data: { keyId: id, publicKey: (0, import_utils4.bytesToHex)(entry.publicKey), ...entry.tags && { tags: entry.tags } } });
   });
   key.command("import").description("Import a key: a secret from a hex file, or a public key as watch-only.").option("--secret-file <path>", "Path to a file containing a 32-byte secret key as hex.").option("--public <hex>", "A 33-byte compressed public key as hex (imported watch-only).").option("--name <name>", "A human-friendly name, stored as a tag.").option("--set-active", "Make this the active key.", false).action((options) => {
     if (Boolean(options.secretFile) === Boolean(options.public)) {
@@ -1240,13 +1982,13 @@ function registerKeyCommand(program, factory, globals) {
     const keyPair = options.secretFile ? new import_keypair.SchnorrKeyPair({ secretKey: readHexFile(options.secretFile, 32, "--secret-file") }) : new import_keypair.SchnorrKeyPair({ publicKey: parseHex(options.public ?? "", 33, "--public") });
     const setActive = options.setActive ?? false;
     const id = api.kms.import(keyPair, { ...options.name && { tags: { name: options.name } }, setActive });
-    print({ action: "key-import", data: { keyId: id, publicKey: (0, import_utils3.bytesToHex)(api.kms.getPublicKey(id)), watchOnly: !options.secretFile, active: setActive } });
+    print({ action: "key-import", data: { keyId: id, publicKey: (0, import_utils4.bytesToHex)(api.kms.getPublicKey(id)), watchOnly: !options.secretFile, active: setActive } });
   });
   key.command("export <ref>").description("Export a key. Public material by default; --secret writes the secret to a file.").option("--secret", "Export the secret key. Requires --out.", false).option("--out <path>", "Write the exported secret to this file (created 0600).").action((ref, options) => {
     const api = factory(void 0, globals());
     const id = resolveKeyRef(api.kms.kms, ref);
     if (!options.secret) {
-      print({ action: "key-export", data: { keyId: id, publicKey: (0, import_utils3.bytesToHex)(api.kms.getPublicKey(id)) } });
+      print({ action: "key-export", data: { keyId: id, publicKey: (0, import_utils4.bytesToHex)(api.kms.getPublicKey(id)) } });
       return;
     }
     if (!options.out) {
@@ -1257,7 +1999,7 @@ function registerKeyCommand(program, factory, globals) {
       throw new CLIError(`Key ${id} is watch-only and has no secret to export.`, "INVALID_ARGUMENT_ERROR", { keyId: id });
     }
     process.stderr.write("warning: writing an unencrypted secret key to disk. Protect this file and delete it when done.\n");
-    writeSecretFile(options.out, (0, import_utils3.bytesToHex)(keyPair.secretKey.bytes));
+    writeSecretFile(options.out, (0, import_utils4.bytesToHex)(keyPair.secretKey.bytes));
     print({ action: "key-export", data: { keyId: id, secretWrittenTo: options.out } });
   });
   key.command("delete <ref>").alias("rm").description("Delete a key from the keystore.").option("--force", "Delete even if it is the active key.", false).action((ref, options) => {
@@ -1282,7 +2024,7 @@ function assertNameAvailable(kms, name) {
 function parseHex(hex, expectedBytes, label) {
   let bytes;
   try {
-    bytes = (0, import_utils3.hexToBytes)(hex.trim());
+    bytes = (0, import_utils4.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(`Invalid hex for ${label}.`, "INVALID_ARGUMENT_ERROR", { label });
   }
@@ -1298,7 +2040,7 @@ function parseHex(hex, expectedBytes, label) {
 function readHexFile(path, expectedBytes, label) {
   let content;
   try {
-    content = (0, import_node_fs6.readFileSync)(path, "utf-8");
+    content = (0, import_node_fs7.readFileSync)(path, "utf-8");
   } catch {
     throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
   }
@@ -1307,7 +2049,7 @@ function readHexFile(path, expectedBytes, label) {
 function writeSecretFile(path, contents) {
   let fd;
   try {
-    fd = (0, import_node_fs6.openSync)(path, "wx", 384);
+    fd = (0, import_node_fs7.openSync)(path, "wx", 384);
   } catch (error) {
     if (error.code === "EEXIST") {
       throw new CLIError(`Refusing to overwrite existing file ${path}. Choose a new --out path.`, "INVALID_ARGUMENT_ERROR", { path });
@@ -1315,62 +2057,316 @@ function writeSecretFile(path, contents) {
     throw error;
   }
   try {
-    (0, import_node_fs6.writeFileSync)(fd, contents);
+    (0, import_node_fs7.writeFileSync)(fd, contents);
   } finally {
-    (0, import_node_fs6.closeSync)(fd);
+    (0, import_node_fs7.closeSync)(fd);
+  }
+}
+
+// src/commands/keystore.ts
+var import_node_fs8 = require("fs");
+function registerKeystoreCommand(program, globals) {
+  const keystore = program.command("keystore").description("Establish, inspect, and re-key the keystore.");
+  const print = (result) => console.log(formatResult(result, globals()));
+  keystore.command("init").description("Establish the keystore (encrypted by default). Prompts for a passphrase and confirms it.").option("--dev", "Create an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only; mainnet operations are refused.", false).option("--force", "Re-establish even if a keystore already exists (discards its keys).", false).action((options) => {
+    const g = globals();
+    const path = resolveKeystorePath(g);
+    if ((0, import_node_fs8.existsSync)(path) && !options.force) {
+      throw new CLIError(
+        `A keystore already exists at ${path}. Use --force to re-establish it (this discards its keys).`,
+        "INVALID_ARGUMENT_ERROR",
+        { path }
+      );
+    }
+    if ((0, import_node_fs8.existsSync)(path) && options.force && !g.quiet) {
+      const { keyCount } = keystoreSummary(path);
+      if (keyCount > 0) {
+        process.stderr.write(
+          `warning: re-establishing the keystore at ${path} permanently discards its ${keyCount} existing key(s).
+`
+        );
+      }
+    }
+    if (options.dev && !g.quiet) {
+      process.stderr.write(
+        "warning: creating an UNENCRYPTED dev keystore. Keys are stored in plaintext. Use it only for disposable testnet material; mainnet operations will be refused.\n"
+      );
+    }
+    initKeystore(path, {
+      protection: options.dev ? "none" : "passphrase",
+      getPassphrase: (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: "New keystore passphrase: " })
+    });
+    print({ action: "keystore-init", data: { path, protection: options.dev ? "dev" : "encrypted" } });
+  });
+  keystore.command("status").description("Show the keystore path, protection mode, and key count. Never decrypts or prompts.").action(() => {
+    const g = globals();
+    const path = resolveKeystorePath(g, { lenient: true });
+    const summary = keystoreSummary(path);
+    if (summary.protection === "dev" && !g.quiet && g.output !== "json") {
+      process.stderr.write("warning: this is an UNENCRYPTED dev keystore; keys are stored in plaintext.\n");
+    }
+    print({ action: "keystore-status", data: { path, ...summary } });
+  });
+  keystore.command("change-passphrase").alias("passwd").description("Change the keystore passphrase, re-sealing every key under the new one. Encrypted keystores only.").action(() => {
+    const g = globals();
+    const path = resolveKeystorePath(g);
+    const summary = keystoreSummary(path);
+    if (summary.protection === "absent") {
+      throw new CLIError(`No keystore at ${path}. Run "btcr2 keystore init" first.`, "INVALID_ARGUMENT_ERROR", { path });
+    }
+    if (summary.protection === "dev") {
+      throw new CLIError(
+        `The keystore at ${path} is an unencrypted dev keystore; there is no passphrase to change.`,
+        "INVALID_ARGUMENT_ERROR",
+        { path }
+      );
+    }
+    const oldPassphrase = acquirePassphrase({ passphraseFile: g.passphraseFile, prompt: "Current keystore passphrase: " });
+    const newPassphrase = acquirePassphrase({ forcePrompt: true, confirm: true, prompt: "New keystore passphrase: " });
+    const rekeyed = changeKeystorePassphrase(path, oldPassphrase, newPassphrase);
+    print({ action: "keystore-change-passphrase", data: { path, rekeyed } });
+  });
+}
+
+// src/commands/config.ts
+var import_node_fs9 = require("fs");
+
+// 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
-var import_node_fs7 = require("fs");
-var import_node_path5 = require("path");
 function registerConfigCommand(program, globals) {
   const config = program.command("config").description("Read and write CLI configuration.");
-  const path = () => globals().config ?? defaultConfigPath();
+  const path = () => globals().config ?? defaultConfigPath(globals());
   const print = (result) => console.log(formatResult(result, globals()));
   config.command("init").description("Create a default config file with one profile per network.").option("--force", "Overwrite an existing config file.", false).action((options) => {
     const p = path();
-    if ((0, import_node_fs7.existsSync)(p) && !options.force) {
+    if ((0, import_node_fs9.existsSync)(p) && !options.force) {
       throw new CLIError(`Config already exists at ${p}. Use --force to overwrite.`, "INVALID_ARGUMENT_ERROR", { path: p });
     }
-    const scaffold = {
-      schemaVersion: CONFIG_SCHEMA_VERSION,
-      defaults: { output: "text" },
-      profiles: Object.fromEntries(SUPPORTED_NETWORKS.map((n) => [n, {}]))
-    };
-    ensureDir((0, import_node_path5.dirname)(p), 448);
-    writeFileAtomic(p, `${JSON.stringify(scaffold, null, 2)}
-`, 384);
+    writeDefaultConfigFile(p);
     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 home directory, config-file, and keystore paths.").action(() => {
+    const g = globals();
+    const data = {
+      home: resolveHome(g),
+      config: g.config ?? defaultConfigPath(g),
+      // Diagnostic command: report the path even when the config is malformed
+      // (this is a command you run to find and fix a broken config).
+      keystore: resolveKeystorePath(g, { lenient: true })
+    };
+    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) {
   const profile = program.command("profile").description("Manage configuration profiles.");
-  const path = () => globals().config ?? defaultConfigPath();
+  const path = () => globals().config ?? defaultConfigPath(globals());
   const print = (result) => console.log(formatResult(result, globals()));
   profile.command("add <name>").description("Add an empty profile.").action((name) => {
     writeConfigFile(path(), (raw) => {
@@ -1388,7 +2384,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 +2394,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) => {
@@ -1442,18 +2439,18 @@ function completionScript(shell) {
 }
 
 // src/version.ts
-var import_node_fs8 = require("fs");
-var import_node_path6 = require("path");
+var import_node_fs10 = require("fs");
+var import_node_path5 = require("path");
 var import_node_url = require("url");
 function readVersion() {
-  let dir = (0, import_node_path6.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+  let dir = (0, import_node_path5.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
   for (let i = 0; i < 5; i++) {
     try {
-      const pkg = JSON.parse((0, import_node_fs8.readFileSync)((0, import_node_path6.join)(dir, "package.json"), "utf-8"));
+      const pkg = JSON.parse((0, import_node_fs10.readFileSync)((0, import_node_path5.join)(dir, "package.json"), "utf-8"));
       if (pkg.name === "@did-btcr2/cli") return pkg.version;
     } catch {
     }
-    dir = (0, import_node_path6.dirname)(dir);
+    dir = (0, import_node_path5.dirname)(dir);
   }
   return "0.0.0";
 }
@@ -1477,13 +2474,19 @@ 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("--home <dir>", "btcr2 home directory holding config.json + keystore.json (default: ~/.btcr2, %LOCALAPPDATA%\\btcr2 on Windows; overrides $BTCR2_HOME)").option("-c, --config <path>", "Path to config file (default: <home>/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: <home>/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, home: opts.home });
+    });
+    registerInitCommand(this.program, globals);
     registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
     registerUpdateCommand(this.program, keystoreFactory, globals);
     registerDeactivateCommand(this.program, keystoreFactory, globals);
     registerKeyCommand(this.program, keystoreFactory, globals);
+    registerKeystoreCommand(this.program, globals);
     registerConfigCommand(this.program, globals);
     registerProfileCommand(this.program, globals);
     registerCompletionCommand(this.program, globals);
@@ -1503,6 +2506,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,28 +2531,51 @@ function handleError(error, verbose) {
   CLIError,
   CONFIG_SCHEMA_VERSION,
   DidBtcr2Cli,
+  ENV_RPC_PASS_FILE,
   ENV_VARS,
+  REDACTED,
   SUPPORTED_NETWORKS,
   VERSION,
+  assertKeystoreAllowedForNetwork,
+  blankToUndef,
   defaultApiFactory,
   defaultConfigPath,
   deriveNetwork,
   formatResult,
   getConfigPath,
+  isSecretKey,
   keystoreApiFactory,
+  parseConfigFileRaw,
+  parseHeaderList,
+  profileNetworkMismatch,
   profileToOverrides,
   readConfigFile,
   readEnvOverrides,
+  redactSecrets,
   registerCompletionCommand,
   registerConfigCommand,
   registerCreateCommand,
   registerDeactivateCommand,
+  registerInitCommand,
   registerKeyCommand,
+  registerKeystoreCommand,
   registerProfileCommand,
   registerResolveCommand,
   registerUpdateCommand,
+  resolveActiveProfile,
+  resolveBroadcastOptions,
+  resolveConnectionConfig,
   resolveDefaultNetwork,
+  resolveEffectiveConfig,
+  resolveKeystorePath,
+  resolveKeystoreProtection,
+  resolveOutputFormat,
+  resolveSecretRef,
+  resolveSigningKeyRef,
+  runDoctor,
+  scrubUrlUserinfo,
   setConfigPath,
   unsetConfigPath,
-  writeConfigFile
+  writeConfigFile,
+  writeDefaultConfigFile
 });