@did-btcr2/cli 0.15.0 → 0.17.0

package/dist/cjs/index.js

@@ -28,6 +28,7 @@ __export(index_exports, {
   REDACTED: () => REDACTED,
   SUPPORTED_NETWORKS: () => SUPPORTED_NETWORKS,
   VERSION: () => VERSION,
+  assertKeystoreAllowedForNetwork: () => assertKeystoreAllowedForNetwork,
   blankToUndef: () => blankToUndef,
   defaultApiFactory: () => defaultApiFactory,
   defaultConfigPath: () => defaultConfigPath,
@@ -47,7 +48,9 @@ __export(index_exports, {
   registerConfigCommand: () => registerConfigCommand,
   registerCreateCommand: () => registerCreateCommand,
   registerDeactivateCommand: () => registerDeactivateCommand,
+  registerInitCommand: () => registerInitCommand,
   registerKeyCommand: () => registerKeyCommand,
+  registerKeystoreCommand: () => registerKeystoreCommand,
   registerProfileCommand: () => registerProfileCommand,
   registerResolveCommand: () => registerResolveCommand,
   registerUpdateCommand: () => registerUpdateCommand,
@@ -57,6 +60,7 @@ __export(index_exports, {
   resolveDefaultNetwork: () => resolveDefaultNetwork,
   resolveEffectiveConfig: () => resolveEffectiveConfig,
   resolveKeystorePath: () => resolveKeystorePath,
+  resolveKeystoreProtection: () => resolveKeystoreProtection,
   resolveOutputFormat: () => resolveOutputFormat,
   resolveSecretRef: () => resolveSecretRef,
   resolveSigningKeyRef: () => resolveSigningKeyRef,
@@ -64,7 +68,8 @@ __export(index_exports, {
   scrubUrlUserinfo: () => scrubUrlUserinfo,
   setConfigPath: () => setConfigPath,
   unsetConfigPath: () => unsetConfigPath,
-  writeConfigFile: () => writeConfigFile
+  writeConfigFile: () => writeConfigFile,
+  writeDefaultConfigFile: () => writeDefaultConfigFile
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -76,15 +81,14 @@ 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_fs7 = 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");
+var import_node_fs6 = require("fs");
+var import_node_path5 = require("path");
 
 // src/error.ts
 var import_common = require("@did-btcr2/common");
@@ -163,6 +167,8 @@ 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_sha2 = require("@noble/hashes/sha2.js");
+var import_utils2 = require("@noble/hashes/utils.js");
 var import_base2 = require("@scure/base");
 
 // src/keystore/envelope.ts
@@ -333,7 +339,7 @@ function withFileLock(lockPath, fn, options = {}) {
   }
 }
 
-// src/keystore/paths.ts
+// src/paths.ts
 var import_node_os = require("os");
 var import_node_path2 = require("path");
 
@@ -351,14 +357,43 @@ function blankToUndef(value) {
   return value.trim() === "" ? void 0 : value;
 }
 
-// src/keystore/paths.ts
-function defaultKeystorePath() {
-  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");
+// src/paths.ts
+var ENV_HOME = "BTCR2_HOME";
+var CONFIG_FILENAME = "config.json";
+var KEYSTORE_FILENAME = "keystore.json";
+var SESSION_FILENAME = "session.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);
+}
+function defaultSessionPath(overrides) {
+  return (0, import_node_path2.join)(resolveHome(overrides), SESSION_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;
@@ -367,12 +402,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();
   }
@@ -396,7 +434,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 {
@@ -416,24 +473,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
     };
@@ -445,7 +545,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();
@@ -476,6 +577,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;
@@ -483,13 +631,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;
         }
       });
@@ -500,12 +655,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 }
       });
     });
@@ -568,7 +756,138 @@ 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 keystoreVerifierId(path) {
+  if (!(0, import_node_fs3.existsSync)(path)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs3.readFileSync)(path, "utf-8"));
+  } catch {
+    return void 0;
+  }
+  if (!parsed.verifier) return void 0;
+  return import_base2.base64urlnopad.encode((0, import_sha2.sha256)((0, import_utils2.utf8ToBytes)(JSON.stringify(parsed.verifier))));
+}
+function verifyKeystorePassphrase(path, passphrase) {
+  if (!(0, import_node_fs3.existsSync)(path)) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs3.readFileSync)(path, "utf-8"));
+  } catch {
+    return false;
+  }
+  if (parsed.protection !== "passphrase" || !parsed.verifier) return false;
+  try {
+    return bytesEqual(decryptSecret(parsed.verifier, passphrase), VERIFIER_PLAINTEXT);
+  } catch {
+    return false;
+  }
+}
+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 {
@@ -629,10 +948,14 @@ 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$/, ""));
+    }
+    const fromSession = options.beforePrompt?.();
+    if (fromSession) return assertNonEmpty(fromSession);
   }
   if (!process.stdin.isTTY) {
     throw new KeyStoreError(
@@ -655,6 +978,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;
@@ -669,7 +998,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;
       }
@@ -680,7 +1012,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);
@@ -692,16 +1024,168 @@ function promptHidden(label) {
   return Buffer.from(bytes).toString("utf-8");
 }
 
+// src/keystore/session.ts
+var import_node_fs5 = require("fs");
+var import_node_path4 = require("path");
+var import_utils3 = require("@noble/hashes/utils.js");
+var import_base3 = require("@scure/base");
+var SESSION_VERSION = 1;
+var DEFAULT_SESSION_TTL_MS = 60 * 60 * 1e3;
+var MAX_SESSION_TTL_MS = 24 * 60 * 60 * 1e3;
+var ENV_KEYSTORE_TTL = "BTCR2_KEYSTORE_TTL";
+function writeSession(sessionPath, input) {
+  const createdAt = Date.now();
+  const session = {
+    v: SESSION_VERSION,
+    keystore: (0, import_node_path4.resolve)(input.keystorePath),
+    verifierId: input.verifierId,
+    passphrase: import_base3.base64urlnopad.encode((0, import_utils3.utf8ToBytes)(input.passphrase)),
+    allowMainnet: input.allowMainnet ?? false,
+    createdAt,
+    expiresAt: createdAt + input.ttlMs,
+    ttlSeconds: Math.round(input.ttlMs / 1e3)
+  };
+  ensureDir((0, import_node_path4.dirname)(sessionPath), 448);
+  writeFileAtomic(sessionPath, `${JSON.stringify(session, null, 2)}
+`, 384);
+  return session;
+}
+function clearSession(sessionPath) {
+  let existed = false;
+  try {
+    existed = (0, import_node_fs5.existsSync)(sessionPath);
+    if (existed) (0, import_node_fs5.rmSync)(sessionPath, { force: true });
+  } catch {
+    existed = false;
+  }
+  sweepSessionTemps(sessionPath);
+  return existed;
+}
+function sweepSessionTemps(sessionPath) {
+  const dir = (0, import_node_path4.dirname)(sessionPath);
+  const prefix = `.${(0, import_node_path4.basename)(sessionPath)}.`;
+  try {
+    for (const name of (0, import_node_fs5.readdirSync)(dir)) {
+      if (name.startsWith(prefix) && name.endsWith(".tmp")) {
+        try {
+          (0, import_node_fs5.rmSync)((0, import_node_path4.join)(dir, name), { force: true });
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+}
+function readLiveSessionPassphrase(sessionPath, keystorePath, currentVerifierId, isMainnetOperation = false) {
+  const verdict = evaluateSession(sessionPath, keystorePath, currentVerifierId, Date.now());
+  if (verdict.status === "live") {
+    if (isMainnetOperation && !verdict.session.allowMainnet) return void 0;
+    try {
+      return Buffer.from(import_base3.base64urlnopad.decode(verdict.session.passphrase)).toString("utf-8");
+    } catch {
+      clearSession(sessionPath);
+      return void 0;
+    }
+  }
+  if (verdict.status === "expired" || verdict.status === "stale" || verdict.status === "future" || verdict.status === "malformed") {
+    clearSession(sessionPath);
+  }
+  return void 0;
+}
+function readSessionStatus(sessionPath, keystorePath, currentVerifierId) {
+  const now = Date.now();
+  const verdict = evaluateSession(sessionPath, keystorePath, currentVerifierId, now);
+  if (verdict.status !== "live") return { active: false };
+  return {
+    active: true,
+    expiresAt: verdict.session.expiresAt,
+    secondsRemaining: Math.max(0, Math.round((verdict.session.expiresAt - now) / 1e3)),
+    allowMainnet: verdict.session.allowMainnet
+  };
+}
+function parseTtlToMs(raw) {
+  const match = /^(\d+)([smh]?)$/.exec(raw.trim());
+  if (!match) return void 0;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n)) return void 0;
+  const unitMs = match[2] === "h" ? 36e5 : match[2] === "m" ? 6e4 : 1e3;
+  return n * unitMs;
+}
+function evaluateSession(sessionPath, keystorePath, currentVerifierId, now) {
+  const session = secureReadSession(sessionPath);
+  if (!session) return { status: "none" };
+  if (session.v !== SESSION_VERSION) return { status: "malformed" };
+  if (typeof session.passphrase !== "string" || typeof session.keystore !== "string" || typeof session.verifierId !== "string" || typeof session.allowMainnet !== "boolean" || typeof session.createdAt !== "number" || typeof session.expiresAt !== "number") {
+    return { status: "malformed" };
+  }
+  if (session.createdAt > now) return { status: "future" };
+  if (now >= session.expiresAt) return { status: "expired" };
+  if ((0, import_node_path4.resolve)(session.keystore) !== (0, import_node_path4.resolve)(keystorePath)) return { status: "foreign" };
+  if (currentVerifierId === void 0 || session.verifierId !== currentVerifierId) return { status: "stale" };
+  return { status: "live", session };
+}
+function secureReadSession(sessionPath) {
+  let raw;
+  if (process.platform === "win32") {
+    try {
+      raw = (0, import_node_fs5.readFileSync)(sessionPath, "utf-8");
+    } catch {
+      return void 0;
+    }
+  } else {
+    let fd;
+    try {
+      fd = (0, import_node_fs5.openSync)(sessionPath, import_node_fs5.constants.O_RDONLY | import_node_fs5.constants.O_NOFOLLOW);
+    } catch {
+      return void 0;
+    }
+    try {
+      const st = (0, import_node_fs5.fstatSync)(fd);
+      const myUid = typeof process.getuid === "function" ? process.getuid() : void 0;
+      if (!st.isFile() || myUid !== void 0 && st.uid !== myUid || (st.mode & 63) !== 0) {
+        try {
+          (0, import_node_fs5.rmSync)(sessionPath, { force: true });
+        } catch {
+        }
+        return void 0;
+      }
+      raw = (0, import_node_fs5.readFileSync)(fd, "utf-8");
+    } catch {
+      return void 0;
+    } finally {
+      try {
+        (0, import_node_fs5.closeSync)(fd);
+      } catch {
+      }
+    }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+
 // src/config.ts
 var CONFIG_SCHEMA_VERSION = 1;
 function writeConfigFile(path, mutate) {
   const raw = readConfigFile(path) ?? {};
   mutate(raw);
   raw.schemaVersion = CONFIG_SCHEMA_VERSION;
-  ensureDir((0, import_node_path4.dirname)(path), 448);
+  ensureDir((0, import_node_path5.dirname)(path), 448);
   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_path5.dirname)(path), 448);
+  writeFileAtomic(path, `${JSON.stringify(scaffold, null, 2)}
+`, 384);
+}
 function getConfigPath(config, path) {
   return path.split(".").reduce(
     (node, key) => node?.[key],
@@ -760,14 +1244,10 @@ function readEnvOverrides() {
     casRpcUrl: env(ENV_VARS.CAS_RPC_URL)
   };
 }
-function defaultConfigPath() {
-  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 parseConfigFileRaw(path) {
   let content;
   try {
-    content = (0, import_node_fs5.readFileSync)(path, "utf-8");
+    content = (0, import_node_fs6.readFileSync)(path, "utf-8");
   } catch (error) {
     if (error.code === "ENOENT") return void 0;
     throw new CLIError(
@@ -822,7 +1302,7 @@ function resolveActiveProfile(file, overrides) {
   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;
@@ -833,7 +1313,7 @@ function resolveDefaultNetwork(overrides) {
 function profileNetworkMismatch(network, overrides) {
   let file;
   try {
-    file = readConfigFile(overrides?.config ?? defaultConfigPath());
+    file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
   } catch {
     return void 0;
   }
@@ -847,7 +1327,7 @@ function resolveOutputFormat(options) {
     process.env.BTCR2_OUTPUT || void 0
   ];
   try {
-    candidates.push(readConfigFile(options.config ?? defaultConfigPath())?.defaults?.output);
+    candidates.push(readConfigFile(options.config ?? defaultConfigPath(options))?.defaults?.output);
   } catch {
   }
   for (const candidate of candidates) {
@@ -873,7 +1353,7 @@ function resolveRpcUnit(overrides, env, fileOverrides) {
 }
 function resolveConnectionConfig(network, overrides) {
   if (!network) return {};
-  const configPath = overrides?.config ?? defaultConfigPath();
+  const configPath = overrides?.config ?? defaultConfigPath(overrides);
   const file = readConfigFile(configPath);
   const { name: activeProfile } = resolveActiveProfile(file, overrides);
   const profileName = activeProfile ?? network;
@@ -959,7 +1439,7 @@ function trimTrailingNewline(value) {
 }
 function readSecretFile(path, source) {
   try {
-    return trimTrailingNewline((0, import_node_fs5.readFileSync)(path, "utf-8"));
+    return trimTrailingNewline((0, import_node_fs6.readFileSync)(path, "utf-8"));
   } catch (error) {
     throw new CLIError(
       `Could not read the RPC password ${source} at ${path}: ${error.message}`,
@@ -985,7 +1465,7 @@ function readRpcPassFile() {
   return readSecretFile(path, `file named by ${ENV_RPC_PASS_FILE}`);
 }
 function resolveBroadcastOptions(network, overrides, flags) {
-  const file = readConfigFile(overrides?.config ?? defaultConfigPath());
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
   const { name: activeProfile } = resolveActiveProfile(file, overrides);
   const profileBtc = file?.profiles?.[activeProfile ?? network]?.btc;
   const options = {};
@@ -1007,7 +1487,7 @@ function parseFeeRate(raw) {
   return rate;
 }
 function resolveEffectiveConfig(network, overrides) {
-  const file = readConfigFile(overrides?.config ?? defaultConfigPath());
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
   const { name: activeProfile } = resolveActiveProfile(file, overrides);
   const profileName = activeProfile ?? network;
   const fileOv = file ? profileToOverrides(file, profileName) : {};
@@ -1093,17 +1573,56 @@ async function runDoctor(network, overrides) {
 function defaultApiFactory(network, overrides) {
   return (0, import_api.createApi)(resolveConnectionConfig(network, overrides));
 }
-function buildKeystoreKms(overrides) {
+function buildKeystoreKms(overrides, network) {
+  const keystorePath = resolveKeystorePath(overrides);
+  const sessionPath = defaultSessionPath(overrides);
+  const isMainnetOperation = network === "bitcoin";
   return new FileBackedKeyManager({
-    path: resolveKeystorePath(overrides),
-    getPassphrase: () => acquirePassphrase({ passphraseFile: overrides?.passphraseFile })
+    path: keystorePath,
+    // 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.
+    //
+    // On the non-establishing path, a cached session (ADR 081) is consulted below
+    // the env var / --passphrase-file and above the interactive prompt. It is
+    // wired ONLY when not confirming, so establishment never consults the session
+    // and a first passphrase is always entered fresh and twice. The session is
+    // bound to this keystore's verifier, so a rotated passphrase invalidates it.
+    getPassphrase: (opts) => acquirePassphrase({
+      passphraseFile: overrides?.passphraseFile,
+      confirm: opts?.confirm,
+      ...opts?.confirm ? {} : {
+        beforePrompt: () => readLiveSessionPassphrase(sessionPath, keystorePath, keystoreVerifierId(keystorePath), isMainnetOperation)
+      }
+    })
   });
 }
-function resolveKeystorePath(overrides) {
-  return overrides?.keystore ?? activeProfileIdentity(overrides)?.keystore ?? defaultKeystorePath();
+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());
+  const file = readConfigFile(overrides?.config ?? defaultConfigPath(overrides));
   const { name } = resolveActiveProfile(file, overrides);
   return name ? file?.profiles?.[name]?.identity : void 0;
 }
@@ -1113,7 +1632,7 @@ function resolveSigningKeyRef(overrides) {
 function keystoreApiFactory(network, overrides) {
   return (0, import_api.createApi)({
     ...resolveConnectionConfig(network, overrides),
-    kms: buildKeystoreKms(overrides)
+    kms: buildKeystoreKms(overrides, network)
   });
 }
 function deriveNetwork(did) {
@@ -1128,6 +1647,86 @@ 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_fs7.existsSync)(configPath) || options.force) {
+      writeDefaultConfigFile(configPath);
+      created.push("config");
+    }
+    const keystoreExists = (0, import_node_fs7.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: " })
+      });
+      clearSession(defaultSessionPath(g));
+      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_utils4 = 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];
@@ -1166,40 +1765,6 @@ function resolveKeyRef(kms, ref) {
   throw new CLIError(`No key matches reference "${ref}".`, "KEY_NOT_FOUND_ERROR", { 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);
-  }
-  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)" },
@@ -1268,14 +1833,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_utils4.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_utils4.bytesToHex)(api.kms.getPublicKey(keyId));
     print(
       { action: "create", data: did, keyId, publicKey },
       `Generated and stored key ${keyId} (now the active key).`
@@ -1284,6 +1850,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
 }
 function overridesFromGlobals(g) {
   return {
+    home: g.home,
     config: g.config,
     profile: g.profile,
     keystore: g.keystore,
@@ -1305,7 +1872,7 @@ function parseGenesisBytes(hex, type) {
   const expected = EXPECTED_BYTES[type];
   let bytes;
   try {
-    bytes = (0, import_utils2.hexToBytes)(hex.trim());
+    bytes = (0, import_utils4.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(
       `Invalid bytes: not valid hex. Expected ${expected.label}.`,
@@ -1420,6 +1987,7 @@ function registerUpdateCommand(program, factory, globals) {
       );
     }
     const network = deriveNetwork(did);
+    assertKeystoreAllowedForNetwork(network, globals());
     const api = factory(network, globals());
     const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
     const signer = new import_key_manager2.KeyManagerSigner(api.kms.kms, keyId);
@@ -1517,6 +2085,7 @@ function registerDeactivateCommand(program, factory, globals) {
       );
     }
     const network = deriveNetwork(did);
+    assertKeystoreAllowedForNetwork(network, globals());
     const api = factory(network, globals());
     const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
     const signer = new import_key_manager3.KeyManagerSigner(api.kms.kms, keyId);
@@ -1563,8 +2132,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_utils5 = require("@noble/hashes/utils.js");
+var import_node_fs8 = 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()));
@@ -1573,7 +2142,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_utils5.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;
@@ -1593,7 +2162,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_utils5.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)) {
@@ -1604,13 +2173,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_utils5.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_utils5.bytesToHex)(api.kms.getPublicKey(id)) } });
       return;
     }
     if (!options.out) {
@@ -1621,7 +2190,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_utils5.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) => {
@@ -1646,7 +2215,7 @@ function assertNameAvailable(kms, name) {
 function parseHex(hex, expectedBytes, label) {
   let bytes;
   try {
-    bytes = (0, import_utils3.hexToBytes)(hex.trim());
+    bytes = (0, import_utils5.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(`Invalid hex for ${label}.`, "INVALID_ARGUMENT_ERROR", { label });
   }
@@ -1662,7 +2231,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_fs8.readFileSync)(path, "utf-8");
   } catch {
     throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
   }
@@ -1671,7 +2240,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_fs8.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 });
@@ -1679,15 +2248,156 @@ function writeSecretFile(path, contents) {
     throw error;
   }
   try {
-    (0, import_node_fs6.writeFileSync)(fd, contents);
+    (0, import_node_fs8.writeFileSync)(fd, contents);
   } finally {
-    (0, import_node_fs6.closeSync)(fd);
+    (0, import_node_fs8.closeSync)(fd);
   }
 }
 
+// src/commands/keystore.ts
+var import_node_fs9 = require("fs");
+function registerKeystoreCommand(program, globals) {
+  const keystore = program.command("keystore").description("Establish, inspect, re-key, and unlock 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_fs9.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_fs9.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: " })
+    });
+    clearSession(defaultSessionPath(g));
+    print({ action: "keystore-init", data: { path, protection: options.dev ? "dev" : "encrypted" } });
+  });
+  keystore.command("status").description("Show the keystore path, protection mode, key count, and session state. Never decrypts or prompts.").action(() => {
+    const g = globals();
+    const path = resolveKeystorePath(g, { lenient: true });
+    const summary = keystoreSummary(path);
+    const session = readSessionStatus(defaultSessionPath(g), path, keystoreVerifierId(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, session } });
+  });
+  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);
+    clearSession(defaultSessionPath(g));
+    print({ action: "keystore-change-passphrase", data: { path, rekeyed } });
+  });
+  keystore.command("unlock").description("Cache the keystore passphrase for a session so later commands do not re-prompt (ADR 081).").option("--ttl <duration>", `Session lifetime: bare seconds or an s/m/h suffix (default 1h, max 24h). Also $${ENV_KEYSTORE_TTL}.`).option("--allow-mainnet", "Permit unlocking when the active network is mainnet (bitcoin); this suspends per-use passphrase auth for the session.", false).action((options) => {
+    const g = globals();
+    const path = resolveKeystorePath(g);
+    const summary = keystoreSummary(path);
+    if (summary.protection === "absent") {
+      throw new CLIError(`No keystore at ${path}. Run "btcr2 init" or "btcr2 keystore init" first.`, "INVALID_ARGUMENT_ERROR", { path });
+    }
+    if (summary.protection === "dev") {
+      throw new CLIError(
+        `The keystore at ${path} is an unencrypted dev keystore; it has no passphrase to cache, so no unlock is needed.`,
+        "INVALID_ARGUMENT_ERROR",
+        { path }
+      );
+    }
+    if (!summary.established) {
+      throw new CLIError(
+        `The keystore at ${path} has no passphrase established yet. Establish one with "btcr2 keystore init" or the first "btcr2 key generate".`,
+        "INVALID_ARGUMENT_ERROR",
+        { path }
+      );
+    }
+    if (!options.allowMainnet && resolveDefaultNetwork(g) === "bitcoin") {
+      throw new CLIError(
+        `Refusing to unlock for a mainnet (bitcoin) context: caching the passphrase suspends per-use authentication for the session. Pass --allow-mainnet to override, or keep signing mainnet updates with a per-use passphrase prompt.`,
+        "MAINNET_UNLOCK_REFUSED_ERROR",
+        { path }
+      );
+    }
+    const ttlMs = resolveSessionTtl(options.ttl);
+    const passphrase = acquirePassphrase({ passphraseFile: g.passphraseFile, prompt: "Keystore passphrase: " });
+    if (!verifyKeystorePassphrase(path, passphrase)) {
+      throw new CLIError(`Incorrect passphrase for the keystore at ${path}; no session was created.`, "DECRYPT_ERROR", { path });
+    }
+    const verifierId = keystoreVerifierId(path);
+    if (!verifierId) {
+      throw new CLIError(`The keystore at ${path} has no verifier to bind a session to.`, "INVALID_ARGUMENT_ERROR", { path });
+    }
+    const session = writeSession(defaultSessionPath(g), {
+      keystorePath: path,
+      verifierId,
+      passphrase,
+      ttlMs,
+      allowMainnet: !!options.allowMainnet
+    });
+    print({ action: "keystore-unlock", data: { keystore: path, expiresAt: session.expiresAt, ttlSeconds: session.ttlSeconds } });
+  });
+  keystore.command("lock").description("Revoke the cached session so later commands prompt for the passphrase again (ADR 081).").action(() => {
+    const g = globals();
+    const sessionPath = defaultSessionPath(g);
+    const cleared = clearSession(sessionPath);
+    print({ action: "keystore-lock", data: { path: sessionPath, cleared } });
+  });
+}
+function resolveSessionTtl(flag) {
+  const fromFlag = blankToUndef(flag);
+  const raw = fromFlag ?? blankToUndef(process.env[ENV_KEYSTORE_TTL]);
+  if (raw === void 0) return DEFAULT_SESSION_TTL_MS;
+  const source = fromFlag !== void 0 ? "--ttl" : `$${ENV_KEYSTORE_TTL}`;
+  const ms = parseTtlToMs(raw);
+  if (ms === void 0 || ms <= 0) {
+    throw new CLIError(
+      `Invalid ${source} "${raw}": expected seconds or a value with an s/m/h suffix, e.g. 3600, 45m, or 2h.`,
+      "INVALID_ARGUMENT_ERROR",
+      { value: raw, source }
+    );
+  }
+  if (ms > MAX_SESSION_TTL_MS) {
+    throw new CLIError(
+      `${source} "${raw}" exceeds the 24h maximum for a cached passphrase.`,
+      "INVALID_ARGUMENT_ERROR",
+      { value: raw, source }
+    );
+  }
+  return ms;
+}
+
 // src/commands/config.ts
-var import_node_fs7 = require("fs");
-var import_node_path5 = require("path");
+var import_node_fs10 = require("fs");
 
 // src/config-schema.ts
 var CONFIG_SCHEMA = {
@@ -1812,21 +2522,14 @@ function walk(obj, prefix, 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();
+  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_fs10.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.").option("--show-secrets", "Reveal secret values (RPC password, etc.) instead of redacting them.", false).action((dotted, opts) => {
@@ -1871,10 +2574,14 @@ function registerConfigCommand(program, globals) {
     }
     print({ action: "config-effective", data });
   });
-  config.command("path").description("Print the resolved config-file and keystore paths.").action(() => {
+  config.command("path").description("Print the resolved home directory, config-file, and keystore paths.").action(() => {
+    const g = globals();
     const data = {
-      config: globals().config ?? defaultConfigPath(),
-      keystore: globals().keystore ?? defaultKeystorePath()
+      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 });
   });
@@ -1927,7 +2634,7 @@ function isStringScalarPath(dotted) {
 // 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) => {
@@ -2000,14 +2707,14 @@ function completionScript(shell) {
 }
 
 // src/version.ts
-var import_node_fs8 = require("fs");
+var import_node_fs11 = require("fs");
 var import_node_path6 = require("path");
 var import_node_url = require("url");
 function readVersion() {
   let dir = (0, import_node_path6.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_fs11.readFileSync)((0, import_node_path6.join)(dir, "package.json"), "utf-8"));
       if (pkg.name === "@did-btcr2/cli") return pkg.version;
     } catch {
     }
@@ -2035,17 +2742,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> (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");
+    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 });
+      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);
@@ -2095,6 +2804,7 @@ function handleError(error, verbose) {
   REDACTED,
   SUPPORTED_NETWORKS,
   VERSION,
+  assertKeystoreAllowedForNetwork,
   blankToUndef,
   defaultApiFactory,
   defaultConfigPath,
@@ -2114,7 +2824,9 @@ function handleError(error, verbose) {
   registerConfigCommand,
   registerCreateCommand,
   registerDeactivateCommand,
+  registerInitCommand,
   registerKeyCommand,
+  registerKeystoreCommand,
   registerProfileCommand,
   registerResolveCommand,
   registerUpdateCommand,
@@ -2124,6 +2836,7 @@ function handleError(error, verbose) {
   resolveDefaultNetwork,
   resolveEffectiveConfig,
   resolveKeystorePath,
+  resolveKeystoreProtection,
   resolveOutputFormat,
   resolveSecretRef,
   resolveSigningKeyRef,
@@ -2131,5 +2844,6 @@ function handleError(error, verbose) {
   scrubUrlUserinfo,
   setConfigPath,
   unsetConfigPath,
-  writeConfigFile
+  writeConfigFile,
+  writeDefaultConfigFile
 });