@did-btcr2/api 0.2.1 → 0.2.2

package/dist/esm/api.js

@@ -1,139 +1,802 @@
-import { BitcoinCoreRpcClient, BitcoinRestClient } from '@did-btcr2/bitcoin';
-import { DEFAULT_BLOCK_CONFIRMATIONS, DEFAULT_REST_CONFIG, DEFAULT_RPC_CONFIG, IdentifierTypes, NotImplementedError } from '@did-btcr2/common';
-import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
-import { SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
+import { BitcoinConnection } from '@did-btcr2/bitcoin';
+import { IdentifierTypes, NotImplementedError } from '@did-btcr2/common';
+import { BIP340Cryptosuite, BIP340DataIntegrityProof, SchnorrMultikey } from '@did-btcr2/cryptosuite';
+import { CompressedSecp256k1PublicKey, SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
+import { Kms, } from '@did-btcr2/kms';
 import { DidBtcr2, DidDocument, DidDocumentBuilder, Identifier } from '@did-btcr2/method';
+import { Did } from '@web5/dids';
 export { DidDocument, DidDocumentBuilder, Identifier, IdentifierTypes };
-/* =========================
- * Sub-facade: KeyPair
- * ========================= */
+const noopFn = () => { };
+/** @internal */
+const NOOP_LOGGER = {
+    debug: noopFn,
+    info: noopFn,
+    warn: noopFn,
+    error: noopFn,
+};
+// ---------------------------------------------------------------------------
+// Validation helpers (module-private)
+// ---------------------------------------------------------------------------
+/** @internal */
+function assertString(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${name} must be a non-empty string.`);
+    }
+}
+/** @internal */
+function assertBytes(value, name) {
+    if (!(value instanceof Uint8Array) || value.length === 0) {
+        throw new Error(`${name} must be a non-empty Uint8Array.`);
+    }
+}
+/** @internal */
+function assertCompressedPubkey(value, name) {
+    assertBytes(value, name);
+    if (value.length !== 33) {
+        throw new Error(`${name} must be a 33-byte compressed public key, got ${value.length} bytes.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// KeyPair sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * Schnorr keypair operations.
+ * @public
+ */
 export class KeyPairApi {
-    /** Generate a new Schnorr keypair (secp256k1). */
-    static generate() {
-        return new SchnorrKeyPair();
+    /**
+     * Generate a new Schnorr keypair.
+     * @returns The generated Schnorr keypair.
+     */
+    generate() {
+        return SchnorrKeyPair.generate();
+    }
+    /**
+     * Create a Schnorr keypair from secret key bytes or hex string.
+     * @param data The secret key bytes or hex string.
+     * @returns The created Schnorr keypair.
+     */
+    fromSecret(data) {
+        return SchnorrKeyPair.fromSecret(data);
+    }
+    /** Create a secret key from entropy (bytes or bigint). */
+    secretKeyFrom(ent) {
+        return new Secp256k1SecretKey(ent);
+    }
+    /** Create a compressed public key from bytes. */
+    publicKeyFrom(byt) {
+        return new CompressedSecp256k1PublicKey(byt);
+    }
+    /** Deserialize a keypair from a JSON object. */
+    fromJSON(obj) {
+        return SchnorrKeyPair.fromJSON(obj);
+    }
+    /** Serialize a keypair to a JSON object. */
+    toJSON(kp) {
+        return kp.exportJSON();
+    }
+    /** Compare two keypairs for equality. */
+    equals(kp1, kp2) {
+        return SchnorrKeyPair.equals(kp1, kp2);
+    }
+}
+// ---------------------------------------------------------------------------
+// Cryptosuite sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * Schnorr cryptosuite operations.
+ *
+ * Optionally stateful: call {@link use} to set a current cryptosuite, then
+ * call {@link createProof}, {@link verifyProof}, or {@link toDataIntegrityProof}
+ * without passing an explicit instance. Pass an explicit instance to any
+ * method to override the current one for that call.
+ * @public
+ */
+export class CryptosuiteApi {
+    #current;
+    /** The currently active cryptosuite, or `undefined` if none is set. */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * Set the current cryptosuite for subsequent operations.
+     * @param cs The cryptosuite to activate.
+     * @returns `this` for chaining.
+     */
+    use(cs) {
+        this.#current = cs;
+        return this;
+    }
+    /** Clear the current cryptosuite. */
+    clear() {
+        this.#current = undefined;
+    }
+    /**
+     * Create a new Schnorr cryptosuite from a multikey.
+     * @param multikey The Schnorr multikey to use.
+     * @returns The created Schnorr cryptosuite.
+     */
+    create(multikey) {
+        return new BIP340Cryptosuite(multikey);
+    }
+    /**
+     * Convenience: resolve a key from the KMS and create a cryptosuite in one step.
+     * @param id The multikey ID (e.g. '#initialKey').
+     * @param controller The DID that controls this key.
+     * @param keyId The KMS key identifier to resolve.
+     * @param kms The KeyManagerApi instance holding the key.
+     * @returns The created Schnorr cryptosuite.
+     */
+    createFromKms(id, controller, keyId, kms) {
+        const pubBytes = kms.getPublicKey(keyId);
+        const mk = SchnorrMultikey.fromPublicKey({ id, controller, publicKeyBytes: pubBytes });
+        return new BIP340Cryptosuite(mk);
+    }
+    /**
+     * Convert a cryptosuite to a Data Integrity Proof instance.
+     * Uses the current cryptosuite when `cryptosuite` is omitted.
+     * @param cryptosuite Optional explicit cryptosuite to convert.
+     * @returns The Data Integrity Proof instance.
+     */
+    toDataIntegrityProof(cryptosuite) {
+        const cs = cryptosuite ?? this.#requireCurrent();
+        return cs.toDataIntegrityProof();
+    }
+    /**
+     * Create a proof for a document.
+     * Uses the current cryptosuite when `cryptosuite` is omitted.
+     * @param document The document to create the proof for.
+     * @param config Configuration for the proof creation.
+     * @param cryptosuite Optional explicit cryptosuite; defaults to current.
+     * @returns The created proof.
+     */
+    createProof(document, config, cryptosuite) {
+        const cs = cryptosuite ?? this.#requireCurrent();
+        return cs.createProof(document, config);
+    }
+    /**
+     * Verify a proof for a document.
+     * Uses the current cryptosuite when `cryptosuite` is omitted.
+     * @param document The document to verify the proof for.
+     * @param cryptosuite Optional explicit cryptosuite; defaults to current.
+     * @returns The full verification result.
+     */
+    verifyProof(document, cryptosuite) {
+        const cs = cryptosuite ?? this.#requireCurrent();
+        return cs.verifyProof(document);
+    }
+    #requireCurrent() {
+        if (!this.#current) {
+            throw new Error('No current cryptosuite set. Call cryptosuite.use(cs) first, or pass an explicit instance.');
+        }
+        return this.#current;
+    }
+}
+// ---------------------------------------------------------------------------
+// Data Integrity Proof sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * Data Integrity Proof operations.
+ *
+ * Optionally stateful: call {@link use} to set a current proof instance, then
+ * call {@link addProof} or {@link verifyProof} without passing an explicit
+ * instance. Pass an explicit instance to override for that call.
+ * @public
+ */
+export class DataIntegrityProofApi {
+    #current;
+    /** The currently active proof instance, or `undefined` if none is set. */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * Set the current proof instance for subsequent operations.
+     * @param p The proof instance to activate.
+     * @returns `this` for chaining.
+     */
+    use(p) {
+        this.#current = p;
+        return this;
+    }
+    /** Clear the current proof instance. */
+    clear() {
+        this.#current = undefined;
+    }
+    /**
+     * Create a BIP340DataIntegrityProof instance with the given cryptosuite.
+     * @param cryptosuite The cryptosuite to use for proof operations.
+     * @returns The created BIP340DataIntegrityProof instance.
+     */
+    create(cryptosuite) {
+        return new BIP340DataIntegrityProof(cryptosuite);
+    }
+    /**
+     * Add a proof to a document.
+     * Uses the current proof instance when `proof` is omitted.
+     * @param document The document to add the proof to.
+     * @param config Configuration for adding the proof.
+     * @param proof Optional explicit proof instance; defaults to current.
+     * @returns A document with a proof added.
+     */
+    addProof(document, config, proof) {
+        const p = proof ?? this.#requireCurrent();
+        return p.addProof(document, config);
+    }
+    /**
+     * Convenience: create a cryptosuite, proof instance, and sign a document
+     * in one call. Requires a multikey with signing capability.
+     * @param multikey The Schnorr multikey (must include secret key).
+     * @param document The unsigned document to sign.
+     * @param config The Data Integrity proof configuration.
+     * @returns The signed document with proof attached.
+     */
+    signDocument(multikey, document, config) {
+        const cs = new BIP340Cryptosuite(multikey);
+        const proofInst = new BIP340DataIntegrityProof(cs);
+        return proofInst.addProof(document, config);
+    }
+    /**
+     * Verify a proof using a BIP340DataIntegrityProof instance.
+     * Uses the current proof instance when `proof` is omitted.
+     * @param document The document to verify the proof for.
+     * @param expectedPurpose The expected proof purpose.
+     * @param mediaType The media type of the document.
+     * @param expectedDomain The expected domain for the proof.
+     * @param expectedChallenge The expected challenge for the proof.
+     * @param proof Optional explicit proof instance; defaults to current.
+     * @returns The result of verifying the proof.
+     */
+    verifyProof(document, expectedPurpose, mediaType, expectedDomain, expectedChallenge, proof) {
+        const p = proof ?? this.#requireCurrent();
+        return p.verifyProof(document, expectedPurpose, mediaType, expectedDomain, expectedChallenge);
     }
-    /** Import from secret key bytes or bigint. */
-    static fromSecret(ent) {
-        const sk = new Secp256k1SecretKey(ent);
-        return new SchnorrKeyPair({ secretKey: sk });
+    #requireCurrent() {
+        if (!this.#current) {
+            throw new Error('No current proof instance set. Call proof.use(p) first, or pass an explicit instance.');
+        }
+        return this.#current;
     }
 }
+// ---------------------------------------------------------------------------
+// Multikey sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * Schnorr multikey operations.
+ *
+ * Optionally stateful: call {@link use} to set a current multikey, then
+ * call {@link sign}, {@link verify}, or {@link toVerificationMethod} without
+ * passing an explicit instance. Pass an explicit instance to any method to
+ * override the current one for that call.
+ * @public
+ */
 export class MultikeyApi {
+    #current;
+    /** The currently active multikey, or `undefined` if none is set. */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * Set the current multikey for subsequent operations.
+     * @param mk The multikey to activate.
+     * @returns `this` for chaining.
+     */
+    use(mk) {
+        this.#current = mk;
+        return this;
+    }
+    /** Clear the current multikey. */
+    clear() {
+        this.#current = undefined;
+    }
+    /**
+     * Create a new Schnorr multikey from a keypair.
+     * @param id The multikey ID.
+     * @param controller The multikey controller.
+     * @param keyPair The Schnorr keypair to use.
+     * @returns The created Schnorr multikey.
+     */
+    create(id, controller, keyPair) {
+        return new SchnorrMultikey({ id, controller, keyPair });
+    }
+    /**
+     * Create a Schnorr multikey from raw secret key bytes.
+     * @param id The multikey ID.
+     * @param controller The multikey controller.
+     * @param secretKeyBytes The secret key bytes.
+     * @returns The created Schnorr multikey.
+     */
+    fromSecretKey(id, controller, secretKeyBytes) {
+        return SchnorrMultikey.fromSecretKey(id, controller, secretKeyBytes);
+    }
     /**
-     * Create a Schnorr Multikey wrapper (includes verificationMethod, sign/verify).
-     * If secret is present, the multikey can sign.
+     * Create a verification-only multikey from public key bytes.
+     * @param params The id, controller, and publicKeyBytes.
+     * @returns The created Multikey.
      */
-    static create(params) {
-        return new SchnorrMultikey(params);
+    fromPublicKey(params) {
+        return SchnorrMultikey.fromPublicKey(params);
     }
-    /** Produce a DID Verification Method JSON from a multikey. */
-    static toVerificationMethod(mk) {
-        return mk.toVerificationMethod();
+    /**
+     * Convenience: resolve a key from the KMS and create a multikey in one step.
+     * @param id The multikey ID.
+     * @param controller The multikey controller DID.
+     * @param keyId The KMS key identifier to resolve.
+     * @param kms The KeyManagerApi instance holding the key.
+     * @returns The created Multikey (verification-only; public key from KMS).
+     */
+    fromKms(id, controller, keyId, kms) {
+        const pubBytes = kms.getPublicKey(keyId);
+        return SchnorrMultikey.fromPublicKey({ id, controller, publicKeyBytes: pubBytes });
+    }
+    /**
+     * Reconstruct a multikey from a DID document's verification method.
+     * @param verificationMethod The verification method to convert.
+     * @returns The reconstructed multikey.
+     */
+    fromVerificationMethod(verificationMethod) {
+        return SchnorrMultikey.fromVerificationMethod(verificationMethod);
+    }
+    /**
+     * Produce a DID Verification Method JSON from a multikey.
+     * Uses the current multikey when `mk` is omitted.
+     * @param mk Optional explicit multikey; defaults to current.
+     */
+    toVerificationMethod(mk) {
+        const m = mk ?? this.#requireCurrent();
+        return m.toVerificationMethod();
+    }
+    /**
+     * Sign bytes via the multikey (requires secret).
+     * Uses the current multikey when `mk` is omitted.
+     * @param data The data to sign.
+     * @param mk Optional explicit multikey; defaults to current.
+     */
+    sign(data, mk) {
+        const m = mk ?? this.#requireCurrent();
+        return m.sign(data);
     }
-    /** Sign bytes via the multikey (requires secret). */
-    static async sign(mk, data) {
-        return mk.sign(data);
+    /**
+     * Verify signature via multikey.
+     * Uses the current multikey when `mk` is omitted.
+     * @param data The data that was signed.
+     * @param signature The signature to verify.
+     * @param mk Optional explicit multikey; defaults to current.
+     */
+    verify(data, signature, mk) {
+        const m = mk ?? this.#requireCurrent();
+        return m.verify(signature, data);
     }
-    /** Verify signature via multikey. */
-    static async verify(mk, data, signature) {
-        return mk.verify(data, signature);
+    #requireCurrent() {
+        if (!this.#current) {
+            throw new Error('No current multikey set. Call multikey.use(mk) first, or pass an explicit instance.');
+        }
+        return this.#current;
     }
 }
-/* =========================
- * Sub-facade: Crypto
- * ========================= */
+// ---------------------------------------------------------------------------
+// Crypto sub-facade (aggregates keypair, multikey, cryptosuite, proof)
+// ---------------------------------------------------------------------------
+/**
+ * Aggregated cryptographic operations sub-facade.
+ *
+ * Provides direct access to the four sub-facades ({@link keypair},
+ * {@link multikey}, {@link cryptosuite}, {@link proof}) plus top-level
+ * convenience methods that orchestrate the full signing/verification
+ * pipeline using their stateful defaults.
+ *
+ * @example Stateful pipeline
+ * ```ts
+ * const api = createApi();
+ * const kp  = api.crypto.keypair.generate();
+ * const mk  = api.crypto.multikey.create('#key-1', 'did:btcr2:test', kp);
+ *
+ * // Set the active multikey — flows through to cryptosuite and proof
+ * api.crypto.activate(mk);
+ *
+ * // Now sign without threading instances
+ * const signed = api.crypto.signDocument(unsignedDoc, proofConfig);
+ * ```
+ * @public
+ */
 export class CryptoApi {
-    static keyPairApi = new KeyPairApi();
-    static multikeyApi = new MultikeyApi();
+    /** Schnorr keypair operations. */
+    keypair = new KeyPairApi();
+    /** Schnorr Multikey operations (optionally stateful). */
+    multikey = new MultikeyApi();
+    /** Schnorr Cryptosuite operations (optionally stateful). */
+    cryptosuite = new CryptosuiteApi();
+    /** Data Integrity Proof operations (optionally stateful). */
+    proof = new DataIntegrityProofApi();
+    /**
+     * Activate a multikey and propagate through the full pipeline.
+     * Sets the current multikey, creates a cryptosuite from it, and creates
+     * a proof instance from the cryptosuite — all three sub-facades become
+     * ready for stateful operations.
+     * @param mk The multikey to activate (must include a secret key for signing).
+     * @returns `this` for chaining.
+     */
+    activate(mk) {
+        this.multikey.use(mk);
+        const cs = this.cryptosuite.create(mk);
+        this.cryptosuite.use(cs);
+        const p = this.proof.create(cs);
+        this.proof.use(p);
+        return this;
+    }
+    /**
+     * Clear stateful defaults from all sub-facades.
+     */
+    deactivate() {
+        this.multikey.clear();
+        this.cryptosuite.clear();
+        this.proof.clear();
+    }
+    /**
+     * Sign data using the current multikey.
+     * Shorthand for `crypto.multikey.sign(data)`.
+     * @param data The data to sign.
+     * @returns The signature bytes.
+     */
+    sign(data) {
+        return this.multikey.sign(data);
+    }
+    /**
+     * Verify a signature using the current multikey.
+     * Shorthand for `crypto.multikey.verify(data, signature)`.
+     * @param data The data that was signed.
+     * @param signature The signature to verify.
+     * @returns `true` if the signature is valid.
+     */
+    verify(data, signature) {
+        return this.multikey.verify(data, signature);
+    }
+    /**
+     * Sign a BTCR2 update document using the current proof instance.
+     * Shorthand for `crypto.proof.addProof(document, config)`.
+     *
+     * Requires {@link activate} to have been called first, or the three
+     * sub-facades to have been configured individually.
+     * @param document The unsigned BTCR2 update document.
+     * @param config The Data Integrity proof configuration.
+     * @returns The signed document with proof attached.
+     */
+    signDocument(document, config) {
+        return this.proof.addProof(document, config);
+    }
+    /**
+     * Verify a signed BTCR2 update document using the current cryptosuite.
+     * Shorthand for `crypto.cryptosuite.verifyProof(document)`.
+     * @param document The signed document to verify.
+     * @returns The full verification result.
+     */
+    verifyDocument(document) {
+        return this.cryptosuite.verifyProof(document);
+    }
 }
-/* =========================
- * Sub-facade: Bitcoin
- * ========================= */
+// ---------------------------------------------------------------------------
+// Bitcoin sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * Bitcoin network operations sub-facade.
+ * Always backed by a {@link BitcoinConnection} so it can be passed to
+ * resolve/update without extra configuration.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} to avoid connection overhead
+ * when Bitcoin features are not used.
+ * @public
+ */
 export class BitcoinApi {
-    rest;
-    rpc;
-    defaultConfirmations;
+    /** The underlying BitcoinConnection used for all operations. */
+    connection;
+    /** REST client for the active network. */
+    get rest() {
+        return this.connection.rest;
+    }
+    /**
+     * RPC client for the active network, or `undefined` if not configured.
+     * Use {@link requireRpc} when RPC is expected to be available.
+     */
+    get rpc() {
+        return this.connection.rpc;
+    }
+    /** Whether an RPC client is available for this network. */
+    get hasRpc() {
+        return this.connection.rpc !== undefined;
+    }
+    /**
+     * RPC client for the active network.
+     * @throws {Error} If RPC was not configured for this network.
+     */
+    requireRpc() {
+        const client = this.connection.rpc;
+        if (!client) {
+            throw new Error('RPC client not configured. Pass an rpc config when creating the BitcoinApi, e.g.: '
+                + '{ network: \'regtest\', rpc: { host: \'http://localhost:18443\', username: \'u\', password: \'p\' } }');
+        }
+        return client;
+    }
+    /**
+     * Create a BitcoinApi for a specific network with optional endpoint overrides.
+     * Uses BitcoinConnection.forNetwork() — no env vars consulted.
+     * @param cfg The network and optional REST/RPC overrides.
+     */
     constructor(cfg) {
-        const restCfg = {
-            host: cfg?.rest?.host ?? DEFAULT_REST_CONFIG.host,
-            ...cfg?.rest
-        };
-        const rpcCfg = {
-            ...DEFAULT_RPC_CONFIG,
-            ...cfg?.rpc
-        };
-        this.rest = new BitcoinRestClient(restCfg);
-        this.rpc = new BitcoinCoreRpcClient(rpcCfg);
-        this.defaultConfirmations = cfg?.defaultConfirmations ?? DEFAULT_BLOCK_CONFIRMATIONS;
-    }
-    /** Fetch a transaction by txid via REST. */
+        let executor = cfg.executor;
+        // Wrap the default fetch with a timeout if configured and no custom
+        // executor was provided.
+        if (!executor && cfg.timeoutMs !== undefined) {
+            const ms = cfg.timeoutMs;
+            executor = (req) => fetch(req.url, {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+                signal: AbortSignal.timeout(ms),
+            });
+        }
+        this.connection = BitcoinConnection.forNetwork(cfg.network, {
+            rest: cfg.rest,
+            rpc: cfg.rpc,
+            executor,
+        });
+    }
+    /**
+     * Fetch a transaction by txid via REST.
+     * @param txid The transaction ID (64-character hex string).
+     * @returns The fetched transaction.
+     */
     async getTransaction(txid) {
+        assertString(txid, 'txid');
         return await this.rest.transaction.get(txid);
     }
-    /** Broadcast a raw tx (hex) via REST. */
+    /**
+     * Broadcast a raw tx (hex) via REST.
+     * @param rawTxHex The raw transaction hex string.
+     */
     async send(rawTxHex) {
+        assertString(rawTxHex, 'rawTxHex');
         return await this.rest.transaction.send(rawTxHex);
     }
-    /** Get UTXOs for an address via REST. */
+    /**
+     * Get UTXOs for an address via REST.
+     * @param address The Bitcoin address.
+     */
     async getUtxos(address) {
+        assertString(address, 'address');
         return await this.rest.address.getUtxos(address);
     }
-    /** Get a block by hash or height via REST. */
+    /**
+     * Get a block by hash or height via REST.
+     * @param params Block identifier — at least one of `hash` or `height` is required.
+     */
     async getBlock(params) {
+        if (!params.hash && params.height === undefined) {
+            throw new Error('getBlock requires at least one of hash or height.');
+        }
         return await this.rest.block.get({ blockhash: params.hash, height: params.height });
     }
+    /** Convert BTC to satoshis (integer-safe string-split arithmetic). */
+    static btcToSats(btc) {
+        return BitcoinConnection.btcToSats(btc);
+    }
+    /** Convert satoshis to BTC (integer-safe string-split arithmetic). */
+    static satsToBtc(sats) {
+        return BitcoinConnection.satsToBtc(sats);
+    }
+}
+// ---------------------------------------------------------------------------
+// KeyManager sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * Key management operations sub-facade.
+ *
+ * Wraps a {@link KeyManager} interface. By default uses the built-in
+ * {@link Kms} implementation; a custom implementation can be injected
+ * via {@link ApiConfig}.
+ * @public
+ */
+export class KeyManagerApi {
+    /** The backing KeyManager instance. */
+    kms;
+    /** Create a new KeyManagerApi, optionally backed by a custom KeyManager. */
+    constructor(kms) {
+        this.kms = kms ?? new Kms();
+    }
+    /** Generate a new key directly in the KMS. */
+    generateKey(options) {
+        return this.kms.generateKey(options);
+    }
+    /** Set the active key by its identifier. */
+    setActive(id) {
+        this.kms.setActiveKey(id);
+    }
+    /** Get the public key bytes for a key identifier. */
+    getPublicKey(id) {
+        return this.kms.getPublicKey(id);
+    }
+    /** Import a Schnorr keypair into the KMS. */
+    import(kp, options) {
+        return this.kms.importKey(kp, options);
+    }
+    /**
+     * Export a Schnorr keypair from the KMS.
+     * Only supported when the backing KMS is the built-in {@link Kms} class.
+     * @throws {Error} If the backing KMS does not support key export.
+     */
+    export(id) {
+        if (!(this.kms instanceof Kms)) {
+            throw new Error('Key export is not supported by the current KeyManager implementation. '
+                + 'Export is only available with the built-in Kms class.');
+        }
+        return this.kms.exportKey(id);
+    }
+    /** List all managed key identifiers. */
+    listKeys() {
+        return this.kms.listKeys();
+    }
+    /** Remove a key from the KMS. */
+    removeKey(id, options = {}) {
+        return this.kms.removeKey(id, options);
+    }
+    /**
+     * Sign data via the KMS.
+     * @param data The data to sign (must be non-empty).
+     * @param id Optional key identifier; uses the active key if omitted.
+     * @param options Signing options (scheme defaults to 'schnorr').
+     */
+    sign(data, id, options) {
+        assertBytes(data, 'data');
+        return this.kms.sign(data, id, options);
+    }
+    /** Verify a signature via the KMS. */
+    verify(signature, data, id, options) {
+        return this.kms.verify(signature, data, id, options);
+    }
+    /** Compute a SHA-256 digest. */
+    digest(data) {
+        return this.kms.digest(data);
+    }
 }
-/* =========================
- * Sub-facade: KeyManager
- * ========================= */
-// export class KeyManagerApi {
-//   readonly impl: IMethodKeyManager;
-//   constructor(params?: ApiKeyManagerConfig) {
-//     this.impl = new MethodKeyManager(params);
-//   }
-//   setActive(keyUri: string) {
-//     this.impl.activeKeyUri = keyUri;
-//   }
-//   export(keyUri: string) {
-//     return this.impl.export(keyUri);
-//   }
-//   import(mk: SchnorrMultikey, opts?: { importKey?: boolean; active?: boolean }) {
-//     return this.impl.import(mk, opts);
-//   }
-//   sign(keyUri: string, hash: HashBytes): Promise<SignatureBytes> {
-//     return this.impl.sign(keyUri, hash);
-//   }
-// }
-/* =========================
- * Sub-facade: DID / CRUD
- * ========================= */
+// ---------------------------------------------------------------------------
+// DID sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * DID identifier operations sub-facade (encode, decode, generate, parse).
+ * @public
+ */
 export class DidApi {
     /**
-     * Create a deterministic DID from a public key (bytes).
+     * Encode a DID from genesis bytes and options.
+     * @param genesisBytes The genesis document bytes.
+     * @param options The creation options.
+     * @returns The encoded DID string.
+     */
+    encode(genesisBytes, options) {
+        assertBytes(genesisBytes, 'genesisBytes');
+        return Identifier.encode(genesisBytes, options);
+    }
+    /**
+     * Decode a DID into its components.
+     * @param did The DID string to decode.
+     * @returns The decoded identifier components.
+     */
+    decode(did) {
+        assertString(did, 'did');
+        return Identifier.decode(did);
+    }
+    /**
+     * Generate a new DID along with its keypair.
+     *
+     * When no `network` is given, defaults to `'regtest'` (upstream default).
+     * Pass an explicit network to generate DIDs for other networks.
+     *
+     * @param network Optional network to generate the DID for.
+     * @returns The generated keypair and DID string.
+     */
+    generate(network) {
+        if (!network)
+            return Identifier.generate();
+        const kp = SchnorrKeyPair.generate();
+        const did = Identifier.encode(kp.publicKey.compressed, {
+            idType: IdentifierTypes.KEY,
+            network,
+        });
+        return { keyPair: kp.exportJSON(), did };
+    }
+    /**
+     * Check if a DID string is valid.
+     * @param did The DID string to validate.
+     * @returns `true` if valid, `false` otherwise.
      */
-    async createDeterministic({ genesisBytes, options }) {
-        return DidBtcr2.create(genesisBytes, options);
+    isValid(did) {
+        if (typeof did !== 'string' || did.length === 0)
+            return false;
+        return Identifier.isValid(did);
     }
     /**
-     * Create from an intermediate DID document (external genesis).
+     * Parse a DID string into a Did instance.
+     * @param did The DID string to parse.
+     * @returns The parsed Did instance, or `null` if parsing failed.
      */
-    async createExternal({ genesisBytes, options }) {
-        return DidBtcr2.create(genesisBytes, options);
+    parse(did) {
+        if (typeof did !== 'string' || did.length === 0)
+            return null;
+        return Did.parse(did);
+    }
+}
+// ---------------------------------------------------------------------------
+// DID Method sub-facade
+// ---------------------------------------------------------------------------
+/**
+ * DID method operations sub-facade: create, resolve, update, deactivate.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} because it depends on
+ * {@link BitcoinApi} which requires network configuration.
+ * @public
+ */
+export class DidMethodApi {
+    #btc;
+    #log;
+    constructor(btc, logger) {
+        this.#btc = btc;
+        this.#log = logger ?? NOOP_LOGGER;
     }
     /**
-     * Resolve DID document from DID (did:btcr2:...).
+     * Create a deterministic (k1) DID from a public key.
+     * Sets idType to KEY automatically.
+     * @param genesisBytes The compressed public key bytes (33 bytes).
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
+     */
+    createDeterministic(genesisBytes, options = {}) {
+        assertCompressedPubkey(genesisBytes, 'genesisBytes');
+        return DidBtcr2.create(genesisBytes, { ...options, idType: IdentifierTypes.KEY });
+    }
+    /**
+     * Create a non-deterministic (x1) DID from external genesis document bytes.
+     * Sets idType to EXTERNAL automatically.
+     * @param genesisBytes The genesis document bytes.
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
+     */
+    createExternal(genesisBytes, options = {}) {
+        assertBytes(genesisBytes, 'genesisBytes');
+        return DidBtcr2.create(genesisBytes, { ...options, idType: IdentifierTypes.EXTERNAL });
+    }
+    /**
+     * Resolve a DID. If a Bitcoin connection is configured on the API, it is
+     * injected automatically as the driver — unless the caller explicitly
+     * provides `drivers.bitcoin` (even as `undefined`) in the options.
+     * @param did The DID to resolve.
+     * @param options Resolution options.
+     * @returns The resolution result.
      */
     async resolve(did, options) {
-        return await DidBtcr2.resolve(did, options);
+        assertString(did, 'did');
+        const opts = { ...options };
+        // Only inject the configured connection when the caller did not
+        // explicitly provide the `bitcoin` driver key at all.
+        const hasExplicitDriver = options?.drivers !== undefined
+            && Object.prototype.hasOwnProperty.call(options.drivers, 'bitcoin');
+        if (!hasExplicitDriver && this.#btc) {
+            opts.drivers = { ...opts.drivers, bitcoin: this.#btc.connection };
+        }
+        this.#log.debug('Resolving DID', did);
+        try {
+            return await DidBtcr2.resolve(did, opts);
+        }
+        catch (err) {
+            this.#log.error('DID resolution failed', did, err);
+            throw new Error(`Failed to resolve DID: ${did}`, { cause: err });
+        }
     }
     /**
-     * Update a DID Document using a JSON Patch, signed as capabilityInvocation.
-     * You provide the prior DID Document (to pick VM), a JSON Patch, and a signer multikey.
-     * This delegates to MethodUpdate (which follows the cryptosuite rules internally).
+     * Update an existing DID document. If a Bitcoin connection is configured on
+     * the API, it is injected automatically.
+     * @param params The update parameters.
+     * @returns The signed update.
      */
     async update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, signingMaterial, bitcoin, }) {
-        // The Update class exposes the algorithm that creates a DID Update Payload and proof;
-        // keep this wrapper narrow so testing can mock MethodUpdate directly.
+        const btcConnection = bitcoin ?? this.#btc?.connection ?? undefined;
         return await DidBtcr2.update({
             sourceDocument,
             patches,
@@ -141,39 +804,339 @@ export class DidApi {
             verificationMethodId,
             beaconId,
             signingMaterial,
-            bitcoin,
+            bitcoin: btcConnection,
         });
     }
-    /** Deactivate convenience: applies the standard `deactivated: true` patch. */
+    /**
+     * Get the signing method from a DID document by method ID.
+     * @param didDocument The DID document.
+     * @param methodId The method ID (if omitted, the first signing method is returned).
+     * @returns The found signing method.
+     */
+    getSigningMethod(didDocument, methodId) {
+        return DidBtcr2.getSigningMethod(didDocument, methodId);
+    }
+    /**
+     * Create a fluent builder for a DID update operation.
+     * @param sourceDocument The current DID document to update.
+     * @returns An {@link UpdateBuilder} for chaining update parameters.
+     *
+     * @example
+     * ```ts
+     * const signed = await api.btcr2
+     *   .buildUpdate(currentDoc)
+     *   .patch({ op: 'add', path: '/service/1', value: newService })
+     *   .version(2)
+     *   .signer('#initialKey')
+     *   .beacon('#beacon-0')
+     *   .execute();
+     * ```
+     */
+    buildUpdate(sourceDocument) {
+        return new UpdateBuilder(this, sourceDocument);
+    }
+    /** Deactivate a DID (not yet implemented in the core method). */
     async deactivate() {
-        // This class is a stub in method right now; expose a narrow wrapper for future expansion.
-        // return DidBtcr2.deactivate({ identifier, patch }); // No-op holder; implement when core adds behavior.
-        throw new NotImplementedError('DidApi.deactivate is not implemented yet.', {
+        throw new NotImplementedError('DidMethodApi.deactivate is not implemented yet.', {
             type: 'DID_API_METHOD_NOT_IMPLEMENTED',
             name: 'NOT_IMPLEMENTED_ERROR'
         });
     }
 }
-/* =========================
- * Root facade
- * ========================= */
+// ---------------------------------------------------------------------------
+// Update builder
+// ---------------------------------------------------------------------------
+/**
+ * Fluent builder for DID update operations. Reduces the cognitive load of
+ * the 7-parameter `update()` call by letting callers chain named steps.
+ *
+ * Created via {@link DidMethodApi.buildUpdate}.
+ * @public
+ */
+export class UpdateBuilder {
+    #methodApi;
+    #sourceDocument;
+    #patches = [];
+    #sourceVersionId;
+    #verificationMethodId;
+    #beaconId;
+    #signingMaterial;
+    #bitcoin;
+    /** @internal */
+    constructor(methodApi, sourceDocument) {
+        this.#methodApi = methodApi;
+        this.#sourceDocument = sourceDocument;
+    }
+    /** Add a single JSON Patch operation. Can be called multiple times. */
+    patch(op) {
+        this.#patches.push(op);
+        return this;
+    }
+    /** Set all patches at once (replaces any previously added). */
+    patches(ops) {
+        this.#patches = [...ops];
+        return this;
+    }
+    /** Set the source version ID. */
+    version(id) {
+        this.#sourceVersionId = id;
+        return this;
+    }
+    /** Set the verification method ID used for signing. */
+    signer(methodId) {
+        this.#verificationMethodId = methodId;
+        return this;
+    }
+    /** Set the beacon ID for the update announcement. */
+    beacon(beaconId) {
+        this.#beaconId = beaconId;
+        return this;
+    }
+    /** Set the signing material (secret key bytes or hex). */
+    signingMaterial(material) {
+        this.#signingMaterial = material;
+        return this;
+    }
+    /** Override the Bitcoin connection for this update. */
+    withBitcoin(connection) {
+        this.#bitcoin = connection;
+        return this;
+    }
+    /**
+     * Execute the update.
+     * @throws {Error} If required fields (version, signer, beacon) are missing.
+     */
+    async execute() {
+        if (this.#sourceVersionId === undefined) {
+            throw new Error('UpdateBuilder: sourceVersionId is required. Call .version(id) before .execute().');
+        }
+        if (!this.#verificationMethodId) {
+            throw new Error('UpdateBuilder: verificationMethodId is required. Call .signer(id) before .execute().');
+        }
+        if (!this.#beaconId) {
+            throw new Error('UpdateBuilder: beaconId is required. Call .beacon(id) before .execute().');
+        }
+        return this.#methodApi.update({
+            sourceDocument: this.#sourceDocument,
+            patches: this.#patches,
+            sourceVersionId: this.#sourceVersionId,
+            verificationMethodId: this.#verificationMethodId,
+            beaconId: this.#beaconId,
+            signingMaterial: this.#signingMaterial,
+            bitcoin: this.#bitcoin,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Main facade
+// ---------------------------------------------------------------------------
+/**
+ * Main DidBtcr2Api facade — the primary entry point for the SDK.
+ *
+ * Exposes sub-facades for Bitcoin, DID Method, KeyPair, Crypto, and
+ * KeyManager operations. Created via the {@link createApi} factory.
+ * @public
+ */
 export class DidBtcr2Api {
-    bitcoin;
-    did;
-    keys;
+    /** Cryptographic operations (keypair, multikey, cryptosuite, proof). */
     crypto;
-    // readonly keyManager: KeyManagerApi;
+    /** DID identifier operations (encode, decode, generate, parse). */
+    did;
+    /** Key management operations. */
+    kms;
+    #btcConfig;
+    #btc;
+    #btcr2;
+    #log;
+    #disposed = false;
     constructor(config) {
-        this.bitcoin = new BitcoinApi(config?.bitcoin);
+        this.#btcConfig = config?.btc;
+        this.#log = config?.logger ?? NOOP_LOGGER;
+        this.kms = new KeyManagerApi(config?.kms);
         this.did = new DidApi();
-        this.keys = new KeyPairApi();
         this.crypto = new CryptoApi();
-        // this.keyManager = new KeyManagerApi(config?.keyManager);
+    }
+    /**
+     * Bitcoin API sub-facade (lazily initialized).
+     * Only available when `btc` config was provided to the constructor.
+     * @throws {Error} If the instance has been disposed or no Bitcoin config was provided.
+     */
+    get btc() {
+        this.#assertNotDisposed();
+        if (!this.#btc) {
+            if (!this.#btcConfig) {
+                throw new Error('Bitcoin not configured. Pass a btc config to createApi(), e.g.: '
+                    + 'createApi({ btc: { network: \'regtest\' } })');
+            }
+            this.#btc = new BitcoinApi(this.#btcConfig);
+        }
+        return this.#btc;
+    }
+    /**
+     * DID Method API sub-facade (lazily initialized with bitcoin wiring).
+     * @throws {Error} If the instance has been disposed.
+     */
+    get btcr2() {
+        this.#assertNotDisposed();
+        if (!this.#btcr2) {
+            this.#btcr2 = new DidMethodApi(this.#btcConfig ? this.btc : undefined, this.#log);
+        }
+        return this.#btcr2;
+    }
+    /**
+     * Whether this API instance has been disposed.
+     */
+    get disposed() {
+        return this.#disposed;
+    }
+    /**
+     * Create a DID using either deterministic (KEY) or external (EXTERNAL) mode.
+     * @param type The creation mode.
+     * @param genesisBytes Public key bytes (deterministic) or document bytes (external).
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
+     */
+    createDid(type, genesisBytes, options) {
+        this.#assertNotDisposed();
+        return type === 'deterministic'
+            ? this.btcr2.createDeterministic(genesisBytes, options)
+            : this.btcr2.createExternal(genesisBytes, options);
+    }
+    /**
+     * Generate a new DID, create the keypair, and import it into the KMS.
+     * @param options Optional settings.
+     * @param options.setActive Whether to set the imported key as active in the KMS (default `true`).
+     * @param options.network Network for the generated DID (default `'regtest'`).
+     * @returns The generated DID string and KMS key identifier.
+     */
+    generateDid(options) {
+        this.#assertNotDisposed();
+        const { keyPair, did } = this.did.generate(options?.network);
+        const kp = SchnorrKeyPair.fromJSON(keyPair);
+        const keyId = this.kms.import(kp, { setActive: options?.setActive ?? true });
+        return { did, keyId };
+    }
+    /**
+     * Resolve a DID, automatically injecting the configured Bitcoin connection.
+     * @param did The DID to resolve.
+     * @param options Optional resolution options.
+     * @returns The resolution result.
+     */
+    async resolveDid(did, options) {
+        this.#assertNotDisposed();
+        return await this.btcr2.resolve(did, options);
+    }
+    /**
+     * Resolve a DID and return a discriminated result instead of throwing.
+     * Useful when resolution failure is an expected outcome (e.g. checking
+     * whether a DID exists before creating it).
+     * @param did The DID to resolve.
+     * @param options Optional resolution options.
+     * @returns A {@link ResolutionResult} with `ok: true` on success or
+     *          `ok: false` with error details on failure.
+     */
+    async tryResolveDid(did, options) {
+        this.#assertNotDisposed();
+        assertString(did, 'did');
+        try {
+            const raw = await this.btcr2.resolve(did, options);
+            if (raw.didDocument) {
+                return {
+                    ok: true,
+                    document: raw.didDocument,
+                    metadata: raw.didDocumentMetadata,
+                    raw,
+                };
+            }
+            return {
+                ok: false,
+                error: raw.didResolutionMetadata?.error ?? 'unknown',
+                errorMessage: raw.didResolutionMetadata?.errorMessage,
+                raw,
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: 'internalError',
+                errorMessage: err.message,
+                raw: {
+                    didDocument: null,
+                    didDocumentMetadata: {},
+                    didResolutionMetadata: { error: 'internalError', errorMessage: err.message },
+                },
+            };
+        }
+    }
+    /**
+     * Update a DID document: resolve the current state, apply patches, sign, and announce.
+     * Automatically injects the configured Bitcoin connection.
+     *
+     * If `sourceDocument` and `sourceVersionId` are both provided, resolution
+     * is skipped. Otherwise the DID is resolved first to obtain them.
+     * @param params The update parameters.
+     * @returns The signed update.
+     */
+    async updateDid({ did, patches, verificationMethodId, beaconId, sourceDocument, sourceVersionId, }) {
+        this.#assertNotDisposed();
+        assertString(did, 'did');
+        let doc = sourceDocument;
+        let versionId = sourceVersionId;
+        if (!doc || versionId === undefined) {
+            const resolution = await this.resolveDid(did);
+            if (!resolution.didDocument) {
+                const meta = resolution.didResolutionMetadata;
+                const detail = meta?.error ? `: ${meta.error}` : '.';
+                const extra = meta?.errorMessage ? ` ${meta.errorMessage}` : '';
+                throw new Error(`Failed to resolve DID ${did} for update${detail}${extra}`, { cause: meta });
+            }
+            doc = doc ?? resolution.didDocument;
+            if (versionId === undefined) {
+                const rawVersionId = resolution.didDocumentMetadata?.versionId;
+                if (rawVersionId === undefined || rawVersionId === null) {
+                    throw new Error(`Resolution of DID ${did} succeeded but returned no versionId in metadata. `
+                        + 'Provide sourceVersionId explicitly.');
+                }
+                const parsed = Number(rawVersionId);
+                if (!Number.isFinite(parsed)) {
+                    throw new Error(`Resolution of DID ${did} returned a non-numeric versionId: ${String(rawVersionId)}.`);
+                }
+                versionId = parsed;
+            }
+        }
+        return await this.btcr2.update({
+            sourceDocument: doc,
+            patches,
+            sourceVersionId: versionId,
+            verificationMethodId,
+            beaconId,
+        });
+    }
+    /**
+     * Release internal references. After disposal, accessing `btc`, `btcr2`,
+     * or calling top-level methods will throw.
+     *
+     * Note: the underlying {@link BitcoinConnection} does not hold persistent
+     * connections, so this is primarily a guard against accidental reuse.
+     */
+    dispose() {
+        this.#btc = undefined;
+        this.#btcr2 = undefined;
+        this.#btcConfig = undefined;
+        this.#disposed = true;
+    }
+    #assertNotDisposed() {
+        if (this.#disposed) {
+            throw new Error('This DidBtcr2Api instance has been disposed and can no longer be used.');
+        }
     }
 }
-/* =========================
- * Factory
- * ========================= */
+/**
+ * Create a new {@link DidBtcr2Api} instance with the given configuration.
+ * @param config Optional configuration for the API.
+ * @returns The created DidBtcr2Api instance.
+ * @public
+ */
 export function createApi(config) {
     return new DidBtcr2Api(config);
 }