@smartledger/bsv 9.19.0 → 9.21.0

package/lib/notaryhash/index.js

@@ -126,12 +126,40 @@ NotaryHash.txidFromRawTx = function (rawTx) {
 /**
  * Find and parse the NotaryHash record in a raw transaction.
  *
+ * **Pass `vout` whenever you are verifying a certificate.** Called with one argument this
+ * scans every output and returns the first record it finds, which is useful for inspecting
+ * a transaction you know nothing about — and wrong for verification, because it makes the
+ * certificate's `anchor.vout` decorative: the field can name a payment output, or one past
+ * the end, and a record is still found somewhere else in the transaction. `anchor.vout` is
+ * covered by no signature, so the scanning form hands an editable field the appearance of
+ * having been checked.
+ *
+ * `verifyAnchorSPV` passes `anchor.vout` for exactly this reason. The one-argument form is
+ * kept for inspection and for callers that predate the parameter.
+ *
  * @param {Buffer|String} rawTx
+ * @param {Number} [vout] read only this output; omit to scan (inspection only)
  * @returns {Object|null} the parsed record, or null if there is none
  */
-NotaryHash.recordFromRawTx = function (rawTx) {
+NotaryHash.recordFromRawTx = function (rawTx, vout) {
   try {
     var tx = new Transaction(Buffer.isBuffer(rawTx) ? rawTx.toString('hex') : rawTx)
+
+    // With a vout, read THAT output and no other.
+    //
+    // Scanning every output means the certificate's `anchor.vout` is decorative: it can name
+    // any index, or one past the end, and the record is still found somewhere else in the
+    // transaction. `anchor.vout` is covered by no signature, so that made it an editable
+    // field that looked authoritative. A caller verifying an anchor must read the output the
+    // certificate points at.
+    if (vout !== undefined && vout !== null) {
+      if (!Number.isInteger(vout) || vout < 0 || vout >= tx.outputs.length) {
+        return null
+      }
+      var at = tx.outputs[vout].script
+      return NotaryScript.isNotaryHash(at) ? NotaryScript.parse(at) : null
+    }
+
     for (var i = 0; i < tx.outputs.length; i++) {
       var script = tx.outputs[i].script
       if (NotaryScript.isNotaryHash(script)) {
@@ -252,9 +280,9 @@ NotaryHash.verifyAnchorSPV = function (certificate, opts) {
       errors.push('rawTx does not hash to anchor.txid')
     }
 
-    var record = NotaryHash.recordFromRawTx(spv.rawTx)
+    var record = NotaryHash.recordFromRawTx(spv.rawTx, c.anchor && c.anchor.vout)
     if (!record) {
-      errors.push('no NotaryHash record found in rawTx')
+      errors.push('no NotaryHash record at anchor.vout in rawTx')
     } else if (!NotaryHash.recordMatchesCertificate(record, c)) {
       errors.push('on-chain record does not match the certificate')
     }
@@ -349,6 +377,68 @@ NotaryHash.verifyAnchorSPV = function (certificate, opts) {
       }
     }
 
+    // The anchor's own labels must agree with what was actually proved.
+    //
+    // `anchor.blockTime` and `anchor.blockHeight` are covered by no signature and were
+    // checked by nothing, so an edited certificate verified while reporting a different time
+    // or height than the header and proof establish. A reader shown "anchored at
+    // 2026-06-23T10:06:04Z in block 954784" has no reason to doubt either number.
+    //
+    // A null is not a claim: a certificate issued before confirmation legitimately carries
+    // nulls, and only a stated value is checked.
+    var headerBuf = Buffer.isBuffer(opts.header)
+      ? opts.header
+      : Buffer.from(String(opts.header).replace(/^0x/, ''), 'hex')
+    if (headerBuf.length === 80 && c.anchor) {
+      if (c.anchor.blockTime !== undefined && c.anchor.blockTime !== null) {
+        var headerTime = headerBuf.readUInt32LE(68)
+        if (Number(c.anchor.blockTime) !== headerTime) {
+          errors.push('anchor.blockTime ' + c.anchor.blockTime +
+            ' is not the time in the block header (' + headerTime + ')')
+        }
+      }
+      if (c.anchor.blockHeight !== undefined && c.anchor.blockHeight !== null &&
+          spv.blockHeight !== undefined && spv.blockHeight !== null &&
+          Number(c.anchor.blockHeight) !== Number(spv.blockHeight)) {
+        errors.push('anchor.blockHeight ' + c.anchor.blockHeight +
+          ' does not equal spv.blockHeight ' + spv.blockHeight)
+      }
+    }
+
+    // anchor.network, when the caller says which chain it expects.
+    //
+    // The last field in a certificate that no signature covers. BRC-220 calls it descriptive
+    // — the headers decide the chain, not the label — so accepting any value is conformant,
+    // and this stays OPT-IN for that reason: a testnet caller must not start failing because
+    // a default appeared. But a relabelled certificate still renders as a verified record on
+    // a page, and a mainnet certificate relabelled "bsv-testnet" verified here, as did one
+    // relabelled "not-a-chain".
+    //
+    // Be clear about what this is worth: it compares a label against the CALLER'S OWN
+    // setting. It does not prove which chain the header source serves. A caller who needs
+    // that must get its headers from a source it trusts for the chain it means — which is
+    // the same reason this library never fetches a header.
+    if (opts.network !== undefined && opts.network !== null &&
+        c.anchor && c.anchor.network !== undefined && c.anchor.network !== null &&
+        String(c.anchor.network) !== String(opts.network)) {
+      errors.push('anchor.network is "' + c.anchor.network + '" but the verifier expects "' +
+        opts.network + '"')
+    }
+
+    // A TSC index must be representable by the path it comes with: a path of n nodes
+    // addresses at most 2^n leaves, so a larger index describes a tree the path cannot
+    // belong to. Unchecked, the index was another unsigned field that verified while naming
+    // an impossible position.
+    var mp = spv.merkleProof
+    if (mp && Array.isArray(mp.nodes) && mp.index !== undefined && mp.index !== null) {
+      var capacity = Math.pow(2, mp.nodes.length)
+      if (!Number.isInteger(Number(mp.index)) || Number(mp.index) < 0 ||
+          Number(mp.index) >= capacity) {
+        errors.push('spv.merkleProof.index ' + mp.index + ' does not fit a path of ' +
+          mp.nodes.length + ' nodes, which addresses at most ' + capacity + ' leaves')
+      }
+    }
+
     return { valid: errors.length === 0, errors: errors }
   } catch (e) {
     return { valid: false, errors: ['anchor verification error: ' + e.message] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "9.19.0",
+  "version": "9.21.0",
   "description": "Bitcoin SV library with an interpreter-verified script engine: OP_PUSH_TX covenants, BIP-143 preimage tooling, and consensus flags that match what miners actually enforce. Also ships DID:web / W3C VC-JWT credentials and the Legal Token Protocol.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",

package/version.js

@@ -1,3 +1,3 @@
 'use strict'
 // GENERATED by scripts/sync-version.js on `npm version` — do not edit.
-module.exports = '9.19.0'
+module.exports = '9.21.0'