@did-btcr2/api 0.4.0 → 0.7.0

package/dist/types/types.d.ts

@@ -1,12 +1,11 @@
 import type { HttpExecutor, NetworkName, RestConfig, RpcConfig } from '@did-btcr2/bitcoin';
-import type { KeyManager } from '@did-btcr2/kms';
+import type { KeyManager } from '@did-btcr2/key-manager';
 import type { Btcr2DidDocument } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import type { CasConfig } from './cas.js';
 /**
  * Pluggable logger interface. All methods are optional-call; the default
  * implementation is a silent no-op.
- * @public
  */
 export type Logger = {
     debug(message: string, ...args: unknown[]): void;
@@ -21,7 +20,6 @@ export type Logger = {
  * than a union. This local alias provides compile-time safety at the API
  * facade level. Upstream runtime validation in `Identifier.encode()` still
  * catches invalid values.
- * @public
  */
 export type IdType = 'KEY' | 'EXTERNAL';
 /**
@@ -35,14 +33,12 @@ export type IdType = 'KEY' | 'EXTERNAL';
  * api.resolveDid(did); // OK
  * api.btc.getTransaction(did); // Type error — DidString is not TxId
  * ```
- * @public
  */
 export type DidString = string & {
     readonly __brand: 'DidString';
 };
 /**
  * A branded string representing a Bitcoin transaction ID (64-char hex).
- * @public
  */
 export type TxId = string & {
     readonly __brand: 'TxId';
@@ -61,7 +57,6 @@ export type TxId = string & {
  *   console.log(result.error, result.errorMessage);
  * }
  * ```
- * @public
  */
 export type ResolutionResult = {
     ok: true;
@@ -91,7 +86,6 @@ export type ResolutionResult = {
  * // Use regtest with custom RPC credentials, default REST
  * { network: 'regtest', rpc: { host: 'http://mynode:18443', username: 'u', password: 'p' } }
  * ```
- * @public
  */
 export type BitcoinApiConfig = {
     /** Bitcoin network name (e.g., 'regtest', 'testnet4', 'bitcoin'). */
@@ -116,7 +110,6 @@ export type BitcoinApiConfig = {
 };
 /**
  * Top-level API configuration options.
- * @public
  */
 export type ApiConfig = {
     btc?: BitcoinApiConfig;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,GACzH;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,OAAO,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,GACzH;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAElF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,OAAO,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/api",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "SDK for accessing the did:btcr2 method functionality.",
   "main": "./dist/cjs/index.js",
@@ -65,10 +65,9 @@
     "api"
   ],
   "dependencies": {
-    "@bitcoinerlab/secp256k1": "^1.2.0",
     "@helia/strings": "^4.0.2",
-    "@noble/curves": "^1.8.1",
-    "@noble/hashes": "^1.5.0",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
     "@noble/secp256k1": "^2.1.0",
     "@scure/base": "^1.1.9",
     "@scure/bip32": "^1.5.0",
@@ -77,19 +76,17 @@
     "@web5/common": "^1.1.0",
     "@web5/crypto": "^1.0.6",
     "@web5/dids": "^1.2.0",
-    "bitcoinjs-lib": "7.0.0-rc.0",
     "canonicalize": "^2.1.0",
     "dotenv": "^16.5.0",
     "helia": "^5.2.1",
     "multiformats": "^13.3.1",
     "nostr-tools": "^2.15.0",
-    "tiny-secp256k1": "^2.2.3",
-    "@did-btcr2/common": "^9.0.0",
-    "@did-btcr2/bitcoin": "^0.5.3",
-    "@did-btcr2/cryptosuite": "^6.0.6",
-    "@did-btcr2/keypair": "^0.11.4",
-    "@did-btcr2/kms": "^0.4.2",
-    "@did-btcr2/method": "^0.26.0"
+    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/keypair": "^0.13.0",
+    "@did-btcr2/method": "^0.32.0",
+    "@did-btcr2/cryptosuite": "^8.0.0",
+    "@did-btcr2/bitcoin": "^0.6.0",
+    "@did-btcr2/key-manager": "^0.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.22.0",

package/src/api.ts

@@ -1,16 +1,17 @@
 import type { NetworkName } from '@did-btcr2/bitcoin';
 import type { DocumentBytes, KeyBytes, PatchOperation } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import { SchnorrKeyPair } from '@did-btcr2/keypair';
-import type { KeyIdentifier } from '@did-btcr2/kms';
+import type { KeyIdentifier } from '@did-btcr2/key-manager';
 import type { Btcr2DidDocument, DidCreateOptions, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import { BitcoinApi } from './bitcoin.js';
-import { CasApi, type CasConfig } from './cas.js';
+import { CasApi, DEFAULT_CAS_GATEWAY, type CasConfig } from './cas.js';
 import { CryptoApi } from './crypto.js';
 import { DidApi } from './did.js';
 import { assertString, NOOP_LOGGER } from './helpers.js';
-import { KeyManagerApi } from './kms.js';
+import { KeyManagerApi } from './key-manager.js';
 import { DidMethodApi } from './method.js';
 import type { ApiConfig, BitcoinApiConfig, Logger, ResolutionResult } from './types.js';
 
@@ -67,19 +68,16 @@ export class DidBtcr2Api {
 
   /**
    * CAS API sub-facade (lazily initialized).
-   * Only available when `cas` config was provided to the constructor.
-   * @throws {Error} If the instance has been disposed or no CAS config was provided.
+   *
+   * When no `cas` config was provided to the constructor, defaults to a
+   * read-only {@link HttpGatewayCasExecutor} backed by the public IPFS
+   * gateway (`https://ipfs.io`). Override via `createApi({ cas: { ... } })`.
+   * @throws {Error} If the instance has been disposed.
    */
   get cas(): CasApi {
     this.#assertNotDisposed();
     if (!this.#cas) {
-      if (!this.#casConfig) {
-        throw new Error(
-          'CAS not configured. Pass a cas config to createApi(), e.g.: '
-          + 'createApi({ cas: { helia: await createHelia() } })'
-        );
-      }
-      this.#cas = new CasApi(this.#casConfig);
+      this.#cas = new CasApi(this.#casConfig ?? { gateway: DEFAULT_CAS_GATEWAY });
     }
     return this.#cas;
   }
@@ -93,7 +91,7 @@ export class DidBtcr2Api {
     if (!this.#btcr2) {
       this.#btcr2 = new DidMethodApi(
         this.#btcConfig ? this.btc : undefined,
-        this.#casConfig ? this.cas : undefined,
+        this.cas,
         this.#log
       );
     }
@@ -207,6 +205,7 @@ export class DidBtcr2Api {
     patches,
     verificationMethodId,
     beaconId,
+    signer,
     sourceDocument,
     sourceVersionId,
   }: {
@@ -214,6 +213,7 @@ export class DidBtcr2Api {
     patches: PatchOperation[];
     verificationMethodId: string;
     beaconId: string;
+    signer: Signer;
     sourceDocument?: Btcr2DidDocument;
     sourceVersionId?: number;
   }): Promise<SignedBTCR2Update> {
@@ -260,6 +260,7 @@ export class DidBtcr2Api {
       sourceVersionId   : versionId,
       verificationMethodId,
       beaconId,
+      signer,
     });
   }
 

package/src/cas.ts

@@ -6,6 +6,9 @@ import * as raw from 'multiformats/codecs/raw';
 import { create as createDigest } from 'multiformats/hashes/digest';
 import { sha256 } from 'multiformats/hashes/sha2';
 
+/** Default IPFS HTTP gateway used for CAS reads when no CAS config is provided. */
+export const DEFAULT_CAS_GATEWAY = 'https://ipfs.io';
+
 /**
  * Executor interface for content-addressed storage.
  *
@@ -55,15 +58,70 @@ export class IpfsCasExecutor implements CasExecutor {
   }
 }
 
+/**
+ * Read-only {@link CasExecutor} backed by an IPFS HTTP gateway.
+ *
+ * Converts the base64url SHA-256 hash to a CIDv1 (raw codec) and fetches
+ * the raw block via the
+ * {@link https://specs.ipfs.tech/http-gateways/trustless-gateway/ | Trustless Gateway}
+ * protocol.
+ *
+ * Publishing is not supported — use {@link IpfsCasExecutor} with a Helia
+ * instance for writes.
+ * @public
+ */
+export class HttpGatewayCasExecutor implements CasExecutor {
+  readonly #gatewayUrl: string;
+
+  constructor(gatewayUrl: string) {
+    this.#gatewayUrl = gatewayUrl.replace(/\/+$/, '');
+  }
+
+  async retrieve(hash: string): Promise<Uint8Array | null> {
+    const hashBytes = decodeHash(hash, 'base64urlnopad');
+    const cid = CID.create(1, raw.code, createDigest(sha256.code, hashBytes));
+    try {
+      const res = await fetch(`${this.#gatewayUrl}/ipfs/${cid.toString()}?format=raw`, {
+        headers : { Accept: 'application/vnd.ipld.raw' },
+      });
+      if (!res.ok) return null;
+      return new Uint8Array(await res.arrayBuffer());
+    } catch {
+      return null;
+    }
+  }
+
+  async publish(): Promise<string> {
+    throw new Error(
+      'HttpGatewayCasExecutor is read-only. '
+      + 'Publishing requires a full IPFS node (use IpfsCasExecutor with Helia).'
+    );
+  }
+}
+
+/** Default timeout (ms) for CAS operations. */
+export const DEFAULT_CAS_TIMEOUT_MS = 30_000;
+
 /**
  * Configuration for the CAS (Content-Addressed Storage) driver.
+ *
+ * Provide exactly one of `executor`, `helia`, or `gateway`.
+ * Priority if multiple are set: `executor` > `helia` > `gateway`.
  * @public
  */
 export type CasConfig = {
-  /** Custom executor implementation (overrides the default IPFS executor). */
+  /** Custom executor implementation (overrides all other options). */
   executor?: CasExecutor;
   /** Pre-existing Helia instance for the default IPFS executor. */
   helia?: Helia;
+  /** IPFS HTTP gateway URL for read-only CAS access (e.g. `'https://ipfs.io'`). */
+  gateway?: string;
+  /**
+   * Timeout in milliseconds for CAS operations. Prevents indefinite hangs
+   * when a Helia DHT lookup or gateway request stalls. Default: 30 000 ms.
+   * Set to `0` to disable.
+   */
+  timeoutMs?: number;
 };
 
 /**
@@ -81,18 +139,22 @@ export type CasConfig = {
  */
 export class CasApi {
   readonly #executor: CasExecutor;
+  readonly #timeoutMs: number;
 
   constructor(config: CasConfig) {
     if (config.executor) {
       this.#executor = config.executor;
     } else if (config.helia) {
       this.#executor = new IpfsCasExecutor(config.helia);
+    } else if (config.gateway) {
+      this.#executor = new HttpGatewayCasExecutor(config.gateway);
     } else {
       throw new Error(
-        'CAS configuration requires either an executor or a Helia instance. '
-        + 'Example: createApi({ cas: { helia: await createHelia() } })'
+        'CAS configuration requires an executor, Helia instance, or gateway URL. '
+        + 'Example: createApi({ cas: { gateway: \'https://ipfs.io\' } })'
       );
     }
+    this.#timeoutMs = config.timeoutMs ?? DEFAULT_CAS_TIMEOUT_MS;
   }
 
   /**
@@ -102,7 +164,7 @@ export class CasApi {
    */
   async retrieve(hashBytes: HashBytes): Promise<object | null> {
     const hash = encodeHash(hashBytes, 'base64urlnopad');
-    const bytes = await this.#executor.retrieve(hash);
+    const bytes = await this.#withTimeout(this.#executor.retrieve(hash));
     if (!bytes) return null;
     return JSON.parse(new TextDecoder().decode(bytes)) as object;
   }
@@ -116,6 +178,23 @@ export class CasApi {
    */
   async publish(object: object): Promise<string> {
     const bytes = new TextEncoder().encode(canonicalize(object as Record<string, any>));
-    return await this.#executor.publish(bytes);
+    return await this.#withTimeout(this.#executor.publish(bytes));
+  }
+
+  /**
+   * Wraps a promise with a timeout. If `#timeoutMs` is 0, no timeout is applied.
+   */
+  #withTimeout<T>(promise: Promise<T>): Promise<T> {
+    if (!this.#timeoutMs) return promise;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`CAS operation timed out after ${this.#timeoutMs}ms`)),
+        this.#timeoutMs
+      );
+      promise.then(
+        (val) => { clearTimeout(timer); resolve(val); },
+        (err) => { clearTimeout(timer); reject(err); },
+      );
+    });
   }
 }

package/src/crypto.ts

@@ -15,9 +15,9 @@ import {
   SchnorrMultikey
 } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey, SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
-import type { KeyIdentifier } from '@did-btcr2/kms';
+import type { KeyIdentifier } from '@did-btcr2/key-manager';
 import type { DidVerificationMethod } from '@web5/dids';
-import type { KeyManagerApi } from './kms.js';
+import type { KeyManagerApi } from './key-manager.js';
 
 /**
  * Schnorr keypair operations.

package/src/index.ts

@@ -30,7 +30,7 @@ export * from './types.js';
 export * from './helpers.js';
 export * from './bitcoin.js';
 export * from './cas.js';
-export * from './kms.js';
+export * from './key-manager.js';
 export * from './crypto.js';
 export * from './did.js';
 export * from './method.js';

package/src/{kms.ts → key-manager.ts}

@@ -1,22 +1,27 @@
 import type { Bytes, HashBytes, SignatureBytes } from '@did-btcr2/common';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
-import type {
-  KeyIdentifier,
-  KeyManager} from '@did-btcr2/kms';
 import {
+  type KeyIdentifier,
+  type KeyManager,
   type GenerateKeyOptions,
   type ImportKeyOptions,
-  Kms,
+  LocalKeyManager,
   type SignOptions,
-} from '@did-btcr2/kms';
+  type VerifyOptions,
+} from '@did-btcr2/key-manager';
 import { assertBytes } from './helpers.js';
 
 /**
  * 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}.
+ * Wraps any {@link KeyManager} interface implementation. By default uses the
+ * bundled {@link LocalKeyManager} (in-process reference implementation); a
+ * custom implementation (AWS KMS, GCP KMS, HashiCorp Vault, HSM, etc.) can
+ * be injected via {@link ApiConfig}.
+ *
+ * The field is named `kms` because that's the category label callers use
+ * conversationally ("plug in your KMS"); the actual contract is the
+ * {@link KeyManager} interface.
  * @public
  */
 export class KeyManagerApi {
@@ -25,7 +30,7 @@ export class KeyManagerApi {
 
   /** Create a new KeyManagerApi, optionally backed by a custom KeyManager. */
   constructor(kms?: KeyManager) {
-    this.kms = kms ?? new Kms();
+    this.kms = kms ?? new LocalKeyManager();
   }
 
   /** Generate a new key directly in the KMS. */
@@ -50,14 +55,18 @@ export class KeyManagerApi {
 
   /**
    * 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.
+   * Routes through the KeyManager's declared capability (`canExport`) rather
+   * than an `instanceof LocalKeyManager` check, so third-party adapters can
+   * opt in to export support without coupling to a specific implementation.
+   * External adapters (AWS, Vault, HSM) typically advertise `canExport: false`.
+   * @throws {Error} If the backing KeyManager does not advertise canExport=true,
+   *   or omits the optional `exportKey` method.
    */
   export(id: KeyIdentifier): SchnorrKeyPair {
-    if (!(this.kms instanceof Kms)) {
+    if (!this.kms.canExport || !this.kms.exportKey) {
       throw new Error(
         'Key export is not supported by the current KeyManager implementation. '
-        + 'Export is only available with the built-in Kms class.'
+        + 'The adapter must advertise `canExport: true` and provide an `exportKey` method.'
       );
     }
     return this.kms.exportKey(id);
@@ -77,15 +86,15 @@ export class KeyManagerApi {
    * 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').
+   * @param options Signing options. Defaults: `scheme: 'bip340'`.
    */
   sign(data: Bytes, id?: KeyIdentifier, options?: SignOptions): SignatureBytes {
     assertBytes(data, 'data');
     return this.kms.sign(data, id, options);
   }
 
-  /** Verify a signature via the KMS. */
-  verify(signature: SignatureBytes, data: Bytes, id?: KeyIdentifier, options?: SignOptions): boolean {
+  /** Verify a signature via the KMS. Defaults: `scheme: 'bip340'`. */
+  verify(signature: SignatureBytes, data: Bytes, id?: KeyIdentifier, options?: VerifyOptions): boolean {
     return this.kms.verify(signature, data, id, options);
   }
 

package/src/method.ts

@@ -1,9 +1,10 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-import type { DocumentBytes, HexString, KeyBytes, PatchOperation } from '@did-btcr2/common';
-import { decode as decodeHash, IdentifierTypes, NotImplementedError } from '@did-btcr2/common';
+import type { DocumentBytes, KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { decode as decodeHash, IdentifierTypes, INVALID_DID_UPDATE, NotImplementedError, UpdateError } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Signer } from '@did-btcr2/keypair';
 import type { Btcr2DidDocument, CASAnnouncement, DidCreateOptions, NeedCASAnnouncement, NeedGenesisDocument, NeedSignedUpdate, ResolutionOptions } from '@did-btcr2/method';
-import { BeaconSignalDiscovery, DidBtcr2 } from '@did-btcr2/method';
+import { BeaconFactory, BeaconSignalDiscovery, DidBtcr2 } from '@did-btcr2/method';
 import type { DidResolutionResult, DidVerificationMethod } from '@web5/dids';
 import type { BitcoinApi } from './bitcoin.js';
 import type { CasApi } from './cas.js';
@@ -162,8 +163,16 @@ export class DidMethodApi {
   }
 
   /**
-   * Update an existing DID document. If a Bitcoin connection is configured on
-   * the API, it is injected automatically.
+   * Update an existing DID document by driving the sans-I/O {@link Updater} state
+   * machine (from @did-btcr2/method). This method handles the I/O side:
+   * - Signing: supplies the {@link Signer} to `NeedSigningKey`.
+   * - Broadcast: establishes a beacon via {@link BeaconFactory} and calls
+   *   `broadcastSignal()` with the bitcoin connection configured on the API.
+   *
+   * For multi-party aggregation of SMT/CAS beacons, the caller should drive the
+   * Updater directly and delegate `NeedBroadcast` to the aggregation runner
+   * rather than using this high-level method.
+   *
    * @param params The update parameters.
    * @returns The signed update.
    */
@@ -173,7 +182,7 @@ export class DidMethodApi {
     sourceVersionId,
     verificationMethodId,
     beaconId,
-    signingMaterial,
+    signer,
     bitcoin,
   }: {
     sourceDocument: Btcr2DidDocument;
@@ -181,19 +190,73 @@ export class DidMethodApi {
     sourceVersionId: number;
     verificationMethodId: string;
     beaconId: string;
-    signingMaterial?: KeyBytes | HexString;
+    signer: Signer;
     bitcoin?: BitcoinConnection;
   }): Promise<SignedBTCR2Update> {
-    const btcConnection = bitcoin ?? this.#btc?.connection ?? undefined;
-    return await DidBtcr2.update({
+    // Bitcoin connection resolution order: per-call `bitcoin` param wins over the
+    // BitcoinApi injected at DidBtcr2Api construction time. One of the two must
+    // be present; this can't be encoded in the type system, so it's a runtime check.
+    const btcConnection = bitcoin ?? this.#btc?.connection;
+    if(!btcConnection) {
+      throw new UpdateError(
+        'Bitcoin connection required for update. Pass a configured `bitcoin` parameter '
+        + 'or configure a BitcoinApi on the DidBtcr2Api instance.',
+        INVALID_DID_UPDATE, { beaconId }
+      );
+    }
+
+    this.#log.debug('Updating DID', sourceDocument.id, { beaconId, verificationMethodId });
+
+    // Factory validates and returns a sans-I/O state machine
+    const updater = DidBtcr2.update({
       sourceDocument,
       patches,
       sourceVersionId,
       verificationMethodId,
       beaconId,
-      signingMaterial,
-      bitcoin : btcConnection,
     });
+
+    // Drive the state machine. All I/O (signing delegation, Bitcoin broadcast)
+    // happens inside the need-handlers below — the Updater itself is pure.
+    let state = updater.advance();
+    while(state.status === 'action-required') {
+      for(const need of state.needs) {
+        switch(need.kind) {
+          case 'NeedSigningKey': {
+            this.#log.debug('Providing signer for', need.verificationMethodId);
+            updater.provide(need, signer);
+            break;
+          }
+          case 'NeedFunding': {
+            this.#log.debug('Checking funding for beacon address %s', need.beaconAddress);
+            const utxos = await btcConnection.rest.address.getUtxos(need.beaconAddress);
+            if(!utxos.length) {
+              throw new UpdateError(
+                `Beacon address ${need.beaconAddress} is unfunded. `
+                + 'Send BTC to this address before broadcasting the update.',
+                INVALID_DID_UPDATE, { beaconAddress: need.beaconAddress }
+              );
+            }
+            this.#log.debug('Beacon address funded (%d UTXOs)', utxos.length);
+            updater.provide(need);
+            break;
+          }
+          case 'NeedBroadcast': {
+            this.#log.debug(
+              'Broadcasting signed update via %s beacon', need.beaconService.type
+            );
+            const beacon = BeaconFactory.establish(need.beaconService);
+            await beacon.broadcastSignal(need.signedUpdate, signer, btcConnection);
+            updater.provide(need);
+            break;
+          }
+        }
+      }
+      state = updater.advance();
+    }
+
+    this.#log.debug('DID update complete', sourceDocument.id);
+    return state.result.signedUpdate;
   }
 
   /**
@@ -217,8 +280,9 @@ export class DidMethodApi {
    *   .buildUpdate(currentDoc)
    *   .patch({ op: 'add', path: '/service/1', value: newService })
    *   .version(2)
-   *   .signer('#initialKey')
+   *   .verificationMethodId('#initialKey')
    *   .beacon('#beacon-0')
+   *   .signer(new LocalSigner(secretKey))
    *   .execute();
    * ```
    */
@@ -252,7 +316,7 @@ export class UpdateBuilder {
   #sourceVersionId?: number;
   #verificationMethodId?: string;
   #beaconId?: string;
-  #signingMaterial?: KeyBytes | HexString;
+  #signer?: Signer;
   #bitcoin?: BitcoinConnection;
 
   /** @internal */
@@ -279,8 +343,8 @@ export class UpdateBuilder {
     return this;
   }
 
-  /** Set the verification method ID used for signing. */
-  signer(methodId: string): this {
+  /** Set the verification method ID used for signing the update. */
+  verificationMethodId(methodId: string): this {
     this.#verificationMethodId = methodId;
     return this;
   }
@@ -291,32 +355,44 @@ export class UpdateBuilder {
     return this;
   }
 
-  /** Set the signing material (secret key bytes or hex). */
-  signingMaterial(material: KeyBytes | HexString): this {
-    this.#signingMaterial = material;
+  /**
+   * Set the {@link Signer} that produces the update's BIP-340 Schnorr proof
+   * and the beacon transaction's ECDSA input signature. Use `LocalSigner`
+   * for in-process secret keys, `KeyManagerSigner` for KMS-managed keys
+   * (AWS, Vault, HSM, etc.), or any custom adapter implementing the `Signer`
+   * interface.
+   */
+  signer(s: Signer): this {
+    this.#signer = s;
     return this;
   }
 
   /** Override the Bitcoin connection for this update. */
-  withBitcoin(connection: BitcoinConnection): this {
+  bitcoin(connection: BitcoinConnection): this {
     this.#bitcoin = connection;
     return this;
   }
 
   /**
    * Execute the update.
-   * @throws {Error} If required fields (version, signer, beacon) are missing.
+   * @throws {Error} If required fields (version, verificationMethodId, beacon, signer) are missing.
    */
   async execute(): Promise<SignedBTCR2Update> {
     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().');
+      throw new Error(
+        'UpdateBuilder: verificationMethodId is required. '
+        + 'Call .verificationMethodId(id) before .execute().'
+      );
     }
     if (!this.#beaconId) {
       throw new Error('UpdateBuilder: beaconId is required. Call .beacon(id) before .execute().');
     }
+    if (!this.#signer) {
+      throw new Error('UpdateBuilder: signer is required. Call .signer(s) before .execute().');
+    }
 
     return this.#methodApi.update({
       sourceDocument       : this.#sourceDocument,
@@ -324,7 +400,7 @@ export class UpdateBuilder {
       sourceVersionId      : this.#sourceVersionId,
       verificationMethodId : this.#verificationMethodId,
       beaconId             : this.#beaconId,
-      signingMaterial      : this.#signingMaterial,
+      signer               : this.#signer,
       bitcoin              : this.#bitcoin,
     });
   }