@did-btcr2/cli 0.10.2 → 0.11.0

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

@@ -0,0 +1,20 @@
+/** Environment variable that supplies the keystore passphrase for unattended use. */
+export declare const ENV_KEYSTORE_PASSPHRASE = "BTCR2_KEYSTORE_PASSPHRASE";
+/** Options controlling how a passphrase is acquired. */
+export type PassphraseOptions = {
+    /** Path to a file whose contents (a trailing newline is trimmed) are the passphrase. */
+    passphraseFile?: string;
+    /** Prompt label shown on a terminal. */
+    prompt?: string;
+    /** When true, prompt twice and require the entries to match (for a new keystore). */
+    confirm?: boolean;
+};
+/**
+ * Acquires a passphrase without ever reading it from a command-line flag value
+ * (which would leak into process listings and shell history). Resolution order:
+ * the {@link ENV_KEYSTORE_PASSPHRASE} environment variable, a passphrase file,
+ * then a non-echoing terminal prompt. Throws if none is available and standard
+ * input is not a terminal.
+ */
+export declare function acquirePassphrase(options?: PassphraseOptions): string;
+//# sourceMappingURL=passphrase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"passphrase.d.ts","sourceRoot":"","sources":["../../../../src/keystore/passphrase.ts"],"names":[],"mappings":"AAGA,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAyBzE"}

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

@@ -0,0 +1,13 @@
+/**
+ * Default keystore file path, following the XDG Base Directory Specification's
+ * data directory. Secret key material is data a user accumulates, so it lives
+ * under the data directory, kept separate from the configuration directory used
+ * for portable settings.
+ *
+ * Resolution order:
+ * 1. `$XDG_DATA_HOME/btcr2/keystore.json`
+ * 2. `%LOCALAPPDATA%/btcr2/keystore.json` (Windows)
+ * 3. `~/.local/share/btcr2/keystore.json` (fallback)
+ */
+export declare function defaultKeystorePath(): string;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/keystore/paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAK5C"}

package/dist/types/src/keystore/resolve-key-ref.d.ts

@@ -0,0 +1,19 @@
+import type { KeyIdentifier, KeyManager } from '@did-btcr2/key-manager';
+/**
+ * Resolves a user-supplied key reference to a key identifier. Resolution order:
+ * 1. No reference: the active key (errors if none is set).
+ * 2. Exact URN identifier match.
+ * 3. Unique fingerprint-prefix match (against the hex tail of the URN).
+ * 4. Unique `name` tag match.
+ *
+ * Reads only public material (listKeys + getEntry), so resolving a reference
+ * never decrypts a secret or prompts for a passphrase.
+ *
+ * @param kms The key manager to resolve against.
+ * @param ref The reference to resolve. When omitted, the active key is used.
+ * @returns The resolved key identifier.
+ * @throws {CLIError} If no key matches, the reference is ambiguous, or no
+ *   reference is given and no active key is set.
+ */
+export declare function resolveKeyRef(kms: KeyManager, ref?: string): KeyIdentifier;
+//# sourceMappingURL=resolve-key-ref.d.ts.map

package/dist/types/src/keystore/resolve-key-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-key-ref.d.ts","sourceRoot":"","sources":["../../../../src/keystore/resolve-key-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAQxE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CAqC1E"}

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

@@ -33,6 +33,94 @@ export type CommandResult = {
 } | {
     action: 'deactivate';
     data: SignedBTCR2Update;
+} | {
+    action: 'key-generate';
+    data: {
+        keyId: string;
+        publicKey: string;
+        active: boolean;
+    };
+} | {
+    action: 'key-list';
+    data: Array<{
+        keyId: string;
+        fingerprint: string;
+        name?: string;
+        active: boolean;
+    }>;
+} | {
+    action: 'key-show';
+    data: {
+        keyId: string;
+        publicKey: string;
+        tags?: Record<string, string>;
+    };
+} | {
+    action: 'key-import';
+    data: {
+        keyId: string;
+        publicKey: string;
+        watchOnly: boolean;
+        active: boolean;
+    };
+} | {
+    action: 'key-export';
+    data: {
+        keyId: string;
+        publicKey?: string;
+        secretWrittenTo?: string;
+    };
+} | {
+    action: 'key-delete';
+    data: {
+        keyId: string;
+        deleted: true;
+    };
+} | {
+    action: 'key-use';
+    data: {
+        keyId: string;
+        active: true;
+    };
+} | {
+    action: 'config-init';
+    data: {
+        path: string;
+    };
+} | {
+    action: 'config-get';
+    data: unknown;
+} | {
+    action: 'config-set';
+    data: {
+        path: string;
+    };
+} | {
+    action: 'config-unset';
+    data: {
+        path: string;
+    };
+} | {
+    action: 'config-list';
+    data: unknown;
+} | {
+    action: 'profile-add';
+    data: {
+        profile: string;
+    };
+} | {
+    action: 'profile-use';
+    data: {
+        profile: string;
+    };
+} | {
+    action: 'profile-show';
+    data: unknown;
+} | {
+    action: 'profile-remove';
+    data: {
+        profile: string;
+    };
 };
 export interface GlobalOptions {
     output: OutputFormat;
@@ -45,5 +133,8 @@ export interface GlobalOptions {
     btcRpcUser?: string;
     btcRpcPass?: string;
     casGateway?: string;
+    keystore?: string;
+    passphraseFile?: string;
+    signingKey?: string;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AACrG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,eAAO,MAAM,kBAAkB,EAAE,aAAa,EAE7C,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAM,GAAG,GAAG,GAAG,CAAC;IACpB,KAAK,EAAK,MAAM,CAAC;IACjB,OAAO,EAAG,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAG,MAAM,CAAC;IACpB,OAAO,CAAC,EAAK,iBAAiB,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAS,gBAAgB,CAAC;IACxC,OAAO,EAAgB,cAAc,EAAE,CAAC;IACxC,eAAe,EAAQ,MAAM,CAAC;IAC9B,oBAAoB,EAAG,MAAM,CAAC;IAC9B,QAAQ,EAAe,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAO,YAAY,CAAC;IAC1B,OAAO,EAAM,OAAO,CAAC;IACrB,KAAK,EAAQ,OAAO,CAAC;IACrB,MAAM,CAAC,EAAM,MAAM,CAAC;IACpB,OAAO,CAAC,EAAK,MAAM,CAAC;IACpB,OAAO,CAAC,EAAK,MAAM,CAAC;IACpB,SAAS,CAAC,EAAG,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"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.10.2",
+  "version": "0.11.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.2",
+    "@did-btcr2/api": "^0.10.0",
+    "@did-btcr2/cryptosuite": "^8.0.0",
     "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/method": "^0.36.0",
-    "@did-btcr2/cryptosuite": "^8.0.0"
+    "@did-btcr2/key-manager": "^0.7.0",
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/method": "^0.39.0"
   },
   "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);
     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/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';