@did-btcr2/method 0.40.2 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.40.2",
+  "version": "0.42.0",
   "type": "module",
   "description": "Reference implementation for the did:btcr2 DID method written in TypeScript and JavaScript. did:btcr2 is a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce changes to the DID document. This is the core method implementation for the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -80,11 +80,11 @@
     "helia": "^5.5.1",
     "multiformats": "^13.4.2",
     "nostr-tools": "^2.23.3",
-    "@did-btcr2/bitcoin": "^0.8.0",
-    "@did-btcr2/cryptosuite": "^8.0.0",
-    "@did-btcr2/smt": "^0.3.0",
     "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/keypair": "^0.13.1"
+    "@did-btcr2/smt": "^0.3.0",
+    "@did-btcr2/cryptosuite": "^9.0.0",
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/bitcoin": "^0.8.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/beacon/beacon.ts

@@ -1,6 +1,6 @@
 import type { AddressUtxo, BitcoinConnection, BTCNetwork } from '@did-btcr2/bitcoin';
 import type { KeyBytes } from '@did-btcr2/common';
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import { concatBytes, hexToBytes } from '@noble/hashes/utils.js';
 import { Address, OutScript, p2pkh, p2tr, p2wpkh, Script, SigHash, Transaction } from '@scure/btc-signer';

package/src/core/beacon/cas-beacon.ts

@@ -1,6 +1,6 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { canonicalHash, canonicalize, decode, encode, hash } from '@did-btcr2/common';
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';

package/src/core/beacon/singleton-beacon.ts

@@ -1,6 +1,6 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { canonicalize, hash } from '@did-btcr2/common';
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import type { BeaconProcessResult, DataNeed } from '../resolver.js';
 import type { SidecarData } from '../types.js';

package/src/core/beacon/smt-beacon.ts

@@ -1,6 +1,6 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import { canonicalize } from '@did-btcr2/common';
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SignedBTCR2Update } from '../btcr2-update.js';
 import type { Signer } from '@did-btcr2/keypair';
 import { base64UrlToHash, blockHash, BTCR2MerkleTree, didToIndex, hashToHex, verifySerializedProof } from '@did-btcr2/smt';
 import { randomBytes } from '@noble/hashes/utils';

package/src/core/btcr2-update.ts

@@ -0,0 +1,87 @@
+import type { PatchOperation } from '@did-btcr2/common';
+import type { DataIntegrityProofObject, DataIntegrityProofOptions } from '@did-btcr2/cryptosuite';
+
+/**
+ * A {@link https://dcdpr.github.io/did-btcr2/terminology.html#btcr2-update | BTCR2 Update} without a data integrity proof.
+ * See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#btcr2-unsigned-update | BTCR2 Unsigned Update (data structure)}.
+ *
+ * This is the did:btcr2-specific document the generic `@did-btcr2/cryptosuite`
+ * suite secures; the suite itself is method-agnostic and knows nothing about it.
+ * Declared as a type alias (not an interface) so it satisfies the suite's
+ * generic `UnsecuredDocument` (a plain JSON record) constraint.
+ */
+export type UnsignedBTCR2Update = {
+  /**
+   * JSON-LD context URIs for interpreting this payload, including contexts
+   * for ZCAP (capabilities), Data Integrity proofs, and JSON-LD patch ops.
+   */
+  '@context': string[];
+
+  /**
+   * A JSON Patch (or JSON-LD Patch) object defining the mutations to apply to
+   * the DID Document. Applying this patch to the current DID Document yields
+   * the new DID Document (which must remain valid per DID Core spec).
+   */
+  patch: Array<PatchOperation>;
+
+  /**
+   * The multihash of the current (source) DID Document, encoded as a multibase
+   * base58-btc string. This is a SHA-256 hash of the canonicalized source DID
+   * Document, used to ensure the patch is applied to the correct document state.
+   */
+  sourceHash: string;
+
+  /**
+   * The multihash of the updated (target) DID Document, encoded as multibase
+   * base58-btc. This is the SHA-256 hash of the canonicalized DID Document
+   * after applying the patch, used to verify the update result.
+   */
+  targetHash: string;
+
+  /**
+   * The version number of the DID Document after this update.
+   * It is equal to the previous document version + 1.
+   */
+  targetVersionId: number;
+};
+
+/**
+ * A Data Integrity proof on a BTCR2 update: the generic proof object plus the
+ * ZCAP capability-invocation fields a did:btcr2 update proof carries.
+ */
+export type Btcr2DataIntegrityProof = DataIntegrityProofObject & {
+  /** The root capability being invoked, e.g. `urn:zcap:root:<urlencoded-did>`. */
+  capability?: string;
+
+  /** The action performed under the capability, set to `"Write"` for DID document updates. */
+  capabilityAction?: string;
+};
+
+/**
+ * A {@link https://dcdpr.github.io/did-btcr2/terminology.html#btcr2-signed-update | BTCR2 Update} with a data integrity proof.
+ * See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#btcr2-signed-update | BTCR2 Signed Update (data structure)}.
+ */
+export type SignedBTCR2Update = UnsignedBTCR2Update & {
+  /** The Data Integrity proof that converts an unsigned update into a signed update. */
+  proof: Btcr2DataIntegrityProof;
+};
+
+/** Either form of a BTCR2 Update. */
+export type BTCR2Update = UnsignedBTCR2Update | SignedBTCR2Update;
+
+/**
+ * Data Integrity proof options for a BTCR2 update: the standard
+ * {@link DataIntegrityProofOptions} plus the ZCAP capability-invocation fields a
+ * did:btcr2 update proof carries. See
+ * {@link https://dcdpr.github.io/did-btcr2/data-structures.html#data-integrity-config | Data Integrity Config}.
+ */
+export type Btcr2DataIntegrityConfig = DataIntegrityProofOptions & {
+  /** JSON-LD context URIs for the proof (ZCAP, Data Integrity, JSON-LD patch). */
+  '@context': string[];
+
+  /** The root capability being invoked, e.g. `urn:zcap:root:<urlencoded-did>`. */
+  capability?: string;
+
+  /** The action performed under the capability, set to `"Write"` for DID document updates. */
+  capabilityAction?: string;
+};

package/src/core/interfaces.ts

@@ -35,6 +35,14 @@ export interface ResolutionOptions extends DidResolutionOptions {
    * Includes Singleton beacon updates, CAS announcements, and SMT proofs.
    */
   sidecar?: Sidecar;
+
+  /**
+   * Maximum number of multi-round beacon-discovery passes before resolution
+   * fails. Each pass applies the updates found so far, then looks for new beacon
+   * services those updates added. A document whose updates keep adding beacon
+   * services would otherwise drive discovery without bound. Default: 10.
+   */
+  maxDiscoveryRounds?: number;
 }
 
 /**

package/src/core/resolver.ts

@@ -17,7 +17,7 @@ import type { HashBytes } from '@did-btcr2/common';
 import type {
   SignedBTCR2Update,
   UnsignedBTCR2Update
-} from '@did-btcr2/cryptosuite';
+} from './btcr2-update.js';
 import {
   BIP340Cryptosuite,
   BIP340DataIntegrityProof,
@@ -36,6 +36,14 @@ import type { SMTProof } from './interfaces.js';
 import type { CASAnnouncement, Sidecar, SidecarData } from './types.js';
 import { equalBytes } from '@noble/curves/utils.js';
 
+/**
+ * Default upper bound on multi-round beacon discovery. Each round applies the
+ * updates found so far and looks for beacon services those updates added; a
+ * document whose updates keep adding services would otherwise loop unbounded.
+ * Overridable via `ResolutionOptions.maxDiscoveryRounds`.
+ */
+export const DEFAULT_MAX_DISCOVERY_ROUNDS = 10;
+
 /**
  * The response object for DID Resolution.
  */
@@ -111,6 +119,38 @@ export interface BeaconProcessResult {
   needs: Array<DataNeed>;
 }
 
+// ─── provide() payload guards ────────────────────────────────────────────────
+// Runtime shape checks so a malformed payload fails fast at the provide()
+// boundary rather than flowing downstream as an unchecked `as` cast.
+
+/** True if `value` is a non-null, non-array object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** True if `value` has the shape of a CAS Announcement (a flat record of string hashes). */
+function isCASAnnouncement(value: unknown): value is CASAnnouncement {
+  return isRecord(value) && Object.values(value).every(v => typeof v === 'string');
+}
+
+/** True if `value` has the shape of a signed BTCR2 update. */
+function isSignedBTCR2Update(value: unknown): value is SignedBTCR2Update {
+  if(!isRecord(value)) return false;
+  return Array.isArray(value.patch)
+    && typeof value.sourceHash === 'string'
+    && typeof value.targetHash === 'string'
+    && typeof value.targetVersionId === 'number'
+    && isRecord(value.proof);
+}
+
+/** True if `value` has the shape of an SMT inclusion / non-inclusion proof. */
+function isSMTProof(value: unknown): value is SMTProof {
+  if(!isRecord(value)) return false;
+  return typeof value.id === 'string'
+    && typeof value.collapsed === 'string'
+    && Array.isArray(value.hashes);
+}
+
 /**
  * Different possible Resolver states representing phases in the resolution process.
  */
@@ -163,6 +203,11 @@ export class Resolver {
   #unsortedUpdates: Array<[SignedBTCR2Update, BlockMetadata]> = [];
   #resolvedResponse: DidResolutionResponse | null = null;
 
+  /** Upper bound on multi-round beacon-discovery passes; see {@link DEFAULT_MAX_DISCOVERY_ROUNDS}. */
+  readonly #maxDiscoveryRounds: number;
+  /** Count of beacon-discovery passes driven by updates adding new beacon services. */
+  #discoveryRounds = 0;
+
   /**
    * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
@@ -170,13 +215,14 @@ export class Resolver {
     didComponents: DidComponents,
     sidecarData: SidecarData,
     currentDocument: DidDocument | null,
-    options?: { versionId?: string; versionTime?: string; genesisDocument?: object }
+    options?: { versionId?: string; versionTime?: string; genesisDocument?: object; maxDiscoveryRounds?: number }
   ) {
     this.#didComponents = didComponents;
     this.#sidecarData = sidecarData;
     this.#currentDocument = currentDocument;
     this.#versionId = options?.versionId;
     this.#versionTime = options?.versionTime;
+    this.#maxDiscoveryRounds = options?.maxDiscoveryRounds ?? DEFAULT_MAX_DISCOVERY_ROUNDS;
 
     // If a genesis document was provided (from sidecar), pre-seed it for validation
     if(options?.genesisDocument) {
@@ -653,6 +699,17 @@ export class Resolver {
             });
 
             if(hasNewServices) {
+              // Bound multi-round discovery: a document whose updates keep adding
+              // beacon services would otherwise loop without end. Fail closed once
+              // the configured number of rounds is exceeded.
+              if(++this.#discoveryRounds > this.#maxDiscoveryRounds) {
+                throw new ResolveError(
+                  `Exceeded maximum beacon-discovery rounds (${this.#maxDiscoveryRounds}); `
+                  + 'the DID document may chain beacon services without terminating.',
+                  INVALID_DID_DOCUMENT,
+                  { maxDiscoveryRounds: this.#maxDiscoveryRounds }
+                );
+              }
               // Loop back to discover signals for new beacon services
               this.#phase = ResolverPhase.BeaconDiscovery;
               continue;
@@ -697,42 +754,85 @@ export class Resolver {
   provide(need: DataNeed, data: object | Map<BeaconService, Array<BeaconSignal>> | CASAnnouncement | SignedBTCR2Update | SMTProof): void {
     switch(need.kind) {
       case 'NeedGenesisDocument': {
+        if(!isRecord(data)) {
+          throw new ResolveError(
+            'Provided data for NeedGenesisDocument must be a document object.',
+            INVALID_DID_UPDATE, { kind: need.kind }
+          );
+        }
         this.#providedGenesisDocument = data;
         break;
       }
 
       case 'NeedBeaconSignals': {
-        const signals = data as Map<BeaconService, Array<BeaconSignal>>;
-        for(const [service, serviceSignals] of signals) {
+        if(!(data instanceof Map)) {
+          throw new ResolveError(
+            'Provided data for NeedBeaconSignals must be a Map of beacon services to signals.',
+            INVALID_DID_UPDATE, { kind: need.kind }
+          );
+        }
+        for(const [service, serviceSignals] of data) {
           this.#beaconServicesSignals.set(service, serviceSignals);
         }
         break;
       }
 
       case 'NeedCASAnnouncement': {
-        const announcement = data as CASAnnouncement;
-        this.#sidecarData.casMap.set(canonicalHash(announcement, { encoding: 'hex' }), announcement);
+        if(!isCASAnnouncement(data)) {
+          throw new ResolveError(
+            'Provided data for NeedCASAnnouncement is not a CAS announcement.',
+            INVALID_DID_UPDATE, { kind: need.kind }
+          );
+        }
+        // Fail fast if the provided announcement is not the one the on-chain
+        // signal requested: its canonical hash must equal the need's hash.
+        const announcementHash = canonicalHash(data, { encoding: 'hex' });
+        if(announcementHash !== need.announcementHash) {
+          throw new ResolveError(
+            `CAS announcement hash mismatch: expected ${need.announcementHash}, got ${announcementHash}.`,
+            INVALID_DID_UPDATE, { expected: need.announcementHash, actual: announcementHash }
+          );
+        }
+        this.#sidecarData.casMap.set(announcementHash, data);
         break;
       }
 
       case 'NeedSignedUpdate': {
-        const update = data as SignedBTCR2Update;
-        this.#sidecarData.updateMap.set(canonicalHash(update, { encoding: 'hex' }), update);
+        if(!isSignedBTCR2Update(data)) {
+          throw new ResolveError(
+            'Provided data for NeedSignedUpdate is not a signed BTCR2 update.',
+            INVALID_DID_UPDATE, { kind: need.kind }
+          );
+        }
+        // Fail fast if the provided update is not the one the on-chain signal
+        // requested: its canonical hash must equal the need's hash.
+        const updateHash = canonicalHash(data, { encoding: 'hex' });
+        if(updateHash !== need.updateHash) {
+          throw new ResolveError(
+            `Signed update hash mismatch: expected ${need.updateHash}, got ${updateHash}.`,
+            INVALID_DID_UPDATE, { expected: need.updateHash, actual: updateHash }
+          );
+        }
+        this.#sidecarData.updateMap.set(updateHash, data);
         break;
       }
 
       case 'NeedSMTProof': {
-        const smtNeed = need as NeedSMTProof;
-        const proof = data as SMTProof;
+        if(!isSMTProof(data)) {
+          throw new ResolveError(
+            'Provided data for NeedSMTProof is not an SMT proof.',
+            INVALID_DID_UPDATE, { kind: need.kind }
+          );
+        }
         // proof.id is base64url per spec; smtRootHash is the hex on-chain signal.
-        const proofIdHex = encodeHash(decodeHash(proof.id, 'base64urlnopad'), 'hex');
-        if(proofIdHex !== smtNeed.smtRootHash) {
+        const proofIdHex = encodeHash(decodeHash(data.id, 'base64urlnopad'), 'hex');
+        if(proofIdHex !== need.smtRootHash) {
           throw new ResolveError(
-            `SMT proof root hash mismatch: expected ${smtNeed.smtRootHash}, got ${proofIdHex}`,
-            INVALID_DID_UPDATE, { expected: smtNeed.smtRootHash, actual: proofIdHex }
+            `SMT proof root hash mismatch: expected ${need.smtRootHash}, got ${proofIdHex}`,
+            INVALID_DID_UPDATE, { expected: need.smtRootHash, actual: proofIdHex }
           );
         }
-        this.#sidecarData.smtMap.set(smtNeed.smtRootHash, proof);
+        this.#sidecarData.smtMap.set(need.smtRootHash, data);
         break;
       }
     }

package/src/core/types.ts

@@ -1,4 +1,4 @@
-import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { SignedBTCR2Update } from './btcr2-update.js';
 import type { SMTProof } from './interfaces.js';
 
 /**

package/src/core/updater.ts

@@ -1,8 +1,9 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import type { PatchOperation } from '@did-btcr2/common';
 import { canonicalHash, INVALID_DID_UPDATE, JSONPatch, UpdateError } from '@did-btcr2/common';
-import { SchnorrMultikey, type DataIntegrityConfig, type SignedBTCR2Update, type UnsignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import type { Signer } from '@did-btcr2/keypair';
+import type { Btcr2DataIntegrityConfig, SignedBTCR2Update, UnsignedBTCR2Update } from './btcr2-update.js';
 import { DidDocument, type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
 import { BeaconFactory } from './beacon/factory.js';
 import type { BeaconService } from './beacon/interfaces.js';
@@ -287,7 +288,7 @@ export class Updater {
       );
     }
 
-    const config: DataIntegrityConfig = {
+    const config: Btcr2DataIntegrityConfig = {
       '@context' : [
         'https://w3id.org/security/v2',
         'https://w3id.org/zcap/v1',

package/src/did-btcr2.ts

@@ -124,9 +124,10 @@ export class DidBtcr2 implements DidMethod {
 
     // Return the sans-I/O state machine
     return new Resolver(didComponents, sidecarData, currentDocument, {
-      versionId       : resolutionOptions.versionId,
-      versionTime     : resolutionOptions.versionTime,
-      genesisDocument : resolutionOptions.sidecar?.genesisDocument
+      versionId          : resolutionOptions.versionId,
+      versionTime        : resolutionOptions.versionTime,
+      genesisDocument    : resolutionOptions.sidecar?.genesisDocument,
+      maxDiscoveryRounds : resolutionOptions.maxDiscoveryRounds
     });
   }
 

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './core/beacon/smt-beacon.js';
 export * from './core/beacon/utils.js';
 
 // Core
+export * from './core/btcr2-update.js';
 export * from './core/did-sender-resolver.js';
 export * from './core/identifier.js';
 export * from './core/interfaces.js';