@did-btcr2/cli 0.10.2 → 0.11.0

package/dist/cjs/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CLIError: () => CLIError,
+  CONFIG_SCHEMA_VERSION: () => CONFIG_SCHEMA_VERSION,
   DidBtcr2Cli: () => DidBtcr2Cli,
   ENV_VARS: () => ENV_VARS,
   SUPPORTED_NETWORKS: () => SUPPORTED_NETWORKS,
@@ -29,21 +30,31 @@ __export(index_exports, {
   defaultConfigPath: () => defaultConfigPath,
   deriveNetwork: () => deriveNetwork,
   formatResult: () => formatResult,
+  getConfigPath: () => getConfigPath,
+  keystoreApiFactory: () => keystoreApiFactory,
   profileToOverrides: () => profileToOverrides,
   readConfigFile: () => readConfigFile,
   readEnvOverrides: () => readEnvOverrides,
+  registerCompletionCommand: () => registerCompletionCommand,
+  registerConfigCommand: () => registerConfigCommand,
   registerCreateCommand: () => registerCreateCommand,
   registerDeactivateCommand: () => registerDeactivateCommand,
+  registerKeyCommand: () => registerKeyCommand,
+  registerProfileCommand: () => registerProfileCommand,
   registerResolveCommand: () => registerResolveCommand,
-  registerUpdateCommand: () => registerUpdateCommand
+  registerUpdateCommand: () => registerUpdateCommand,
+  setConfigPath: () => setConfigPath,
+  unsetConfigPath: () => unsetConfigPath,
+  writeConfigFile: () => writeConfigFile
 });
 module.exports = __toCommonJS(index_exports);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.7.3_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_typescript@5.7.3_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/cli.ts
+var import_common3 = require("@did-btcr2/common");
 var import_commander = require("commander");
 
 // src/error.ts
@@ -139,9 +150,503 @@ var import_promises = require("fs/promises");
 
 // src/config.ts
 var import_api = require("@did-btcr2/api");
+var import_node_fs4 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path4 = require("path");
+
+// src/keystore/atomic.ts
 var import_node_fs = require("fs");
-var import_node_os = require("os");
 var import_node_path = require("path");
+
+// src/keystore/error.ts
+var import_common2 = require("@did-btcr2/common");
+var KeyStoreError = class extends import_common2.DidMethodError {
+  constructor(message, type = "KeyStoreError", data) {
+    super(message, { type, name: type, data });
+  }
+};
+
+// src/keystore/atomic.ts
+var isWindows = process.platform === "win32";
+var permsWarned = false;
+var tmpCounter = 0;
+function ensureDir(dir, mode) {
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode });
+  if (!isWindows) {
+    try {
+      (0, import_node_fs.chmodSync)(dir, mode);
+    } catch {
+    }
+  }
+}
+function writeFileAtomic(path, data, mode) {
+  const tmp = (0, import_node_path.join)((0, import_node_path.dirname)(path), `.${(0, import_node_path.basename)(path)}.${process.pid}.${tmpCounter++}.tmp`);
+  try {
+    (0, import_node_fs.writeFileSync)(tmp, data, { mode });
+    if (!isWindows) (0, import_node_fs.chmodSync)(tmp, mode);
+    (0, import_node_fs.renameSync)(tmp, path);
+  } catch (error) {
+    try {
+      (0, import_node_fs.rmSync)(tmp, { force: true });
+    } catch {
+    }
+    throw new KeyStoreError(
+      `Failed to write keystore at ${path}.`,
+      "ATOMIC_WRITE_ERROR",
+      { path, cause: error instanceof Error ? error.message : String(error) }
+    );
+  }
+}
+function assertSecurePerms(path) {
+  if (isWindows) {
+    if (!permsWarned) {
+      process.stderr.write(
+        "warning: file permissions are not enforced on Windows; protect the keystore directory manually.\n"
+      );
+      permsWarned = true;
+    }
+    return;
+  }
+  const mode = (0, import_node_fs.statSync)(path).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new KeyStoreError(
+      `Keystore at ${path} has insecure permissions 0${mode.toString(8)}; expected 0600.`,
+      "KEYSTORE_PERMISSION_ERROR",
+      { path, mode: `0${mode.toString(8)}` }
+    );
+  }
+}
+
+// src/keystore/file-backed-key-manager.ts
+var import_key_manager = require("@did-btcr2/key-manager");
+
+// src/keystore/file-key-store.ts
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+var import_base2 = require("@scure/base");
+
+// src/keystore/envelope.ts
+var import_chacha = require("@noble/ciphers/chacha.js");
+var import_argon2 = require("@noble/hashes/argon2.js");
+var import_utils = require("@noble/hashes/utils.js");
+var import_base = require("@scure/base");
+var ENVELOPE_VERSION = 1;
+var SALT_BYTES = 16;
+var NONCE_BYTES = 24;
+var KEY_BYTES = 32;
+var DEFAULT_ARGON_PARAMS = { t: 3, m: 65536, p: 4, dkLen: KEY_BYTES };
+function buildHeader(saltB64, params) {
+  return {
+    v: ENVELOPE_VERSION,
+    kdf: {
+      alg: "argon2id",
+      salt: saltB64,
+      t: params.t,
+      m: params.m,
+      p: params.p,
+      dkLen: params.dkLen
+    },
+    cipher: "xchacha20poly1305"
+  };
+}
+function headerAad(header) {
+  return (0, import_utils.utf8ToBytes)(JSON.stringify(header));
+}
+function deriveKey(passphrase, salt, params) {
+  const password = (0, import_utils.utf8ToBytes)(passphrase);
+  try {
+    return (0, import_argon2.argon2id)(password, salt, { t: params.t, m: params.m, p: params.p, dkLen: params.dkLen });
+  } finally {
+    password.fill(0);
+  }
+}
+function encryptSecret(secret, passphrase, params = DEFAULT_ARGON_PARAMS) {
+  if (secret.length === 0) {
+    throw new KeyStoreError("Cannot encrypt an empty secret.", "ENVELOPE_ENCRYPT_ERROR");
+  }
+  const salt = (0, import_utils.randomBytes)(SALT_BYTES);
+  const nonce = (0, import_utils.randomBytes)(NONCE_BYTES);
+  const header = buildHeader(import_base.base64urlnopad.encode(salt), params);
+  const key = deriveKey(passphrase, salt, params);
+  try {
+    const ciphertext = (0, import_chacha.xchacha20poly1305)(key, nonce, headerAad(header)).encrypt(secret);
+    return {
+      ...header,
+      nonce: import_base.base64urlnopad.encode(nonce),
+      ciphertext: import_base.base64urlnopad.encode(ciphertext)
+    };
+  } finally {
+    key.fill(0);
+  }
+}
+function decryptSecret(env, passphrase) {
+  if (env.v !== ENVELOPE_VERSION) {
+    throw new KeyStoreError(
+      `Unsupported keystore envelope version: ${String(env.v)}.`,
+      "ENVELOPE_VERSION_ERROR",
+      { version: env.v }
+    );
+  }
+  if (env.kdf?.alg !== "argon2id" || env.cipher !== "xchacha20poly1305") {
+    throw new KeyStoreError("Unsupported keystore envelope algorithm.", "ENVELOPE_VERSION_ERROR");
+  }
+  const params = { t: env.kdf.t, m: env.kdf.m, p: env.kdf.p, dkLen: env.kdf.dkLen };
+  const salt = import_base.base64urlnopad.decode(env.kdf.salt);
+  const nonce = import_base.base64urlnopad.decode(env.nonce);
+  const ciphertext = import_base.base64urlnopad.decode(env.ciphertext);
+  const header = buildHeader(env.kdf.salt, params);
+  const key = deriveKey(passphrase, salt, params);
+  try {
+    return (0, import_chacha.xchacha20poly1305)(key, nonce, headerAad(header)).decrypt(ciphertext);
+  } catch (error) {
+    if (error instanceof KeyStoreError) throw error;
+    throw new KeyStoreError(
+      "Keystore decryption failed: wrong passphrase or corrupted keystore.",
+      "DECRYPT_ERROR"
+    );
+  } finally {
+    key.fill(0);
+  }
+}
+
+// src/keystore/paths.ts
+var import_node_os = require("os");
+var import_node_path2 = require("path");
+function defaultKeystorePath() {
+  const base = process.env.XDG_DATA_HOME ?? process.env.LOCALAPPDATA ?? (0, import_node_path2.join)((0, import_node_os.homedir)(), ".local", "share");
+  return (0, import_node_path2.join)(base, "btcr2", "keystore.json");
+}
+
+// src/keystore/file-key-store.ts
+var KEYSTORE_VERSION = 1;
+var FileKeyStore = class {
+  #path;
+  #getPassphrase;
+  #argonParams;
+  #cache = /* @__PURE__ */ new Map();
+  #active;
+  constructor(options) {
+    this.#path = options.path ?? defaultKeystorePath();
+    this.#getPassphrase = options.getPassphrase;
+    this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
+    ensureDir((0, import_node_path3.dirname)(this.#path), 448);
+    this.#load();
+  }
+  #load() {
+    if (!(0, import_node_fs2.existsSync)(this.#path)) return;
+    assertSecurePerms(this.#path);
+    let parsed;
+    try {
+      parsed = JSON.parse((0, import_node_fs2.readFileSync)(this.#path, "utf-8"));
+    } catch {
+      throw new KeyStoreError(
+        `Keystore at ${this.#path} is corrupt or unreadable.`,
+        "KEYSTORE_CORRUPT_ERROR",
+        { path: this.#path }
+      );
+    }
+    if (parsed.v !== KEYSTORE_VERSION) {
+      throw new KeyStoreError(
+        `Unsupported keystore version: ${String(parsed.v)}.`,
+        "KEYSTORE_VERSION_ERROR",
+        { version: parsed.v }
+      );
+    }
+    this.#active = parsed.active;
+    for (const [id, stored] of Object.entries(parsed.keys ?? {})) {
+      let publicKey;
+      try {
+        if (typeof stored.publicKey !== "string") throw new Error("missing publicKey");
+        publicKey = import_base2.base64urlnopad.decode(stored.publicKey);
+      } catch {
+        throw new KeyStoreError(
+          `Keystore entry ${id} has a malformed public key.`,
+          "KEYSTORE_CORRUPT_ERROR",
+          { path: this.#path, keyId: id }
+        );
+      }
+      if (publicKey.length !== 33) {
+        throw new KeyStoreError(
+          `Keystore entry ${id} has a ${publicKey.length}-byte public key; expected 33.`,
+          "KEYSTORE_CORRUPT_ERROR",
+          { path: this.#path, keyId: id }
+        );
+      }
+      this.#cache.set(id, {
+        publicKey,
+        ...stored.tags && { tags: stored.tags },
+        ...stored.secret && { secret: stored.secret }
+      });
+    }
+  }
+  #flush() {
+    const keys = {};
+    for (const [id, entry] of this.#cache) {
+      keys[id] = {
+        publicKey: import_base2.base64urlnopad.encode(entry.publicKey),
+        ...entry.tags && { tags: entry.tags },
+        ...entry.secret && { secret: entry.secret }
+      };
+    }
+    const file = {
+      v: KEYSTORE_VERSION,
+      ...this.#active && { active: this.#active },
+      keys
+    };
+    writeFileAtomic(this.#path, `${JSON.stringify(file, null, 2)}
+`, 384);
+  }
+  get(id) {
+    const entry = this.#cache.get(id);
+    if (!entry) return void 0;
+    const result = {
+      publicKey: entry.publicKey,
+      ...entry.tags && { tags: entry.tags }
+    };
+    if (entry.secret) {
+      const sealed = entry.secret;
+      Object.defineProperty(result, "secretKey", {
+        configurable: true,
+        enumerable: false,
+        get: () => {
+          entry.decrypted ??= decryptSecret(sealed, this.#getPassphrase());
+          return entry.decrypted;
+        }
+      });
+    }
+    return result;
+  }
+  has(id) {
+    return this.#cache.has(id);
+  }
+  set(id, value) {
+    const secret = value.secretKey ? encryptSecret(value.secretKey, this.#getPassphrase(), this.#argonParams) : void 0;
+    this.#cache.set(id, {
+      publicKey: value.publicKey,
+      ...value.tags && { tags: value.tags },
+      ...secret && { secret },
+      ...value.secretKey && { decrypted: value.secretKey }
+    });
+    this.#flush();
+  }
+  delete(id) {
+    const existed = this.#cache.delete(id);
+    if (existed) {
+      if (this.#active === id) this.#active = void 0;
+      this.#flush();
+    }
+    return existed;
+  }
+  clear() {
+    this.#cache.clear();
+    this.#active = void 0;
+    this.#flush();
+  }
+  /** All stored values with secret keys omitted. Never decrypts, never prompts. */
+  list() {
+    return this.entries().map(([, value]) => value);
+  }
+  /**
+   * All entries as id-value tuples with secret keys omitted. Never decrypts,
+   * never prompts: {@link FileKeyStore.get} is the only secret-materializing
+   * path, so callers that only need identifiers (such as `listKeys`) do not
+   * force a passphrase prompt. This deviates intentionally from the in-memory
+   * store, which returns stored values verbatim.
+   */
+  entries() {
+    const out = [];
+    for (const [id, entry] of this.#cache) {
+      out.push([id, {
+        publicKey: entry.publicKey,
+        ...entry.tags && { tags: entry.tags }
+      }]);
+    }
+    return out;
+  }
+  close() {
+    for (const entry of this.#cache.values()) {
+      entry.decrypted?.fill(0);
+      entry.decrypted = void 0;
+    }
+    this.#cache.clear();
+  }
+  /** The persisted active-key identifier, or undefined if none is set. */
+  getActive() {
+    return this.#active;
+  }
+  /**
+   * Persists the active-key pointer in the keystore file. Passing undefined
+   * clears it. Throws if the identifier is not a known key.
+   */
+  setActive(id) {
+    if (id !== void 0 && !this.#cache.has(id)) {
+      throw new KeyStoreError(`Cannot set unknown key as active: ${id}.`, "KEY_NOT_FOUND_ERROR", { keyId: id });
+    }
+    this.#active = id;
+    this.#flush();
+  }
+};
+
+// src/keystore/file-backed-key-manager.ts
+var FileBackedKeyManager = class {
+  /** Capability probe: the local store supports exporting secret material. */
+  canExport = true;
+  #store;
+  #inner;
+  constructor(options) {
+    this.#store = new FileKeyStore(options);
+    this.#inner = new import_key_manager.LocalKeyManager(this.#store);
+    const active = this.#store.getActive();
+    if (active && this.#store.has(active)) this.#inner.setActiveKey(active);
+  }
+  get activeKeyId() {
+    return this.#inner.activeKeyId;
+  }
+  setActiveKey(id) {
+    this.#inner.setActiveKey(id);
+    this.#store.setActive(id);
+  }
+  importKey(keyPair, options) {
+    const id = this.#inner.importKey(keyPair, options);
+    if (options?.setActive) this.#store.setActive(id);
+    return id;
+  }
+  generateKey(options) {
+    const id = this.#inner.generateKey(options);
+    if (options?.setActive) this.#store.setActive(id);
+    return id;
+  }
+  removeKey(id, options) {
+    this.#inner.removeKey(id, options);
+  }
+  listKeys() {
+    return this.#inner.listKeys();
+  }
+  getPublicKey(id) {
+    return this.#inner.getPublicKey(id);
+  }
+  getEntry(id) {
+    return this.#inner.getEntry(id);
+  }
+  sign(data, id, options) {
+    return this.#inner.sign(data, id, options);
+  }
+  verify(signature, data, id, options) {
+    return this.#inner.verify(signature, data, id, options);
+  }
+  digest(data) {
+    return this.#inner.digest(data);
+  }
+  exportKey(id) {
+    return this.#inner.exportKey(id);
+  }
+};
+
+// src/keystore/passphrase.ts
+var import_node_fs3 = require("fs");
+var ENV_KEYSTORE_PASSPHRASE = "BTCR2_KEYSTORE_PASSPHRASE";
+function acquirePassphrase(options = {}) {
+  const fromEnv = process.env[ENV_KEYSTORE_PASSPHRASE];
+  if (fromEnv) return assertNonEmpty(fromEnv.replace(/\r?\n$/, ""));
+  if (options.passphraseFile) {
+    return assertNonEmpty((0, import_node_fs3.readFileSync)(options.passphraseFile, "utf-8").replace(/\r?\n$/, ""));
+  }
+  if (!process.stdin.isTTY) {
+    throw new KeyStoreError(
+      `No passphrase available. Set ${ENV_KEYSTORE_PASSPHRASE}, pass --passphrase-file, or run in a terminal.`,
+      "PASSPHRASE_REQUIRED_ERROR"
+    );
+  }
+  const passphrase = promptHidden(options.prompt ?? "Keystore passphrase: ");
+  if (options.confirm) {
+    const again = promptHidden("Confirm passphrase: ");
+    if (passphrase !== again) {
+      throw new KeyStoreError("Passphrases did not match.", "PASSPHRASE_MISMATCH_ERROR");
+    }
+  }
+  return assertNonEmpty(passphrase);
+}
+function assertNonEmpty(passphrase) {
+  if (passphrase.trim() === "") {
+    throw new KeyStoreError("A non-empty keystore passphrase is required.", "PASSPHRASE_REQUIRED_ERROR");
+  }
+  return passphrase;
+}
+function promptHidden(label) {
+  process.stderr.write(label);
+  const stdin = process.stdin;
+  const wasRaw = stdin.isRaw ?? false;
+  stdin.setRawMode(true);
+  const byte = Buffer.alloc(1);
+  const bytes = [];
+  try {
+    for (; ; ) {
+      let read = 0;
+      try {
+        read = (0, import_node_fs3.readSync)(stdin.fd, byte, 0, 1, null);
+      } catch (error) {
+        const code = error.code;
+        if (code === "EAGAIN") continue;
+        if (code === "EOF") break;
+        throw error;
+      }
+      if (read === 0) break;
+      const ch = byte[0];
+      if (ch === 10 || ch === 13) break;
+      if (ch === 3) {
+        throw new KeyStoreError("Passphrase entry aborted.", "PASSPHRASE_REQUIRED_ERROR");
+      }
+      if (ch === 127 || ch === 8) {
+        bytes.pop();
+        continue;
+      }
+      bytes.push(ch);
+    }
+  } finally {
+    stdin.setRawMode(wasRaw);
+    process.stderr.write("\n");
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+// src/config.ts
+var CONFIG_SCHEMA_VERSION = 1;
+function writeConfigFile(path, mutate) {
+  const raw = readConfigFile(path) ?? {};
+  mutate(raw);
+  raw.schemaVersion = CONFIG_SCHEMA_VERSION;
+  ensureDir((0, import_node_path4.dirname)(path), 448);
+  writeFileAtomic(path, `${JSON.stringify(raw, null, 2)}
+`, 384);
+}
+function getConfigPath(config, path) {
+  return path.split(".").reduce(
+    (node, key) => node?.[key],
+    config
+  );
+}
+function setConfigPath(config, path, value) {
+  const keys = path.split(".");
+  const last = keys.pop();
+  if (!last) throw new CLIError("Config path must be non-empty.", "INVALID_ARGUMENT_ERROR");
+  let node = config;
+  for (const key of keys) {
+    if (typeof node[key] !== "object" || node[key] === null) node[key] = {};
+    node = node[key];
+  }
+  node[last] = value;
+}
+function unsetConfigPath(config, path) {
+  const keys = path.split(".");
+  const last = keys.pop();
+  if (!last) return;
+  let node = config;
+  for (const key of keys) {
+    node = node?.[key];
+    if (!node) return;
+  }
+  delete node[last];
+}
 var ENV_VARS = {
   BTC_REST: "BTCR2_BTC_REST",
   BTC_RPC_URL: "BTCR2_BTC_RPC_URL",
@@ -160,12 +665,12 @@ function readEnvOverrides() {
   };
 }
 function defaultConfigPath() {
-  const base = process.env.XDG_CONFIG_HOME ?? process.env.APPDATA ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".config");
-  return (0, import_node_path.join)(base, "btcr2", "config.json");
+  const base = process.env.XDG_CONFIG_HOME ?? process.env.APPDATA ?? (0, import_node_path4.join)((0, import_node_os2.homedir)(), ".config");
+  return (0, import_node_path4.join)(base, "btcr2", "config.json");
 }
 function readConfigFile(path) {
   try {
-    const content = (0, import_node_fs.readFileSync)(path, "utf-8");
+    const content = (0, import_node_fs4.readFileSync)(path, "utf-8");
     return JSON.parse(content);
   } catch {
     return void 0;
@@ -182,11 +687,11 @@ function profileToOverrides(config, profileName) {
     casGateway: profile.cas?.gateway
   };
 }
-function defaultApiFactory(network, overrides) {
-  if (!network) return (0, import_api.createApi)();
+function resolveConnectionConfig(network, overrides) {
+  if (!network) return {};
   const configPath = overrides?.config ?? defaultConfigPath();
-  const profileName = overrides?.profile ?? network;
   const file = readConfigFile(configPath);
+  const profileName = overrides?.profile ?? file?.defaults?.profile ?? network;
   const fileOverrides = file ? profileToOverrides(file, profileName) : {};
   const env = readEnvOverrides();
   const merged = {
@@ -208,7 +713,22 @@ function defaultApiFactory(network, overrides) {
     };
   }
   const cas = merged.casGateway ? { gateway: merged.casGateway } : void 0;
-  return (0, import_api.createApi)({ btc, ...cas && { cas } });
+  return { btc, ...cas && { cas } };
+}
+function defaultApiFactory(network, overrides) {
+  return (0, import_api.createApi)(resolveConnectionConfig(network, overrides));
+}
+function buildKeystoreKms(overrides) {
+  return new FileBackedKeyManager({
+    path: overrides?.keystore ?? defaultKeystorePath(),
+    getPassphrase: () => acquirePassphrase({ passphraseFile: overrides?.passphraseFile })
+  });
+}
+function keystoreApiFactory(network, overrides) {
+  return (0, import_api.createApi)({
+    ...resolveConnectionConfig(network, overrides),
+    kms: buildKeystoreKms(overrides)
+  });
 }
 function deriveNetwork(did) {
   const { network } = import_api.Identifier.decode(did);
@@ -261,6 +781,47 @@ async function validateResolveOptions(options) {
   return { identifier: options.identifier, options: resolutionOptions };
 }
 
+// src/commands/update.ts
+var import_key_manager2 = require("@did-btcr2/key-manager");
+
+// src/keystore/resolve-key-ref.ts
+function fingerprintOf(id) {
+  return /^urn:kms:secp256k1:([0-9a-f]{32})$/.exec(id)?.[1];
+}
+function resolveKeyRef(kms, ref) {
+  if (!ref) {
+    if (!kms.activeKeyId) {
+      throw new CLIError(
+        "No key specified and no active key is set. Use --key <ref> or set one with `btcr2 key use <ref>`.",
+        "INVALID_ARGUMENT_ERROR"
+      );
+    }
+    return kms.activeKeyId;
+  }
+  const ids = kms.listKeys();
+  if (ids.includes(ref)) return ref;
+  const prefix = ref.toLowerCase();
+  const byPrefix = ids.filter((id) => fingerprintOf(id)?.startsWith(prefix));
+  if (byPrefix.length === 1) return byPrefix[0];
+  if (byPrefix.length > 1) {
+    throw new CLIError(
+      `Ambiguous key reference "${ref}" matches ${byPrefix.length} keys by fingerprint.`,
+      "KEY_REF_AMBIGUOUS_ERROR",
+      { ref }
+    );
+  }
+  const byName = ids.filter((id) => kms.getEntry(id).tags?.name === ref);
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    throw new CLIError(
+      `Ambiguous key name "${ref}" matches ${byName.length} keys.`,
+      "KEY_REF_AMBIGUOUS_ERROR",
+      { ref }
+    );
+  }
+  throw new CLIError(`No key matches reference "${ref}".`, "KEY_NOT_FOUND_ERROR", { ref });
+}
+
 // src/commands/update.ts
 function registerUpdateCommand(program, factory, globals) {
   program.command("update").description("Update a did:btcr2 document.").requiredOption(
@@ -282,6 +843,13 @@ function registerUpdateCommand(program, factory, globals) {
     "Beacon ID as a JSON string",
     parseJsonArg("--beacon-id")
   ).action(async (options) => {
+    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 = {
       sourceDocument: options.sourceDocument,
       patches: options.patches,
@@ -297,15 +865,19 @@ function registerUpdateCommand(program, factory, globals) {
         options
       );
     }
-    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: "update" }
-    );
+    const network = deriveNetwork(did);
+    const api = factory(network, globals());
+    const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+    const signer = new import_key_manager2.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: "update", data }, globals()));
   });
 }
 function parseJsonArg(flagName) {
@@ -323,6 +895,7 @@ function parseJsonArg(flagName) {
 }
 
 // src/commands/deactivate.ts
+var import_key_manager3 = require("@did-btcr2/key-manager");
 var DEACTIVATION_PATCH = [{ op: "add", path: "/deactivated", value: true }];
 function registerDeactivateCommand(program, factory, globals) {
   program.command("deactivate").alias("delete").description("Deactivate the did:btcr2 identifier permanently. This is irreversible.").requiredOption(
@@ -340,6 +913,13 @@ function registerDeactivateCommand(program, factory, globals) {
     "Beacon ID as a JSON string",
     parseJsonArg2("--beacon-id")
   ).action(async (options) => {
+    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 = {
       sourceDocument: options.sourceDocument,
       patches: DEACTIVATION_PATCH,
@@ -355,15 +935,19 @@ function registerDeactivateCommand(program, factory, globals) {
         options
       );
     }
-    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" }
-    );
+    const network = deriveNetwork(did);
+    const api = factory(network, globals());
+    const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+    const signer = new import_key_manager3.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()));
   });
 }
 function parseJsonArg2(flagName) {
@@ -380,19 +964,263 @@ function parseJsonArg2(flagName) {
   };
 }
 
+// src/commands/key.ts
+var import_keypair = require("@did-btcr2/keypair");
+var import_utils2 = require("@noble/hashes/utils.js");
+var import_node_fs5 = require("fs");
+function registerKeyCommand(program, factory, globals) {
+  const key = program.command("key").description("Manage keypairs in the encrypted keystore.");
+  const print = (result) => console.log(formatResult(result, globals()));
+  key.command("generate").description("Generate a new keypair and store it.").option("--name <name>", "A human-friendly name, stored as a tag and usable as a key reference.").option("--set-active", "Make this the active key.", false).action((options) => {
+    const api = factory(void 0, globals());
+    assertNameAvailable(api.kms.kms, options.name);
+    const setActive = options.setActive ?? false;
+    const id = api.kms.generateKey({ ...options.name && { tags: { name: options.name } }, setActive });
+    print({ action: "key-generate", data: { keyId: id, publicKey: (0, import_utils2.bytesToHex)(api.kms.getPublicKey(id)), active: setActive } });
+  });
+  key.command("list").alias("ls").description("List stored keys.").action(() => {
+    const kms = factory(void 0, globals()).kms.kms;
+    const active = kms.activeKeyId;
+    const data = kms.listKeys().map((id) => {
+      const entry = kms.getEntry(id);
+      return {
+        keyId: id,
+        fingerprint: id.split(":").pop() ?? id,
+        ...entry.tags?.name && { name: entry.tags.name },
+        active: id === active
+      };
+    });
+    print({ action: "key-list", data });
+  });
+  key.command("show <ref>").description("Show a key's public material and tags. Never prints the secret.").action((ref) => {
+    const kms = factory(void 0, globals()).kms.kms;
+    const id = resolveKeyRef(kms, ref);
+    const entry = kms.getEntry(id);
+    print({ action: "key-show", data: { keyId: id, publicKey: (0, import_utils2.bytesToHex)(entry.publicKey), ...entry.tags && { tags: entry.tags } } });
+  });
+  key.command("import").description("Import a key: a secret from a hex file, or a public key as watch-only.").option("--secret-file <path>", "Path to a file containing a 32-byte secret key as hex.").option("--public <hex>", "A 33-byte compressed public key as hex (imported watch-only).").option("--name <name>", "A human-friendly name, stored as a tag.").option("--set-active", "Make this the active key.", false).action((options) => {
+    if (Boolean(options.secretFile) === Boolean(options.public)) {
+      throw new CLIError("Provide exactly one of --secret-file or --public.", "INVALID_ARGUMENT_ERROR");
+    }
+    const api = factory(void 0, globals());
+    assertNameAvailable(api.kms.kms, options.name);
+    const keyPair = options.secretFile ? new import_keypair.SchnorrKeyPair({ secretKey: readHexFile(options.secretFile, 32, "--secret-file") }) : new import_keypair.SchnorrKeyPair({ publicKey: parseHex(options.public ?? "", 33, "--public") });
+    const setActive = options.setActive ?? false;
+    const id = api.kms.import(keyPair, { ...options.name && { tags: { name: options.name } }, setActive });
+    print({ action: "key-import", data: { keyId: id, publicKey: (0, import_utils2.bytesToHex)(api.kms.getPublicKey(id)), watchOnly: !options.secretFile, active: setActive } });
+  });
+  key.command("export <ref>").description("Export a key. Public material by default; --secret writes the secret to a file.").option("--secret", "Export the secret key. Requires --out.", false).option("--out <path>", "Write the exported secret to this file (created 0600).").action((ref, options) => {
+    const api = factory(void 0, globals());
+    const id = resolveKeyRef(api.kms.kms, ref);
+    if (!options.secret) {
+      print({ action: "key-export", data: { keyId: id, publicKey: (0, import_utils2.bytesToHex)(api.kms.getPublicKey(id)) } });
+      return;
+    }
+    if (!options.out) {
+      throw new CLIError("Exporting a secret requires --out <file> so it is not written to the terminal.", "INVALID_ARGUMENT_ERROR");
+    }
+    const keyPair = api.kms.export(id);
+    if (!keyPair.hasSecretKey) {
+      throw new CLIError(`Key ${id} is watch-only and has no secret to export.`, "INVALID_ARGUMENT_ERROR", { keyId: id });
+    }
+    process.stderr.write("warning: writing an unencrypted secret key to disk. Protect this file and delete it when done.\n");
+    writeSecretFile(options.out, (0, import_utils2.bytesToHex)(keyPair.secretKey.bytes));
+    print({ action: "key-export", data: { keyId: id, secretWrittenTo: options.out } });
+  });
+  key.command("delete <ref>").alias("rm").description("Delete a key from the keystore.").option("--force", "Delete even if it is the active key.", false).action((ref, options) => {
+    const api = factory(void 0, globals());
+    const id = resolveKeyRef(api.kms.kms, ref);
+    api.kms.removeKey(id, { force: options.force ?? false });
+    print({ action: "key-delete", data: { keyId: id, deleted: true } });
+  });
+  key.command("use <ref>").description("Set the active key, persisted across invocations.").action((ref) => {
+    const api = factory(void 0, globals());
+    const id = resolveKeyRef(api.kms.kms, ref);
+    api.kms.setActive(id);
+    print({ action: "key-use", data: { keyId: id, active: true } });
+  });
+}
+function assertNameAvailable(kms, name) {
+  if (!name) return;
+  if (kms.listKeys().some((id) => kms.getEntry(id).tags?.name === name)) {
+    throw new CLIError(`A key named "${name}" already exists.`, "INVALID_ARGUMENT_ERROR", { name });
+  }
+}
+function parseHex(hex, expectedBytes, label) {
+  let bytes;
+  try {
+    bytes = (0, import_utils2.hexToBytes)(hex.trim());
+  } catch {
+    throw new CLIError(`Invalid hex for ${label}.`, "INVALID_ARGUMENT_ERROR", { label });
+  }
+  if (bytes.length !== expectedBytes) {
+    throw new CLIError(
+      `${label} must be ${expectedBytes} bytes (${expectedBytes * 2} hex chars), got ${bytes.length}.`,
+      "INVALID_ARGUMENT_ERROR",
+      { label }
+    );
+  }
+  return bytes;
+}
+function readHexFile(path, expectedBytes, label) {
+  let content;
+  try {
+    content = (0, import_node_fs5.readFileSync)(path, "utf-8");
+  } catch {
+    throw new CLIError(`Cannot read ${label} at ${path}.`, "INVALID_ARGUMENT_ERROR", { label, path });
+  }
+  return parseHex(content, expectedBytes, label);
+}
+function writeSecretFile(path, contents) {
+  let fd;
+  try {
+    fd = (0, import_node_fs5.openSync)(path, "wx", 384);
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      throw new CLIError(`Refusing to overwrite existing file ${path}. Choose a new --out path.`, "INVALID_ARGUMENT_ERROR", { path });
+    }
+    throw error;
+  }
+  try {
+    (0, import_node_fs5.writeFileSync)(fd, contents);
+  } finally {
+    (0, import_node_fs5.closeSync)(fd);
+  }
+}
+
+// src/commands/config.ts
+var import_node_fs6 = require("fs");
+var import_node_path5 = require("path");
+function registerConfigCommand(program, globals) {
+  const config = program.command("config").description("Read and write CLI configuration.");
+  const path = () => globals().config ?? defaultConfigPath();
+  const print = (result) => 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) => {
+    const p = path();
+    if ((0, import_node_fs6.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((0, import_node_path5.dirname)(p), 448);
+    writeFileAtomic(p, `${JSON.stringify(scaffold, null, 2)}
+`, 384);
+    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) => {
+    const file = readConfigFile(path()) ?? {};
+    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, value) => {
+    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) => {
+    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()) ?? {} });
+  });
+}
+function parseValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+// src/commands/profile.ts
+function registerProfileCommand(program, globals) {
+  const profile = program.command("profile").description("Manage configuration profiles.");
+  const path = () => globals().config ?? defaultConfigPath();
+  const print = (result) => console.log(formatResult(result, globals()));
+  profile.command("add <name>").description("Add an empty profile.").action((name) => {
+    writeConfigFile(path(), (raw) => {
+      if (raw.profiles === void 0 || raw.profiles === null) raw.profiles = {};
+      const profiles = raw.profiles;
+      if (profiles[name]) throw new CLIError(`Profile "${name}" already exists.`, "INVALID_ARGUMENT_ERROR", { name });
+      profiles[name] = {};
+    });
+    print({ action: "profile-add", data: { profile: name } });
+  });
+  profile.command("use <name>").description("Set the active profile (writes defaults.profile).").action((name) => {
+    writeConfigFile(path(), (raw) => {
+      if (raw.defaults === void 0 || raw.defaults === null) raw.defaults = {};
+      raw.defaults.profile = name;
+    });
+    print({ action: "profile-use", data: { profile: name } });
+  });
+  profile.command("show [name]").description("Show a profile (defaults to the active profile).").action((name) => {
+    const file = readConfigFile(path()) ?? {};
+    const target = name ?? file.defaults?.profile;
+    if (!target) {
+      throw new CLIError("No profile specified and no active profile is set.", "INVALID_ARGUMENT_ERROR");
+    }
+    const data = file.profiles?.[target];
+    if (!data) {
+      throw new CLIError(`Profile "${target}" not found.`, "INVALID_ARGUMENT_ERROR", { profile: target });
+    }
+    print({ action: "profile-show", data: { profile: target, ...data } });
+  });
+  profile.command("remove <name>").alias("rm").description("Remove a profile.").action((name) => {
+    writeConfigFile(path(), (raw) => {
+      const profiles = raw.profiles;
+      if (!profiles?.[name]) throw new CLIError(`Profile "${name}" not found.`, "INVALID_ARGUMENT_ERROR", { name });
+      delete profiles[name];
+    });
+    print({ action: "profile-remove", data: { profile: name } });
+  });
+}
+
+// src/commands/completion.ts
+var COMMANDS = "create resolve read update deactivate delete key config profile completion";
+function registerCompletionCommand(program, _globals) {
+  program.command("completion [shell]").description("Print a shell completion script (bash, zsh, or fish) to stdout.").action((shell = "bash") => {
+    console.log(completionScript(shell));
+  });
+}
+function completionScript(shell) {
+  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 });
+  }
+}
+
 // src/version.ts
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_node_fs7 = require("fs");
+var import_node_path6 = require("path");
 var import_node_url = require("url");
 function readVersion() {
-  let dir = (0, import_node_path2.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+  let dir = (0, import_node_path6.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
   for (let i = 0; i < 5; i++) {
     try {
-      const pkg = JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(dir, "package.json"), "utf-8"));
+      const pkg = JSON.parse((0, import_node_fs7.readFileSync)((0, import_node_path6.join)(dir, "package.json"), "utf-8"));
       if (pkg.name === "@did-btcr2/cli") return pkg.version;
     } catch {
     }
-    dir = (0, import_node_path2.dirname)(dir);
+    dir = (0, import_node_path6.dirname)(dir);
   }
   return "0.0.0";
 }
@@ -409,15 +1237,23 @@ var DidBtcr2Cli = class {
    * {@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 = defaultApiFactory) {
-    this.program = new import_commander.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("--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("--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").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");
+  constructor(factory = defaultApiFactory, keystoreFactory = keystoreApiFactory) {
+    this.program = new import_commander.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("--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("--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").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("--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 = () => this.program.opts();
     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);
   }
   /**
    * Runs the CLI with the provided argv or process.argv.
@@ -430,7 +1266,7 @@ var DidBtcr2Cli = class {
       await this.program.parseAsync(normalized, { from: "node" });
       if (!this.program.args.length) this.program.outputHelp();
     } catch (error) {
-      handleError(error);
+      handleError(error, Boolean(this.program.opts().verbose));
     }
   }
 };
@@ -439,12 +1275,12 @@ function normalizeArgv(argv) {
   if (argv.length === 1) return ["node", argv[0]];
   return ["node", "btcr2"];
 }
-function handleError(error) {
+function handleError(error, verbose) {
   if (error instanceof import_commander.CommanderError && (error.code === "commander.helpDisplayed" || error.code === "commander.help")) {
     return;
   }
-  if (error instanceof CLIError) {
-    console.error(error.message);
+  if (error instanceof import_common3.DidMethodError) {
+    console.error(verbose ? error : error.message);
     process.exitCode ??= 1;
     return;
   }
@@ -454,6 +1290,7 @@ function handleError(error) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CLIError,
+  CONFIG_SCHEMA_VERSION,
   DidBtcr2Cli,
   ENV_VARS,
   SUPPORTED_NETWORKS,
@@ -462,11 +1299,20 @@ function handleError(error) {
   defaultConfigPath,
   deriveNetwork,
   formatResult,
+  getConfigPath,
+  keystoreApiFactory,
   profileToOverrides,
   readConfigFile,
   readEnvOverrides,
+  registerCompletionCommand,
+  registerConfigCommand,
   registerCreateCommand,
   registerDeactivateCommand,
+  registerKeyCommand,
+  registerProfileCommand,
   registerResolveCommand,
-  registerUpdateCommand
+  registerUpdateCommand,
+  setConfigPath,
+  unsetConfigPath,
+  writeConfigFile
 });