@did-btcr2/cli 0.16.0 → 0.18.0

package/src/commands/init.ts

@@ -1,21 +1,142 @@
 import type { Command } from 'commander';
 import { existsSync } from 'node:fs';
-import { defaultConfigPath, resolveKeystorePath, writeDefaultConfigFile } from '../config.js';
+import {
+  assertSupportedNetwork,
+  defaultConfigPath,
+  persistDefaultNetwork,
+  resolveKeystorePath,
+  writeDefaultConfigFile,
+} from '../config.js';
 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 type { CommandResult, GlobalOptions } from '../types.js';
+import { defaultSessionPath, resolveHome } from '../paths.js';
+import type { CommandResult, GlobalOptions, KeystoreProtectionLabel, NetworkOption } from '../types.js';
+
+/** Options for the shared {@link runInit} scaffolding step. */
+export interface RunInitOptions {
+  /** Establish an UNENCRYPTED dev keystore (plaintext keys, testnet only). */
+  dev?     : boolean;
+  /** Re-scaffold the regenerable config even if it exists (never the keystore). */
+  force?   : boolean;
+  /** Explicit network from `-n/--network`, already validated. Persisted to `defaults.network`. */
+  network? : NetworkOption;
+  /**
+   * Network to persist when `-n` is absent and `defaults.network` is unset: a
+   * command's opinionated default (mutinynet for `quickstart`). Omitted by plain
+   * `init`, which never persists a merely-defaulted network.
+   */
+  fallbackNetwork? : NetworkOption;
+  /**
+   * Capture the establish-time confirmed passphrase so the caller can seed a
+   * session with no second prompt (`quickstart --unlock`). Only populated when a
+   * fresh ENCRYPTED keystore is established in this call. Never printed.
+   */
+  captureEstablishedPassphrase? : boolean;
+}
+
+/** Result of the shared {@link runInit} scaffolding step. */
+export interface RunInitResult {
+  home       : string;
+  config     : string;
+  keystore   : string;
+  network    : NetworkOption;
+  created    : string[];
+  protection : KeystoreProtectionLabel;
+  /**
+   * The confirmed passphrase from a fresh ENCRYPTED establishment in this call,
+   * present only when {@link RunInitOptions.captureEstablishedPassphrase} was set
+   * and a keystore was established. Consumed to seed a session; never printed.
+   */
+  establishedPassphrase? : string;
+}
+
+/**
+ * The shared scaffolding step behind `btcr2 init` and `btcr2 quickstart` (ADR
+ * 079/080/083): create the home, a default config if none exists, and establish
+ * the keystore if none exists (encrypted by default, `--dev` for unencrypted).
+ * Idempotent: existing files are left untouched, and `--force` re-scaffolds only
+ * the regenerable config, never the keystore. Records `defaults.network` via
+ * {@link persistDefaultNetwork}. Returns the resolved paths, network, protection,
+ * and (when asked) the establish-time passphrase for session seeding.
+ */
+export function runInit(g: GlobalOptions, options: RunInitOptions = {}): RunInitResult {
+  const home = resolveHome(g);
+  const configPath = g.config ?? defaultConfigPath(g);
+  const keystorePath = resolveKeystorePath(g);
+  ensureDir(home, 0o700);
+
+  const created: string[] = [];
+
+  // The config is regenerable, so --force may re-scaffold it.
+  if (!existsSync(configPath) || options.force) {
+    writeDefaultConfigFile(configPath);
+    created.push('config');
+  }
+
+  // The keystore holds unrecoverable secret keys, so init never overwrites an
+  // existing one, even with --force: re-establishing a keystore is the explicit,
+  // deliberate `keystore init --force`. init only establishes when none exists.
+  const keystoreExists = 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".\n',
+    );
+  }
+
+  let establishedPassphrase: string | undefined;
+  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: ',
+        });
+        // Capture only a fresh ENCRYPTED establishment, for session seeding.
+        if (options.captureEstablishedPassphrase && !options.dev) establishedPassphrase = passphrase;
+        return 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` (ADR 081).
+    clearSession(defaultSessionPath(g));
+    created.push('keystore');
+  }
+
+  // Record the network as defaults.network idempotently (ADR 083): an explicit
+  // -n always writes; a merely-defaulted network writes only when the raw config
+  // has none yet, so a re-run never clobbers an operator's earlier choice.
+  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 };
+}
 
 /**
  * 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
  * establishes the keystore if none exists (encrypted with a confirmed passphrase
- * by default, or `--dev` for an unencrypted testnet keystore). Idempotent:
- * existing files are left untouched unless `--force` is given. Establishing the
- * passphrase here, up front and confirmed, is what keeps the first `key generate`
- * off the accidental-first-seal path (ADR 080).
+ * by default, or `--dev` for an unencrypted testnet keystore). `-n/--network`
+ * records `defaults.network` so later commands can drop `-n` (ADR 083).
+ * Idempotent: existing files are left untouched unless `--force` is given.
+ * Establishing the passphrase here, up front and confirmed, is what keeps the
+ * first `key generate` off the accidental-first-seal path (ADR 080).
  */
 export function registerInitCommand(program: Command, globals: () => GlobalOptions): void {
   const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
@@ -23,52 +144,29 @@ export function registerInitCommand(program: Command, globals: () => GlobalOptio
   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 and keystore even if they already exist.', false)
-    .action((options: { dev?: boolean; force?: boolean }) => {
+    .option('--force', 'Re-create the config even if it already exists (never the keystore).', false)
+    .action((options: { network?: string; dev?: boolean; force?: boolean }) => {
       const g = globals();
-      const home = resolveHome(g);
-      const configPath = g.config ?? defaultConfigPath(g);
-      const keystorePath = resolveKeystorePath(g);
-      ensureDir(home, 0o700);
-
-      const created: string[] = [];
-
-      // The config is regenerable, so --force may re-scaffold it.
-      if (!existsSync(configPath) || options.force) {
-        writeDefaultConfigFile(configPath);
-        created.push('config');
-      }
-
-      // The keystore holds unrecoverable secret keys, so `init` never overwrites
-      // an existing one, even with --force: re-establishing a keystore is the
-      // explicit, deliberate `keystore init --force`. `init` only establishes a
-      // keystore when none exists.
-      const keystoreExists = 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".\n',
-        );
-      }
-      if (!keystoreExists) {
-        if (options.dev && !g.quiet) {
-          process.stderr.write(
-            'warning: establishing an UNENCRYPTED dev keystore. Keys are stored in plaintext. '
-            + 'Use it only for disposable testnet material; mainnet operations will be refused.\n',
-          );
-        }
-        initKeystore(keystorePath, {
-          protection    : options.dev ? 'none' : 'passphrase',
-          getPassphrase : (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: 'New keystore passphrase: ' }),
-        });
-        created.push('keystore');
-      }
-
-      const protection = keystoreSummary(keystorePath).protection;
-      print({ action: 'init', data: { home, config: configPath, keystore: keystorePath, created, protection } });
+      const network = options.network ? assertSupportedNetwork(options.network) : undefined;
+      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 ${home}. Next: btcr2 key generate --set-active\n`);
+        process.stderr.write(`btcr2 home ready at ${result.home} on ${result.network}. Next: btcr2 key generate --set-active\n`);
       }
     });
 }

package/src/commands/keystore.ts

@@ -1,20 +1,38 @@
 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,
+  type SessionFile,
+  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, type NetworkOption } 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 +69,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 +116,157 @@ 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 ttlMs = resolveSessionTtl(options.ttl);
+      // The op network for the mainnet gate is the configured default here; the
+      // session records `allowMainnet` and the authoritative check happens at
+      // consumption, where a `bitcoin` operation (network derived from the DID) is
+      // withheld from a session that lacks it.
+      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();
+      // 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 } });
+    });
+}
+
+/** Input for the shared {@link unlockSession} step. */
+export interface UnlockSessionInput {
+  g            : GlobalOptions;
+  /** The resolved keystore path to unlock. */
+  keystorePath : string;
+  /** The operation network for the mainnet gate, passed explicitly (never re-derived). */
+  network      : NetworkOption;
+  /** Whether a mainnet (bitcoin) unlock is permitted (`--allow-mainnet`). */
+  allowMainnet : boolean;
+  /** Session lifetime in milliseconds (already resolved via {@link resolveSessionTtl}). */
+  ttlMs        : number;
+  /**
+   * A pre-acquired passphrase to reuse instead of prompting (the establish-time
+   * passphrase from `quickstart --unlock` on a fresh keystore). Still verified
+   * against the keystore verifier before caching.
+   */
+  passphrase?  : string;
+}
+
+/**
+ * The shared unlock step behind `keystore unlock` and `quickstart --unlock` (ADR
+ * 081/083): validate the keystore, enforce the mainnet gate against the passed
+ * `network`, acquire (or reuse) and verify the passphrase, and write the session.
+ * Refuses an absent, dev, or unestablished keystore. A wrong passphrase writes no
+ * session file. Returns the written {@link SessionFile}. The op network is passed
+ * in rather than re-derived so the mainnet gate is order-independent even when a
+ * caller has just written `defaults.network`.
+ */
+export function unlockSession(input: UnlockSessionInput): SessionFile {
+  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 },
+    );
+  }
+  // An unlocked encrypted keystore signs prompt-free for the whole TTL, silently
+  // removing per-use passphrase auth. Refuse a bitcoin context unless allowed; the
+  // authoritative per-use check still happens at consumption from the session's
+  // recorded `allowMainnet` (ADR 081).
+  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 },
+    );
+  }
+  // Acquire the passphrase directly (env / file / prompt) with NO session
+  // consultation and NO confirm, or reuse a caller-provided one, then verify it
+  // against the keystore verifier before caching. A wrong passphrase writes no
+  // session file.
+  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) {
+    // 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 });
+  }
+  return writeSession(defaultSessionPath(g), {
+    keystorePath : path,
+    verifierId,
+    passphrase,
+    ttlMs,
+    allowMainnet,
+  });
+}
+
+/**
+ * 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.
+ */
+export 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/commands/quickstart.ts

@@ -0,0 +1,209 @@
+import { faucetUrl } from '@did-btcr2/api';
+import type { Command } from 'commander';
+import {
+  assertSupportedNetwork,
+  readConfiguredDefaultNetwork,
+  runDoctor,
+  type DoctorReport,
+} from '../config.js';
+import { CLIError } from '../error.js';
+import { keystoreVerifierId } from '../keystore/file-key-store.js';
+import { ENV_KEYSTORE_TTL, readSessionStatus } from '../keystore/session.js';
+import { formatResult } from '../output.js';
+import { defaultSessionPath } from '../paths.js';
+import type { CommandResult, GlobalOptions, NetworkOption } from '../types.js';
+import { runInit, type RunInitResult } from './init.js';
+import { resolveSessionTtl, unlockSession } from './keystore.js';
+
+/** The opinionated default network for `quickstart`: zero local infra, a free faucet, 30s blocks. */
+const QUICKSTART_DEFAULT_NETWORK: NetworkOption = 'mutinynet';
+
+/** The session sub-object reported in the quickstart envelope. */
+type SessionReport = { expiresAt: number; ttlSeconds: number };
+
+/**
+ * Registers the top-level `btcr2 quickstart` (ADR 083): a one-command onboarding
+ * that COMPOSES the existing primitives - the {@link runInit} scaffold, the
+ * network record, the optional {@link unlockSession} cache, and the advisory
+ * {@link runDoctor} probe - into a single step for a workshop follow-along.
+ * Reimplements nothing; the ADR 080/081 keystore and session guarantees hold by
+ * construction.
+ */
+export function registerQuickstartCommand(program: Command, globals: () => GlobalOptions): void {
+  const print = (result: CommandResult): void => 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: {
+      network?      : string;
+      dev?          : boolean;
+      unlock?       : boolean;
+      ttl?          : string;
+      doctor        : boolean; // commander sets false for --no-doctor, true otherwise
+      allowMainnet? : boolean;
+      force?        : boolean;
+    }) => {
+      const g = globals();
+      const explicit = options.network ? assertSupportedNetwork(options.network) : undefined;
+      // The network quickstart will operate on, computed BEFORE any write so the
+      // mainnet guard sees the real target: explicit -n, else an existing
+      // defaults.network, else the mutinynet default. runInit resolves to the
+      // same value.
+      const network = explicit ?? readConfiguredDefaultNetwork(g) ?? QUICKSTART_DEFAULT_NETWORK;
+
+      // Mainnet is guarded before any files are written (ADR 083). A dev keystore
+      // never operates on mainnet; an encrypted mainnet setup needs the explicit
+      // opt-in that also gates the session-unlock mainnet suspension.
+      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 },
+          );
+        }
+      }
+
+      // 1-2. Scaffold and record the network. An explicit -n always writes; a
+      // merely-defaulted mutinynet writes only when defaults.network is unset.
+      const init = runInit(g, {
+        dev                          : options.dev,
+        force                        : options.force,
+        network                      : explicit,
+        fallbackNetwork              : explicit ? undefined : QUICKSTART_DEFAULT_NETWORK,
+        captureEstablishedPassphrase : !!options.unlock && !options.dev,
+      });
+
+      // 3. Optionally cache the session (ADR 081 opt-in; never on a dev keystore).
+      let unlocked = false;
+      let session: SessionReport | undefined;
+      if (options.unlock && !options.dev) {
+        const outcome = cacheSession(g, init, options.ttl, !!options.allowMainnet);
+        unlocked = outcome.unlocked;
+        session = outcome.session;
+      }
+
+      // 4. Advisory endpoint probe (on by default; a failed probe warns, exit 0).
+      let doctor: DoctorReport | undefined;
+      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') {
+        printNextSteps(init, unlocked, session, doctor);
+      }
+    });
+}
+
+/**
+ * Caches the session for `quickstart --unlock`. On a fresh keystore, reuses the
+ * establish-time confirmed passphrase (no second prompt). On an existing keystore
+ * with a live matching session, skips (idempotent re-run). Otherwise acquires and
+ * verifies the passphrase. In a non-interactive context with no passphrase source
+ * on an existing keystore, the step is a non-fatal skip (warn, `unlocked: false`),
+ * so `quickstart` still exits 0 (ADR 083).
+ */
+function cacheSession(
+  g            : GlobalOptions,
+  init         : RunInitResult,
+  ttlFlag      : string | undefined,
+  allowMainnet : boolean,
+): { unlocked: boolean; session?: SessionReport } {
+  const ttlMs = resolveSessionTtl(ttlFlag);
+  const freshlyEstablished = init.created.includes('keystore');
+
+  // Existing encrypted keystore already unlocked: report it and skip re-writing.
+  if (!freshlyEstablished) {
+    const status = readSessionStatus(defaultSessionPath(g), init.keystore, keystoreVerifierId(init.keystore));
+    if (status.active && status.expiresAt !== undefined) {
+      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 : undefined,
+    });
+    return { unlocked: true, session: { expiresAt: written.expiresAt, ttlSeconds: written.ttlSeconds } };
+  } catch (error) {
+    // On an EXISTING keystore with no passphrase source and no terminal, caching
+    // is a non-fatal skip: the scaffold already succeeded (ADR 083). A fresh
+    // keystore cannot reach here (its passphrase was just captured), and an
+    // interactive wrong passphrase still propagates.
+    const type = (error as { type?: string }).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;
+  }
+}
+
+/** Prints the text-mode next-step hints after quickstart (ADR 082/083). */
+function printNextSteps(
+  init     : RunInitResult,
+  unlocked : boolean,
+  session  : SessionReport | undefined,
+  doctor   : DoctorReport | undefined,
+): void {
+  const lines: string[] = [`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 = faucetUrl(init.network);
+  if (faucet) lines.push(`Faucet (fund your beacon after "btcr2 create"): ${faucet}`);
+  process.stderr.write(`${lines.join('\n')}\n`);
+}