@did-btcr2/cli 0.14.0 → 0.16.0

package/src/commands/init.ts

@@ -0,0 +1,74 @@
+import type { Command } from 'commander';
+import { existsSync } from 'node:fs';
+import { defaultConfigPath, 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 { formatResult } from '../output.js';
+import { resolveHome } from '../paths.js';
+import type { CommandResult, GlobalOptions } from '../types.js';
+
+/**
+ * Registers the top-level `btcr2 init`: the one-command entry point that creates
+ * the btcr2 home (ADR 079), writes a default config if none exists, and
+ * 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).
+ */
+export function registerInitCommand(program: Command, globals: () => GlobalOptions): void {
+  const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
+
+  program
+    .command('init')
+    .description('Set up the btcr2 home: create the directory, a default config, and establish the keystore.')
+    .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 }) => {
+      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 } });
+      if (!g.quiet && g.output !== 'json') {
+        process.stderr.write(`btcr2 home ready at ${home}. Next: btcr2 key generate --set-active\n`);
+      }
+    });
+}

package/src/commands/keystore.ts

@@ -0,0 +1,98 @@
+import type { Command } from 'commander';
+import { existsSync } from 'node:fs';
+import { resolveKeystorePath } from '../config.js';
+import { CLIError } from '../error.js';
+import { changeKeystorePassphrase, initKeystore, keystoreSummary } from '../keystore/file-key-store.js';
+import { acquirePassphrase } from '../keystore/passphrase.js';
+import { formatResult } from '../output.js';
+import type { CommandResult, GlobalOptions } from '../types.js';
+
+/**
+ * Registers the `keystore` command group: establish, inspect, and re-key the
+ * encrypted keystore (ADR 080). These operate on the keystore file directly (no
+ * Bitcoin connection or KeyManager) and never decrypt a key except when
+ * re-sealing during `change-passphrase`.
+ */
+export function registerKeystoreCommand(program: Command, globals: () => GlobalOptions): void {
+  const keystore = program.command('keystore').description('Establish, inspect, and re-key the keystore.');
+  const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
+
+  keystore
+    .command('init')
+    .description('Establish the keystore (encrypted by default). Prompts for a passphrase and confirms it.')
+    .option('--dev', 'Create an UNENCRYPTED dev keystore: plaintext keys, no passphrase. Testnet only; mainnet operations are refused.', false)
+    .option('--force', 'Re-establish even if a keystore already exists (discards its keys).', false)
+    .action((options: { dev?: boolean; force?: boolean }) => {
+      const g = globals();
+      const path = resolveKeystorePath(g);
+      if (existsSync(path) && !options.force) {
+        throw new CLIError(
+          `A keystore already exists at ${path}. Use --force to re-establish it (this discards its keys).`,
+          'INVALID_ARGUMENT_ERROR',
+          { path },
+        );
+      }
+      // --force re-establishes over an existing keystore; make the key loss loud.
+      if (existsSync(path) && options.force && !g.quiet) {
+        const { keyCount } = keystoreSummary(path);
+        if (keyCount > 0) {
+          process.stderr.write(
+            `warning: re-establishing the keystore at ${path} permanently discards its ${keyCount} existing key(s).\n`,
+          );
+        }
+      }
+      if (options.dev && !g.quiet) {
+        process.stderr.write(
+          'warning: creating an UNENCRYPTED dev keystore. Keys are stored in plaintext. '
+          + 'Use it only for disposable testnet material; mainnet operations will be refused.\n',
+        );
+      }
+      initKeystore(path, {
+        protection    : options.dev ? 'none' : 'passphrase',
+        getPassphrase : (opts) => acquirePassphrase({ passphraseFile: g.passphraseFile, confirm: opts?.confirm, prompt: 'New keystore passphrase: ' }),
+      });
+      print({ action: 'keystore-init', data: { path, protection: options.dev ? 'dev' : 'encrypted' } });
+    });
+
+  keystore
+    .command('status')
+    .description('Show the keystore path, protection mode, and key count. Never decrypts or prompts.')
+    .action(() => {
+      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);
+      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 } });
+    });
+
+  keystore
+    .command('change-passphrase')
+    .alias('passwd')
+    .description('Change the keystore passphrase, re-sealing every key under the new one. Encrypted keystores only.')
+    .action(() => {
+      const g = globals();
+      const path = resolveKeystorePath(g);
+      const summary = keystoreSummary(path);
+      if (summary.protection === 'absent') {
+        throw new CLIError(`No keystore at ${path}. Run "btcr2 keystore init" first.`, 'INVALID_ARGUMENT_ERROR', { path });
+      }
+      if (summary.protection === 'dev') {
+        throw new CLIError(
+          `The keystore at ${path} is an unencrypted dev keystore; there is no passphrase to change.`,
+          'INVALID_ARGUMENT_ERROR',
+          { path },
+        );
+      }
+      // Current passphrase may come from the env var / file (unattended); the new
+      // one must be entered fresh (forcePrompt) so it cannot be silently satisfied
+      // by the same source and make the change a no-op.
+      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);
+      print({ action: 'keystore-change-passphrase', data: { path, rekeyed } });
+    });
+}

package/src/commands/profile.ts

@@ -1,13 +1,13 @@
 import type { Command } from 'commander';
 import { defaultConfigPath, readConfigFile, writeConfigFile } from '../config.js';
 import { CLIError } from '../error.js';
-import { formatResult } from '../output.js';
+import { formatResult, redactSecrets } from '../output.js';
 import type { CommandResult, GlobalOptions } from '../types.js';
 
 /** Registers the `profile` command group for managing configuration profiles. */
 export function registerProfileCommand(program: Command, globals: () => GlobalOptions): void {
   const profile = program.command('profile').description('Manage configuration profiles.');
-  const path = (): string => globals().config ?? defaultConfigPath();
+  const path = (): string => globals().config ?? defaultConfigPath(globals());
   const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
 
   profile
@@ -37,7 +37,8 @@ export function registerProfileCommand(program: Command, globals: () => GlobalOp
   profile
     .command('show [name]')
     .description('Show a profile (defaults to the active profile).')
-    .action((name?: string) => {
+    .option('--show-secrets', 'Reveal secret values (RPC password, etc.) instead of redacting them.', false)
+    .action((name: string | undefined, opts: { showSecrets?: boolean }) => {
       const file = readConfigFile(path()) ?? {};
       const target = name ?? file.defaults?.profile;
       if (!target) {
@@ -47,7 +48,8 @@ export function registerProfileCommand(program: Command, globals: () => GlobalOp
       if (!data) {
         throw new CLIError(`Profile "${target}" not found.`, 'INVALID_ARGUMENT_ERROR', { profile: target });
       }
-      print({ action: 'profile-show', data: { profile: target, ...data } });
+      const payload = { profile: target, ...data };
+      print({ action: 'profile-show', data: opts.showSecrets ? payload : redactSecrets(payload) });
     });
 
   profile

package/src/commands/update.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';
@@ -45,6 +45,16 @@ export function registerUpdateCommand(
       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;
@@ -52,6 +62,8 @@ export function registerUpdateCommand(
       verificationMethodId : string;
       beaconId             : unknown;
       publishToCas         : PublishToCasMode;
+      feeRate?             : string;
+      changeAddress?       : string;
     }) => {
       if (!/^\d+$/.test(options.sourceVersionId)) {
         throw new CLIError(
@@ -76,9 +88,18 @@ export function registerUpdateCommand(
         );
       }
       const network = deriveNetwork(did);
+      // Refuse to sign a mainnet update 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 registerUpdateCommand(
         beaconId             : parsed.beaconId,
         signer,
         publishToCas         : options.publishToCas,
+        ...(broadcastOptions ? { broadcastOptions } : {}),
       });
       console.log(formatResult({ action: 'update', data }, globals()));
     });

package/src/config-schema.ts

@@ -0,0 +1,178 @@
+import { CLIError } from './error.js';
+import { SUPPORTED_NETWORKS } from './types.js';
+
+/**
+ * Declarative schema of the known config-file paths, used by both the write-time
+ * validation in `config set` and the strict `config validate` check so the two
+ * cannot disagree. Leaves name a value kind: `'string'`, `'number'`, `'object'`
+ * (a free-form map, e.g. headers), or `'enum:<name>'`. The `'*'` key under
+ * `profiles` matches any profile name.
+ */
+const CONFIG_SCHEMA: SchemaNode = {
+  schemaVersion : 'number',
+  defaults      : {
+    profile : 'string',
+    network : 'enum:network',
+    output  : 'enum:output',
+  },
+  profiles : {
+    '*' : {
+      network : 'enum:network',
+      btc     : {
+        rest          : 'string',
+        rpcUrl        : 'string',
+        rpcUser       : 'string',
+        rpcPass       : 'string',
+        feeRate       : 'number',
+        changeAddress : 'string',
+        timeoutMs     : 'number',
+        headers       : 'object',
+        wallet        : 'string',
+        rpcHeaders    : 'object',
+      },
+      cas : {
+        gateway   : 'string',
+        rpcUrl    : 'string',
+        timeoutMs : 'number',
+      },
+      identity : {
+        keystore : 'string',
+        default  : 'string',
+      },
+    },
+  },
+};
+
+type SchemaLeaf = 'string' | 'number' | 'object' | `enum:${string}`;
+type SchemaNode = { [key: string]: SchemaLeaf | SchemaNode };
+
+/** One problem found in a config file: the dotted path and a human-readable reason. */
+export interface ConfigIssue {
+  path  : string;
+  issue : string;
+}
+
+/**
+ * Resolves a dotted config path to its schema node: a leaf kind string, a nested
+ * {@link SchemaNode}, or `undefined` when the path is not part of the known
+ * schema. A segment under `profiles` matches the `'*'` template.
+ */
+function lookupSchemaNode(dotted: string): SchemaLeaf | SchemaNode | undefined {
+  let node: SchemaLeaf | SchemaNode | undefined = CONFIG_SCHEMA;
+  for (const segment of dotted.split('.')) {
+    if (typeof node !== 'object') return undefined;
+    // Own-property checks only: `in` would match inherited Object.prototype names
+    // (`toString`, `constructor`, `__proto__`), treating a builtin as a known key.
+    if (Object.hasOwn(node, segment)) {
+      node = node[segment];
+    } else if (Object.hasOwn(node, '*')) {
+      node = node['*'];
+    } else {
+      return undefined;
+    }
+  }
+  return node;
+}
+
+/** Whether a dotted path is part of the known config schema (leaf or intermediate). */
+export function isKnownConfigPath(dotted: string): boolean {
+  return lookupSchemaNode(dotted) !== undefined;
+}
+
+/**
+ * Validates a value against a leaf kind, throwing a {@link CLIError} for a value
+ * that does not match: an out-of-range enum, a non-number for a `number` leaf, or
+ * a non-object for an `object` leaf (a map such as `headers`). A no-op for
+ * `string` leaves and for intermediate nodes.
+ */
+function assertLeafValue(kind: SchemaLeaf, dotted: string, value: unknown): void {
+  if (kind === 'enum:network' && !SUPPORTED_NETWORKS.includes(value as never)) {
+    throw new CLIError(
+      `Invalid value for ${dotted}: "${String(value)}". Expected one of ${SUPPORTED_NETWORKS.join(', ')}.`,
+      'INVALID_ARGUMENT_ERROR',
+      { path: dotted, value },
+    );
+  }
+  if (kind === 'enum:output' && value !== 'json' && value !== 'text') {
+    throw new CLIError(
+      `Invalid value for ${dotted}: "${String(value)}". Expected "json" or "text".`,
+      'INVALID_ARGUMENT_ERROR',
+      { path: dotted, value },
+    );
+  }
+  if (kind === 'number' && typeof value !== 'number') {
+    throw new CLIError(
+      `Invalid value for ${dotted}: expected a number, got ${typeof value}. `
+      + 'Pass a bare number (e.g. `config set ' + dotted + ' 5`).',
+      'INVALID_ARGUMENT_ERROR',
+      { path: dotted, value },
+    );
+  }
+  if (kind === 'object' && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+    throw new CLIError(
+      `Invalid value for ${dotted}: expected a JSON object (e.g. \`config set ${dotted} '{"Key":"Value"}'\`).`,
+      'INVALID_ARGUMENT_ERROR',
+      { path: dotted, value },
+    );
+  }
+}
+
+/**
+ * Write-time validation for `config set`. An enum, number, or object leaf whose
+ * value has the wrong kind is a hard rejection (throws). An unknown path is
+ * permitted but reported, so `config set` can warn and still write (keeping
+ * forward-compatible and third-party keys usable). Returns `{ unknownPath }`.
+ */
+export function validateConfigSet(dotted: string, value: unknown): { unknownPath: boolean } {
+  const node = lookupSchemaNode(dotted);
+  if (node === undefined) return { unknownPath: true };
+  if (typeof node === 'string') {
+    assertLeafValue(node, dotted, value);
+  }
+  return { unknownPath: false };
+}
+
+/**
+ * Strict validation for `config validate`: walks a parsed config and collects
+ * every unknown key and out-of-enum value, plus a `schemaVersion` that is newer
+ * than this CLI supports. Never throws; returns the full list so the caller can
+ * report all problems at once.
+ */
+export function findConfigIssues(config: Record<string, unknown>, supportedSchemaVersion: number): ConfigIssue[] {
+  const issues: ConfigIssue[] = [];
+
+  const version = config.schemaVersion;
+  if (typeof version === 'number' && version > supportedSchemaVersion) {
+    issues.push({
+      path  : 'schemaVersion',
+      issue : `newer than supported (${version} > ${supportedSchemaVersion}); upgrade the CLI to use this file`,
+    });
+  }
+
+  walk(config, [], issues);
+  return issues;
+}
+
+/** Recursively collects unknown-key and bad-enum issues under `prefix`. */
+function walk(obj: Record<string, unknown>, prefix: string[], issues: ConfigIssue[]): void {
+  for (const [ key, value ] of Object.entries(obj)) {
+    const path = [ ...prefix, key ];
+    const dotted = path.join('.');
+    const node = lookupSchemaNode(dotted);
+
+    if (node === undefined) {
+      issues.push({ path: dotted, issue: 'unknown key' });
+      continue; // Do not descend into an unknown subtree.
+    }
+
+    if (typeof node === 'string') {
+      try {
+        assertLeafValue(node, dotted, value);
+      } catch (error) {
+        issues.push({ path: dotted, issue: (error as Error).message });
+      }
+    } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      walk(value as Record<string, unknown>, path, issues);
+    }
+  }
+}