@did-btcr2/cli 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "CLI for interacting with did-btcr2-js, the JavaScript/TypeScript reference implementation of the did:btcr2 method. Exposes various parts of multiple packages in the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -62,10 +62,10 @@
     "@web5/dids": "^1.2.0",
     "commander": "^13.1.0",
     "@did-btcr2/api": "^0.16.1",
-    "@did-btcr2/keypair": "^0.13.1",
-    "@did-btcr2/common": "^9.1.0",
     "@did-btcr2/key-manager": "^0.7.0",
-    "@did-btcr2/method": "^0.54.1"
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/method": "^0.54.1",
+    "@did-btcr2/keypair": "^0.13.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",

package/src/commands/init.ts

@@ -4,8 +4,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';
 import type { CommandResult, GlobalOptions } from '../types.js';
 
 /**
@@ -62,6 +63,11 @@ export function registerInitCommand(program: Command, globals: () => GlobalOptio
           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');
       }
 

package/src/commands/keystore.ts

@@ -1,20 +1,37 @@
 import type { Command } from 'commander';
 import { existsSync } from 'node:fs';
-import { resolveKeystorePath } from '../config.js';
+import { resolveDefaultNetwork, resolveKeystorePath } from '../config.js';
 import { CLIError } from '../error.js';
-import { changeKeystorePassphrase, initKeystore, keystoreSummary } from '../keystore/file-key-store.js';
+import {
+  changeKeystorePassphrase,
+  initKeystore,
+  keystoreSummary,
+  keystoreVerifierId,
+  verifyKeystorePassphrase,
+} from '../keystore/file-key-store.js';
 import { acquirePassphrase } from '../keystore/passphrase.js';
+import {
+  clearSession,
+  DEFAULT_SESSION_TTL_MS,
+  ENV_KEYSTORE_TTL,
+  MAX_SESSION_TTL_MS,
+  parseTtlToMs,
+  readSessionStatus,
+  writeSession,
+} from '../keystore/session.js';
 import { formatResult } from '../output.js';
-import type { CommandResult, GlobalOptions } from '../types.js';
+import { defaultSessionPath } from '../paths.js';
+import { blankToUndef, type CommandResult, type GlobalOptions } from '../types.js';
 
 /**
  * Registers the `keystore` command group: establish, inspect, and re-key the
- * encrypted keystore (ADR 080). These operate on the keystore file directly (no
- * Bitcoin connection or KeyManager) and never decrypt a key except when
- * re-sealing during `change-passphrase`.
+ * encrypted keystore (ADR 080), plus the session unlock agent (ADR 081). These
+ * operate on the keystore and session files directly (no Bitcoin connection or
+ * KeyManager) and never decrypt a key except when re-sealing during
+ * `change-passphrase`.
  */
 export function registerKeystoreCommand(program: Command, globals: () => GlobalOptions): void {
-  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: CommandResult): void => console.log(formatResult(result, globals()));
 
   keystore
@@ -51,22 +68,27 @@ export function registerKeystoreCommand(program: Command, globals: () => GlobalO
         protection    : options.dev ? 'none' : 'passphrase',
         getPassphrase : (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: 'New keystore passphrase: ' }),
       });
+      // A re-established keystore mints a new verifier (or none, for --dev), so any
+      // cached session now holds a passphrase for a keystore that no longer exists.
+      // Drop it rather than leave a stale plaintext passphrase behind (ADR 081).
+      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.')
+    .description('Show the keystore path, protection mode, key count, and session state. Never decrypts or prompts.')
     .action(() => {
       const g = globals();
       // Diagnostic command: report status even when the config is malformed,
       // rather than crashing on the config you ran this to inspect.
       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
@@ -93,6 +115,118 @@ export function registerKeystoreCommand(program: Command, globals: () => GlobalO
       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);
+      // The rotated verifier already invalidates a cached session by fingerprint,
+      // but the session file still holds the OLD passphrase in plaintext; delete it.
+      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: { ttl?: string; allowMainnet?: boolean }) => {
+      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 },
+        );
+      }
+      // An unlocked encrypted keystore signs prompt-free for the whole TTL,
+      // silently removing per-use passphrase auth. Two guards, both keyed to
+      // --allow-mainnet (ADR 081): this early refusal when the *configured* default
+      // network is mainnet (a clear signal before caching anything), plus the
+      // authoritative one at consumption, where the session records `allowMainnet`
+      // (below) and a `bitcoin` operation, whose network is derived from the DID
+      // rather than the config, is withheld from a session that lacks it. The
+      // active network defaults to a testnet, so this early refusal never fires
+      // for the demo.
+      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);
+      // Acquire the passphrase directly (env / file / prompt) with NO session
+      // consultation and NO confirm, verify it against the keystore verifier, and
+      // only then cache it. A wrong passphrase writes no session file.
+      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) {
+        // An established keystore always carries a verifier; defensive guard.
+        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();
+      // Resolve the session from the home only (defaultSessionPath never reads the
+      // config), so lock revokes even under a malformed config.
+      const sessionPath = defaultSessionPath(g);
+      const cleared = clearSession(sessionPath);
+      print({ action: 'keystore-lock', data: { path: sessionPath, cleared } });
+    });
+}
+
+/**
+ * Resolves the session TTL in milliseconds from the `--ttl` flag, then
+ * `$BTCR2_KEYSTORE_TTL`, then the one-hour default. Rejects a non-positive,
+ * malformed, or over-24h value with a {@link CLIError} that names the actual
+ * source (the flag or the env var) so the operator fixes the right input.
+ */
+function resolveSessionTtl(flag?: string): number {
+  const fromFlag = blankToUndef(flag);
+  const raw = fromFlag ?? blankToUndef(process.env[ENV_KEYSTORE_TTL]);
+  if (raw === undefined) return DEFAULT_SESSION_TTL_MS;
+  const source = fromFlag !== undefined ? '--ttl' : `$${ENV_KEYSTORE_TTL}`;
+  const ms = parseTtlToMs(raw);
+  if (ms === undefined || 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;
 }

package/src/config.ts

@@ -7,10 +7,11 @@ import { dirname } from 'node:path';
 import { CLIError } from './error.js';
 import { ensureDir, writeFileAtomic } from './keystore/atomic.js';
 import { FileBackedKeyManager } from './keystore/file-backed-key-manager.js';
-import { keystoreProtection } from './keystore/file-key-store.js';
+import { keystoreProtection, keystoreVerifierId } from './keystore/file-key-store.js';
 import { defaultKeystorePath } from './keystore/paths.js';
 import { acquirePassphrase } from './keystore/passphrase.js';
-import { defaultConfigPath } from './paths.js';
+import { readLiveSessionPassphrase } from './keystore/session.js';
+import { defaultConfigPath, defaultSessionPath } from './paths.js';
 import { blankToUndef, SUPPORTED_NETWORKS, type KeystoreProtectionLabel, type NetworkOption, type OutputFormat } from './types.js';
 
 export { defaultConfigPath };
@@ -947,13 +948,34 @@ export function defaultApiFactory(network?: NetworkOption, overrides?: Connectio
  * or opened. The persisted active-key pointer is re-applied (a non-decrypting
  * existence check) so "the active key" survives across invocations.
  */
-function buildKeystoreKms(overrides?: ConnectionOverrides): KeyManager {
+function buildKeystoreKms(overrides?: ConnectionOverrides, network?: NetworkOption): KeyManager {
+  const keystorePath = resolveKeystorePath(overrides);
+  const sessionPath = defaultSessionPath(overrides);
+  // The network the operation will sign under, known here because the factory
+  // receives it. A `bitcoin` operation must not consume a session that was not
+  // unlocked with `--allow-mainnet`, so mainnet keeps per-use authentication even
+  // while a session is live (ADR 081). Key commands pass no network, so the
+  // session serves them as before.
+  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 : (): string | undefined =>
+          readLiveSessionPassphrase(sessionPath, keystorePath, keystoreVerifierId(keystorePath), isMainnetOperation),
+      }),
+    }),
   });
 }
 
@@ -1048,7 +1070,7 @@ export function resolveSigningKeyRef(overrides?: ConnectionOverrides): string |
 export function keystoreApiFactory(network?: NetworkOption, overrides?: ConnectionOverrides): DidBtcr2Api {
   return createApi({
     ...resolveConnectionConfig(network, overrides),
-    kms : buildKeystoreKms(overrides),
+    kms : buildKeystoreKms(overrides, network),
   });
 }
 

package/src/keystore/file-key-store.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { KeyEntry, KeyIdentifier, KeyValueStore } from '@did-btcr2/key-manager';
+import { sha256 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes } from '@noble/hashes/utils.js';
 import { base64urlnopad } from '@scure/base';
 import type { KeystoreProtectionLabel } from '../types.js';
@@ -664,6 +665,48 @@ export function keystoreProtection(path: string): KeystoreProtectionLabel {
   return keystoreSummary(path).protection;
 }
 
+/**
+ * A stable fingerprint of a keystore's passphrase verifier, or `undefined` when
+ * the file is absent, unparsable, or carries no verifier. Compared by equality
+ * to detect a rotated passphrase (`change-passphrase`, `init --force`) or a
+ * re-established keystore, so a cached session (ADR 081) stops matching a
+ * keystore whose passphrase has changed. Never decrypts, never throws.
+ */
+export function keystoreVerifierId(path: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  let parsed: KeystoreFile;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as KeystoreFile;
+  } catch {
+    return undefined;
+  }
+  if (!parsed.verifier) return undefined;
+  return base64urlnopad.encode(sha256(utf8ToBytes(JSON.stringify(parsed.verifier))));
+}
+
+/**
+ * Checks a candidate passphrase against the keystore's verifier without
+ * constructing a store or opening any key. Returns `false` for an absent,
+ * unparsable, dev, or verifier-less keystore and for a wrong passphrase; `true`
+ * only when the passphrase opens the verifier sentinel. Never throws. Used by
+ * `keystore unlock` (ADR 081) to refuse caching a wrong passphrase.
+ */
+export function verifyKeystorePassphrase(path: string, passphrase: string): boolean {
+  if (!existsSync(path)) return false;
+  let parsed: KeystoreFile;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as KeystoreFile;
+  } catch {
+    return false;
+  }
+  if (parsed.protection !== 'passphrase' || !parsed.verifier) return false;
+  try {
+    return bytesEqual(decryptSecret(parsed.verifier, passphrase), VERIFIER_PLAINTEXT);
+  } catch {
+    return false;
+  }
+}
+
 /** Options for {@link initKeystore}. */
 export interface InitKeystoreOptions {
   protection    : KeystoreProtection;

package/src/keystore/passphrase.ts

@@ -19,6 +19,16 @@ export type PassphraseOptions = {
    * satisfy the new one (which would make the change a no-op).
    */
   forcePrompt?: boolean;
+  /**
+   * An optional non-interactive source consulted *after* the env var and
+   * passphrase file and *before* the terminal prompt (and before the "no TTY"
+   * failure). The session unlock agent (ADR 081) wires this to a cached
+   * passphrase, so a returning command consumes the session instead of
+   * prompting, and a non-interactive follow-on command does not hard-fail. It
+   * returns `undefined` when no session is available. Skipped when `forcePrompt`
+   * is set, and never wired during passphrase establishment (`confirm`).
+   */
+  beforePrompt?: () => string | undefined;
 };
 
 /**
@@ -39,6 +49,19 @@ export function acquirePassphrase(options: PassphraseOptions = {}): string {
     if (options.passphraseFile) {
       return assertNonEmpty(readFileSync(options.passphraseFile, 'utf-8').replace(/\r?\n$/, ''));
     }
+
+    // A cached session (ADR 081) sits below the env var and file but above the
+    // interactive prompt, so it is consulted before the "no TTY" failure: a
+    // scripted or piped follow-on command consumes the session instead of
+    // hard-failing. Establishment never reaches here (its caller omits it).
+    //
+    // The session already holds the exact, keystore-verified passphrase (encoded
+    // and decoded byte-for-byte), not a raw source needing newline normalization.
+    // Return it verbatim: re-stripping a trailing newline here would corrupt the
+    // KDF input for a passphrase that legitimately ends in one, even though unlock
+    // itself succeeded. assertNonEmpty is a defensive guard only.
+    const fromSession = options.beforePrompt?.();
+    if (fromSession) return assertNonEmpty(fromSession);
   }
 
   if (!process.stdin.isTTY) {