@did-btcr2/cli 0.16.0 → 0.18.0

package/src/commands/update.ts

@@ -3,6 +3,7 @@ import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
 import { assertKeystoreAllowedForNetwork, deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
+import { printWatchHint } from '../hints.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
 import type { GlobalOptions, UpdateCommandOptions } from '../types.js';
@@ -117,6 +118,7 @@ export function registerUpdateCommand(
         ...(broadcastOptions ? { broadcastOptions } : {}),
       });
       console.log(formatResult({ action: 'update', data }, globals()));
+      printWatchHint(globals(), network, data.txid);
     });
 }
 

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 };
@@ -397,6 +398,81 @@ export function resolveDefaultNetwork(overrides?: ConnectionOverrides): NetworkO
   return 'regtest';
 }
 
+/**
+ * The network recorded at `defaults.network` in the config file, validated, or
+ * `undefined` when the file is absent, malformed, or the value is unset/unknown.
+ * Unlike {@link resolveDefaultNetwork} this consults ONLY the raw
+ * `defaults.network` (no profile fallback, no regtest default), so `quickstart`
+ * can distinguish "the operator set a default" from "there is none yet" before
+ * it writes (ADR 083). Never throws: a malformed config is surfaced loudly by
+ * the write path, so this pre-write read stays quiet.
+ */
+export function readConfiguredDefaultNetwork(overrides?: ConnectionOverrides): NetworkOption | undefined {
+  const configPath = overrides?.config ?? defaultConfigPath(overrides);
+  let raw: Record<string, unknown> | undefined;
+  try {
+    raw = parseConfigFileRaw(configPath);
+  } catch {
+    return undefined;
+  }
+  const value = raw ? getConfigPath(raw, 'defaults.network') : undefined;
+  return typeof value === 'string' && SUPPORTED_NETWORKS.includes(value as NetworkOption)
+    ? value as NetworkOption
+    : undefined;
+}
+
+/**
+ * Persists `defaults.network` idempotently and returns the resolved network,
+ * the shared network-recording step behind `btcr2 init -n` and `btcr2 quickstart`
+ * (ADR 083). Writes when `explicit` (an explicit `-n`) is given, or when a
+ * `fallback` is given and the raw config has no `defaults.network` yet. Keyed on
+ * the **raw** file value (not {@link resolveDefaultNetwork}, which never returns
+ * undefined), so a defaulted re-run never clobbers a network the operator set
+ * earlier. When neither condition writes, the existing default is returned
+ * unchanged. Assumes `configPath` names a parseable config (the caller has just
+ * scaffolded one, or an existing one that a malformed-JSON read surfaces loudly).
+ */
+export function persistDefaultNetwork(
+  configPath : string,
+  opts       : { explicit?: NetworkOption; fallback?: NetworkOption; overrides?: ConnectionOverrides },
+): { network: NetworkOption; wrote: boolean } {
+  const raw = parseConfigFileRaw(configPath);
+  const rawValue = raw ? getConfigPath(raw, 'defaults.network') : undefined;
+  const rawNetwork = typeof rawValue === 'string' && SUPPORTED_NETWORKS.includes(rawValue as NetworkOption)
+    ? rawValue as NetworkOption
+    : undefined;
+
+  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 };
+}
+
+/**
+ * Validates an explicit network string against {@link SUPPORTED_NETWORKS},
+ * returning it typed as a {@link NetworkOption} or throwing a {@link CLIError}.
+ * Shared by the `-n/--network` flags on `init` and `quickstart` (ADR 083).
+ */
+export function assertSupportedNetwork(value: string): NetworkOption {
+  if (!SUPPORTED_NETWORKS.includes(value as NetworkOption)) {
+    throw new CLIError(
+      `Invalid network "${value}". Must be one of ${SUPPORTED_NETWORKS.join(', ')}.`,
+      'INVALID_ARGUMENT_ERROR',
+      { network: value },
+    );
+  }
+  return value as NetworkOption;
+}
+
 /**
  * Reports a coherence conflict between the network a `create` run is about to
  * encode and the network the active profile declares, so the CLI can warn
@@ -947,13 +1023,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 +1145,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/hints.ts

@@ -0,0 +1,51 @@
+import { explorerAddressUrl, explorerTxUrl, faucetUrl } from '@did-btcr2/api';
+import { BeaconUtils } from '@did-btcr2/method';
+import type { GlobalOptions, NetworkOption } from './types.js';
+
+/**
+ * Text-mode stderr hints derived from the per-network presets (ADR 082). All of
+ * these are suppressed under `--quiet` and `--output json` so machine output is
+ * never touched, and they never throw: a presentation hint must never break the
+ * command that produced the real result.
+ */
+
+/**
+ * Prints a funding hint after a KEY `create` on a network with a public faucet:
+ * the derived initial P2WPKH beacon address next to the faucet and explorer
+ * links the operator would otherwise hand-copy. A no-op on a network without a
+ * faucet (regtest/mainnet), which also keeps mainnet from showing a fund-me
+ * affordance. The beacon address is derived from the DID string alone via
+ * {@link BeaconUtils.createBeaconService}, so it matches the resolver's
+ * `#initialP2WPKH` service rather than a divergent re-derivation.
+ */
+export function printCreateFundingHint(g: GlobalOptions, network: NetworkOption, did: string): void {
+  if (g.quiet || g.output === 'json') return;
+  const faucet = faucetUrl(network);
+  if (!faucet) return;
+  let beaconAddress: string;
+  try {
+    const { serviceEndpoint } = BeaconUtils.createBeaconService(did, 'p2wpkh', 'SingletonBeacon');
+    beaconAddress = serviceEndpoint.replace(/^bitcoin:/, '');
+  } catch {
+    return;
+  }
+  const explorer = 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')}\n`);
+}
+
+/**
+ * Prints a watch link after an `update`/`deactivate` broadcast: the
+ * block-explorer URL for the signal txid. A no-op on a network without an
+ * explorer (regtest).
+ */
+export function printWatchHint(g: GlobalOptions, network: NetworkOption, txid: string): void {
+  if (g.quiet || g.output === 'json') return;
+  const url = explorerTxUrl(network, txid);
+  if (url) process.stderr.write(`Watch: ${url}\n`);
+}

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) {

package/src/keystore/session.ts

@@ -0,0 +1,303 @@
+import { closeSync, constants, existsSync, fstatSync, openSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+import { base64urlnopad } from '@scure/base';
+import { ensureDir, writeFileAtomic } from './atomic.js';
+
+/**
+ * The session unlock agent (ADR 081). `keystore unlock` caches the verified
+ * keystore passphrase in a single `<home>/session.json`, and subsequent commands
+ * read it in place of a prompt until it expires or `keystore lock` revokes it.
+ *
+ * This is an on-disk v1 design. The cached passphrase is base64url-*encoded*, not
+ * encrypted: its only protection at rest is the file's `0600` mode. That is the
+ * deliberate, documented cost of a portable, minimal-diff convenience; a future
+ * in-memory agent (v2) that never persists the secret is the real fix. Every read
+ * here is defensive and never throws, so a bad or hostile session degrades to a
+ * passphrase prompt rather than a crash.
+ */
+
+/** Current session-file format version. */
+export const SESSION_VERSION = 1 as const;
+
+/** Default session lifetime: one hour. */
+export const DEFAULT_SESSION_TTL_MS = 60 * 60 * 1000;
+/** Hard cap on a cached-passphrase lifetime: 24 hours. A longer TTL is refused. */
+export const MAX_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+/** Environment variable supplying a default TTL below the `--ttl` flag. */
+export const ENV_KEYSTORE_TTL = 'BTCR2_KEYSTORE_TTL';
+
+/**
+ * The on-disk session file. `passphrase` is base64url(utf8(passphrase)): an
+ * encoding, not encryption. `keystore` binds the session to one keystore, and
+ * `verifierId` (a hash of that keystore's verifier) invalidates the session when
+ * the passphrase is rotated. `allowMainnet` records whether the operator unlocked
+ * with `--allow-mainnet`; a session without it is withheld from a `bitcoin`
+ * operation so mainnet keeps per-use authentication (ADR 081). No derived key,
+ * keystore ciphertext, or signing-key bytes ever appear here.
+ */
+export interface SessionFile {
+  v            : typeof SESSION_VERSION;
+  keystore     : string;
+  verifierId   : string;
+  passphrase   : string;
+  allowMainnet : boolean;
+  createdAt    : number;
+  expiresAt    : number;
+  ttlSeconds   : number;
+}
+
+/** Inputs for {@link writeSession}. */
+export interface WriteSessionInput {
+  /** The keystore this session unlocks (stored resolved/normalized). */
+  keystorePath  : string;
+  /** Fingerprint of the keystore verifier, from `keystoreVerifierId`. */
+  verifierId    : string;
+  /** The verified passphrase to cache. */
+  passphrase    : string;
+  /** Lifetime in milliseconds. */
+  ttlMs         : number;
+  /**
+   * Whether this session may be consumed for a mainnet (`bitcoin`) operation,
+   * from the `unlock --allow-mainnet` flag. Defaults to `false` (deny), so
+   * mainnet operations fall through to a per-use passphrase prompt (ADR 081).
+   */
+  allowMainnet? : boolean;
+}
+
+/**
+ * Writes the session file atomically at `0600` (temp sibling + rename), returning
+ * the written record so the caller can report expiry without re-reading. The
+ * caller is responsible for verifying the passphrase first; this only persists it.
+ */
+export function writeSession(sessionPath: string, input: WriteSessionInput): SessionFile {
+  const createdAt = Date.now();
+  const session: SessionFile = {
+    v            : SESSION_VERSION,
+    keystore     : resolve(input.keystorePath),
+    verifierId   : input.verifierId,
+    passphrase   : base64urlnopad.encode(utf8ToBytes(input.passphrase)),
+    allowMainnet : input.allowMainnet ?? false,
+    createdAt,
+    expiresAt    : createdAt + input.ttlMs,
+    ttlSeconds   : Math.round(input.ttlMs / 1000),
+  };
+  ensureDir(dirname(sessionPath), 0o700);
+  writeFileAtomic(sessionPath, `${JSON.stringify(session, null, 2)}\n`, 0o600);
+  return session;
+}
+
+/**
+ * Deletes the session file and any crash-orphaned `writeFileAtomic` temp sibling
+ * (each of which would hold a plaintext passphrase). Idempotent; needs no
+ * passphrase. Returns whether a session file was present. Unlink is best-effort:
+ * it removes the name, it does not securely erase the bytes (see ADR 081).
+ */
+export function clearSession(sessionPath: string): boolean {
+  let existed = false;
+  try {
+    existed = existsSync(sessionPath);
+    if (existed) rmSync(sessionPath, { force: true });
+  } catch {
+    // Best effort: a session we cannot remove is reported as not-cleared below.
+    existed = false;
+  }
+  sweepSessionTemps(sessionPath);
+  return existed;
+}
+
+/** Removes `.session.json.<pid>.<n>.tmp` leftovers from an interrupted atomic write. */
+function sweepSessionTemps(sessionPath: string): void {
+  const dir = dirname(sessionPath);
+  const prefix = `.${basename(sessionPath)}.`;
+  try {
+    for (const name of readdirSync(dir)) {
+      if (name.startsWith(prefix) && name.endsWith('.tmp')) {
+        try {
+          rmSync(join(dir, name), { force: true });
+        } catch {
+          // A temp file we cannot remove is left for the next sweep.
+        }
+      }
+    }
+  } catch {
+    // Directory unreadable or absent: nothing to sweep.
+  }
+}
+
+/**
+ * Returns the cached passphrase for `keystorePath` when a live, matching session
+ * exists, else `undefined`. Never throws. A session that is expired, stale (the
+ * keystore passphrase rotated), future-dated, or malformed is pruned on read; a
+ * live session bound to a *different* keystore is left in place (it prompts for
+ * the current keystore instead).
+ *
+ * `isMainnetOperation` gates the one case the network is known at consumption: a
+ * live session that was not unlocked with `--allow-mainnet` is withheld from a
+ * `bitcoin` operation (returning `undefined` so the caller falls through to a
+ * per-use prompt) but *not* pruned, since it remains valid for the non-mainnet
+ * operations the operator unlocked for (ADR 081).
+ */
+export function readLiveSessionPassphrase(
+  sessionPath        : string,
+  keystorePath       : string,
+  currentVerifierId  : string | undefined,
+  isMainnetOperation = false,
+): string | undefined {
+  const verdict = evaluateSession(sessionPath, keystorePath, currentVerifierId, Date.now());
+  if (verdict.status === 'live') {
+    // Withhold a session lacking mainnet allowance from a mainnet operation, so
+    // signing a `bitcoin` DID still authenticates per use. Leave it in place: it
+    // is a valid session, just not for this operation (like a foreign keystore).
+    if (isMainnetOperation && !verdict.session.allowMainnet) return undefined;
+    try {
+      return Buffer.from(base64urlnopad.decode(verdict.session.passphrase)).toString('utf-8');
+    } catch {
+      clearSession(sessionPath);
+      return undefined;
+    }
+  }
+  // Prune a session that is dead for everyone or dead for this keystore. A
+  // 'foreign' (live, different keystore) or 'none' session is left untouched.
+  if (verdict.status === 'expired' || verdict.status === 'stale'
+    || verdict.status === 'future' || verdict.status === 'malformed') {
+    clearSession(sessionPath);
+  }
+  return undefined;
+}
+
+/** Public, redacted view of the session state for `keystore status`. Never emits the passphrase. */
+export interface SessionStatus {
+  active            : boolean;
+  expiresAt?        : number;
+  secondsRemaining? : number;
+  /** Whether the session may sign a mainnet operation prompt-free (unlocked with `--allow-mainnet`). */
+  allowMainnet?     : boolean;
+}
+
+/**
+ * Reports whether a live session exists for `keystorePath` and its remaining
+ * lifetime, without decrypting, prompting, throwing, or emitting the passphrase.
+ * An expired, foreign, stale, or malformed session reports inactive. Read-only:
+ * unlike {@link readLiveSessionPassphrase}, it does not prune.
+ */
+export function readSessionStatus(
+  sessionPath       : string,
+  keystorePath      : string,
+  currentVerifierId : string | undefined,
+): SessionStatus {
+  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) / 1000)),
+    allowMainnet     : verdict.session.allowMainnet,
+  };
+}
+
+/**
+ * Parses a TTL string into milliseconds: a bare integer is seconds; an `s`, `m`,
+ * or `h` suffix scales it. Returns `undefined` for any malformed input. The
+ * caller applies the default, the 24h cap, and the `<= 0` rejection.
+ */
+export function parseTtlToMs(raw: string): number | undefined {
+  const match = /^(\d+)([smh]?)$/.exec(raw.trim());
+  if (!match) return undefined;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n)) return undefined;
+  const unitMs = match[2] === 'h' ? 3_600_000 : match[2] === 'm' ? 60_000 : 1_000;
+  return n * unitMs;
+}
+
+/** The outcome of inspecting a session file against the current keystore and clock. */
+type SessionVerdict =
+  | { status: 'live'; session: SessionFile }
+  | { status: 'none' | 'foreign' | 'expired' | 'stale' | 'future' | 'malformed' };
+
+/**
+ * Classifies the session file: read it securely, then check version, shape,
+ * clock, keystore binding, and verifier fingerprint in that order. Ordering
+ * `expired` before `foreign` means an expired session is pruned regardless of
+ * which keystore it was for. Never throws.
+ */
+function evaluateSession(
+  sessionPath       : string,
+  keystorePath      : string,
+  currentVerifierId : string | undefined,
+  now               : number,
+): SessionVerdict {
+  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 (resolve(session.keystore) !== resolve(keystorePath)) return { status: 'foreign' };
+  if (currentVerifierId === undefined || session.verifierId !== currentVerifierId) return { status: 'stale' };
+  return { status: 'live', session };
+}
+
+/**
+ * Reads and parses the session file with a plaintext secret in mind. On POSIX,
+ * opens with `O_NOFOLLOW` (refusing a symlink) and refuses a non-regular file, a
+ * file not owned by this user, or one accessible by group or other, best-effort
+ * deleting a rejected file and reading only from the opened descriptor (no TOCTOU
+ * re-open). On Windows those POSIX guards are skipped (they would throw), so the
+ * file is read normally under the same directory ACL the keystore trusts, keeping
+ * the session usable rather than silently ignored. Returns `undefined` on any
+ * failure; never throws.
+ */
+function secureReadSession(sessionPath: string): SessionFile | undefined {
+  let raw: string;
+  if (process.platform === 'win32') {
+    try {
+      raw = readFileSync(sessionPath, 'utf-8');
+    } catch {
+      return undefined;
+    }
+  } else {
+    let fd: number;
+    try {
+      fd = openSync(sessionPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    } catch {
+      // ENOENT (no session), ELOOP (symlink refused by O_NOFOLLOW), or any other
+      // open failure: no usable session.
+      return undefined;
+    }
+    try {
+      const st = fstatSync(fd);
+      const myUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+      if (!st.isFile() || (myUid !== undefined && st.uid !== myUid) || (st.mode & 0o077) !== 0) {
+        // Not a regular file we own with 0600 perms: it was not written by this
+        // process. Best-effort remove it (it may hold a plaintext passphrase) and
+        // fall back to a prompt.
+        try {
+          rmSync(sessionPath, { force: true });
+        } catch {
+          // Cannot remove a file we do not own; ignoring it is enough.
+        }
+        return undefined;
+      }
+      raw = readFileSync(fd, 'utf-8');
+    } catch {
+      return undefined;
+    } finally {
+      try {
+        closeSync(fd);
+      } catch {
+        // Descriptor already gone; nothing to close.
+      }
+    }
+  }
+  try {
+    return JSON.parse(raw) as SessionFile;
+  } catch {
+    return undefined;
+  }
+}

package/src/paths.ts

@@ -23,6 +23,8 @@ export const ENV_HOME = 'BTCR2_HOME';
 /** The config and keystore file names, kept side by side under the home root. */
 export const CONFIG_FILENAME = 'config.json';
 export const KEYSTORE_FILENAME = 'keystore.json';
+/** The session file name, holding the unlock agent's cached passphrase (ADR 081). */
+export const SESSION_FILENAME = 'session.json';
 
 /**
  * Resolves the CLI home directory: the single root that holds `config.json` and
@@ -77,3 +79,14 @@ export function defaultConfigPath(overrides?: PathOverrides): string {
 export function defaultKeystorePath(overrides?: PathOverrides): string {
   return join(resolveHome(overrides), KEYSTORE_FILENAME);
 }
+
+/**
+ * Session file path: `<home>/session.json`, where the unlock agent caches the
+ * keystore passphrase (ADR 081). Deliberately derived from the home root alone,
+ * never from `--config` / `--keystore` or the config file, so `keystore lock`
+ * can revoke a session even under a malformed config, and so the read and write
+ * paths always agree on one location per home.
+ */
+export function defaultSessionPath(overrides?: PathOverrides): string {
+  return join(resolveHome(overrides), SESSION_FILENAME);
+}

package/src/types.ts

@@ -4,6 +4,7 @@ import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import type { DoctorReport, EffectiveConfig } from './config.js';
 import type { ConfigIssue } from './config-schema.js';
+import type { SessionStatus } from './keystore/session.js';
 
 export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
 export type OutputFormat = 'json' | 'text';
@@ -55,7 +56,18 @@ export type CommandResult =
   | { action: 'key-export'; data: { keyId: string; publicKey?: string; secretWrittenTo?: string } }
   | { action: 'key-delete'; data: { keyId: string; deleted: true } }
   | { action: 'key-use'; data: { keyId: string; active: true } }
-  | { action: 'init'; data: { home: string; config: string; keystore: string; created: string[]; protection: KeystoreProtectionLabel } }
+  | { action: 'init'; data: { home: string; config: string; keystore: string; network: NetworkOption; created: string[]; protection: KeystoreProtectionLabel } }
+  | { action: 'quickstart'; data: {
+      home       : string;
+      config     : string;
+      keystore   : string;
+      network    : NetworkOption;
+      created    : string[];
+      protection : KeystoreProtectionLabel;
+      unlocked   : boolean;
+      session?   : { expiresAt: number; ttlSeconds: number };
+      doctor?    : DoctorReport;
+    } }
   | { action: 'config-init'; data: { path: string } }
   | { action: 'config-get'; data: unknown }
   | { action: 'config-set'; data: { path: string } }
@@ -66,8 +78,10 @@ export type CommandResult =
   | { action: 'config-path'; data: { home: string; config: string; keystore: string } }
   | { action: 'config-doctor'; data: DoctorReport }
   | { action: 'keystore-init'; data: { path: string; protection: 'encrypted' | 'dev' } }
-  | { action: 'keystore-status'; data: { path: string; protection: KeystoreProtectionLabel; established: boolean; keyCount: number; active: string | undefined } }
+  | { action: 'keystore-status'; data: { path: string; protection: KeystoreProtectionLabel; established: boolean; keyCount: number; active: string | undefined; session: SessionStatus } }
   | { action: 'keystore-change-passphrase'; data: { path: string; rekeyed: number } }
+  | { action: 'keystore-unlock'; data: { keystore: string; expiresAt: number; ttlSeconds: number } }
+  | { action: 'keystore-lock'; data: { path: string; cleared: boolean } }
   | { action: 'profile-add'; data: { profile: string } }
   | { action: 'profile-use'; data: { profile: string } }
   | { action: 'profile-show'; data: unknown }