@did-btcr2/cli 0.14.0 → 0.16.0

package/dist/types/src/paths.d.ts

@@ -0,0 +1,54 @@
+/**
+ * State-location overrides that influence where the CLI keeps its home
+ * directory and its two state files. A subset of the broader
+ * `ConnectionOverrides`, restated here so this module (the single source of
+ * truth for on-disk locations) has no runtime dependency on `config.ts`.
+ */
+export interface PathOverrides {
+    /** Explicit home root from the `--home` flag. Wins over `$BTCR2_HOME`. */
+    home?: string;
+    /** Explicit config-file path from the `--config` flag. Overrides the home default. */
+    config?: string;
+    /** Explicit keystore path from the `--keystore` flag. Overrides the home default. */
+    keystore?: string;
+}
+/** Environment variable naming the CLI home directory (all state colocated). */
+export declare const ENV_HOME = "BTCR2_HOME";
+/** The config and keystore file names, kept side by side under the home root. */
+export declare const CONFIG_FILENAME = "config.json";
+export declare const KEYSTORE_FILENAME = "keystore.json";
+/**
+ * Resolves the CLI home directory: the single root that holds `config.json` and
+ * `keystore.json` side by side (ADR 079). Resolution order, highest wins:
+ *
+ * 1. `--home <dir>` (the {@link PathOverrides.home} flag)
+ * 2. `$BTCR2_HOME`
+ * 3. the platform default (see {@link platformDefaultHome})
+ *
+ * A blank value at any layer defers to the next, mirroring the `blankToUndef`
+ * treatment every other precedence layer uses, so an exported-but-empty
+ * `BTCR2_HOME` does not resolve the home to a bare relative path.
+ */
+export declare function resolveHome(overrides?: PathOverrides): string;
+/**
+ * The default home when no `--home` / `$BTCR2_HOME` override is present, chosen
+ * per OS so the location is idiomatic while staying a single colocated dir:
+ *
+ * - Windows: `%LOCALAPPDATA%\btcr2` (fallback `%APPDATA%\btcr2`, then the user
+ *   profile), the native place for per-user application state.
+ * - Linux / macOS: `~/.btcr2`, the short, teachable dot-directory in the same
+ *   family as `~/.ssh`, `~/.aws`, and `~/.gnupg`.
+ */
+export declare function platformDefaultHome(): string;
+/**
+ * Default config-file path: `<home>/config.json`. The `--config` flag, when
+ * present, overrides it wholesale (it names a specific file, not a home).
+ */
+export declare function defaultConfigPath(overrides?: PathOverrides): string;
+/**
+ * Default keystore path: `<home>/keystore.json`. The `--keystore` flag and a
+ * profile's `identity.keystore` (resolved in `config.ts`) override it; this
+ * function is the final fallback in that chain.
+ */
+export declare function defaultKeystorePath(overrides?: PathOverrides): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/types/src/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/paths.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,IAAI,CAAC,EAAO,MAAM,CAAC;IACnB,sFAAsF;IACtF,MAAM,CAAC,EAAK,MAAM,CAAC;IACnB,qFAAqF;IACrF,QAAQ,CAAC,EAAG,MAAM,CAAC;CACpB;AAED,gFAAgF;AAChF,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,iFAAiF;AACjF,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAI7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAErE"}

package/dist/types/src/types.d.ts

@@ -2,9 +2,24 @@ import type { DidUpdateResult } from '@did-btcr2/api';
 import type { PatchOperation } from '@did-btcr2/common';
 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';
 export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
 export type OutputFormat = 'json' | 'text';
+/**
+ * How a keystore protects its secrets, as reported by `keystore status` and
+ * `btcr2 init`: `encrypted` (passphrase-sealed), `dev` (plaintext, testnet-only),
+ * or `absent` (no keystore file yet).
+ */
+export type KeystoreProtectionLabel = 'encrypted' | 'dev' | 'absent';
 export declare const SUPPORTED_NETWORKS: NetworkOption[];
+/**
+ * Normalizes a blank value (empty or whitespace-only) to `undefined`, so a
+ * blank at any precedence layer defers to the next layer instead of masking it.
+ * A non-blank value is returned unchanged. This mirrors the `|| undefined`
+ * treatment the environment layer already applies in `readEnvOverrides`.
+ */
+export declare function blankToUndef(value: string | undefined): string | undefined;
 export interface ResolveCommandOptions {
     identifier: string;
     options?: ResolutionOptions;
@@ -79,6 +94,15 @@ export type CommandResult = {
         keyId: string;
         active: true;
     };
+} | {
+    action: 'init';
+    data: {
+        home: string;
+        config: string;
+        keystore: string;
+        created: string[];
+        protection: KeystoreProtectionLabel;
+    };
 } | {
     action: 'config-init';
     data: {
@@ -100,6 +124,46 @@ export type CommandResult = {
 } | {
     action: 'config-list';
     data: unknown;
+} | {
+    action: 'config-validate';
+    data: {
+        ok: boolean;
+        issues: ConfigIssue[];
+    };
+} | {
+    action: 'config-effective';
+    data: EffectiveConfig;
+} | {
+    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-change-passphrase';
+    data: {
+        path: string;
+        rekeyed: number;
+    };
 } | {
     action: 'profile-add';
     data: {
@@ -123,6 +187,7 @@ export interface GlobalOptions {
     output: OutputFormat;
     verbose: boolean;
     quiet: boolean;
+    home?: string;
     config?: string;
     profile?: string;
     btcRest?: string;
@@ -131,6 +196,11 @@ export interface GlobalOptions {
     btcRpcPass?: string;
     casGateway?: string;
     casRpcUrl?: string;
+    btcTimeout?: string;
+    casTimeout?: string;
+    btcRestHeader?: string[];
+    btcRpcWallet?: string;
+    btcRpcHeader?: string[];
     keystore?: string;
     passphraseFile?: string;
     signingKey?: string;

package/dist/types/src/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/cli",
-  "version": "0.14.0",
+  "version": "0.16.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",
@@ -61,11 +61,11 @@
     "@scure/base": "^1.2.6",
     "@web5/dids": "^1.2.0",
     "commander": "^13.1.0",
-    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/api": "^0.16.1",
     "@did-btcr2/keypair": "^0.13.1",
-    "@did-btcr2/method": "^0.54.0",
-    "@did-btcr2/api": "^0.16.0",
-    "@did-btcr2/key-manager": "^0.7.0"
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/key-manager": "^0.7.0",
+    "@did-btcr2/method": "^0.54.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",

package/src/cli.ts

@@ -5,12 +5,14 @@ import {
   registerConfigCommand,
   registerCreateCommand,
   registerDeactivateCommand,
+  registerInitCommand,
   registerKeyCommand,
+  registerKeystoreCommand,
   registerProfileCommand,
   registerResolveCommand,
   registerUpdateCommand,
 } from './commands/index.js';
-import { defaultApiFactory, keystoreApiFactory, type ApiFactory } from './config.js';
+import { defaultApiFactory, keystoreApiFactory, resolveOutputFormat, type ApiFactory } from './config.js';
 import type { GlobalOptions } from './types.js';
 import { VERSION } from './version.js';
 
@@ -41,10 +43,11 @@ export class DidBtcr2Cli {
     this.program = new Command('btcr2')
       .version(`btcr2 ${VERSION}`, '-v, --version', 'Output the current version')
       .description('CLI tool for the did:btcr2 method')
-      .option('-o, --output <format>', 'Output format <json|text>', 'text')
+      .option('-o, --output <format>', 'Output format <json|text> (default: config defaults.output, else text)')
       .option('--verbose', 'Verbose output', false)
       .option('--quiet', 'Suppress non-essential output', false)
-      .option('-c, --config <path>', 'Path to config file (default: $XDG_CONFIG_HOME/btcr2/config.json)')
+      .option('--home <dir>', 'btcr2 home directory holding config.json + keystore.json (default: ~/.btcr2, %LOCALAPPDATA%\\btcr2 on Windows; overrides $BTCR2_HOME)')
+      .option('-c, --config <path>', 'Path to config file (default: <home>/config.json)')
       .option('--profile <name>', 'Config profile name (default: auto-detected from network)')
       .option('--btc-rest <url>', 'Override Bitcoin REST endpoint (Esplora API)')
       .option('--btc-rpc-url <url>', 'Override Bitcoin Core RPC endpoint')
@@ -52,17 +55,34 @@ export class DidBtcr2Cli {
       .option('--btc-rpc-pass <pass>', 'Bitcoin Core RPC password')
       .option('--cas-gateway <url>', 'IPFS HTTP gateway for CAS reads (read-only)')
       .option('--cas-rpc-url <url>', 'IPFS HTTP RPC endpoint for a writable CAS (reads + writes; enables --publish-to-cas)')
-      .option('--keystore <path>', 'Path to the keystore file (default: $XDG_DATA_HOME/btcr2/keystore.json)')
+      .option('--btc-timeout <ms>', 'Bitcoin REST/RPC request timeout in milliseconds (default: unbounded)')
+      .option('--cas-timeout <ms>', 'CAS request timeout in milliseconds (default: 30000; 0 disables)')
+      .option('--btc-rest-header <header>', 'Extra Bitcoin REST header "Key: Value" (repeatable)', collectHeader, [])
+      .option('--btc-rpc-wallet <name>', 'Bitcoin Core wallet name for wallet-scoped RPCs')
+      .option('--btc-rpc-header <header>', 'Extra Bitcoin Core RPC header "Key: Value" (repeatable)', collectHeader, [])
+      .option('--keystore <path>', 'Path to the keystore file (default: <home>/keystore.json)')
       .option('--passphrase-file <path>', 'Read the keystore passphrase from a file (unattended use)')
       .option('--signing-key <ref>', 'Key for create/update/deactivate signing: a URN, fingerprint prefix, or name');
 
     const globals = (): GlobalOptions => this.program.opts() as GlobalOptions;
 
+    // Resolve the effective output format (flag -> BTCR2_OUTPUT -> config
+    // defaults.output -> 'text') before any command action runs, so a configured
+    // default is honored while an explicit flag still wins. The commander option
+    // carries no hard default (which would mask defaults.output); the resolved
+    // value is written back so every command reads it through globals().output.
+    this.program.hook('preAction', () => {
+      const opts = this.program.opts() as GlobalOptions;
+      opts.output = resolveOutputFormat({ output: opts.output, config: opts.config, home: opts.home });
+    });
+
+    registerInitCommand(this.program, globals);
     registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
     registerUpdateCommand(this.program, keystoreFactory, globals);
     registerDeactivateCommand(this.program, keystoreFactory, globals);
     registerKeyCommand(this.program, keystoreFactory, globals);
+    registerKeystoreCommand(this.program, globals);
     registerConfigCommand(this.program, globals);
     registerProfileCommand(this.program, globals);
     registerCompletionCommand(this.program, globals);
@@ -84,6 +104,14 @@ export class DidBtcr2Cli {
   }
 }
 
+/**
+ * Commander collector for a repeatable header option: accumulates each
+ * `Key: Value` occurrence into an array, preserving order.
+ */
+function collectHeader(value: string, previous: string[]): string[] {
+  return [ ...previous, value ];
+}
+
 /**
  * Normalizes argv to ensure it has at least two elements.
  * @param {string[]} argv - The original argv array.

package/src/commands/config.ts

@@ -1,25 +1,31 @@
 import type { Command } from 'commander';
 import { existsSync } from 'node:fs';
-import { dirname } from 'node:path';
 import {
   CONFIG_SCHEMA_VERSION,
   defaultConfigPath,
   getConfigPath,
+  parseConfigFileRaw,
   readConfigFile,
+  resolveDefaultNetwork,
+  resolveEffectiveConfig,
+  resolveKeystorePath,
+  runDoctor,
   setConfigPath,
   unsetConfigPath,
   writeConfigFile,
+  writeDefaultConfigFile,
 } from '../config.js';
+import { findConfigIssues, validateConfigSet } from '../config-schema.js';
 import { CLIError } from '../error.js';
-import { ensureDir, writeFileAtomic } from '../keystore/atomic.js';
-import { formatResult } from '../output.js';
-import type { CommandResult, GlobalOptions } from '../types.js';
+import { formatResult, REDACTED, redactSecrets, scrubUrlUserinfo } from '../output.js';
+import { resolveHome } from '../paths.js';
+import type { CommandResult, GlobalOptions, NetworkOption } from '../types.js';
 import { SUPPORTED_NETWORKS } from '../types.js';
 
 /** Registers the `config` command group for reading and writing CLI configuration. */
 export function registerConfigCommand(program: Command, globals: () => GlobalOptions): void {
   const config = program.command('config').description('Read and write CLI configuration.');
-  const path = (): string => globals().config ?? defaultConfigPath();
+  const path = (): string => globals().config ?? defaultConfigPath(globals());
   const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
 
   config
@@ -31,29 +37,33 @@ export function registerConfigCommand(program: Command, globals: () => GlobalOpt
       if (existsSync(p) && !options.force) {
         throw new CLIError(`Config already exists at ${p}. Use --force to overwrite.`, 'INVALID_ARGUMENT_ERROR', { path: p });
       }
-      const scaffold = {
-        schemaVersion : CONFIG_SCHEMA_VERSION,
-        defaults      : { output: 'text' },
-        profiles      : Object.fromEntries(SUPPORTED_NETWORKS.map(n => [ n, {} ])),
-      };
-      ensureDir(dirname(p), 0o700);
-      writeFileAtomic(p, `${JSON.stringify(scaffold, null, 2)}\n`, 0o600);
+      writeDefaultConfigFile(p);
       print({ action: 'config-init', data: { path: p } });
     });
 
   config
     .command('get [path]')
     .description('Print a value at a dotted path, or the whole config.')
-    .action((dotted?: string) => {
+    .option('--show-secrets', 'Reveal secret values (RPC password, etc.) instead of redacting them.', false)
+    .action((dotted: string | undefined, opts: { showSecrets?: boolean }) => {
       const file = (readConfigFile(path()) ?? {}) as Record<string, unknown>;
-      print({ action: 'config-get', data: (dotted ? getConfigPath(file, dotted) : file) ?? null });
+      const raw = (dotted ? getConfigPath(file, dotted) : file) ?? null;
+      const leaf = dotted ? dotted.split('.').pop() : undefined;
+      print({ action: 'config-get', data: opts.showSecrets ? raw : redactSecrets(raw, leaf) });
     });
 
   config
     .command('set <path> <value>')
     .description('Set a value at a dotted path. The value is parsed as JSON when valid, else stored as a string.')
     .action((dotted: string, value: string) => {
-      writeConfigFile(path(), raw => setConfigPath(raw, dotted, parseValue(value)));
+      const parsed = parseValue(dotted, value);
+      // Reject an invalid enum value for a known key up-front; warn (but still
+      // write) an unknown path so forward-compatible and third-party keys work.
+      const { unknownPath } = validateConfigSet(dotted, parsed);
+      if (unknownPath && !globals().quiet) {
+        console.error(`Warning: "${dotted}" is not a known config path; writing it anyway.`);
+      }
+      writeConfigFile(path(), raw => setConfigPath(raw, dotted, parsed));
       print({ action: 'config-set', data: { path: dotted } });
     });
 
@@ -69,16 +79,131 @@ export function registerConfigCommand(program: Command, globals: () => GlobalOpt
     .command('list')
     .alias('ls')
     .description('Print the entire config file.')
+    .option('--show-secrets', 'Reveal secret values (RPC password, etc.) instead of redacting them.', false)
+    .action((opts: { showSecrets?: boolean }) => {
+      const file = readConfigFile(path()) ?? {};
+      print({ action: 'config-list', data: opts.showSecrets ? file : redactSecrets(file) });
+    });
+
+  config
+    .command('validate')
+    .description('Check the config for unknown keys, invalid enum values, and an unsupported schema version.')
     .action(() => {
-      print({ action: 'config-list', data: readConfigFile(path()) ?? {} });
+      // Read raw (bypassing the schema-version ceiling that readConfigFile
+      // enforces) so a newer-than-supported version is reported as a finding
+      // rather than aborting the very command meant to diagnose it.
+      const file = parseConfigFileRaw(path()) ?? {};
+      const issues = findConfigIssues(file, CONFIG_SCHEMA_VERSION);
+      if (issues.length > 0) process.exitCode ??= 1;
+      print({ action: 'config-validate', data: { ok: issues.length === 0, issues } });
+    });
+
+  config
+    .command('effective')
+    .description('Print the resolved connection config with per-value provenance (flag|env|file|default).')
+    .option('-n, --network <network>', 'Network to resolve for (default: config default network)')
+    .option('--show-secrets', 'Reveal secret values (RPC password) instead of redacting them.', false)
+    .action((opts: { network?: string; showSecrets?: boolean }) => {
+      const network = resolveIntrospectionNetwork(opts.network, globals());
+      const data = resolveEffectiveConfig(network, globals());
+      // Redact the resolved RPC password and any password embedded in an endpoint
+      // URL by default; provenance still shows where each value came from.
+      // --show-secrets reveals them for deliberate debugging.
+      if (!opts.showSecrets) {
+        if (data.btc.rpcPass.value !== undefined) {
+          data.btc.rpcPass = { ...data.btc.rpcPass, value: REDACTED };
+        }
+        for (const entry of [ data.btc.rest, data.btc.rpcUrl, data.cas.gateway, data.cas.rpcUrl ]) {
+          if (typeof entry.value === 'string') entry.value = scrubUrlUserinfo(entry.value);
+        }
+      }
+      print({ action: 'config-effective', data });
+    });
+
+  config
+    .command('path')
+    .description('Print the resolved home directory, config-file, and keystore paths.')
+    .action(() => {
+      const g = globals();
+      const data = {
+        home     : resolveHome(g),
+        config   : g.config ?? defaultConfigPath(g),
+        // Diagnostic command: report the path even when the config is malformed
+        // (this is a command you run to find and fix a broken config).
+        keystore : resolveKeystorePath(g, { lenient: true }),
+      };
+      print({ action: 'config-path', data });
+    });
+
+  config
+    .command('doctor')
+    .description('Probe reachability of the resolved endpoints (read-only; touches the network).')
+    .option('-n, --network <network>', 'Network to resolve for (default: config default network)')
+    .action(async (opts: { network?: string }) => {
+      const network = resolveIntrospectionNetwork(opts.network, globals());
+      const report = await runDoctor(network, globals());
+      if (report.checks.some(check => !check.ok)) process.exitCode ??= 1;
+      print({ action: 'config-doctor', data: report });
     });
 }
 
-/** Parses a value as JSON when valid, otherwise treats it as a plain string. */
-function parseValue(value: string): unknown {
+/**
+ * Resolves the network an introspection command (`effective`/`doctor`) operates
+ * on: an explicit `--network`, validated, else the config's default network.
+ */
+function resolveIntrospectionNetwork(explicit: string | undefined, globals: GlobalOptions): NetworkOption {
+  if (explicit) {
+    if (!SUPPORTED_NETWORKS.includes(explicit as NetworkOption)) {
+      throw new CLIError(
+        `Invalid network "${explicit}". Must be one of ${SUPPORTED_NETWORKS.join(', ')}.`,
+        'INVALID_ARGUMENT_ERROR',
+        { network: explicit },
+      );
+    }
+    return explicit as NetworkOption;
+  }
+  return resolveDefaultNetwork(globals);
+}
+
+/**
+ * Parses a `config set` value. Known scalar endpoint, credential, and defaults
+ * paths are stored as raw strings so a bare `8080` is not coerced to the number
+ * `8080` (which would flow into a host field as a non-string). Every other path
+ * is parsed as JSON when valid, else stored as a plain string, so structured
+ * values (objects, arrays, booleans, and genuinely numeric fields) still work.
+ */
+function parseValue(dotted: string, value: string): unknown {
+  if (isStringScalarPath(dotted)) return value;
   try {
     return JSON.parse(value);
   } catch {
     return value;
   }
 }
+
+/**
+ * Whether a dotted config path addresses a leaf that must be stored as a string
+ * (an endpoint URL, a credential, a network/profile/output name), so JSON
+ * coercion never turns it into a non-string.
+ */
+function isStringScalarPath(dotted: string): boolean {
+  const segments = dotted.split('.');
+
+  if (segments.length === 2 && segments[0] === 'defaults') {
+    return [ 'profile', 'network', 'output' ].includes(segments[1]);
+  }
+
+  if (segments.length === 3 && segments[0] === 'profiles' && segments[2] === 'network') {
+    return true;
+  }
+
+  if (segments.length === 4 && segments[0] === 'profiles') {
+    const group = segments[2];
+    const leaf = segments[3];
+    if (group === 'btc') return [ 'rest', 'rpcUrl', 'rpcUser', 'rpcPass', 'changeAddress', 'wallet' ].includes(leaf);
+    if (group === 'cas') return [ 'gateway', 'rpcUrl' ].includes(leaf);
+    if (group === 'identity') return [ 'keystore', 'default' ].includes(leaf);
+  }
+
+  return false;
+}

package/src/commands/create.ts

@@ -1,7 +1,7 @@
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import type { Command } from 'commander';
 import type { ApiFactory, ConnectionOverrides } from '../config.js';
-import { resolveDefaultNetwork } from '../config.js';
+import { assertKeystoreAllowedForNetwork, profileNetworkMismatch, resolveDefaultNetwork } from '../config.js';
 import { CLIError } from '../error.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
@@ -63,6 +63,18 @@ export function registerCreateCommand(
       const network = resolveNetwork(options.network, overrides);
       const signingKey = g.signingKey;
 
+      // Warn (never block) when the network being encoded disagrees with the
+      // active profile's declared network, so a `production` profile holding
+      // mainnet endpoints cannot silently mint a regtest DID.
+      const mismatch = profileNetworkMismatch(network, overrides);
+      if (mismatch && !g.quiet) {
+        process.stderr.write(
+          `Warning: creating a "${network}" identifier while the active profile `
+          + `"${mismatch.profile}" declares network "${mismatch.declared}". The `
+          + 'identifier\'s network and the profile\'s endpoints may not match.\n'
+        );
+      }
+
       /** Prints the result, plus a stderr provenance line in text mode. */
       const print = (result: CommandResult, note?: string): void => {
         console.log(formatResult(result, g));
@@ -120,6 +132,8 @@ export function registerCreateCommand(
       }
 
       // Generate: mint a fresh key, persist it, and set it active (passphrase prompt).
+      // Refuse to seal a fresh mainnet key into an unencrypted dev keystore (ADR 080).
+      assertKeystoreAllowedForNetwork(network, overrides);
       const api = keystoreFactory(undefined, overrides);
       const { did, keyId } = api.generateDid({ network, setActive: true });
       const publicKey = bytesToHex(api.kms.getPublicKey(keyId));
@@ -133,6 +147,7 @@ export function registerCreateCommand(
 /** Builds the keystore- and config-resolution overrides from the global flags. */
 function overridesFromGlobals(g: GlobalOptions): ConnectionOverrides {
   return {
+    home           : g.home,
     config         : g.config,
     profile        : g.profile,
     keystore       : g.keystore,

package/src/commands/deactivate.ts

@@ -1,7 +1,7 @@
 import type { PublishToCasMode } from '@did-btcr2/api';
 import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
-import { deriveNetwork, type ApiFactory } from '../config.js';
+import { assertKeystoreAllowedForNetwork, deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
@@ -44,12 +44,24 @@ export function registerDeactivateCommand(
       parsePublishToCasMode,
       'never',
     )
+    .option(
+      '--fee-rate <satsPerVByte>',
+      'Fee rate in sats/vByte for the beacon transaction (default: 5). '
+        + 'Raise it under congestion so the transaction confirms.',
+    )
+    .option(
+      '--change-address <address>',
+      'Send transaction change to this address instead of the beacon address, '
+        + 'so a DID\'s announcements are not linked on-chain (ADR 044).',
+    )
     .action(async (options: {
       sourceDocument       : unknown;
       sourceVersionId      : string;
       verificationMethodId : string;
       beaconId             : unknown;
       publishToCas         : PublishToCasMode;
+      feeRate?             : string;
+      changeAddress?       : string;
     }) => {
       if (!/^\d+$/.test(options.sourceVersionId)) {
         throw new CLIError(
@@ -76,9 +88,18 @@ export function registerDeactivateCommand(
       // Deactivation is an update that applies the deactivation patch. The core
       // method has no separate deactivate path, so this routes through update.
       const network = deriveNetwork(did);
+      // Refuse to sign a mainnet deactivation with an unencrypted dev keystore (ADR 080).
+      assertKeystoreAllowedForNetwork(network, globals());
       const api = factory(network, globals());
-      const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+      const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
       const signer = new KeyManagerSigner(api.kms.kms, keyId);
+      // Resolve fee-rate/change-address through the flag -> env -> profile chain
+      // into beacon broadcast options. Undefined when neither is set, so the
+      // SDK defaults (5 sat/vB, change back to the beacon address) still apply.
+      const broadcastOptions = resolveBroadcastOptions(network, globals(), {
+        feeRate       : options.feeRate,
+        changeAddress : options.changeAddress,
+      });
       // CAS publication is optional and never required: every beacon update can
       // be completed and shared via sidecar alone. It is opt-in and defaults to
       // 'never'; pass --publish-to-cas auto|always to publish the signed update
@@ -93,6 +114,7 @@ export function registerDeactivateCommand(
         beaconId             : parsed.beaconId,
         signer,
         publishToCas         : options.publishToCas,
+        ...(broadcastOptions ? { broadcastOptions } : {}),
       });
       console.log(formatResult({ action: 'deactivate', data }, globals()));
     });

package/src/commands/index.ts

@@ -1,8 +1,10 @@
+export { registerInitCommand } from './init.js';
 export { registerCreateCommand } from './create.js';
 export { registerResolveCommand } from './resolve.js';
 export { registerUpdateCommand } from './update.js';
 export { registerDeactivateCommand } from './deactivate.js';
 export { registerKeyCommand } from './key.js';
+export { registerKeystoreCommand } from './keystore.js';
 export { registerConfigCommand } from './config.js';
 export { registerProfileCommand } from './profile.js';
 export { registerCompletionCommand } from './completion.js';