@did-btcr2/api 0.2.2 → 0.3.0

package/src/kms.ts

@@ -0,0 +1,95 @@
+import type { Bytes, HashBytes, SignatureBytes } from '@did-btcr2/common';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import {
+  type GenerateKeyOptions,
+  type ImportKeyOptions,
+  KeyIdentifier,
+  KeyManager,
+  Kms,
+  type SignOptions,
+} from '@did-btcr2/kms';
+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}.
+ * @public
+ */
+export class KeyManagerApi {
+  /** The backing KeyManager instance. */
+  readonly kms: KeyManager;
+
+  /** Create a new KeyManagerApi, optionally backed by a custom KeyManager. */
+  constructor(kms?: KeyManager) {
+    this.kms = kms ?? new Kms();
+  }
+
+  /** Generate a new key directly in the KMS. */
+  generateKey(options?: GenerateKeyOptions): KeyIdentifier {
+    return this.kms.generateKey(options);
+  }
+
+  /** Set the active key by its identifier. */
+  setActive(id: KeyIdentifier): void {
+    this.kms.setActiveKey(id);
+  }
+
+  /** Get the public key bytes for a key identifier. */
+  getPublicKey(id?: KeyIdentifier): Bytes {
+    return this.kms.getPublicKey(id);
+  }
+
+  /** Import a Schnorr keypair into the KMS. */
+  import(kp: SchnorrKeyPair, options?: ImportKeyOptions): KeyIdentifier {
+    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: KeyIdentifier): SchnorrKeyPair {
+    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(): KeyIdentifier[] {
+    return this.kms.listKeys();
+  }
+
+  /** Remove a key from the KMS. */
+  removeKey(id: KeyIdentifier, options: { force?: boolean } = {}): void {
+    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: 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 {
+    return this.kms.verify(signature, data, id, options);
+  }
+
+  /** Compute a SHA-256 digest. */
+  digest(data: Uint8Array): HashBytes {
+    return this.kms.digest(data);
+  }
+}

package/src/method.ts

@@ -0,0 +1,331 @@
+import { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { DocumentBytes, HexString, KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { IdentifierTypes, NotImplementedError } from '@did-btcr2/common';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Btcr2DidDocument, CASAnnouncement, DidCreateOptions, NeedCASAnnouncement, NeedGenesisDocument, NeedSignedUpdate, ResolutionOptions } from '@did-btcr2/method';
+import { BeaconSignalDiscovery, DidBtcr2 } from '@did-btcr2/method';
+import type { DidResolutionResult, DidVerificationMethod } from '@web5/dids';
+import { BitcoinApi } from './bitcoin.js';
+import { CasApi } from './cas.js';
+import { assertBytes, assertCompressedPubkey, assertString, NOOP_LOGGER } from './helpers.js';
+import type { Logger } from './types.js';
+
+/**
+ * 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?: BitcoinApi;
+  #cas?: CasApi;
+  #log: Logger;
+
+  constructor(btc?: BitcoinApi, cas?: CasApi, logger?: Logger) {
+    this.#btc = btc;
+    this.#cas = cas;
+    this.#log = logger ?? NOOP_LOGGER;
+  }
+
+  /**
+   * 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: KeyBytes, options: Omit<DidCreateOptions, 'idType'> = {}): string {
+    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: DocumentBytes, options: Omit<DidCreateOptions, 'idType'> = {}): string {
+    assertBytes(genesisBytes, 'genesisBytes');
+    return DidBtcr2.create(genesisBytes, { ...options, idType: IdentifierTypes.EXTERNAL });
+  }
+
+  /**
+   * Resolve a DID by driving the sans-I/O {@link Resolver} state machine.
+   * If a Bitcoin connection is configured on the API, it is used automatically
+   * to fetch beacon signals. Sidecar data flows through `options.sidecar`.
+   * @param did The DID to resolve.
+   * @param options Resolution options.
+   * @returns The resolution result.
+   */
+  async resolve(did: string, options?: ResolutionOptions): Promise<DidResolutionResult> {
+    assertString(did, 'did');
+    this.#log.debug('Resolving DID', did);
+    try {
+      const resolver = DidBtcr2.resolve(did, options);
+      let state = resolver.resolve();
+
+      while(state.status === 'action-required') {
+        for(const need of state.needs) {
+          switch(need.kind) {
+            case 'NeedBeaconSignals': {
+              if(!this.#btc) {
+                throw new Error(
+                  'Bitcoin connection required to fetch beacon signals. '
+                  + 'Configure a BitcoinApi on the DidBtcr2Api instance.'
+                );
+              }
+              this.#log.debug(
+                'Fetching beacon signals for %d service(s)',
+                need.beaconServices.length
+              );
+              const signals = await BeaconSignalDiscovery.indexer(
+                [...need.beaconServices], this.#btc.connection
+              );
+              resolver.provide(need, signals);
+              break;
+            }
+            case 'NeedGenesisDocument': {
+              if(!this.#cas) {
+                throw new Error(
+                  `Genesis document required but not in sidecar (hash: ${need.genesisHash}), `
+                  + 'and no CAS driver configured. Either provide the genesis document via '
+                  + 'options.sidecar.genesisDocument or configure a CAS driver.'
+                );
+              }
+              this.#log.debug('Fetching genesis document from CAS: %s', need.genesisHash);
+              const doc = await this.#cas.retrieve(need.genesisHash);
+              if(!doc) {
+                throw new Error(
+                  `Genesis document not found in CAS (hash: ${need.genesisHash}).`
+                );
+              }
+              resolver.provide(need as NeedGenesisDocument, doc);
+              break;
+            }
+            case 'NeedCASAnnouncement': {
+              if(!this.#cas) {
+                throw new Error(
+                  `CAS announcement required but not in sidecar (hash: ${need.announcementHash}), `
+                  + 'and no CAS driver configured. Either provide it via '
+                  + 'options.sidecar.casUpdates or configure a CAS driver.'
+                );
+              }
+              this.#log.debug('Fetching CAS announcement from CAS: %s', need.announcementHash);
+              const announcement = await this.#cas.retrieve(need.announcementHash);
+              if(!announcement) {
+                throw new Error(
+                  `CAS announcement not found in CAS (hash: ${need.announcementHash}).`
+                );
+              }
+              resolver.provide(need as NeedCASAnnouncement, announcement as CASAnnouncement);
+              break;
+            }
+            case 'NeedSignedUpdate': {
+              if(!this.#cas) {
+                throw new Error(
+                  `Signed update required but not in sidecar (hash: ${need.updateHash}), `
+                  + 'and no CAS driver configured. Either provide it via '
+                  + 'options.sidecar.updates or configure a CAS driver.'
+                );
+              }
+              this.#log.debug('Fetching signed update from CAS: %s', need.updateHash);
+              const update = await this.#cas.retrieve(need.updateHash);
+              if(!update) {
+                throw new Error(
+                  `Signed update not found in CAS (hash: ${need.updateHash}).`
+                );
+              }
+              resolver.provide(need as NeedSignedUpdate, update as SignedBTCR2Update);
+              break;
+            }
+          }
+        }
+        state = resolver.resolve();
+      }
+
+      this.#log.debug('DID resolved successfully', did, state.result.metadata);
+      return {
+        didResolutionMetadata : {},
+        didDocument           : state.result.didDocument as unknown as DidResolutionResult['didDocument'],
+        didDocumentMetadata   : state.result.metadata,
+      };
+    } catch (err) {
+      this.#log.error('DID resolution failed', did, err);
+      throw new Error(
+        `Failed to resolve DID: ${did}`,
+        { cause: err }
+      );
+    }
+  }
+
+  /**
+   * 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,
+  }: {
+    sourceDocument: Btcr2DidDocument;
+    patches: PatchOperation[];
+    sourceVersionId: number;
+    verificationMethodId: string;
+    beaconId: string;
+    signingMaterial?: KeyBytes | HexString;
+    bitcoin?: BitcoinConnection;
+  }): Promise<SignedBTCR2Update> {
+    const btcConnection = bitcoin ?? this.#btc?.connection ?? undefined;
+    return await DidBtcr2.update({
+      sourceDocument,
+      patches,
+      sourceVersionId,
+      verificationMethodId,
+      beaconId,
+      signingMaterial,
+      bitcoin : btcConnection,
+    });
+  }
+
+  /**
+   * 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: Btcr2DidDocument, methodId?: string): DidVerificationMethod {
+    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: Btcr2DidDocument): UpdateBuilder {
+    return new UpdateBuilder(this, sourceDocument);
+  }
+
+  /** Deactivate a DID (not yet implemented in the core method). */
+  async deactivate(): Promise<SignedBTCR2Update> {
+    throw new NotImplementedError(
+      'DidMethodApi.deactivate is not implemented yet.',
+      {
+        type : 'DID_API_METHOD_NOT_IMPLEMENTED',
+        name : 'NOT_IMPLEMENTED_ERROR'
+      }
+    );
+  }
+}
+
+/**
+ * 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: DidMethodApi;
+  #sourceDocument: Btcr2DidDocument;
+  #patches: PatchOperation[] = [];
+  #sourceVersionId?: number;
+  #verificationMethodId?: string;
+  #beaconId?: string;
+  #signingMaterial?: KeyBytes | HexString;
+  #bitcoin?: BitcoinConnection;
+
+  /** @internal */
+  constructor(methodApi: DidMethodApi, sourceDocument: Btcr2DidDocument) {
+    this.#methodApi = methodApi;
+    this.#sourceDocument = sourceDocument;
+  }
+
+  /** Add a single JSON Patch operation. Can be called multiple times. */
+  patch(op: PatchOperation): this {
+    this.#patches.push(op);
+    return this;
+  }
+
+  /** Set all patches at once (replaces any previously added). */
+  patches(ops: PatchOperation[]): this {
+    this.#patches = [...ops];
+    return this;
+  }
+
+  /** Set the source version ID. */
+  version(id: number): this {
+    this.#sourceVersionId = id;
+    return this;
+  }
+
+  /** Set the verification method ID used for signing. */
+  signer(methodId: string): this {
+    this.#verificationMethodId = methodId;
+    return this;
+  }
+
+  /** Set the beacon ID for the update announcement. */
+  beacon(beaconId: string): this {
+    this.#beaconId = beaconId;
+    return this;
+  }
+
+  /** Set the signing material (secret key bytes or hex). */
+  signingMaterial(material: KeyBytes | HexString): this {
+    this.#signingMaterial = material;
+    return this;
+  }
+
+  /** Override the Bitcoin connection for this update. */
+  withBitcoin(connection: BitcoinConnection): this {
+    this.#bitcoin = connection;
+    return this;
+  }
+
+  /**
+   * Execute the update.
+   * @throws {Error} If required fields (version, signer, beacon) 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().');
+    }
+    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,
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,122 @@
+import type { HttpExecutor, NetworkName, RestConfig, RpcConfig } from '@did-btcr2/bitcoin';
+import type { KeyManager } from '@did-btcr2/kms';
+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;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+};
+
+/**
+ * The two supported DID identifier types.
+ *
+ * Note: the upstream `DidCreateOptions.idType` is typed as `string` rather
+ * 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';
+
+/**
+ * A branded string representing a DID identifier (e.g. `did:btcr2:k1q...`).
+ * Use branded types to prevent accidentally passing a txid where a DID is
+ * expected, or vice versa, at compile time.
+ *
+ * @example
+ * ```ts
+ * const did = api.generateDid().did as DidString;
+ * 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' };
+
+/**
+ * Result of a DID resolution attempt. Wraps the standard
+ * {@link DidResolutionResult} with a discriminated `ok` flag for ergonomic
+ * pattern matching without exception handling.
+ *
+ * @example
+ * ```ts
+ * const result = await api.tryResolveDid(did);
+ * if (result.ok) {
+ *   console.log(result.document);
+ * } else {
+ *   console.log(result.error, result.errorMessage);
+ * }
+ * ```
+ * @public
+ */
+export type ResolutionResult =
+  | { ok: true;  document: Btcr2DidDocument; metadata: DidResolutionResult['didDocumentMetadata']; raw: DidResolutionResult }
+  | { ok: false; error: string; errorMessage?: string; raw: DidResolutionResult };
+
+/**
+ * Bitcoin API configuration options.
+ * The `network` field is required and determines default REST/RPC endpoints.
+ * Optional `rest` and `rpc` fields override individual endpoints on top of
+ * the network defaults.
+ *
+ * @example
+ * ```ts
+ * // Use regtest defaults (localhost Polar + Esplora)
+ * { network: 'regtest' }
+ *
+ * // Use testnet4 with a custom REST endpoint
+ * { network: 'testnet4', rest: { host: 'https://my-mempool.example/api' } }
+ *
+ * // 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'). */
+  network: NetworkName;
+  /** Override REST client settings on top of network defaults. */
+  rest?: Partial<RestConfig>;
+  /** Override RPC client settings on top of network defaults. */
+  rpc?: RpcConfig;
+  /**
+   * Optional HTTP executor for sans-I/O usage. Defaults to global `fetch`.
+   * Inject a custom executor to intercept requests in tests or route through
+   * a proxy without monkey-patching globals.
+   */
+  executor?: HttpExecutor;
+  /**
+   * Optional request timeout in milliseconds for REST calls.
+   * When set, wraps the HTTP executor with an `AbortSignal.timeout()`.
+   * Has no effect when a custom `executor` is provided (the custom
+   * executor is responsible for its own timeouts).
+   */
+  timeoutMs?: number;
+};
+
+/**
+ * Top-level API configuration options.
+ * @public
+ */
+export type ApiConfig = {
+  btc?: BitcoinApiConfig;
+  cas?: CasConfig;
+  kms?: KeyManager;
+  /** Optional logger. Defaults to a silent no-op logger. */
+  logger?: Logger;
+};