@did-btcr2/cli 0.10.3 → 0.12.0

package/dist/esm/src/keystore/envelope.js

@@ -0,0 +1,123 @@
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { argon2id } from '@noble/hashes/argon2.js';
+import { randomBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+import { base64urlnopad } from '@scure/base';
+import { KeyStoreError } from './error.js';
+/** Current keystore secret-envelope format version. */
+export const ENVELOPE_VERSION = 1;
+/** Random salt length in bytes for argon2id. */
+const SALT_BYTES = 16;
+/** XChaCha20-Poly1305 extended nonce length in bytes (safe with random nonces). */
+const NONCE_BYTES = 24;
+/** Derived symmetric key length in bytes (the XChaCha20-Poly1305 key size). */
+const KEY_BYTES = 32;
+/**
+ * Production argon2id parameters: 3 passes over 64 MiB across 4 lanes, deriving
+ * a 32-byte key. Recorded in every envelope so the cost can be raised later
+ * without making previously sealed envelopes undecryptable.
+ */
+export const DEFAULT_ARGON_PARAMS = { t: 3, m: 65536, p: 4, dkLen: KEY_BYTES };
+/**
+ * Builds the header with a fixed key order so the additional-data bytes are
+ * byte-identical on the encrypt and decrypt paths.
+ */
+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',
+    };
+}
+/** Serializes the header into the AEAD additional-data byte string. */
+function headerAad(header) {
+    return utf8ToBytes(JSON.stringify(header));
+}
+/**
+ * Stretches a passphrase into the symmetric key. The transient UTF-8 copy of
+ * the passphrase is zeroized here; the caller is responsible for zeroizing the
+ * returned key after use.
+ */
+function deriveKey(passphrase, salt, params) {
+    const password = utf8ToBytes(passphrase);
+    try {
+        return argon2id(password, salt, { t: params.t, m: params.m, p: params.p, dkLen: params.dkLen });
+    }
+    finally {
+        password.fill(0);
+    }
+}
+/**
+ * Seals a secret under a passphrase into a {@link SecretEnvelope}. A fresh
+ * random salt and nonce are generated per call, so encrypting the same secret
+ * twice yields different envelopes.
+ *
+ * @param secret - The secret bytes to encrypt. Must be non-empty.
+ * @param passphrase - The passphrase the encryption key is derived from.
+ * @param params - argon2id cost parameters. Defaults to {@link DEFAULT_ARGON_PARAMS}.
+ * @returns The versioned, authenticated envelope.
+ * @throws {KeyStoreError} `ENVELOPE_ENCRYPT_ERROR` when `secret` is empty.
+ */
+export 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 = randomBytes(SALT_BYTES);
+    const nonce = randomBytes(NONCE_BYTES);
+    const header = buildHeader(base64urlnopad.encode(salt), params);
+    const key = deriveKey(passphrase, salt, params);
+    try {
+        const ciphertext = xchacha20poly1305(key, nonce, headerAad(header)).encrypt(secret);
+        return {
+            ...header,
+            nonce: base64urlnopad.encode(nonce),
+            ciphertext: base64urlnopad.encode(ciphertext),
+        };
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/**
+ * Opens a {@link SecretEnvelope} sealed by {@link encryptSecret} and returns the
+ * plaintext secret. A wrong passphrase, corrupted ciphertext, or a tampered
+ * header all fail authentication and raise `DECRYPT_ERROR`.
+ *
+ * @param env - The envelope to open.
+ * @param passphrase - The passphrase the envelope was sealed with.
+ * @returns The decrypted secret bytes.
+ * @throws {KeyStoreError} `ENVELOPE_VERSION_ERROR` for an unknown version or
+ *   algorithm; `DECRYPT_ERROR` for failed authentication.
+ */
+export 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 = base64urlnopad.decode(env.kdf.salt);
+    const nonce = base64urlnopad.decode(env.nonce);
+    const ciphertext = base64urlnopad.decode(env.ciphertext);
+    const header = buildHeader(env.kdf.salt, params);
+    const key = deriveKey(passphrase, salt, params);
+    try {
+        return 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);
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/esm/src/keystore/envelope.js.map

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

package/dist/esm/src/keystore/error.js

@@ -0,0 +1,16 @@
+import { DidMethodError } from '@did-btcr2/common';
+/**
+ * Error raised by the CLI keystore layer: secret-envelope encryption and
+ * decryption, on-disk file permission enforcement, and passphrase acquisition.
+ *
+ * Unlike {@link CLIError} (whose `name` is fixed to `'CLIError'`), this follows
+ * the {@link DidMethodError} sibling convention where `name` mirrors the `type`
+ * code, so a thrown error's `name` reflects the specific failure category
+ * (for example `DECRYPT_ERROR` or `KEYSTORE_PERMISSION_ERROR`).
+ */
+export class KeyStoreError extends DidMethodError {
+    constructor(message, type = 'KeyStoreError', data) {
+        super(message, { type, name: type, data });
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/esm/src/keystore/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../../src/keystore/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,cAAc;IAC/C,YAAY,OAAe,EAAE,OAAe,eAAe,EAAE,IAA0B;QACrF,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/esm/src/keystore/file-backed-key-manager.js

@@ -0,0 +1,78 @@
+import { LocalKeyManager, } from '@did-btcr2/key-manager';
+import { FileKeyStore } from './file-key-store.js';
+/**
+ * A {@link KeyManager} backed by the encrypted on-disk {@link FileKeyStore}.
+ *
+ * It composes a {@link LocalKeyManager} over a {@link FileKeyStore} and adds the
+ * one thing the store interface cannot express: persisting the active-key
+ * pointer. `LocalKeyManager` tracks the active key only in process memory, so
+ * this wrapper mirrors every active-key change to the keystore file and
+ * re-applies the persisted pointer at construction. Read and signing
+ * operations delegate straight through.
+ *
+ * Injected as the api's KeyManager so every command reaches it uniformly via
+ * `api.kms`, and "the active key" survives across CLI invocations.
+ */
+export class FileBackedKeyManager {
+    /** Capability probe: the local store supports exporting secret material. */
+    canExport = true;
+    #store;
+    #inner;
+    constructor(options) {
+        this.#store = new FileKeyStore(options);
+        this.#inner = new LocalKeyManager(this.#store);
+        // Apply the persisted active pointer only if the key still exists. A
+        // dangling pointer (from out-of-band file editing or a partial write) is
+        // ignored rather than thrown, so recovery commands stay usable; the next
+        // setActiveKey overwrites it. has() is a non-decrypting cache lookup.
+        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) {
+        // LocalKeyManager.removeKey calls FileKeyStore.delete, which already clears
+        // the persisted active pointer when the removed key was the active one.
+        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);
+    }
+}
+//# sourceMappingURL=file-backed-key-manager.js.map

package/dist/esm/src/keystore/file-backed-key-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-backed-key-manager.js","sourceRoot":"","sources":["../../../../src/keystore/file-backed-key-manager.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/keystore/file-key-store.js

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { base64urlnopad } from '@scure/base';
+import { assertSecurePerms, ensureDir, writeFileAtomic } from './atomic.js';
+import { DEFAULT_ARGON_PARAMS, decryptSecret, encryptSecret } from './envelope.js';
+import { KeyStoreError } from './error.js';
+import { defaultKeystorePath } from './paths.js';
+/** Current on-disk keystore file format version. */
+export const KEYSTORE_VERSION = 1;
+/**
+ * A Node-only, file-backed {@link KeyValueStore} that encrypts secret keys at
+ * rest. It satisfies the synchronous store contract by caching the parsed file
+ * in memory at construction and flushing the whole file atomically on every
+ * mutation.
+ *
+ * Secrets are materialized only through {@link FileKeyStore.get}. The
+ * {@link FileKeyStore.list} and {@link FileKeyStore.entries} projections omit
+ * secret keys and never decrypt, so enumerating the store never triggers a
+ * passphrase prompt.
+ */
+export class FileKeyStore {
+    #path;
+    #getPassphrase;
+    #argonParams;
+    #cache = new Map();
+    #active;
+    constructor(options) {
+        this.#path = options.path ?? defaultKeystorePath();
+        this.#getPassphrase = options.getPassphrase;
+        this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
+        ensureDir(dirname(this.#path), 0o700);
+        this.#load();
+    }
+    #load() {
+        if (!existsSync(this.#path))
+            return;
+        assertSecurePerms(this.#path);
+        let parsed;
+        try {
+            parsed = JSON.parse(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 = 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: 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)}\n`, 0o600);
+    }
+    get(id) {
+        const entry = this.#cache.get(id);
+        if (!entry)
+            return undefined;
+        const result = {
+            publicKey: entry.publicKey,
+            ...(entry.tags && { tags: entry.tags }),
+        };
+        if (entry.secret) {
+            // Materialize the secret lazily, only when it is actually accessed, so
+            // reads that need just public material (an active-key existence check,
+            // getPublicKey, getEntry) never trigger a passphrase prompt. The property
+            // is non-enumerable so spreading or serializing the entry cannot silently
+            // decrypt the 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)
+            : undefined;
+        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 = undefined;
+            this.#flush();
+        }
+        return existed;
+    }
+    clear() {
+        this.#cache.clear();
+        this.#active = undefined;
+        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 = undefined;
+        }
+        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 !== undefined && !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();
+    }
+}
+//# sourceMappingURL=file-key-store.js.map

package/dist/esm/src/keystore/file-key-store.js.map

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

package/dist/esm/src/keystore/passphrase.js

@@ -0,0 +1,87 @@
+import { readFileSync, readSync } from 'node:fs';
+import { KeyStoreError } from './error.js';
+/** Environment variable that supplies the keystore passphrase for unattended use. */
+export const ENV_KEYSTORE_PASSPHRASE = 'BTCR2_KEYSTORE_PASSPHRASE';
+/**
+ * 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 function acquirePassphrase(options = {}) {
+    // All sources are normalized identically (at most one trailing newline
+    // removed) so the KDF input is source-independent.
+    const fromEnv = process.env[ENV_KEYSTORE_PASSPHRASE];
+    if (fromEnv)
+        return assertNonEmpty(fromEnv.replace(/\r?\n$/, ''));
+    if (options.passphraseFile) {
+        return assertNonEmpty(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);
+}
+/** Rejects an empty or whitespace-only passphrase, which would seal the keystore with no protection. */
+function assertNonEmpty(passphrase) {
+    if (passphrase.trim() === '') {
+        throw new KeyStoreError('A non-empty keystore passphrase is required.', 'PASSPHRASE_REQUIRED_ERROR');
+    }
+    return passphrase;
+}
+/**
+ * Reads a line from the terminal synchronously without echoing keystrokes.
+ * Bytes are accumulated and decoded as UTF-8 so multibyte passphrases survive.
+ * This path runs only when standard input is a terminal.
+ */
+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 = readSync(stdin.fd, byte, 0, 1, null);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'EAGAIN')
+                    continue; // no byte ready yet on a non-blocking TTY
+                if (code === 'EOF')
+                    break;
+                throw error;
+            }
+            if (read === 0)
+                break;
+            const ch = byte[0];
+            if (ch === 0x0a || ch === 0x0d)
+                break; // LF or CR ends the line
+            if (ch === 0x03) { // Ctrl-C aborts
+                throw new KeyStoreError('Passphrase entry aborted.', 'PASSPHRASE_REQUIRED_ERROR');
+            }
+            if (ch === 0x7f || ch === 0x08) { // DEL or backspace
+                bytes.pop();
+                continue;
+            }
+            bytes.push(ch);
+        }
+    }
+    finally {
+        stdin.setRawMode(wasRaw);
+        process.stderr.write('\n');
+    }
+    return Buffer.from(bytes).toString('utf-8');
+}
+//# sourceMappingURL=passphrase.js.map

package/dist/esm/src/keystore/passphrase.js.map

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

package/dist/esm/src/keystore/paths.js

@@ -0,0 +1,20 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * 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 function defaultKeystorePath() {
+    const base = process.env.XDG_DATA_HOME
+        ?? process.env.LOCALAPPDATA
+        ?? join(homedir(), '.local', 'share');
+    return join(base, 'btcr2', 'keystore.json');
+}
+//# sourceMappingURL=paths.js.map

package/dist/esm/src/keystore/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/keystore/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa;WACjC,OAAO,CAAC,GAAG,CAAC,YAAY;WACxB,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;AAC9C,CAAC"}

package/dist/esm/src/keystore/resolve-key-ref.js

@@ -0,0 +1,47 @@
+import { CLIError } from '../error.js';
+/** Extracts the 32-hex fingerprint from a `urn:kms:secp256k1:<hex>` identifier. */
+function fingerprintOf(id) {
+    return /^urn:kms:secp256k1:([0-9a-f]{32})$/.exec(id)?.[1];
+}
+/**
+ * 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 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 });
+}
+//# sourceMappingURL=resolve-key-ref.js.map

package/dist/esm/src/keystore/resolve-key-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-key-ref.js","sourceRoot":"","sources":["../../../../src/keystore/resolve-key-ref.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,mFAAmF;AACnF,SAAS,aAAa,CAAC,EAAiB;IACtC,OAAO,oCAAoC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,GAAe,EAAE,GAAY;IACzD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,QAAQ,CAChB,mGAAmG,EACnG,wBAAwB,CACzB,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC,WAAW,CAAC;IACzB,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IAE3B,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAElC,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAChB,4BAA4B,GAAG,aAAa,QAAQ,CAAC,MAAM,uBAAuB,EAClF,yBAAyB,EACzB,EAAE,GAAG,EAAE,CACR,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,CAAC;IACrE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,QAAQ,CAChB,uBAAuB,GAAG,aAAa,MAAM,CAAC,MAAM,QAAQ,EAC5D,yBAAyB,EACzB,EAAE,GAAG,EAAE,CACR,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,QAAQ,CAAC,6BAA6B,GAAG,IAAI,EAAE,qBAAqB,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AAC3F,CAAC"}

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

@@ -13,9 +13,13 @@ export declare 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);
+    constructor(factory?: ApiFactory, keystoreFactory?: ApiFactory);
     /**
      * Runs the CLI with the provided argv or process.argv.
      * @param {string[]} [argv] - Optional array of command-line arguments.

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAOpD,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAKjE;;GAEG;AACH,qBAAa,WAAW;IACtB,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;;;;;;;;OASG;gBACS,OAAO,GAAE,UAA8B;IAuBnD;;;;OAIG;IACU,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CASjD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAWpD,OAAO,EAAyC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAIrF;;GAEG;AACH,qBAAa,WAAW;IACtB,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;;;;;;;;;;;;OAaG;gBAED,OAAO,GAAE,UAA8B,EACvC,eAAe,GAAE,UAA+B;IA+BlD;;;;OAIG;IACU,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CASjD"}

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

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+import type { GlobalOptions } from '../types.js';
+/** Registers the `completion` command, which prints a shell completion script to stdout. */
+export declare function registerCompletionCommand(program: Command, _globals: () => GlobalOptions): void;
+//# sourceMappingURL=completion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../../../src/commands/completion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,4FAA4F;AAC5F,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,GAAG,IAAI,CAO/F"}

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

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+import type { GlobalOptions } from '../types.js';
+/** Registers the `config` command group for reading and writing CLI configuration. */
+export declare function registerConfigCommand(program: Command, globals: () => GlobalOptions): void;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,aAAa,CAAC;AAGhE,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CAuD1F"}