@did-btcr2/method 0.54.1 → 0.56.0

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

@@ -1 +1 @@
-{"version":3,"file":"appendix.d.ts","sourceRoot":"","sources":["../../../src/utils/appendix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EAAC,MAAM,YAAY,CAAC;AAM3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB;;;;OAIG;WACW,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAMpE;;;;OAIG;WACW,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB;IAcjF;;;;OAIG;WACW,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU;IAW3D;;;;;OAKG;WACW,sBAAsB,CAAC,WAAW,EAAE,WAAW,GAAG,qBAAqB,EAAE;IAgBvF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc;IAU/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;WACW,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc;CA8CtE"}
+{"version":3,"file":"appendix.d.ts","sourceRoot":"","sources":["../../../src/utils/appendix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EAAC,MAAM,YAAY,CAAC;AAO3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB;;;;OAIG;WACW,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAMpE;;;;OAIG;WACW,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB;IAcjF;;;;OAIG;WACW,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU;IAW3D;;;;;OAKG;WACW,sBAAsB,CAAC,WAAW,EAAE,WAAW,GAAG,qBAAqB,EAAE;IAgBvF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc;IAU/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;WACW,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc;CA8CtE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/method",
-  "version": "0.54.1",
+  "version": "0.56.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",
@@ -69,11 +69,11 @@
     "@scure/base": "^1.2.6",
     "@scure/btc-signer": "^1.8.1",
     "@web5/dids": "^1.2.0",
-    "@did-btcr2/bitcoin": "^0.9.0",
-    "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/keypair": "^0.13.1",
-    "@did-btcr2/cryptosuite": "^9.0.0",
-    "@did-btcr2/smt": "^0.3.0"
+    "@did-btcr2/common": "^9.3.0",
+    "@did-btcr2/bitcoin": "^0.10.0",
+    "@did-btcr2/smt": "^0.3.0",
+    "@did-btcr2/cryptosuite": "^10.0.0",
+    "@did-btcr2/keypair": "^0.13.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/src/core/beacon/signal-discovery.ts

@@ -1,6 +1,7 @@
 import type {
   BitcoinConnection,
   BlockV3,
+  RawTransactionRest,
   RawTransactionV2} from '@did-btcr2/bitcoin';
 import {
   GENESIS_TX_ID,
@@ -11,37 +12,44 @@ import type { BeaconService, BeaconSignal } from './interfaces.js';
 import { BeaconUtils } from './utils.js';
 
 /**
- * Parses a scriptPubKey asm string and returns the beacon signal hash if and only
- * if the output is exactly `OP_RETURN OP_PUSHBYTES_32 <32-byte hex>`.
+ * The serialized form of a Beacon Signal output: `OP_RETURN` (`0x6a`), the 32-byte push
+ * opcode (`0x20`), then the 32-byte hash. This is the exact inverse of `opReturnScript`,
+ * which encodes signals as `0x6a 0x20 <32 bytes>` and is pinned byte for byte by
+ * `op-return-script.spec.ts`.
+ */
+const BEACON_SIGNAL_SCRIPT = /^6a20([0-9a-f]{64})$/i;
+
+/**
+ * Parses a serialized scriptPubKey and returns the beacon signal hash if and only if the
+ * output is exactly `OP_RETURN OP_PUSHBYTES_32 <32-byte hash>`.
  *
- * Beacon signals encode a single 32-byte update or announcement hash in an
- * OP_RETURN data push. Any other shape (a bare `OP_RETURN`, a push of the wrong
- * size, or a non-hex payload) is not a valid signal and returns `null`, so a
- * malformed or adversarial on-chain output cannot be mistaken for a real signal
- * downstream.
+ * Beacon signals encode a single 32-byte update or announcement hash in an OP_RETURN data
+ * push. Any other shape (a bare `OP_RETURN`, a push of the wrong size, a second push, or a
+ * non-canonical push opcode such as `OP_PUSHDATA1`) is not a valid signal and returns
+ * `null`, so a malformed or adversarial on-chain output cannot be mistaken for a real
+ * signal downstream.
  *
- * @param {string | undefined} asm The scriptPubKey asm string to parse.
+ * The input is the script itself, not a rendered `asm` string, because `asm` is a
+ * human-readable rendering whose dialect differs per backend: Bitcoin Core prints
+ * `OP_RETURN <hash>` while Esplora prints `OP_RETURN OP_PUSHBYTES_32 <hash>`. Both return
+ * the identical serialized script (Esplora as `scriptpubkey`, Core as `scriptPubKey.hex`),
+ * so decoding the script is backend-agnostic and matches the bytes actually committed to
+ * the chain.
+ *
+ * @param {string | undefined} scriptPubKey Hex-encoded scriptPubKey of the output to parse.
  * @returns {string | null} The lowercased 32-byte hex hash, or `null` if not a valid signal.
  */
-export function extractOpReturnSignal(asm: string | undefined): string | null {
-  if(!asm) {
-    return null;
-  }
-
-  // A standard NULL_DATA beacon output is exactly three asm tokens: the OP_RETURN
-  // opcode, the 32-byte push opcode, and the 64-character hex payload.
-  const tokens = asm.trim().split(/\s+/);
-  if(tokens.length !== 3 || tokens[0] !== 'OP_RETURN' || tokens[1] !== 'OP_PUSHBYTES_32') {
+export function extractOpReturnSignalHash(scriptPubKey: string | undefined): string | null {
+  if(!scriptPubKey) {
     return null;
   }
 
-  // The payload must be exactly 32 bytes of hex (64 hex characters).
-  const signalHash = tokens[2];
-  if(!/^[0-9a-fA-F]{64}$/.test(signalHash)) {
+  const signal = BEACON_SIGNAL_SCRIPT.exec(scriptPubKey.trim());
+  if(!signal) {
     return null;
   }
 
-  return signalHash.toLowerCase();
+  return signal[1].toLowerCase();
 }
 
 /**
@@ -52,6 +60,52 @@ export function extractOpReturnSignal(asm: string | undefined): string | null {
  */
 export class BeaconSignalDiscovery {
 
+  /**
+   * Determines whether a candidate transaction spends an output controlled by the given
+   * beacon address.
+   *
+   * A Beacon Signal is a transaction that *spends from* a Beacon Address, but an address
+   * transaction listing returns every transaction touching the address in either
+   * direction. Without this check, anyone able to pay dust to a beacon address could
+   * attach an arbitrary 32-byte OP_RETURN and have it read as a signal, so the input side
+   * has to be inspected before a transaction is treated as one.
+   *
+   * Esplora embeds the spent output in `vin[].prevout`; when a backend omits it the
+   * funding transaction is fetched instead, so a missing field cannot silently drop a
+   * real signal.
+   *
+   * @param {RawTransactionRest} tx The candidate transaction.
+   * @param {string} address The beacon address the transaction must spend from.
+   * @param {BitcoinConnection} bitcoin Bitcoin network connection to use for REST calls.
+   * @returns {Promise<boolean>} True if at least one input spends an output of the beacon address.
+   */
+  private static async spendsFromAddress(
+    tx: RawTransactionRest,
+    address: string,
+    bitcoin: BitcoinConnection
+  ): Promise<boolean> {
+    for(const vin of tx.vin ?? []) {
+      // A coinbase input spends no prior output, so it can never spend from a beacon.
+      if(vin.is_coinbase) {
+        continue;
+      }
+
+      let prevout = vin.prevout;
+
+      // Fall back to the funding transaction when the backend does not embed the prevout.
+      if(!prevout && vin.txid) {
+        const fundingTx = await bitcoin.rest.transaction.get(vin.txid);
+        prevout = fundingTx?.vout?.[vin.vout];
+      }
+
+      if(prevout?.scriptpubkey_address === address) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   /**
    * Retrieves the beacon signals for the given array of BeaconService objects
    * using an esplora/electrs REST API connection via a bitcoin I/O driver.
@@ -71,10 +125,9 @@ export class BeaconSignalDiscovery {
     // Iterate over each beacon
     for (const beaconService of beaconServices) {
       beaconServiceSignals.set(beaconService, []);
+      const beaconAddress = BeaconUtils.parseBitcoinAddress(beaconService.serviceEndpoint as string);
       // Get the transactions for the beacon address via REST
-      const beaconSignals = await bitcoin.rest.address.getTxs(
-        BeaconUtils.parseBitcoinAddress(beaconService.serviceEndpoint as string)
-      );
+      const beaconSignals = await bitcoin.rest.address.getTxs(beaconAddress);
 
       // If no signals are found, continue
       if (!beaconSignals || !beaconSignals.length) {
@@ -84,10 +137,11 @@ export class BeaconSignalDiscovery {
       // Iterate over each signal
       for (const beaconSignal of beaconSignals) {
         // Get the last vout in the transaction
-        const signalVout = beaconSignal.vout.slice(-1)[0];
+        const lastSignalVout = beaconSignal.vout.slice(-1)[0];
 
         /**
-         * Look for OP_RETURN in last vout scriptpubkey_asm
+         * Decode the signal from the serialized script, not from `scriptpubkey_asm`: the
+         * asm rendering is backend-specific, the script is not.
          * Vout (rest) format:
          * {
          *  scriptpubkey: '6a20570f177c65e64fb5cf61180b664cdddf09ab76153c2b192e22006e5b22a3917a',
@@ -96,18 +150,24 @@ export class BeaconSignalDiscovery {
          *  value: 0
          * }
          */
-        if(!signalVout) {
+        if(!lastSignalVout) {
           continue;
         }
 
         // A beacon signal output must be exactly `OP_RETURN OP_PUSHBYTES_32 <32-byte hash>`.
         // Reject any other shape (bare OP_RETURN, wrong push size, non-hex payload) so a
         // malformed on-chain output cannot masquerade as a phantom signal downstream.
-        const updateHash = extractOpReturnSignal(signalVout.scriptpubkey_asm);
+        const updateHash = extractOpReturnSignalHash(lastSignalVout.scriptpubkey);
         if(!updateHash) {
           continue;
         }
 
+        // The address listing returns inbound payments too, so require the transaction to
+        // spend from the beacon before treating its OP_RETURN as a signal.
+        if(!await BeaconSignalDiscovery.spendsFromAddress(beaconSignal, beaconAddress, bitcoin)) {
+          continue;
+        }
+
         // Use the pre-fetched block count instead of calling per-signal
         const confirmations = currentBlockCount - beaconSignal.status.block_height + 1;
 
@@ -154,8 +214,16 @@ export class BeaconSignalDiscovery {
     // Get the current block height once before the loop
     const targetHeight = await rpc.getBlockCount();
 
-    // Hoist the beacon services map before the loop
-    const beaconServicesMap = BeaconUtils.getBeaconServicesMap(beaconServices);
+    /**
+     * Hoist the beacon address lookup before the loop, mapping each address to the caller's
+     * own service object. The results below are keyed by object identity, so the map has to
+     * hold those exact instances rather than copies of them. Addresses are parsed the same
+     * way as on the indexer path, so a BIP21 endpoint carrying query parameters resolves to
+     * the bare address a spent output reports.
+     */
+    const beaconServicesMap = new Map<string, BeaconService>(
+      beaconServices.map(service => [BeaconUtils.parseBitcoinAddress(service.serviceEndpoint as string), service])
+    );
 
     // Set genesis height
     let height = 0;
@@ -167,11 +235,50 @@ export class BeaconSignalDiscovery {
     while (block.height <= targetHeight) {
       // Iterate over each transaction in the block
       for (const tx of block.tx) {
-        // If the txid is a coinbase, continue ...
+        // If the txid is a genesis transaction, continue ...
         if (tx.txid === GENESIS_TX_ID) {
           continue;
         }
 
+        /**
+         * A Beacon Signal announces its update hash in the last output of the *spending*
+         * transaction, so the hash is resolved once per transaction, before the input side
+         * is inspected. The output being spent carries a plain locking script and never a
+         * signal. A beacon signal output must be exactly
+         * `OP_RETURN OP_PUSHBYTES_32 <32-byte hash>`; rejecting any other shape here also
+         * keeps the free filter ahead of the prevout lookups below.
+         *
+         * The signal is decoded from `scriptPubKey.hex`, the same serialized script the
+         * indexer path reads as `scriptpubkey`. Core's `asm` renders a data push as bare
+         * hex (`OP_RETURN <hash>`) where Esplora names the push opcode
+         * (`OP_RETURN OP_PUSHBYTES_32 <hash>`), so an asm-shaped check written against one
+         * backend silently discards every signal from the other.
+         * Vout (rpc) format:
+         * {
+         *  value: 0,
+         *  n: 1,
+         *  scriptPubKey: {
+         *    asm: "OP_RETURN 7af2be9fcb371dfcc5465a74373d499c11b1f7bba47e0507fce892ea12ec1cd6",
+         *    desc: "raw(6a207af2be9fcb371dfcc5465a74373d499c11b1f7bba47e0507fce892ea12ec1cd6)#g064zwfr",
+         *    hex: "6a207af2be9fcb371dfcc5465a74373d499c11b1f7bba47e0507fce892ea12ec1cd6",
+         *    type: "nulldata",
+         *  },
+         * }
+         */
+        const lastSignalVout = tx.vout.slice(-1)[0];
+        if (!lastSignalVout) {
+          continue;
+        }
+
+        const updateHash = extractOpReturnSignalHash(lastSignalVout.scriptPubKey?.hex);
+        if (!updateHash) {
+          continue;
+        }
+
+        // One transaction is one signal per beacon, however many of that beacon's UTXOs
+        // it spends, so track the services already credited with this transaction.
+        const signaled = new Set<BeaconService>();
+
         // Iterate over each input in the transaction
         for (const vin of tx.vin) {
 
@@ -213,21 +320,13 @@ export class BeaconSignalDiscovery {
 
           // Use the hoisted beaconServicesMap instead of rebuilding per-vin
           const beaconService = beaconServicesMap.get(scriptPubKey.address);
-          if (!beaconService) {
-            continue;
-          }
-
-          // A beacon signal output must be exactly `OP_RETURN OP_PUSHBYTES_32 <32-byte hash>`.
-          // Reject any other shape so a malformed on-chain output cannot masquerade as a
-          // phantom signal downstream.
-          const txVoutScriptPubkeyAsm = prevout.vout[vin.vout].scriptPubKey.asm;
-          const updateHash = extractOpReturnSignal(txVoutScriptPubkeyAsm);
-          if(!updateHash) {
+          if (!beaconService || signaled.has(beaconService)) {
             continue;
           }
+          signaled.add(beaconService);
 
           // Log the found txid and beacon
-          console.info(`Tx ${tx.txid} contains beacon service address ${scriptPubKey.address} and OP_RETURN!`, tx);
+          console.info(`Tx ${tx.txid} contains beacon address ${scriptPubKey.address}`);
 
           // Push the beacon signal object to the beacon signals array for that beacon service
           beaconServiceSignals.get(beaconService)?.push({

package/src/core/beacon/utils.ts

@@ -172,19 +172,6 @@ export class BeaconUtils {
     return { ...beacon, serviceEndpoint: beacon.serviceEndpoint.replace('bitcoin:', '')};
   }
 
-  /**
-   * Create a map of address => beaconService with address field.
-   * @param {Array<BeaconService>} beacons The list of beacon services.
-   * @returns {Map<string, BeaconService>} A map of address => beaconService.
-   */
-  static getBeaconServicesMap(beacons: Array<BeaconService>): Map<string, BeaconService> {
-    return new Map<string, BeaconService>(
-      beacons
-        .map(this.parseBeaconServiceEndpoint)
-        .map((beacon) => ([beacon.serviceEndpoint as string, beacon]))
-    );
-  }
-
   /**
    * Get the beacon service ids from a list of beacon services.
    * @param {DidDocument} didDocument The DID Document to extract the services from.

package/src/core/resolver.ts

@@ -149,6 +149,32 @@ function isSMTProof(value: unknown): value is SMTProof {
     && Array.isArray(value.hashes);
 }
 
+// ─── verification relationship membership ────────────────────────────────────
+
+/**
+ * Resolves a verification relationship entry to the absolute DID URL of the
+ * method it names, or `undefined` when the entry names no method.
+ *
+ * An entry is either a reference (a bare fragment such as `#key-0`, or an
+ * absolute DID URL) or an embedded verification method object. A bare fragment
+ * is relative to the document that carries it, so it is resolved against
+ * `documentId` before comparison; every other string is returned unchanged, so
+ * a reference naming a different DID can never collapse onto this document's.
+ *
+ * Malformed entries yield `undefined` rather than a placeholder string, so two
+ * unusable values never compare equal to each other.
+ *
+ * @param {string} documentId The `id` of the DID document carrying the entry.
+ * @param {unknown} entry The relationship entry: a reference or an embedded method.
+ * @returns {string | undefined} The absolute DID URL, or undefined if unusable.
+ */
+function relationshipMethodId(documentId: string, entry: unknown): string | undefined {
+  // An embedded method names itself with its `id`; a reference is the id itself.
+  const id = isRecord(entry) ? entry.id : entry;
+  if(typeof id !== 'string' || id.length === 0) return undefined;
+  return id.startsWith('#') ? `${documentId}${id}` : id;
+}
+
 /**
  * Different possible Resolver states representing phases in the resolution process.
  */
@@ -601,6 +627,29 @@ export class Resolver {
       throw new ResolveError('No verificationMethod found in update', INVALID_DID_UPDATE, update);
     }
 
+    // Spec "Check update.proof": raise INVALID_DID_UPDATE if
+    // currentDocument.capabilityInvocation does not contain
+    // update.proof.verificationMethod. Locating the method in verificationMethod[] and
+    // verifying its signature is not sufficient on its own: a key the controller
+    // published only for authentication (or for no relationship at all) must not be
+    // able to authorize a DID update. The write path enforces this in DidBtcr2.update();
+    // without it here the read path applies an update signed by any key in the document.
+    // Checked before the method is located so an unauthorized method always fails with
+    // this typed error, whether or not it also appears in verificationMethod[].
+    const authorizedMethodId = relationshipMethodId(currentDocument.id, verificationMethodId);
+    const authorized = authorizedMethodId !== undefined && currentDocument.capabilityInvocation?.some(
+      entry => relationshipMethodId(currentDocument.id, entry) === authorizedMethodId
+    );
+    if(!authorized) {
+      throw new ResolveError(
+        'Invalid update: verificationMethod is not authorized for capabilityInvocation',
+        INVALID_DID_UPDATE, {
+          verificationMethodId,
+          capabilityInvocation : currentDocument.capabilityInvocation
+        }
+      );
+    }
+
     // Get the verificationMethod from the DID Document using the verificationMethodId.
     const vm = DidBtcr2.getSigningMethod(currentDocument, verificationMethodId);
 

package/src/utils/appendix.ts

@@ -7,6 +7,7 @@ import {
   DidErrorCode,
   DidVerificationRelationship
 } from '@web5/dids';
+import { DidDocumentError } from '@did-btcr2/common';
 import type { RootCapability } from '../core/interfaces.js';
 
 /**
@@ -66,10 +67,10 @@ export class Appendix {
    * Extracts the verification methods from a given DID Document.
    * @param didDocument The DID Document to extract the verification methods from
    * @returns An array of DidVerificationMethod objects
-   * @throws TypeError if the didDocument is not provided
+   * @throws {DidDocumentError} if the didDocument is not provided
    */
   public static getVerificationMethods(didDocument: DidDocument): DidVerificationMethod[] {
-    if (!didDocument) throw new TypeError(`Required parameter missing: 'didDocument'`);
+    if (!didDocument) throw new DidDocumentError(`Required parameter missing: 'didDocument'`);
     const verificationMethods: DidVerificationMethod[] = [];
     // Check the 'verificationMethod' array.
     verificationMethods.push(...didDocument.verificationMethod?.filter(Appendix.isDidVerificationMethod) ?? []);