@did-btcr2/cli 0.10.3 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/cli",
-  "version": "0.10.3",
+  "version": "0.12.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",
@@ -56,12 +56,17 @@
     "cli"
   ],
   "dependencies": {
+    "@noble/ciphers": "^2.1.1",
+    "@noble/hashes": "^2.0.1",
+    "@scure/base": "^1.2.6",
     "@web5/dids": "^1.2.0",
     "commander": "^13.1.0",
-    "@did-btcr2/api": "^0.9.3",
+    "@did-btcr2/api": "^0.11.0",
     "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/method": "^0.37.0",
-    "@did-btcr2/cryptosuite": "^8.0.0"
+    "@did-btcr2/cryptosuite": "^8.0.0",
+    "@did-btcr2/key-manager": "^0.7.0",
+    "@did-btcr2/method": "^0.39.0",
+    "@did-btcr2/keypair": "^0.13.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",

package/src/cli.ts

@@ -1,12 +1,16 @@
+import { DidMethodError } from '@did-btcr2/common';
 import { Command, CommanderError } from 'commander';
 import {
+  registerCompletionCommand,
+  registerConfigCommand,
   registerCreateCommand,
   registerDeactivateCommand,
+  registerKeyCommand,
+  registerProfileCommand,
   registerResolveCommand,
   registerUpdateCommand,
 } from './commands/index.js';
-import { defaultApiFactory, type ApiFactory } from './config.js';
-import { CLIError } from './error.js';
+import { defaultApiFactory, keystoreApiFactory, type ApiFactory } from './config.js';
 import type { GlobalOptions } from './types.js';
 import { VERSION } from './version.js';
 
@@ -24,9 +28,16 @@ export class DidBtcr2Cli {
    * {@link defaultApiFactory} which uses public endpoints (mempool.space)
    * for known networks and localhost Polar for regtest.
    *
-   * @param factory - Optional API factory. Defaults to {@link defaultApiFactory}.
+   * @param factory - Optional API factory for keystore-free commands (create,
+   *   resolve). Defaults to {@link defaultApiFactory}.
+   * @param keystoreFactory - Optional keystore-aware API factory for commands
+   *   that need a signing identity (key, update, deactivate). Defaults to
+   *   {@link keystoreApiFactory}.
    */
-  constructor(factory: ApiFactory = defaultApiFactory) {
+  constructor(
+    factory: ApiFactory = defaultApiFactory,
+    keystoreFactory: ApiFactory = keystoreApiFactory,
+  ) {
     this.program = new Command('btcr2')
       .version(`btcr2 ${VERSION}`, '-v, --version', 'Output the current version')
       .description('CLI tool for the did:btcr2 method')
@@ -39,14 +50,21 @@ export class DidBtcr2Cli {
       .option('--btc-rpc-url <url>', 'Override Bitcoin Core RPC endpoint')
       .option('--btc-rpc-user <user>', 'Bitcoin Core RPC username')
       .option('--btc-rpc-pass <pass>', 'Bitcoin Core RPC password')
-      .option('--cas-gateway <url>', 'IPFS HTTP gateway for CAS reads');
+      .option('--cas-gateway <url>', 'IPFS HTTP gateway for CAS reads')
+      .option('--keystore <path>', 'Path to the keystore file (default: $XDG_DATA_HOME/btcr2/keystore.json)')
+      .option('--passphrase-file <path>', 'Read the keystore passphrase from a file (unattended use)')
+      .option('--signing-key <ref>', 'Key for update/deactivate signing: a URN, fingerprint prefix, or name');
 
     const globals = (): GlobalOptions => this.program.opts() as GlobalOptions;
 
-    registerCreateCommand(this.program, factory, globals);
+    registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
-    registerUpdateCommand(this.program, factory, globals);
-    registerDeactivateCommand(this.program, factory, globals);
+    registerUpdateCommand(this.program, keystoreFactory, globals);
+    registerDeactivateCommand(this.program, keystoreFactory, globals);
+    registerKeyCommand(this.program, keystoreFactory, globals);
+    registerConfigCommand(this.program, globals);
+    registerProfileCommand(this.program, globals);
+    registerCompletionCommand(this.program, globals);
   }
 
   /**
@@ -60,7 +78,7 @@ export class DidBtcr2Cli {
       await this.program.parseAsync(normalized, { from: 'node' });
       if (!this.program.args.length) this.program.outputHelp();
     } catch (error: unknown) {
-      handleError(error);
+      handleError(error, Boolean(this.program.opts().verbose));
     }
   }
 }
@@ -78,18 +96,25 @@ function normalizeArgv(argv: string[]): string[] {
 
 /**
  * Handles errors thrown during CLI execution.
+ *
+ * Known method errors ({@link DidMethodError} and its subclasses, including
+ * {@link CLIError} and the keystore errors) print only their message, never the
+ * stack or the structured `data` payload, so internal shapes are not leaked.
+ * The full error object and stack are shown only under `--verbose`.
+ *
  * @param {unknown} error - The error to handle.
+ * @param {boolean} verbose - Whether to print the full error object and stack.
  * @returns {void}
  */
-function handleError(error: unknown): void {
+function handleError(error: unknown, verbose: boolean): void {
   if (
     error instanceof CommanderError &&
     (error.code === 'commander.helpDisplayed' || error.code === 'commander.help')
   ) {
     return;
   }
-  if (error instanceof CLIError) {
-    console.error(error.message);
+  if (error instanceof DidMethodError) {
+    console.error(verbose ? error : error.message);
     process.exitCode ??= 1;
     return;
   }

package/src/commands/completion.ts

@@ -0,0 +1,40 @@
+import type { Command } from 'commander';
+import { CLIError } from '../error.js';
+import type { GlobalOptions } from '../types.js';
+
+const COMMANDS = 'create resolve read update deactivate delete key config profile completion';
+
+/** Registers the `completion` command, which prints a shell completion script to stdout. */
+export function registerCompletionCommand(program: Command, _globals: () => GlobalOptions): void {
+  program
+    .command('completion [shell]')
+    .description('Print a shell completion script (bash, zsh, or fish) to stdout.')
+    .action((shell = 'bash') => {
+      console.log(completionScript(shell));
+    });
+}
+
+/** Returns a completion script for the given shell. */
+function completionScript(shell: string): string {
+  switch (shell) {
+    case 'bash':
+      return [
+        '# btcr2 bash completion. Install with: eval "$(btcr2 completion bash)"',
+        '_btcr2() { COMPREPLY=( $(compgen -W "' + COMMANDS + '" -- "${COMP_WORDS[COMP_CWORD]}") ); }',
+        'complete -F _btcr2 btcr2',
+      ].join('\n');
+    case 'zsh':
+      return [
+        '# btcr2 zsh completion. Install with: eval "$(btcr2 completion zsh)"',
+        '_btcr2() { compadd ' + COMMANDS + ' }',
+        'compdef _btcr2 btcr2',
+      ].join('\n');
+    case 'fish':
+      return [
+        '# btcr2 fish completion. Save to ~/.config/fish/completions/btcr2.fish',
+        'complete -c btcr2 -f -a "' + COMMANDS + '"',
+      ].join('\n');
+    default:
+      throw new CLIError(`Unsupported shell "${shell}". Use bash, zsh, or fish.`, 'INVALID_ARGUMENT_ERROR', { shell });
+  }
+}

package/src/commands/config.ts

@@ -0,0 +1,84 @@
+import type { Command } from 'commander';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  CONFIG_SCHEMA_VERSION,
+  defaultConfigPath,
+  getConfigPath,
+  readConfigFile,
+  setConfigPath,
+  unsetConfigPath,
+  writeConfigFile,
+} from '../config.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 { 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 print = (result: CommandResult): void => console.log(formatResult(result, globals()));
+
+  config
+    .command('init')
+    .description('Create a default config file with one profile per network.')
+    .option('--force', 'Overwrite an existing config file.', false)
+    .action((options: { force?: boolean }) => {
+      const p = path();
+      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);
+      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) => {
+      const file = (readConfigFile(path()) ?? {}) as Record<string, unknown>;
+      print({ action: 'config-get', data: (dotted ? getConfigPath(file, dotted) : file) ?? null });
+    });
+
+  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)));
+      print({ action: 'config-set', data: { path: dotted } });
+    });
+
+  config
+    .command('unset <path>')
+    .description('Delete a value at a dotted path.')
+    .action((dotted: string) => {
+      writeConfigFile(path(), raw => unsetConfigPath(raw, dotted));
+      print({ action: 'config-unset', data: { path: dotted } });
+    });
+
+  config
+    .command('list')
+    .alias('ls')
+    .description('Print the entire config file.')
+    .action(() => {
+      print({ action: 'config-list', data: readConfigFile(path()) ?? {} });
+    });
+}
+
+/** Parses a value as JSON when valid, otherwise treats it as a plain string. */
+function parseValue(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}

package/src/commands/create.ts

@@ -1,14 +1,12 @@
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import type { Command } from 'commander';
-import type { ApiFactory } from '../config.js';
+import type { ApiFactory, ConnectionOverrides } from '../config.js';
+import { resolveDefaultNetwork } from '../config.js';
 import { CLIError } from '../error.js';
+import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
-import type {
-  CreateCommandOptions,
-  GlobalOptions,
-  NetworkOption} from '../types.js';
-import {
-  SUPPORTED_NETWORKS,
-} from '../types.js';
+import type { CommandResult, GlobalOptions, NetworkOption } from '../types.js';
+import { SUPPORTED_NETWORKS } from '../types.js';
 
 /** Expected byte length per identifier type: compressed secp256k1 = 33, SHA-256 hash = 32. */
 const EXPECTED_BYTES: Record<'k' | 'x', { length: number; label: string }> = {
@@ -16,74 +14,164 @@ const EXPECTED_BYTES: Record<'k' | 'x', { length: number; label: string }> = {
   x : { length: 32, label: 'SHA-256 hash (32 bytes)' },
 };
 
+/**
+ * Registers the `create` command.
+ *
+ * A deterministic (`-t k`) identifier has three mutually-exclusive input modes,
+ * selected by which is present:
+ * - generate (neither `--bytes` nor `--signing-key`): mint a fresh key, persist
+ *   it to the keystore, set it active, and print the identifier. Sealing the
+ *   secret prompts for the keystore passphrase.
+ * - existing (`--signing-key <ref>`): use a stored key's public key as the
+ *   genesis bytes. Reading a public key never decrypts, so this never prompts.
+ * - raw (`--bytes <hex>`): a 33-byte public key as hex. Offline, keystore-free.
+ *
+ * An external (`-t x`) identifier is raw-bytes-only: a 32-byte genesis-document
+ * hash via `--bytes`. Generation and `--signing-key` apply only to `-t k`.
+ *
+ * The keystore-free `factory` serves the raw-bytes path; the keystore-aware
+ * `keystoreFactory` serves the generate and existing-key paths.
+ */
 export function registerCreateCommand(
-  program : Command,
-  factory : ApiFactory,
-  globals : () => GlobalOptions,
+  program         : Command,
+  factory         : ApiFactory,
+  keystoreFactory : ApiFactory,
+  globals         : () => GlobalOptions,
 ): void {
   program
     .command('create')
     .description('Create an identifier and initial DID document')
-    .requiredOption('-t, --type <type>', 'Identifier type <k|x>', 'k')
-    .requiredOption(
+    .option('-t, --type <type>', 'Identifier type <k|x>', 'k')
+    .option(
       '-n, --network <network>',
-      'Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest>'
+      'Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> '
+      + '(default: config defaults.network, else regtest)'
     )
-    .requiredOption(
+    .option(
       '-b, --bytes <bytes>',
-      'Genesis bytes as a hex string. ' +
-      'If type=k, MUST be secp256k1 public key. ' +
-      'If type=x, MUST be SHA-256 hash of a genesis document'
+      'Genesis bytes as a hex string. '
+      + 'For type=k, a 33-byte secp256k1 public key (omit to generate a key). '
+      + 'For type=x, the 32-byte SHA-256 hash of a genesis document.'
     )
-    .action(async (options: { type: string; network: string; bytes: string }) => {
-      const parsed = validateCreateOptions(options);
-      const api = factory();
-      const type = parsed.type === 'k' ? 'deterministic' : 'external';
-      const genesisBytes = Buffer.from(parsed.bytes, 'hex');
-      const data = api.createDid(type, genesisBytes, { network: parsed.network });
-      const result = { action: 'create' as const, data };
-      console.log(formatResult(result, globals()));
+    .action(async (options: { type: string; network?: string; bytes?: string }) => {
+      const g = globals();
+      if (options.type !== 'k' && options.type !== 'x') {
+        throw new CLIError('Invalid type. Must be "k" or "x".', 'INVALID_ARGUMENT_ERROR', options);
+      }
+
+      const overrides = overridesFromGlobals(g);
+      const network = resolveNetwork(options.network, overrides);
+      const signingKey = g.signingKey;
+
+      /** Prints the result, plus a stderr provenance line in text mode. */
+      const print = (result: CommandResult, note?: string): void => {
+        console.log(formatResult(result, g));
+        if (note && g.output !== 'json') process.stderr.write(`${note}\n`);
+      };
+
+      // External: raw-bytes only.
+      if (options.type === 'x') {
+        if (signingKey) {
+          throw new CLIError(
+            '--signing-key applies only to deterministic identifiers (-t k).',
+            'INVALID_ARGUMENT_ERROR',
+          );
+        }
+        if (options.bytes === undefined) {
+          throw new CLIError(
+            'External identifiers (-t x) require --bytes <hex>, the 32-byte genesis document hash. '
+            + 'Key generation is only available for -t k.',
+            'INVALID_ARGUMENT_ERROR',
+          );
+        }
+        const genesisBytes = parseGenesisBytes(options.bytes, 'x');
+        const did = factory().createDid('external', genesisBytes, { network });
+        print({ action: 'create', data: did });
+        return;
+      }
+
+      // Deterministic (KEY): three mutually-exclusive modes.
+      if (options.bytes !== undefined && signingKey) {
+        throw new CLIError(
+          'Provide at most one of --bytes or --signing-key.',
+          'INVALID_ARGUMENT_ERROR',
+        );
+      }
+
+      // Raw bytes: keystore-free, offline.
+      if (options.bytes !== undefined) {
+        const genesisBytes = parseGenesisBytes(options.bytes, 'k');
+        const did = factory().createDid('deterministic', genesisBytes, { network });
+        print({ action: 'create', data: did });
+        return;
+      }
+
+      // Existing key: read its public key from the keystore (no passphrase prompt).
+      if (signingKey) {
+        const api = keystoreFactory(undefined, overrides);
+        const keyId = resolveKeyRef(api.kms.kms, signingKey);
+        const publicKey = api.kms.getPublicKey(keyId);
+        const did = api.createDid('deterministic', publicKey, { network });
+        print(
+          { action: 'create', data: did, keyId, publicKey: bytesToHex(publicKey) },
+          `Using stored key ${keyId}.`,
+        );
+        return;
+      }
+
+      // Generate: mint a fresh key, persist it, and set it active (passphrase prompt).
+      const api = keystoreFactory(undefined, overrides);
+      const { did, keyId } = api.generateDid({ network, setActive: true });
+      const publicKey = bytesToHex(api.kms.getPublicKey(keyId));
+      print(
+        { action: 'create', data: did, keyId, publicKey },
+        `Generated and stored key ${keyId} (now the active key).`,
+      );
     });
 }
 
-function validateCreateOptions(
-  options: { type: string; network: string; bytes: string }
-): CreateCommandOptions {
-  if (!['k', 'x'].includes(options.type)) {
-    throw new CLIError(
-      'Invalid type. Must be "k" or "x".',
-      'INVALID_ARGUMENT_ERROR',
-      options
-    );
-  }
-  if (!SUPPORTED_NETWORKS.includes(options.network as NetworkOption)) {
+/** Builds the keystore- and config-resolution overrides from the global flags. */
+function overridesFromGlobals(g: GlobalOptions): ConnectionOverrides {
+  return {
+    config         : g.config,
+    profile        : g.profile,
+    keystore       : g.keystore,
+    passphraseFile : g.passphraseFile,
+  };
+}
+
+/** Validates an explicit `--network`, or resolves the default from configuration. */
+function resolveNetwork(explicit: string | undefined, overrides: ConnectionOverrides): NetworkOption {
+  if (!explicit) return resolveDefaultNetwork(overrides);
+  if (!SUPPORTED_NETWORKS.includes(explicit as NetworkOption)) {
     throw new CLIError(
       'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
       'INVALID_ARGUMENT_ERROR',
-      options
+      { network: explicit },
     );
   }
+  return explicit as NetworkOption;
+}
 
-  const buf = Buffer.from(options.bytes, 'hex');
-  if (buf.length === 0) {
+/** Parses and length-checks hex genesis bytes for the given identifier type. */
+function parseGenesisBytes(hex: string, type: 'k' | 'x'): Uint8Array {
+  const expected = EXPECTED_BYTES[type];
+  let bytes: Uint8Array;
+  try {
+    bytes = hexToBytes(hex.trim());
+  } catch {
     throw new CLIError(
-      'Invalid bytes. Must be a non-empty hex string.',
+      `Invalid bytes: not valid hex. Expected ${expected.label}.`,
       'INVALID_ARGUMENT_ERROR',
-      options
+      { bytes: hex },
     );
   }
-  const expected = EXPECTED_BYTES[options.type as 'k' | 'x'];
-  if (buf.length !== expected.length) {
+  if (bytes.length !== expected.length) {
     throw new CLIError(
-      `Invalid bytes length for type="${options.type}": expected ${expected.label}, got ${buf.length} bytes.`,
+      `Invalid bytes length for type="${type}": expected ${expected.label}, got ${bytes.length} bytes.`,
       'INVALID_ARGUMENT_ERROR',
-      options
+      { bytes: hex },
     );
   }
-
-  return {
-    type    : options.type as 'k' | 'x',
-    network : options.network as NetworkOption,
-    bytes   : options.bytes,
-  };
+  return bytes;
 }

package/src/commands/deactivate.ts

@@ -1,6 +1,9 @@
+import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
 import { deriveNetwork, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
+import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
+import { formatResult } from '../output.js';
 import type { GlobalOptions, UpdateCommandOptions } from '../types.js';
 
 /** The JSON Patch that marks a DID document as permanently deactivated. */
@@ -39,6 +42,13 @@ export function registerDeactivateCommand(
       verificationMethodId : string;
       beaconId             : unknown;
     }) => {
+      if (!/^\d+$/.test(options.sourceVersionId)) {
+        throw new CLIError(
+          '--source-version-id must be a non-negative integer.',
+          'INVALID_ARGUMENT_ERROR',
+          { value: options.sourceVersionId },
+        );
+      }
       const parsed: UpdateCommandOptions = {
         sourceDocument       : options.sourceDocument as UpdateCommandOptions['sourceDocument'],
         patches              : DEACTIVATION_PATCH,
@@ -54,18 +64,21 @@ export function registerDeactivateCommand(
           options
         );
       }
-      // CLI signing is not yet wired up; deactivate uses the same update path
-      // and inherits the same gap. Drive the SDK directly with a `Signer` for now.
-      // Variables above are kept so command parsing + validation still works.
-      void deriveNetwork(did);
-      void factory;
-      void globals;
-      void parsed;
-      throw new CLIError(
-        'CLI signing is not yet implemented. Use @did-btcr2/api with a Signer directly.',
-        'NOT_IMPLEMENTED_ERROR',
-        { command: 'deactivate' }
-      );
+      // 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);
+      const api = factory(network, globals());
+      const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+      const signer = new KeyManagerSigner(api.kms.kms, keyId);
+      const data = await api.btcr2.update({
+        sourceDocument       : parsed.sourceDocument,
+        patches              : parsed.patches,
+        sourceVersionId      : parsed.sourceVersionId,
+        verificationMethodId : parsed.verificationMethodId,
+        beaconId             : parsed.beaconId,
+        signer,
+      });
+      console.log(formatResult({ action: 'deactivate', data }, globals()));
     });
 }
 

package/src/commands/index.ts

@@ -2,3 +2,7 @@ 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 { registerConfigCommand } from './config.js';
+export { registerProfileCommand } from './profile.js';
+export { registerCompletionCommand } from './completion.js';