@did-btcr2/cli 0.16.0 → 0.17.0

package/dist/cjs/index.js

@@ -82,13 +82,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 +167,7 @@ var import_key_manager = require("@did-btcr2/key-manager");
 // src/keystore/file-key-store.ts
 var import_node_fs3 = require("fs");
 var import_node_path3 = require("path");
+var import_sha2 = require("@noble/hashes/sha2.js");
 var import_utils2 = require("@noble/hashes/utils.js");
 var import_base2 = require("@scure/base");
 
@@ -360,6 +361,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 +378,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 +835,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 +954,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 +1024,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 +1182,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 +1247,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(
@@ -1264,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}`,
@@ -1398,13 +1573,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 +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) {
@@ -1501,11 +1691,11 @@ function registerInitCommand(program, globals) {
     const keystorePath = resolveKeystorePath(g);
     ensureDir(home, 448);
     const created = [];
-    if (!(0, import_node_fs6.existsSync)(configPath) || options.force) {
+    if (!(0, import_node_fs7.existsSync)(configPath) || options.force) {
       writeDefaultConfigFile(configPath);
       created.push("config");
     }
-    const keystoreExists = (0, import_node_fs6.existsSync)(keystorePath);
+    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".
@@ -1522,6 +1712,7 @@ function registerInitCommand(program, globals) {
         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;
@@ -1534,7 +1725,7 @@ function registerInitCommand(program, globals) {
 }
 
 // src/commands/create.ts
-var import_utils3 = require("@noble/hashes/utils.js");
+var import_utils4 = require("@noble/hashes/utils.js");
 
 // src/keystore/resolve-key-ref.ts
 function fingerprintOf(id) {
@@ -1642,7 +1833,7 @@ 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}.`
       );
       return;
@@ -1650,7 +1841,7 @@ function registerCreateCommand(program, factory, keystoreFactory, globals) {
     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).`
@@ -1681,7 +1872,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}.`,
@@ -1941,8 +2132,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_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()));
@@ -1951,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_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 +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_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 +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_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 +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_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 +2215,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 +2231,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_fs8.readFileSync)(path, "utf-8");
   } catch {
     throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
   }
@@ -2049,7 +2240,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_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 });
@@ -2057,28 +2248,28 @@ function writeSecretFile(path, contents) {
     throw error;
   }
   try {
-    (0, import_node_fs7.writeFileSync)(fd, contents);
+    (0, import_node_fs8.writeFileSync)(fd, contents);
   } finally {
-    (0, import_node_fs7.closeSync)(fd);
+    (0, import_node_fs8.closeSync)(fd);
   }
 }
 
 // src/commands/keystore.ts
-var import_node_fs8 = require("fs");
+var import_node_fs9 = require("fs");
 function registerKeystoreCommand(program, globals) {
-  const keystore = program.command("keystore").description("Establish, inspect, and re-key the keystore.");
+  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) {
+    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_fs8.existsSync)(path) && options.force && !g.quiet) {
+    if ((0, import_node_fs9.existsSync)(path) && options.force && !g.quiet) {
       const { keyCount } = keystoreSummary(path);
       if (keyCount > 0) {
         process.stderr.write(
@@ -2096,16 +2287,18 @@ function registerKeystoreCommand(program, globals) {
       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, and key count. Never decrypts or prompts.").action(() => {
+  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 } });
+    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();
@@ -2124,12 +2317,87 @@ function registerKeystoreCommand(program, globals) {
     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_fs9 = require("fs");
+var import_node_fs10 = require("fs");
 
 // src/config-schema.ts
 var CONFIG_SCHEMA = {
@@ -2258,7 +2526,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 +2707,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";
 }

package/dist/esm/src/commands/init.js

@@ -3,8 +3,9 @@ import { defaultConfigPath, resolveKeystorePath, writeDefaultConfigFile } from '
 import { ensureDir } from '../keystore/atomic.js';
 import { initKeystore, keystoreSummary } from '../keystore/file-key-store.js';
 import { acquirePassphrase } from '../keystore/passphrase.js';
+import { clearSession } from '../keystore/session.js';
 import { formatResult } from '../output.js';
-import { resolveHome } from '../paths.js';
+import { defaultSessionPath, resolveHome } from '../paths.js';
 /**
  * Registers the top-level `btcr2 init`: the one-command entry point that creates
  * the btcr2 home (ADR 079), writes a default config if none exists, and
@@ -51,6 +52,11 @@ export function registerInitCommand(program, globals) {
                 protection: options.dev ? 'none' : 'passphrase',
                 getPassphrase: (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: 'New keystore passphrase: ' }),
             });
+            // A freshly established keystore mints a new verifier (or none, for --dev),
+            // so any cached session holds a passphrase for a keystore that no longer
+            // exists. Drop it, matching `keystore init` / `change-passphrase`, rather
+            // than leave a stale plaintext passphrase behind (ADR 081).
+            clearSession(defaultSessionPath(g));
             created.push('keystore');
         }
         const protection = keystoreSummary(keystorePath).protection;

package/dist/esm/src/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../../src/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../../src/commands/init.ts"],"names":[],"mappings":"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"}