@did-btcr2/cli 0.16.0 → 0.18.0

package/dist/cjs/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   SUPPORTED_NETWORKS: () => SUPPORTED_NETWORKS,
   VERSION: () => VERSION,
   assertKeystoreAllowedForNetwork: () => assertKeystoreAllowedForNetwork,
+  assertSupportedNetwork: () => assertSupportedNetwork,
   blankToUndef: () => blankToUndef,
   defaultApiFactory: () => defaultApiFactory,
   defaultConfigPath: () => defaultConfigPath,
@@ -39,9 +40,11 @@ __export(index_exports, {
   keystoreApiFactory: () => keystoreApiFactory,
   parseConfigFileRaw: () => parseConfigFileRaw,
   parseHeaderList: () => parseHeaderList,
+  persistDefaultNetwork: () => persistDefaultNetwork,
   profileNetworkMismatch: () => profileNetworkMismatch,
   profileToOverrides: () => profileToOverrides,
   readConfigFile: () => readConfigFile,
+  readConfiguredDefaultNetwork: () => readConfiguredDefaultNetwork,
   readEnvOverrides: () => readEnvOverrides,
   redactSecrets: () => redactSecrets,
   registerCompletionCommand: () => registerCompletionCommand,
@@ -52,6 +55,7 @@ __export(index_exports, {
   registerKeyCommand: () => registerKeyCommand,
   registerKeystoreCommand: () => registerKeystoreCommand,
   registerProfileCommand: () => registerProfileCommand,
+  registerQuickstartCommand: () => registerQuickstartCommand,
   registerResolveCommand: () => registerResolveCommand,
   registerUpdateCommand: () => registerUpdateCommand,
   resolveActiveProfile: () => resolveActiveProfile,
@@ -82,13 +86,13 @@ var import_common3 = require("@did-btcr2/common");
 var import_commander = require("commander");
 
 // src/commands/init.ts
-var import_node_fs6 = require("fs");
+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_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");
@@ -167,6 +171,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_sha2 = require("@noble/hashes/sha2.js");
 var import_utils2 = require("@noble/hashes/utils.js");
 var import_base2 = require("@scure/base");
 
@@ -360,6 +365,7 @@ function blankToUndef(value) {
 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();
 }
@@ -376,6 +382,9 @@ function defaultConfigPath(overrides) {
 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;
@@ -830,6 +839,32 @@ function keystoreSummary(path) {
 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;
@@ -923,6 +958,8 @@ function acquirePassphrase(options = {}) {
     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(
@@ -991,13 +1028,155 @@ 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);
 }
@@ -1007,7 +1186,7 @@ function writeDefaultConfigFile(path) {
     defaults: { output: "text" },
     profiles: Object.fromEntries(SUPPORTED_NETWORKS.map((n) => [n, {}]))
   };
-  ensureDir((0, import_node_path4.dirname)(path), 448);
+  ensureDir((0, import_node_path5.dirname)(path), 448);
   writeFileAtomic(path, `${JSON.stringify(scaffold, null, 2)}
 `, 384);
 }
@@ -1072,7 +1251,7 @@ function readEnvOverrides() {
 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(
@@ -1135,6 +1314,45 @@ function resolveDefaultNetwork(overrides) {
   if (network) return network;
   return "regtest";
 }
+function readConfiguredDefaultNetwork(overrides) {
+  const configPath = overrides?.config ?? defaultConfigPath(overrides);
+  let raw;
+  try {
+    raw = parseConfigFileRaw(configPath);
+  } catch {
+    return void 0;
+  }
+  const value = raw ? getConfigPath(raw, "defaults.network") : void 0;
+  return typeof value === "string" && SUPPORTED_NETWORKS.includes(value) ? value : void 0;
+}
+function persistDefaultNetwork(configPath, opts) {
+  const raw = parseConfigFileRaw(configPath);
+  const rawValue = raw ? getConfigPath(raw, "defaults.network") : void 0;
+  const rawNetwork = typeof rawValue === "string" && SUPPORTED_NETWORKS.includes(rawValue) ? rawValue : void 0;
+  if (opts.explicit) {
+    if (opts.explicit !== rawNetwork) {
+      writeConfigFile(configPath, (r) => setConfigPath(r, "defaults.network", opts.explicit));
+      return { network: opts.explicit, wrote: true };
+    }
+    return { network: opts.explicit, wrote: false };
+  }
+  if (rawNetwork) return { network: rawNetwork, wrote: false };
+  if (opts.fallback) {
+    writeConfigFile(configPath, (r) => setConfigPath(r, "defaults.network", opts.fallback));
+    return { network: opts.fallback, wrote: true };
+  }
+  return { network: resolveDefaultNetwork(opts.overrides), wrote: false };
+}
+function assertSupportedNetwork(value) {
+  if (!SUPPORTED_NETWORKS.includes(value)) {
+    throw new CLIError(
+      `Invalid network "${value}". Must be one of ${SUPPORTED_NETWORKS.join(", ")}.`,
+      "INVALID_ARGUMENT_ERROR",
+      { network: value }
+    );
+  }
+  return value;
+}
 function profileNetworkMismatch(network, overrides) {
   let file;
   try {
@@ -1264,7 +1482,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}`,
@@ -1398,13 +1616,28 @@ 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),
+    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.
-    getPassphrase: (opts) => acquirePassphrase({ passphraseFile: overrides?.passphraseFile, confirm: opts?.confirm })
+    //
+    // 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 resolveKeystoreProtection(overrides) {
@@ -1442,7 +1675,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) {
@@ -1492,49 +1725,383 @@ function formatResult(result, options) {
 }
 
 // src/commands/init.ts
+function runInit(g, options = {}) {
+  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".
+`
+    );
+  }
+  let establishedPassphrase;
+  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) => {
+        const passphrase = acquirePassphrase({
+          passphraseFile: g.passphraseFile,
+          confirm: opts?.confirm,
+          prompt: "New keystore passphrase: "
+        });
+        if (options.captureEstablishedPassphrase && !options.dev) establishedPassphrase = passphrase;
+        return passphrase;
+      }
+    });
+    clearSession(defaultSessionPath(g));
+    created.push("keystore");
+  }
+  const { network } = persistDefaultNetwork(configPath, {
+    explicit: options.network,
+    fallback: options.fallbackNetwork,
+    overrides: g
+  });
+  const protection = keystoreSummary(keystorePath).protection;
+  return { home, config: configPath, keystore: keystorePath, network, created, protection, establishedPassphrase };
+}
 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) => {
+  program.command("init").description("Set up the btcr2 home: create the directory, a default config, and establish the keystore.").option(
+    "-n, --network <network>",
+    "Bitcoin network to record as defaults.network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest>"
+  ).option("--dev", "Establish an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only.", false).option("--force", "Re-create the config even if it already exists (never the keystore).", 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".
-`
+    const network = options.network ? assertSupportedNetwork(options.network) : void 0;
+    const result = runInit(g, { dev: options.dev, force: options.force, network });
+    print({
+      action: "init",
+      data: {
+        home: result.home,
+        config: result.config,
+        keystore: result.keystore,
+        network: result.network,
+        created: result.created,
+        protection: result.protection
+      }
+    });
+    if (!g.quiet && g.output !== "json") {
+      process.stderr.write(`btcr2 home ready at ${result.home} on ${result.network}. Next: btcr2 key generate --set-active
+`);
+    }
+  });
+}
+
+// src/commands/quickstart.ts
+var import_api2 = require("@did-btcr2/api");
+
+// src/commands/keystore.ts
+var import_node_fs8 = 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_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 (!keystoreExists) {
-      if (options.dev && !g.quiet) {
+    if ((0, import_node_fs8.existsSync)(path) && options.force && !g.quiet) {
+      const { keyCount } = keystoreSummary(path);
+      if (keyCount > 0) {
         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"
+          `warning: re-establishing the keystore at ${path} permanently discards its ${keyCount} existing key(s).
+`
         );
       }
-      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 (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 ttlMs = resolveSessionTtl(options.ttl);
+    const session = unlockSession({
+      g,
+      keystorePath: path,
+      network: resolveDefaultNetwork(g),
+      allowMainnet: !!options.allowMainnet,
+      ttlMs
+    });
+    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 unlockSession(input) {
+  const { g, keystorePath: path, network, allowMainnet, ttlMs } = input;
+  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 (!allowMainnet && network === "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 passphrase = input.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 });
+  }
+  return writeSession(defaultSessionPath(g), {
+    keystorePath: path,
+    verifierId,
+    passphrase,
+    ttlMs,
+    allowMainnet
+  });
+}
+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/quickstart.ts
+var QUICKSTART_DEFAULT_NETWORK = "mutinynet";
+function registerQuickstartCommand(program, globals) {
+  const print = (result) => console.log(formatResult(result, globals()));
+  program.command("quickstart").description("One-command onboarding: create the home + config + keystore, record the network, and (optionally) cache the session and probe endpoints.").option(
+    "-n, --network <network>",
+    "Bitcoin network to set up <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> (default: mutinynet)"
+  ).option("--dev", "Establish an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only.", false).option("--unlock", "Cache the passphrase for the session so later commands do not re-prompt (ADR 081).", false).option("--ttl <duration>", `Session lifetime with --unlock: bare seconds or an s/m/h suffix (default 1h, max 24h). Also $${ENV_KEYSTORE_TTL}.`).option("--no-doctor", "Skip the endpoint reachability probe.").option("--allow-mainnet", "Permit -n bitcoin (records mainnet as the default; dev keystores are still refused).", false).option("--force", "Re-create the config even if it already exists (never the keystore).", false).action(async (options) => {
+    const g = globals();
+    const explicit = options.network ? assertSupportedNetwork(options.network) : void 0;
+    const network = explicit ?? readConfiguredDefaultNetwork(g) ?? QUICKSTART_DEFAULT_NETWORK;
+    if (network === "bitcoin") {
+      if (options.dev) {
+        throw new CLIError(
+          "Refusing to quickstart a mainnet (bitcoin) dev keystore: dev keystores store keys in plaintext and never operate on mainnet. Drop --dev, or choose a testnet with -n.",
+          "MAINNET_QUICKSTART_REFUSED_ERROR",
+          { network }
+        );
+      }
+      if (!options.allowMainnet) {
+        throw new CLIError(
+          "Refusing to quickstart on mainnet (bitcoin) without --allow-mainnet. Pass --allow-mainnet to record mainnet as the default, or choose a testnet with -n (the default is mutinynet).",
+          "MAINNET_QUICKSTART_REFUSED_ERROR",
+          { network }
+        );
+      }
+    }
+    const init = runInit(g, {
+      dev: options.dev,
+      force: options.force,
+      network: explicit,
+      fallbackNetwork: explicit ? void 0 : QUICKSTART_DEFAULT_NETWORK,
+      captureEstablishedPassphrase: !!options.unlock && !options.dev
+    });
+    let unlocked = false;
+    let session;
+    if (options.unlock && !options.dev) {
+      const outcome = cacheSession(g, init, options.ttl, !!options.allowMainnet);
+      unlocked = outcome.unlocked;
+      session = outcome.session;
+    }
+    let doctor;
+    if (options.doctor) {
+      doctor = await runDoctor(init.network, g);
+    }
+    print({
+      action: "quickstart",
+      data: {
+        home: init.home,
+        config: init.config,
+        keystore: init.keystore,
+        network: init.network,
+        created: init.created,
+        protection: init.protection,
+        unlocked,
+        ...session ? { session } : {},
+        ...doctor ? { doctor } : {}
+      }
+    });
     if (!g.quiet && g.output !== "json") {
-      process.stderr.write(`btcr2 home ready at ${home}. Next: btcr2 key generate --set-active
-`);
+      printNextSteps(init, unlocked, session, doctor);
     }
   });
 }
+function cacheSession(g, init, ttlFlag, allowMainnet) {
+  const ttlMs = resolveSessionTtl(ttlFlag);
+  const freshlyEstablished = init.created.includes("keystore");
+  if (!freshlyEstablished) {
+    const status = readSessionStatus(defaultSessionPath(g), init.keystore, keystoreVerifierId(init.keystore));
+    if (status.active && status.expiresAt !== void 0) {
+      return { unlocked: true, session: { expiresAt: status.expiresAt, ttlSeconds: status.secondsRemaining ?? 0 } };
+    }
+  }
+  try {
+    const written = unlockSession({
+      g,
+      keystorePath: init.keystore,
+      network: init.network,
+      allowMainnet,
+      ttlMs,
+      // Reuse the establish-time passphrase on a fresh keystore: no second prompt.
+      passphrase: freshlyEstablished ? init.establishedPassphrase : void 0
+    });
+    return { unlocked: true, session: { expiresAt: written.expiresAt, ttlSeconds: written.ttlSeconds } };
+  } catch (error) {
+    const type = error.type;
+    if (!freshlyEstablished && !process.stdin.isTTY && type === "PASSPHRASE_REQUIRED_ERROR") {
+      if (!g.quiet) {
+        process.stderr.write(
+          'note: no passphrase source and no terminal; skipped caching the session. Run "btcr2 keystore unlock" later to cache it.\n'
+        );
+      }
+      return { unlocked: false };
+    }
+    throw error;
+  }
+}
+function printNextSteps(init, unlocked, session, doctor) {
+  const lines = [`btcr2 home ready at ${init.home} on ${init.network}.`];
+  if (unlocked && session) {
+    lines.push(`Session cached until ${new Date(session.expiresAt).toISOString()}; signing will not re-prompt until it expires.`);
+  }
+  if (init.protection === "dev") {
+    lines.push("Dev keystore: keys are stored in plaintext; mainnet operations are refused.");
+  }
+  if (doctor && doctor.checks.some((c) => !c.ok)) {
+    lines.push('Warning: one or more endpoints were unreachable (see the doctor report). Re-run "btcr2 config doctor" for detail.');
+  }
+  lines.push("Next: btcr2 key generate --name demo --set-active");
+  const faucet = (0, import_api2.faucetUrl)(init.network);
+  if (faucet) lines.push(`Faucet (fund your beacon after "btcr2 create"): ${faucet}`);
+  process.stderr.write(`${lines.join("\n")}
+`);
+}
 
 // src/commands/create.ts
-var import_utils3 = require("@noble/hashes/utils.js");
+var import_utils4 = require("@noble/hashes/utils.js");
+
+// src/hints.ts
+var import_api3 = require("@did-btcr2/api");
+var import_method2 = require("@did-btcr2/method");
+function printCreateFundingHint(g, network, did) {
+  if (g.quiet || g.output === "json") return;
+  const faucet = (0, import_api3.faucetUrl)(network);
+  if (!faucet) return;
+  let beaconAddress;
+  try {
+    const { serviceEndpoint } = import_method2.BeaconUtils.createBeaconService(did, "p2wpkh", "SingletonBeacon");
+    beaconAddress = serviceEndpoint.replace(/^bitcoin:/, "");
+  } catch {
+    return;
+  }
+  const explorer = (0, import_api3.explorerAddressUrl)(network, beaconAddress);
+  const lines = [
+    "Fund the initial beacon to anchor updates:",
+    `  Beacon:   ${beaconAddress}`,
+    `  Faucet:   ${faucet}`
+  ];
+  if (explorer) lines.push(`  Explorer: ${explorer}`);
+  process.stderr.write(`${lines.join("\n")}
+`);
+}
+function printWatchHint(g, network, txid) {
+  if (g.quiet || g.output === "json") return;
+  const url = (0, import_api3.explorerTxUrl)(network, txid);
+  if (url) process.stderr.write(`Watch: ${url}
+`);
+}
 
 // src/keystore/resolve-key-ref.ts
 function fingerprintOf(id) {
@@ -1634,6 +2201,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
       const genesisBytes = parseGenesisBytes(options.bytes, "k");
       const did2 = factory().createDid("deterministic", genesisBytes, { network });
       print({ action: "create", data: did2 });
+      printCreateFundingHint(g, network, did2);
       return;
     }
     if (signingKey) {
@@ -1642,19 +2210,21 @@ 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_utils3.bytesToHex)(publicKey2) },
+        { action: "create", data: did2, keyId: keyId2, publicKey: (0, import_utils4.bytesToHex)(publicKey2) },
         `Using stored key ${keyId2}.`
       );
+      printCreateFundingHint(g, network, did2);
       return;
     }
     assertKeystoreAllowedForNetwork(network, overrides);
     const api = keystoreFactory(void 0, overrides);
     const { did, keyId } = api.generateDid({ network, setActive: true });
-    const publicKey = (0, import_utils3.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).`
     );
+    printCreateFundingHint(g, network, did);
   });
 }
 function overridesFromGlobals(g) {
@@ -1681,7 +2251,7 @@ function parseGenesisBytes(hex, type) {
   const expected = EXPECTED_BYTES[type];
   let bytes;
   try {
-    bytes = (0, import_utils3.hexToBytes)(hex.trim());
+    bytes = (0, import_utils4.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(
       `Invalid bytes: not valid hex. Expected ${expected.label}.`,
@@ -1700,7 +2270,7 @@ function parseGenesisBytes(hex, type) {
 }
 
 // src/commands/resolve.ts
-var import_api2 = require("@did-btcr2/api");
+var import_api4 = require("@did-btcr2/api");
 var import_promises = require("fs/promises");
 function registerResolveCommand(program, factory, globals) {
   program.command("resolve").alias("read").description("Resolve the DID document of the identifier.").requiredOption("-i, --identifier <identifier>", "did:btcr2 identifier").option("-r, --resolution-options <json>", "JSON string containing resolution options").option("-p, --resolution-options-path <path>", "Path to a JSON file containing resolution options").action(async (options) => {
@@ -1713,7 +2283,7 @@ function registerResolveCommand(program, factory, globals) {
   });
 }
 async function validateResolveOptions(options) {
-  import_api2.Identifier.decode(options.identifier);
+  import_api4.Identifier.decode(options.identifier);
   let resolutionOptions = void 0;
   if (options.resolutionOptions) {
     try {
@@ -1815,6 +2385,7 @@ function registerUpdateCommand(program, factory, globals) {
       ...broadcastOptions ? { broadcastOptions } : {}
     });
     console.log(formatResult({ action: "update", data }, globals()));
+    printWatchHint(globals(), network, data.txid);
   });
 }
 function parsePublishToCasMode(value) {
@@ -1913,6 +2484,7 @@ function registerDeactivateCommand(program, factory, globals) {
       ...broadcastOptions ? { broadcastOptions } : {}
     });
     console.log(formatResult({ action: "deactivate", data }, globals()));
+    printWatchHint(globals(), network, data.txid);
   });
 }
 function parsePublishToCasMode2(value) {
@@ -1941,8 +2513,8 @@ function parseJsonArg2(flagName) {
 
 // src/commands/key.ts
 var import_keypair = require("@did-btcr2/keypair");
-var import_utils4 = require("@noble/hashes/utils.js");
-var import_node_fs7 = require("fs");
+var import_utils5 = require("@noble/hashes/utils.js");
+var import_node_fs9 = 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()));
@@ -1951,7 +2523,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_utils4.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;
@@ -1971,7 +2543,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_utils4.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)) {
@@ -1982,13 +2554,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_utils4.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_utils4.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) {
@@ -1999,7 +2571,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_utils4.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) => {
@@ -2024,7 +2596,7 @@ function assertNameAvailable(kms, name) {
 function parseHex(hex, expectedBytes, label) {
   let bytes;
   try {
-    bytes = (0, import_utils4.hexToBytes)(hex.trim());
+    bytes = (0, import_utils5.hexToBytes)(hex.trim());
   } catch {
     throw new CLIError(`Invalid hex for ${label}.`, "INVALID_ARGUMENT_ERROR", { label });
   }
@@ -2040,7 +2612,7 @@ function parseHex(hex, expectedBytes, label) {
 function readHexFile(path, expectedBytes, label) {
   let content;
   try {
-    content = (0, import_node_fs7.readFileSync)(path, "utf-8");
+    content = (0, import_node_fs9.readFileSync)(path, "utf-8");
   } catch {
     throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
   }
@@ -2049,7 +2621,7 @@ function readHexFile(path, expectedBytes, label) {
 function writeSecretFile(path, contents) {
   let fd;
   try {
-    fd = (0, import_node_fs7.openSync)(path, "wx", 384);
+    fd = (0, import_node_fs9.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 });
@@ -2057,79 +2629,14 @@ function writeSecretFile(path, contents) {
     throw error;
   }
   try {
-    (0, import_node_fs7.writeFileSync)(fd, contents);
+    (0, import_node_fs9.writeFileSync)(fd, contents);
   } finally {
-    (0, import_node_fs7.closeSync)(fd);
+    (0, import_node_fs9.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");
+var import_node_fs10 = require("fs");
 
 // src/config-schema.ts
 var CONFIG_SCHEMA = {
@@ -2258,7 +2765,7 @@ function registerConfigCommand(program, 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_fs9.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 });
     }
     writeDefaultConfigFile(p);
@@ -2439,18 +2946,18 @@ function completionScript(shell) {
 }
 
 // src/version.ts
-var import_node_fs10 = require("fs");
-var import_node_path5 = require("path");
+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_path5.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+  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_fs10.readFileSync)((0, import_node_path5.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 {
     }
-    dir = (0, import_node_path5.dirname)(dir);
+    dir = (0, import_node_path6.dirname)(dir);
   }
   return "0.0.0";
 }
@@ -2481,6 +2988,7 @@ var DidBtcr2Cli = class {
       opts.output = resolveOutputFormat({ output: opts.output, config: opts.config, home: opts.home });
     });
     registerInitCommand(this.program, globals);
+    registerQuickstartCommand(this.program, globals);
     registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
     registerUpdateCommand(this.program, keystoreFactory, globals);
@@ -2537,6 +3045,7 @@ function handleError(error, verbose) {
   SUPPORTED_NETWORKS,
   VERSION,
   assertKeystoreAllowedForNetwork,
+  assertSupportedNetwork,
   blankToUndef,
   defaultApiFactory,
   defaultConfigPath,
@@ -2547,9 +3056,11 @@ function handleError(error, verbose) {
   keystoreApiFactory,
   parseConfigFileRaw,
   parseHeaderList,
+  persistDefaultNetwork,
   profileNetworkMismatch,
   profileToOverrides,
   readConfigFile,
+  readConfiguredDefaultNetwork,
   readEnvOverrides,
   redactSecrets,
   registerCompletionCommand,
@@ -2560,6 +3071,7 @@ function handleError(error, verbose) {
   registerKeyCommand,
   registerKeystoreCommand,
   registerProfileCommand,
+  registerQuickstartCommand,
   registerResolveCommand,
   registerUpdateCommand,
   resolveActiveProfile,