@smartledger/bsv 8.1.0 → 8.3.0

package/docs/migration/FROM_BSV_1_5_6.md

@@ -159,17 +159,17 @@ const recovered = bsv.reconstructSecret([shares[0], shares[2], shares[4]]);
 ### **New Modular Options** 
 ```html
 <!-- Core compatibility (same size as bsv@1.5.6) -->
-<script src="https://unpkg.com/@smartledger/bsv@8.1.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
 
 <!-- Add smart contracts when ready -->
-<script src="https://unpkg.com/@smartledger/bsv@8.1.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js"></script>
 
 <!-- Add advanced features as needed -->
-<script src="https://unpkg.com/@smartledger/bsv@8.1.0/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.1.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js"></script>
 
 <!-- Everything in one file -->
-<script src="https://unpkg.com/@smartledger/bsv@8.1.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js"></script>
 ```
 
 ## 🔍 **Testing Your Migration**

package/index.js

@@ -115,6 +115,11 @@ bsv.Block = require('./lib/block')
 bsv.MerkleBlock = require('./lib/block/merkleblock')
 bsv.BlockHeader = require('./lib/block/blockheader')
 bsv.SPV = require('./lib/spv')
+
+// BRC-220 NotaryHash. Exposed only now that verification exists: build/parse alone would
+// let a caller construct a record whose proofHash means nothing, with nothing to stop
+// them. See docs/BRC220_PLAN.md.
+bsv.NotaryHash = require('./lib/notaryhash')
 bsv.HDPrivateKey = require('./lib/hdprivatekey.js')
 bsv.HDPublicKey = require('./lib/hdpublickey.js')
 bsv.Networks = require('./lib/networks')

package/index.mjs

@@ -23,6 +23,7 @@ export const {
   Message,
   Mnemonic,
   Networks,
+  NotaryHash,
   Opcode,
   Ordinals,
   Output,

package/lib/gdaf/attestation-signer.js

@@ -7,6 +7,7 @@ var Hash = require('../crypto/hash')
 var ECDSA = require('../crypto/ecdsa')
 var Signature = require('../crypto/signature')
 var $ = require('../util/preconditions')
+var JCS = require('../util/jcs')
 var _ = require('../util/_')
 
 /**
@@ -94,16 +95,67 @@ AttestationSigner._canonicalizeJSON = function(obj) {
   return JSON.stringify(AttestationSigner._sortValue(obj))
 }
 
+/**
+ * RFC 8785 (JCS) canonical JSON.
+ *
+ * `_canonicalizeJSON` above sorts keys and then REBUILDS an object, which loses the
+ * sort: V8 orders integer-like own properties numerically ahead of string keys whatever
+ * order they were inserted in. So `{ '10': …, '2': … }` serialized as
+ *
+ *     ours   {"2":"two","10":"ten"}
+ *     JCS    {"10":"ten","2":"two"}      (UTF-16 code-unit order)
+ *
+ * Within this library that is merely deterministic-but-nonstandard: signing and
+ * verification agree, and no forgery follows from it. Across implementations it is a
+ * verification failure — GDAF credentials exist to be checked by other parties, and a
+ * JCS-conformant verifier in any language computes a different hash and rejects a valid
+ * signature. The previous implementation acknowledged this with "do not feed integer-like
+ * keys here", which is a constraint the data cannot be relied upon to honour.
+ *
+ * This serializes directly instead of round-tripping through an object, so the order
+ * actually survives. Array.prototype.sort already compares strings by UTF-16 code unit,
+ * which is exactly what JCS specifies; the bug was never the sort.
+ *
+ * JSON.stringify is used for the leaf types on purpose: for finite numbers it produces
+ * ECMAScript Number::toString, which is what JCS mandates, and since ES2019 it emits
+ * well-formed output for lone surrogates. Both are hard to reproduce by hand and easy to
+ * get subtly wrong.
+ *
+ * @param {*} value - Value to serialize
+ * @returns {String} RFC 8785 canonical JSON
+ */
+AttestationSigner._canonicalizeJCS = function (value) {
+  return JCS.stringify(value)
+}
+
 /**
  * Create hash of credential for signing
  * @param {Object} credential - Credential object
  * @returns {Buffer} SHA256 hash
  */
-AttestationSigner._hashCredential = function(credential) {
-  var canonical = AttestationSigner._canonicalizeJSON(credential)
+AttestationSigner._hashCredential = function (credential, canonicalization) {
+  // RFC 8785 by default. `'legacy'` selects the pre-JCS sorted-key form, which is kept
+  // ONLY so credentials signed before the change still verify — see
+  // AttestationSigner.CANONICALIZATION. New signatures must never use it.
+  var canonical = canonicalization === AttestationSigner.CANONICALIZATION.LEGACY
+    ? AttestationSigner._canonicalizeJSON(credential)
+    : AttestationSigner._canonicalizeJCS(credential)
   return Hash.sha256(Buffer.from(canonical, 'utf8'))
 }
 
+/**
+ * Canonicalization forms understood when hashing a credential.
+ *
+ * JCS is RFC 8785 and is what everything signs with now. LEGACY is the sorted-key form
+ * this library used before, retained so existing credentials keep verifying: it is
+ * deterministic but not interoperable, because rebuilding the object let V8 reorder
+ * integer-like keys ahead of the sort.
+ */
+AttestationSigner.CANONICALIZATION = {
+  JCS: 'jcs',
+  LEGACY: 'legacy'
+}
+
 /**
  * Create base credential structure
  * @param {Object} credentialSubject - Subject data

package/lib/gdaf/attestation-verifier.js

@@ -306,18 +306,23 @@ AttestationVerifier._verifySignature = async function(credential) {
     delete credentialCopy.proof
     delete credentialCopy.rootHash
     
-    // Create hash
-    var credentialHash = AttestationSigner._hashCredential(credentialCopy)
-    
-    // Verify signature
+    // Signatures are made over RFC 8785 canonical JSON. Credentials signed before that
+    // change used the older sorted-key form, so both are tried — JCS first, so a
+    // current credential never pays for the legacy attempt. This is a compatibility
+    // path, not a weakening: each form is a complete, deterministic serialization and
+    // the signature must verify against one of them exactly.
     var signature = AttestationVerifier._parseJWSSignature(proof.jws)
-    
-    var ecdsa = new ECDSA()
-    ecdsa.hashbuf = credentialHash
-    ecdsa.pubkey = publicKey
-    ecdsa.sig = signature
 
-    var valid = ecdsa.verify()
+    var valid = [
+      AttestationSigner.CANONICALIZATION.JCS,
+      AttestationSigner.CANONICALIZATION.LEGACY
+    ].some(function (form) {
+      var ecdsa = new ECDSA()
+      ecdsa.hashbuf = AttestationSigner._hashCredential(credentialCopy, form)
+      ecdsa.pubkey = publicKey
+      ecdsa.sig = signature
+      return ecdsa.verify() === true
+    })
 
     if (valid) {
       return {
@@ -369,22 +374,24 @@ AttestationVerifier._verifyPresentationSignature = async function(presentation)
     var presentationCopy = JSON.parse(JSON.stringify(presentation))
     delete presentationCopy.proof
     
-    // Create hash
-    var presentationHash = AttestationSigner._hashCredential(presentationCopy)
-    
-    // Verify signature
+    // Both canonicalizations, for the reason given on the credential path above:
+    // presentations signed before the move to RFC 8785 must keep verifying.
     var signature = AttestationVerifier._parseJWSSignature(proof.jws)
-    
-    var ecdsa = new ECDSA()
-    ecdsa.hashbuf = presentationHash
-    ecdsa.pubkey = publicKey
-    ecdsa.sig = signature
 
-    var valid = ecdsa.verify()
+    var presentationValid = [
+      AttestationSigner.CANONICALIZATION.JCS,
+      AttestationSigner.CANONICALIZATION.LEGACY
+    ].some(function (form) {
+      var e = new ECDSA()
+      e.hashbuf = AttestationSigner._hashCredential(presentationCopy, form)
+      e.pubkey = publicKey
+      e.sig = signature
+      return e.verify() === true
+    })
 
     return {
-      valid: valid,
-      errors: valid ? [] : ['Presentation signature verification failed']
+      valid: presentationValid,
+      errors: presentationValid ? [] : ['Presentation signature verification failed']
     }
     
   } catch (error) {
@@ -541,10 +548,19 @@ AttestationVerifier.verifyCredentialHash = function(credential) {
     delete credentialCopy.proof
     delete credentialCopy.rootHash
     
-    var computedHash = AttestationSigner._hashCredential(credentialCopy)
+    // A rootHash written before the move to RFC 8785 was computed over the legacy
+    // form, so both are accepted. Buffer.compare on each is still an exact match —
+    // this widens which serialization is recognised, not what counts as equal.
     var storedHash = Buffer.from(credential.rootHash, 'hex')
-    
-    return Buffer.compare(computedHash, storedHash) === 0
+
+    return [
+      AttestationSigner.CANONICALIZATION.JCS,
+      AttestationSigner.CANONICALIZATION.LEGACY
+    ].some(function (form) {
+      return Buffer.compare(
+        AttestationSigner._hashCredential(credentialCopy, form), storedHash
+      ) === 0
+    })
   } catch (error) {
     return false
   }

package/lib/gdaf/zk-prover.js

@@ -8,18 +8,26 @@ var $ = require('../util/preconditions')
 
 /**
  * ZKProver
- * 
- * Zero-Knowledge Proof system for selective disclosure of credential fields.
- * Implements Merkle tree-based proofs and commitment schemes for privacy-preserving
- * credential verification.
- * 
- * Features:
- * - Selective field disclosure
- * - Merkle inclusion proofs
- * - Commitment schemes with salt
- * - Range proofs for numerical values
- * - Proof of age without revealing birthdate
- * - Hash-based privacy preservation
+ *
+ * Selective disclosure of credential fields, built on a salted Merkle tree and hash
+ * commitments.
+ *
+ * NOT ZERO-KNOWLEDGE, despite the name this module has carried. There is no
+ * zero-knowledge machinery here — no Bulletproofs, no pairing, no circuit. What it
+ * provides is:
+ *
+ * - Selective field disclosure that genuinely withholds the undisclosed fields. Each
+ *   leaf carries its own salt and only the disclosed leaves' salts travel in the proof,
+ *   so an undisclosed leaf hash is a commitment under a secret the verifier never sees.
+ * - Merkle inclusion proofs binding disclosed fields to a credential root.
+ * - Hash commitments for ranges and ages. These can only be verified by OPENING them,
+ *   which reveals the committed value to the verifier. A real age proof would not; this
+ *   cannot do that, and callers who need it need a different primitive.
+ *
+ * The range and age verifiers previously returned a boolean the prover wrote about
+ * itself, so any object of the right shape verified. They now require the opening and
+ * check the commitment. Keep that distinction in mind before describing anything built
+ * on this module as zero-knowledge to a reviewer.
  */
 
 /**
@@ -43,29 +51,46 @@ function ZKProver(options) {
  * @returns {Object} Merkle tree data
  */
 ZKProver.createMerkleTree = function(credential, salt) {
-  salt = salt || Random.getRandomBuffer(32).toString('hex')
-  
   $.checkArgument(credential && typeof credential === 'object', 'Invalid credential')
-  
+
   // Extract all fields from credential
   var fields = ZKProver._extractFields(credential)
-  
-  // Create leaf hashes
-  var leaves = fields.map(function(field) {
-    var fieldData = field.path + ':' + JSON.stringify(field.value) + ':' + salt
+
+  // PER-LEAF salts. A single salt shared by every leaf defeats selective disclosure
+  // entirely: the proof has to carry the salt so the verifier can recompute the
+  // disclosed leaves, and with that one value an attacker can hash candidate
+  // (path, value) pairs against the sibling hashes on the Merkle path and read back
+  // exactly the fields the holder withheld. Confirmed against a synthetic credential —
+  // disclosing only `credentialSubject.name` leaked `id`, `partyAffiliation` and
+  // `eligible`, the last two by brute-forcing their shared parent node.
+  //
+  // With a salt per leaf, only the disclosed leaves' salts travel in the proof, so an
+  // undisclosed leaf hash is a commitment under a secret the verifier never sees.
+  //
+  // `salt` is accepted only to derive DETERMINISTIC per-leaf salts, so a caller that
+  // needs reproducible trees still gets them without sharing one value across leaves.
+  var master = salt || Random.getRandomBuffer(32).toString('hex')
+
+  var leaves = fields.map(function(field, index) {
+    var leafSalt = Hash.sha256(
+      Buffer.from(master + ':' + index + ':' + field.path, 'utf8')
+    ).toString('hex')
+    var fieldData = field.path + ':' + JSON.stringify(field.value) + ':' + leafSalt
     return {
       path: field.path,
       value: field.value,
       hash: Hash.sha256(Buffer.from(fieldData, 'utf8')).toString('hex'),
-      salt: salt
+      salt: leafSalt
     }
   })
-  
+
   // Build Merkle tree
   var tree = ZKProver._buildMerkleTree(leaves.map(l => l.hash))
-  
+
   return {
-    salt: salt,
+    // The MASTER salt. Never put this in a proof — it re-derives every leaf salt and
+    // reopens the whole credential. generateSelectiveProof() ships per-leaf salts.
+    salt: master,
     leaves: leaves,
     tree: tree,
     root: tree[tree.length - 1][0]
@@ -122,11 +147,16 @@ ZKProver.generateSelectiveProof = function(credential, disclosePaths, salt) {
       return {
         path: leaf.path,
         value: leaf.value,
-        hash: leaf.hash
+        hash: leaf.hash,
+        // The salt for THIS leaf only. Shipping one salt for the whole credential let
+        // a verifier — or anyone the proof is shown to — brute-force the withheld
+        // fields off the Merkle path.
+        salt: leaf.salt
       }
     }),
-    merkleProofs: merkleProofs,
-    salt: salt
+    merkleProofs: merkleProofs
+    // NOTE: the master salt is deliberately absent. It re-derives every leaf salt,
+    // including the undisclosed ones, which would reopen the whole credential.
   }
 }
 
@@ -157,8 +187,13 @@ ZKProver.verifySelectiveProof = function(proof, expectedRoot) {
         continue
       }
       
-      // Verify field hash
-      var fieldData = field.path + ':' + JSON.stringify(field.value) + ':' + proof.salt
+      // Verify field hash, using the salt carried with THIS field. Reading a
+      // credential-wide `proof.salt` is what the leak fix removed.
+      if (typeof field.salt !== 'string' || !field.salt) {
+        result.errors.push('Missing per-field salt for: ' + field.path)
+        continue
+      }
+      var fieldData = field.path + ':' + JSON.stringify(field.value) + ':' + field.salt
       var computedHash = Hash.sha256(Buffer.from(fieldData, 'utf8')).toString('hex')
       
       if (computedHash !== field.hash) {
@@ -235,7 +270,10 @@ ZKProver.generateAgeProof = function(birthDate, minimumAge, salt) {
     meetsRequirement: true,
     birthDateCommitment: commitment,
     ageProofHash: ageProofHash,
-    challengeResponse: ZKProver._generateAgeChallenge(birthDate, minimumAge, salt)
+    challengeResponse: ZKProver._generateAgeChallenge(birthDate, minimumAge, salt),
+    // As with the range proof: the commitment can only be checked by opening it, and
+    // opening it reveals the birth date. Returned alongside the proof, never inside it.
+    opening: { birthDate: birthDateString, salt: salt }
   }
 }
 
@@ -245,7 +283,7 @@ ZKProver.generateAgeProof = function(birthDate, minimumAge, salt) {
  * @param {Number} requiredAge - Required minimum age
  * @returns {Boolean} True if proof is valid
  */
-ZKProver.verifyAgeProof = function(proof, requiredAge) {
+ZKProver.verifyAgeProof = function(proof, requiredAge, opening) {
   try {
     $.checkArgument(proof && typeof proof === 'object', 'Invalid proof')
     $.checkArgument(typeof requiredAge === 'number', 'Required age must be number')
@@ -258,15 +296,40 @@ ZKProver.verifyAgeProof = function(proof, requiredAge) {
     if (proof.minimumAge !== requiredAge) {
       return false
     }
-    
-    if (!proof.meetsRequirement) {
+
+    // Same defect as verifyRangeProof, and the same fix. This used to accept
+    // `proof.meetsRequirement` — the prover's own claim — and then check only that
+    // `challengeResponse` was a non-empty string, which any forged proof satisfies.
+    // `birthDateCommitment` was never opened.
+    //
+    // The commitment is over the birth date, so verifying it requires the birth date.
+    // That reveals it, which is precisely what an age proof is supposed to avoid — the
+    // honest reading is that this construction cannot do what its name promises, and a
+    // caller who needs real age proofs needs a different primitive.
+    if (!opening || typeof opening !== 'object') {
       return false
     }
-    
-    // Verify challenge response (simplified)
-    // In production, this would use more sophisticated ZK techniques
-    return proof.challengeResponse && proof.challengeResponse.length > 0
-    
+    var birthDate = opening.birthDate
+    if (typeof birthDate === 'string') birthDate = new Date(birthDate)
+    if (!(birthDate instanceof Date) || isNaN(birthDate.getTime())) {
+      return false
+    }
+    if (typeof opening.salt !== 'string') {
+      return false
+    }
+
+    var birthDateString = birthDate.toISOString().split('T')[0]
+    var commitment = Hash.sha256(
+      Buffer.from(birthDateString + ':' + opening.salt, 'utf8')
+    ).toString('hex')
+    if (commitment !== proof.birthDateCommitment) {
+      return false
+    }
+
+    // Recompute the age rather than trusting `meetsRequirement`.
+    var ageInYears = Math.floor((Date.now() - birthDate.getTime()) / (365.25 * 24 * 60 * 60 * 1000))
+    return ageInYears >= requiredAge
+
   } catch (error) {
     return false
   }
@@ -291,7 +354,8 @@ ZKProver.generateRangeProof = function(value, min, max, salt) {
   // Create commitment to value
   var commitment = Hash.sha256(Buffer.from(value.toString() + ':' + salt, 'utf8')).toString('hex')
   
-  // Generate proof components (simplified Bulletproof-style)
+  // Generate proof components. NOT a Bulletproof — this is a hash commitment plus a
+  // hash over the parameters. It says nothing without the opening returned below.
   var proofData = {
     min: min,
     max: max,
@@ -309,7 +373,13 @@ ZKProver.generateRangeProof = function(value, min, max, salt) {
     range: { min: min, max: max },
     valueCommitment: commitment,
     proofHash: proofHash,
-    inRange: true
+    inRange: true,
+    // The OPENING. verifyRangeProof() cannot check the commitment without it, so the
+    // holder must pass it to the verifier out of band. It is returned here rather than
+    // embedded in the proof precisely because handing it over reveals the value — that
+    // disclosure is the cost of a commitment scheme, and hiding it inside the proof
+    // would make every proof self-opening.
+    opening: { value: value, salt: salt }
   }
 }
 
@@ -320,20 +390,47 @@ ZKProver.generateRangeProof = function(value, min, max, salt) {
  * @param {Number} max - Expected maximum
  * @returns {Boolean} True if proof is valid
  */
-ZKProver.verifyRangeProof = function(proof, min, max) {
+ZKProver.verifyRangeProof = function(proof, min, max, opening) {
   try {
     $.checkArgument(proof && typeof proof === 'object', 'Invalid proof')
-    
+
     if (proof.type !== 'RangeProof') {
       return false
     }
-    
-    if (proof.range.min !== min || proof.range.max !== max) {
+
+    if (!proof.range || proof.range.min !== min || proof.range.max !== max) {
       return false
     }
-    
-    return proof.inRange === true
-    
+
+    // WITHOUT AN OPENING, NOTHING HAS BEEN PROVEN. This used to end at
+    // `return proof.inRange === true` — a boolean the prover writes about itself, never
+    // checked against `valueCommitment`. Any object of the right shape verified:
+    //
+    //   { type: 'RangeProof', range: { min: 18, max: 120 },
+    //     valueCommitment: '00…', proofHash: 'de…', inRange: true }   -> true
+    //
+    // These are hash commitments, not zero-knowledge proofs: the commitment can only be
+    // checked by opening it, so the holder must supply { value, salt } out of band. That
+    // reveals the value to the verifier, which is the honest cost of this construction
+    // and the reason it must not be described as zero-knowledge.
+    if (!opening || typeof opening !== 'object') {
+      return false
+    }
+    if (typeof opening.value !== 'number' || typeof opening.salt !== 'string') {
+      return false
+    }
+
+    // The commitment must actually open to the claimed value...
+    var commitment = Hash.sha256(
+      Buffer.from(opening.value.toString() + ':' + opening.salt, 'utf8')
+    ).toString('hex')
+    if (commitment !== proof.valueCommitment) {
+      return false
+    }
+
+    // ...and that value must genuinely lie in the range, rather than the prover saying so.
+    return opening.value >= min && opening.value <= max
+
   } catch (error) {
     return false
   }