@smartledger/bsv 8.1.0 → 8.3.0

package/test/gdaf/zk_prover.js

@@ -0,0 +1,204 @@
+'use strict'
+
+/* global describe, it */
+
+// This module had ZERO test coverage, and carried three defects that coverage would have
+// caught immediately. Each is pinned below as the attack that worked, not as a paraphrase
+// of the fix, so a regression reproduces the exploit rather than merely failing a check.
+//
+// It is also not zero-knowledge, and the tests say so where it matters: the range and age
+// commitments can only be verified by opening them, which reveals the committed value.
+
+require('chai').should()
+var bsv = require('../..')
+var ZK = require('../../lib/gdaf/zk-prover')
+var Hash = require('../../lib/crypto/hash')
+
+var CRED = {
+  id: 'urn:x',
+  credentialSubject: { name: 'Alice', partyAffiliation: 'DEM', eligible: true }
+}
+
+describe('ZKProver', function () {
+  describe('range proofs', function () {
+    // The original read `return proof.inRange === true` — a boolean the prover writes
+    // about itself. valueCommitment was never consulted, so this forgery verified.
+    it('rejects a forged proof that merely claims inRange', function () {
+      var forged = {
+        type: 'RangeProof',
+        range: { min: 18, max: 120 },
+        valueCommitment: '00'.repeat(32),
+        proofHash: 'de'.repeat(32),
+        inRange: true
+      }
+      ZK.verifyRangeProof(forged, 18, 120).should.equal(false)
+    })
+
+    it('rejects an honest proof presented without its opening', function () {
+      var proof = ZK.generateRangeProof(41, 18, 120)
+      ZK.verifyRangeProof(proof, 18, 120).should.equal(false)
+    })
+
+    it('accepts an honest proof with its opening', function () {
+      var proof = ZK.generateRangeProof(41, 18, 120)
+      ZK.verifyRangeProof(proof, 18, 120, proof.opening).should.equal(true)
+    })
+
+    // The commitment must actually bind the value: a lie about what was committed to
+    // has to fail even though the range and structure are right.
+    it('rejects an opening that does not match the commitment', function () {
+      var proof = ZK.generateRangeProof(41, 18, 120)
+      var lie = { value: 12, salt: proof.opening.salt }
+      ZK.verifyRangeProof(proof, 18, 120, lie).should.equal(false)
+    })
+
+    it('rejects a value outside the stated range even if the commitment opens', function () {
+      var proof = ZK.generateRangeProof(41, 18, 120)
+      ZK.verifyRangeProof(proof, 50, 120, proof.opening).should.equal(false)
+    })
+
+    it('returns a strict boolean', function () {
+      var proof = ZK.generateRangeProof(41, 18, 120)
+      ZK.verifyRangeProof(proof, 18, 120, proof.opening).should.be.a('boolean')
+      ZK.verifyRangeProof({}, 18, 120).should.be.a('boolean')
+    })
+  })
+
+  describe('age proofs', function () {
+    var BIRTH = new Date('1985-01-01T00:00:00Z')
+
+    it('rejects a forged proof that merely claims meetsRequirement', function () {
+      var forged = {
+        type: 'AgeProof',
+        minimumAge: 18,
+        meetsRequirement: true,
+        birthDateCommitment: '00'.repeat(32),
+        challengeResponse: 'anything-non-empty'
+      }
+      ZK.verifyAgeProof(forged, 18).should.equal(false)
+    })
+
+    it('rejects an honest proof presented without its opening', function () {
+      var proof = ZK.generateAgeProof(BIRTH, 18)
+      ZK.verifyAgeProof(proof, 18).should.equal(false)
+    })
+
+    it('accepts an honest proof with its opening', function () {
+      var proof = ZK.generateAgeProof(BIRTH, 18)
+      ZK.verifyAgeProof(proof, 18, proof.opening).should.equal(true)
+    })
+
+    it('rejects an opening that does not match the commitment', function () {
+      var proof = ZK.generateAgeProof(BIRTH, 18)
+      ZK.verifyAgeProof(proof, 18, { birthDate: '2015-01-01', salt: proof.opening.salt })
+        .should.equal(false)
+    })
+  })
+
+  describe('selective disclosure', function () {
+    // THE LEAK. One salt covered every leaf and travelled in the proof, so the sibling
+    // hashes on the Merkle path could be brute-forced back into the withheld fields.
+    // Disclosing only the name recovered id, partyAffiliation and eligible.
+    it('does not leak the withheld fields to someone holding the proof', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'aa'.repeat(16))
+
+      // Everything an attacker gets: the proof's salts and the Merkle path.
+      var salts = proof.disclosedFields.map(function (f) { return f.salt })
+      var siblings = []
+      proof.merkleProofs.forEach(function (mp) {
+        mp.proof.forEach(function (n) { siblings.push(n.hash) })
+      })
+
+      function leaf (p, v, s) {
+        return Hash.sha256(Buffer.from(p + ':' + JSON.stringify(v) + ':' + s, 'utf8')).toString('hex')
+      }
+      function node (a, b) {
+        return Hash.sha256(Buffer.from(a + b, 'hex')).toString('hex')
+      }
+
+      var paths = ['id', 'credentialSubject.partyAffiliation', 'credentialSubject.eligible']
+      var values = ['urn:x', 'DEM', 'REP', 'IND', true, false]
+      var recovered = []
+
+      salts.forEach(function (s) {
+        // Direct leaf siblings.
+        paths.forEach(function (p) {
+          values.forEach(function (v) {
+            if (siblings.indexOf(leaf(p, v, s)) !== -1) recovered.push(p)
+          })
+        })
+        // Internal nodes: brute-force the pair beneath them.
+        paths.forEach(function (p1) {
+          values.forEach(function (v1) {
+            paths.forEach(function (p2) {
+              values.forEach(function (v2) {
+                if (siblings.indexOf(node(leaf(p1, v1, s), leaf(p2, v2, s))) !== -1) {
+                  recovered.push(p1, p2)
+                }
+              })
+            })
+          })
+        })
+      })
+
+      recovered.should.deep.equal([], 'recovered withheld fields: ' + recovered.join(', '))
+    })
+
+    it('never ships the master salt, which would reopen every leaf', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'aa'.repeat(16))
+      ;(proof.salt === undefined).should.equal(true)
+    })
+
+    // The generated salt used to be dropped on the floor: the proof returned the
+    // (undefined) `salt` ARGUMENT rather than the one createMerkleTree produced, so a
+    // proof made without an explicit salt could never verify.
+    it('verifies a proof generated without an explicit salt', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'])
+      var result = ZK.verifySelectiveProof(proof, proof.credentialRoot)
+      result.valid.should.equal(true, JSON.stringify(result.errors))
+    })
+
+    it('verifies a proof generated with an explicit salt', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'aa'.repeat(16))
+      ZK.verifySelectiveProof(proof, proof.credentialRoot).valid.should.equal(true)
+    })
+
+    it('rejects a tampered disclosed value', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'aa'.repeat(16))
+      proof.disclosedFields[0].value = 'Mallory'
+      ZK.verifySelectiveProof(proof, proof.credentialRoot).valid.should.equal(false)
+    })
+
+    it('rejects a proof checked against the wrong root', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'aa'.repeat(16))
+      ZK.verifySelectiveProof(proof, '00'.repeat(32)).valid.should.equal(false)
+    })
+
+    it('rejects a field whose salt has been stripped', function () {
+      var proof = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'aa'.repeat(16))
+      delete proof.disclosedFields[0].salt
+      ZK.verifySelectiveProof(proof, proof.credentialRoot).valid.should.equal(false)
+    })
+
+    // Deterministic trees are still available for callers that need them, without the
+    // single-salt weakness that made them dangerous.
+    it('is deterministic given the same master salt', function () {
+      var a = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'bb'.repeat(16))
+      var b = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'bb'.repeat(16))
+      a.credentialRoot.should.equal(b.credentialRoot)
+    })
+
+    it('gives different roots for different master salts', function () {
+      var a = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'bb'.repeat(16))
+      var b = ZK.generateSelectiveProof(CRED, ['credentialSubject.name'], 'cc'.repeat(16))
+      a.credentialRoot.should.not.equal(b.credentialRoot)
+    })
+  })
+
+  // The module is reachable from the public GDAF surface, so the fixes above are not
+  // internal-only.
+  it('is exposed on the GDAF instance', function () {
+    var g = new bsv.GDAF()
+    ;(typeof g.zkProver.verifyRangeProof).should.equal('function')
+  })
+})

package/test/notaryhash/certificate.js

@@ -0,0 +1,249 @@
+'use strict'
+
+/* global describe, it */
+
+// BRC-220 certificate. This is validity check 2 of the three the spec requires — proof
+// integrity — plus the object a verifier is actually handed.
+//
+// The tests below concentrate on three things the spec makes explicit and that would fail
+// silently if got wrong: the certificate carries FULL blobs even when the chain carries
+// digests; the SPV envelope never disturbs proofHash; and proofHash is over the binary
+// proof bytes, NOT over the certificate JSON.
+
+require('chai').should()
+var Certificate = require('../../lib/notaryhash/certificate')
+var Encoding = require('../../lib/notaryhash/encoding')
+var NS = require('../../lib/notaryhash/script')
+var Hash = require('../../lib/crypto/hash')
+var JCS = require('../../lib/util/jcs')
+
+var PARAMS = {
+  mode: NS.MODE.FULL,
+  algorithm: 'ECDSA-secp256k1',
+  hashAlgorithm: 'SHA-256',
+  payloadHash: Buffer.alloc(32, 0x11),
+  publicKey: Buffer.alloc(33, 0x02),
+  signature: Buffer.alloc(64, 0x30),
+  createdAt: '2026-08-16T00:00:00.000Z',
+  anchor: { txid: 'ab'.repeat(32), blockHeight: 800000 }
+}
+
+var SPV = {
+  rawTx: 'deadbeef',
+  blockHash: 'cc'.repeat(32),
+  blockHeight: 800000,
+  merkleProof: { index: 0, nodes: ['aa'.repeat(32), '*'] }
+}
+
+describe('BRC-220 certificate', function () {
+  describe('build', function () {
+    it('carries every field the spec requires', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.REQUIRED_FIELDS.forEach(function (field) {
+        ;(cert[field] === undefined).should.equal(false, 'missing ' + field)
+      })
+    })
+
+    it('defaults encoding to raw', function () {
+      Certificate.build(PARAMS).encoding.should.equal('raw')
+    })
+
+    it('accepts der for Bitcoin-native signers', function () {
+      Certificate.build(Object.assign({}, PARAMS, { encoding: 'der' })).encoding.should.equal('der')
+    })
+
+    it('rejects an unknown encoding rather than passing it through', function () {
+      ;(function () {
+        Certificate.build(Object.assign({}, PARAMS, { encoding: 'base64' }))
+      }).should.throw(/encoding must be/)
+    })
+
+    it('hex-encodes the byte fields', function () {
+      var cert = Certificate.build(PARAMS)
+      cert.payloadHash.should.equal(PARAMS.payloadHash.toString('hex'))
+      cert.publicKey.should.equal(PARAMS.publicKey.toString('hex'))
+      cert.signature.should.equal(PARAMS.signature.toString('hex'))
+    })
+
+    // proofHash is computed, never accepted. A caller cannot hand in a value that
+    // disagrees with the fields beside it — which is precisely the artefact this protocol
+    // exists to make impossible.
+    it('computes proofHash rather than accepting one', function () {
+      var cert = Certificate.build(Object.assign({}, PARAMS, { proofHash: 'ff'.repeat(32) }))
+      cert.proofHash.should.not.equal('ff'.repeat(32))
+      Certificate.proofHashMatches(cert).should.equal(true)
+    })
+
+    it('requires a merkle proof for batch mode', function () {
+      ;(function () {
+        Certificate.build(Object.assign({}, PARAMS, { mode: NS.MODE.BATCH }))
+      }).should.throw(/merkle/)
+    })
+
+    it('carries the merkle proof when batched', function () {
+      var cert = Certificate.build(Object.assign({}, PARAMS, {
+        mode: NS.MODE.BATCH,
+        merkle: { root: 'aa'.repeat(32), leafIndex: 2, leafCount: 8, path: [] }
+      }))
+      cert.merkle.leafIndex.should.equal(2)
+      cert.merkle.leafCount.should.equal(8)
+    })
+
+    // Hybrid puts only digests on chain; the certificate keeps the originals. That
+    // asymmetry is the whole point of the mode.
+    it('keeps the FULL key and signature in hybrid mode', function () {
+      var cert = Certificate.build(Object.assign({}, PARAMS, { mode: NS.MODE.HYBRID }))
+      cert.publicKey.should.equal(PARAMS.publicKey.toString('hex'))
+      cert.signature.should.equal(PARAMS.signature.toString('hex'))
+      // What goes on chain is the digest of each — different values entirely.
+      var onChain = NS.parse(NS.build(Object.assign({}, PARAMS, { mode: NS.MODE.HYBRID, proofHash: Buffer.alloc(32) })))
+      onChain.publicKeyHash.toString('hex').should.equal(Hash.sha256(PARAMS.publicKey).toString('hex'))
+      onChain.publicKeyHash.toString('hex').should.not.equal(cert.publicKey)
+    })
+  })
+
+  describe('proof integrity (validity check 2)', function () {
+    it('matches for a well-formed certificate', function () {
+      Certificate.proofHashMatches(Certificate.build(PARAMS)).should.equal(true)
+    })
+
+    // Each field is inside the canonical proof bytes, so tampering with any of them must
+    // be detected. This is the certificate-level counterpart of the encoding module's
+    // coverage test.
+    it('detects tampering with any covered field', function () {
+      var cert = Certificate.build(PARAMS)
+      var tampers = {
+        algorithm: 'ML-DSA-65',
+        hashAlgorithm: 'SHA-512',
+        payloadHash: 'ff'.repeat(32),
+        publicKey: '03' + '11'.repeat(32),
+        signature: 'aa'.repeat(64),
+        createdAt: '2026-08-17T00:00:00.000Z'
+      }
+      Object.keys(tampers).forEach(function (field) {
+        var bad = Object.assign({}, cert)
+        bad[field] = tampers[field]
+        Certificate.proofHashMatches(bad)
+          .should.equal(false, 'tampering with ' + field + ' was not detected')
+      })
+    })
+
+    // Fields NOT in the canonical proof bytes must not affect it — otherwise the SPV
+    // envelope could not be additive.
+    it('is unaffected by fields outside the canonical bytes', function () {
+      var cert = Certificate.build(PARAMS)
+      var moved = Object.assign({}, cert, {
+        anchor: { txid: 'ff'.repeat(32), blockHeight: 999999 },
+        mode: NS.MODE.HYBRID
+      })
+      Certificate.proofHashMatches(moved).should.equal(true)
+    })
+
+    it('returns a strict boolean, never a truthy object', function () {
+      Certificate.proofHashMatches(Certificate.build(PARAMS)).should.be.a('boolean')
+      Certificate.proofHashMatches(null).should.equal(false)
+      Certificate.proofHashMatches({}).should.equal(false)
+      Certificate.proofHashMatches({ proofHash: 'nonsense' }).should.equal(false)
+    })
+
+    // The hex fields decode to bytes before hashing. Hashing the strings would be twice
+    // as many bytes and produce something that still looks like a hash.
+    it('hashes the decoded bytes, not the hex strings', function () {
+      var cert = Certificate.build(PARAMS)
+      var overHex = Hash.sha256(Encoding.canonicalBytes({
+        algorithm: cert.algorithm,
+        hashAlgorithm: cert.hashAlgorithm,
+        payloadHash: Buffer.from(cert.payloadHash, 'utf8'), // the STRING, wrongly
+        publicKey: Buffer.from(cert.publicKey, 'hex'),
+        signature: Buffer.from(cert.signature, 'hex'),
+        createdAtUnix: Encoding.toUnixSeconds(cert.createdAt)
+      })).toString('hex')
+      overHex.should.not.equal(cert.proofHash)
+    })
+  })
+
+  describe('SPV envelope', function () {
+    // The spec's explicit guarantee. If it ever broke, every previously issued
+    // certificate would become unverifiable.
+    it('never changes proofHash', function () {
+      var cert = Certificate.build(PARAMS)
+      var withSPV = Certificate.attachSPV(cert, SPV)
+      withSPV.proofHash.should.equal(cert.proofHash)
+      Certificate.proofHashMatches(withSPV).should.equal(true)
+    })
+
+    it('does not mutate the certificate it was given', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.attachSPV(cert, SPV)
+      ;(cert.spv === undefined).should.equal(true)
+    })
+
+    it('defaults format to TSC', function () {
+      Certificate.attachSPV(Certificate.build(PARAMS), SPV).spv.format.should.equal('TSC')
+    })
+
+    it('keeps an explicit format, for BUMP or BEEF', function () {
+      var withSPV = Certificate.attachSPV(Certificate.build(PARAMS),
+        Object.assign({}, SPV, { format: 'BUMP' }))
+      withSPV.spv.format.should.equal('BUMP')
+    })
+  })
+
+  describe('validateShape', function () {
+    it('passes a well-formed certificate', function () {
+      Certificate.validateShape(Certificate.build(PARAMS)).should.deep.equal([])
+    })
+
+    it('names every missing required field', function () {
+      var problems = Certificate.validateShape({})
+      problems.length.should.equal(Certificate.REQUIRED_FIELDS.length)
+      problems[0].should.match(/missing required field/)
+    })
+
+    it('rejects a foreign protocol or version', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.validateShape(Object.assign({}, cert, { protocol: 'Other' }))
+        .should.include('protocol must be "NotaryHash"')
+      Certificate.validateShape(Object.assign({}, cert, { version: 2 }))
+        .should.include('unsupported version: 2')
+    })
+
+    it('rejects a hash field of the wrong length or that is not hex', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.validateShape(Object.assign({}, cert, { payloadHash: 'ab' }))
+        .should.include('payloadHash must be 32 bytes (64 hex chars)')
+      Certificate.validateShape(Object.assign({}, cert, { proofHash: 'zz'.repeat(32) }))
+        .should.include('proofHash must be a hex string')
+    })
+
+    // Shape is not verification, and a test says so — otherwise it gets used as one.
+    it('says nothing about whether the proofHash is correct', function () {
+      var cert = Certificate.build(PARAMS)
+      var lying = Object.assign({}, cert, { proofHash: '00'.repeat(32) })
+      Certificate.validateShape(lying).should.deep.equal([])
+      Certificate.proofHashMatches(lying).should.equal(false)
+    })
+  })
+
+  describe('canonicalize', function () {
+    it('is RFC 8785 over the certificate', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.canonicalize(cert).should.equal(JCS.stringify(cert))
+    })
+
+    it('sorts keys, so transport order does not matter', function () {
+      var cert = Certificate.build(PARAMS)
+      var reordered = {}
+      Object.keys(cert).reverse().forEach(function (k) { reordered[k] = cert[k] })
+      Certificate.canonicalize(reordered).should.equal(Certificate.canonicalize(cert))
+    })
+
+    // proofHash is over the length-prefixed BINARY proof bytes, not over this JSON.
+    // Confusing the two produces a value that looks like a proofHash and is not one.
+    it('is not what proofHash is computed over', function () {
+      var cert = Certificate.build(PARAMS)
+      Hash.sha256(Buffer.from(Certificate.canonicalize(cert), 'utf8')).toString('hex')
+        .should.not.equal(cert.proofHash)
+    })
+  })
+})

package/test/notaryhash/encoding.js

@@ -0,0 +1,186 @@
+'use strict'
+
+/* global describe, it */
+
+// BRC-220 canonical encoding. The property that matters is not that these bytes are
+// stable for us — it is that another implementation reading the spec produces the same
+// ones. So the tests assert the byte layout the spec dictates, field by field, rather
+// than only pinning our own output.
+//
+// The failure this module is most exposed to is a proofHash that is self-consistent and
+// wrong: it verifies against itself, every local test passes, and nobody finds out until
+// a third party tries to verify a certificate. Several tests below exist only to make
+// that shape impossible.
+
+require('chai').should()
+var Encoding = require('../../lib/notaryhash/encoding')
+var Hash = require('../../lib/crypto/hash')
+
+var FIELDS = {
+  algorithm: 'ECDSA-secp256k1',
+  hashAlgorithm: 'SHA-256',
+  payloadHash: Buffer.alloc(32, 0x11),
+  publicKey: Buffer.alloc(33, 0x02),
+  signature: Buffer.alloc(71, 0x30),
+  createdAtUnix: 1786838400
+}
+
+describe('BRC-220 encoding', function () {
+  describe('lp()', function () {
+    it('is u32be(len) followed by the bytes', function () {
+      Encoding.lp(Buffer.from([0xaa, 0xbb])).toString('hex').should.equal('00000002aabb')
+    })
+
+    it('encodes an empty value as a bare zero length', function () {
+      Encoding.lp(Buffer.alloc(0)).toString('hex').should.equal('00000000')
+    })
+
+    it('measures BYTES, not characters, for text', function () {
+      // 'é' is one character and two UTF-8 bytes. Using .length here would prefix 1,
+      // and every proof containing a non-ASCII algorithm name would be unverifiable.
+      Encoding.lp('é').toString('hex').should.equal('00000002c3a9')
+      Encoding.lp('abc').toString('hex').should.equal('00000003616263')
+    })
+
+    // Length-prefixing exists to make field boundaries unambiguous. If it did not, these
+    // two field pairs would concatenate to identical bytes.
+    it('keeps ambiguous field splits distinct', function () {
+      var a = Buffer.concat([Encoding.lp('ab'), Encoding.lp('c')])
+      var b = Buffer.concat([Encoding.lp('a'), Encoding.lp('bc')])
+      a.toString('hex').should.not.equal(b.toString('hex'))
+    })
+  })
+
+  describe('u64be()', function () {
+    it('is 8 bytes, big-endian', function () {
+      Encoding.u64be(1).toString('hex').should.equal('0000000000000001')
+      Encoding.u64be(1786838400).toString('hex').should.equal('000000006a80fd80')
+    })
+
+    // Date.now() is milliseconds. A caller who forgets to divide gets a timestamp about
+    // a thousand years in the future that still encodes cleanly, so the guard is on the
+    // input rather than the output.
+    it('rejects a fractional value, which is what a millisecond mistake looks like', function () {
+      ;(function () { Encoding.u64be(1786838400.5) }).should.throw(/whole seconds/)
+    })
+
+    it('rejects non-finite and negative values', function () {
+      ;(function () { Encoding.u64be(NaN) }).should.throw(/finite/)
+      ;(function () { Encoding.u64be(-1) }).should.throw(/negative/)
+    })
+  })
+
+  describe('toUnixSeconds()', function () {
+    it('converts an ISO 8601 string to whole seconds', function () {
+      Encoding.toUnixSeconds('2026-08-16T00:00:00.000Z').should.equal(1786838400)
+    })
+
+    // Certificates carry millisecond precision in createdAt; the canonical bytes do not.
+    // Two implementations must agree on the fractional part, and truncation is the only
+    // choice that never moves a timestamp forward.
+    it('truncates rather than rounds', function () {
+      Encoding.toUnixSeconds('2026-08-16T00:00:00.999Z').should.equal(1786838400)
+    })
+
+    it('rejects an unparseable date', function () {
+      ;(function () { Encoding.toUnixSeconds('not-a-date') }).should.throw(/not a valid date/)
+    })
+  })
+
+  describe('canonicalBytes()', function () {
+    // The layout, asserted against a hand-built expectation rather than against the
+    // function's own output — otherwise this only proves the function is deterministic.
+    it('lays the fields out exactly as the spec specifies', function () {
+      var expected = Buffer.concat([
+        Encoding.lp('NotaryHash/1.0'),
+        Buffer.from([1]),
+        Encoding.lp('ECDSA-secp256k1'),
+        Encoding.lp('SHA-256'),
+        Encoding.lp(FIELDS.payloadHash),
+        Encoding.lp(FIELDS.publicKey),
+        Encoding.lp(FIELDS.signature),
+        Encoding.u64be(FIELDS.createdAtUnix)
+      ])
+      Encoding.canonicalBytes(FIELDS).toString('hex').should.equal(expected.toString('hex'))
+    })
+
+    it('opens with the protocol prefix and the version byte', function () {
+      var bytes = Encoding.canonicalBytes(FIELDS)
+      bytes.slice(0, 4).readUInt32BE(0).should.equal(14) // len('NotaryHash/1.0')
+      bytes.slice(4, 18).toString('utf8').should.equal('NotaryHash/1.0')
+      bytes[18].should.equal(1) // u8(version)
+    })
+
+    it('ends with the timestamp', function () {
+      var bytes = Encoding.canonicalBytes(FIELDS)
+      bytes.slice(-8).toString('hex').should.equal(Encoding.u64be(FIELDS.createdAtUnix).toString('hex'))
+    })
+
+    // THE test for this module. GDAF once signed a serialization that silently omitted
+    // credentialSubject, so a forger could rewrite the claims without breaking the proof.
+    // Every field must move the hash, or it is not covered by it.
+    it('covers every field — changing any one changes the hash', function () {
+      var base = Encoding.proofHash(FIELDS).toString('hex')
+      var mutations = {
+        algorithm: 'ML-DSA-65',
+        hashAlgorithm: 'SHA-512',
+        payloadHash: Buffer.alloc(32, 0x12),
+        publicKey: Buffer.alloc(33, 0x03),
+        signature: Buffer.alloc(71, 0x31),
+        createdAtUnix: FIELDS.createdAtUnix + 1
+      }
+      Object.keys(mutations).forEach(function (field) {
+        var altered = Object.assign({}, FIELDS)
+        altered[field] = mutations[field]
+        Encoding.proofHash(altered).toString('hex')
+          .should.not.equal(base, field + ' does not affect proofHash, so it is not covered by it')
+      })
+    })
+
+    // Hex is what certificates carry, and hex is twice as long as the bytes it encodes.
+    // Accepting it here would produce a proof that verifies locally and nowhere else.
+    it('refuses a hex string where raw bytes are required', function () {
+      var withHex = Object.assign({}, FIELDS, { payloadHash: FIELDS.payloadHash.toString('hex') })
+      ;(function () { Encoding.canonicalBytes(withHex) }).should.throw(/must be a Buffer/)
+    })
+
+    it('names the offending field and points at the hex trap', function () {
+      var withHex = Object.assign({}, FIELDS, { signature: FIELDS.signature.toString('hex') })
+      ;(function () { Encoding.canonicalBytes(withHex) }).should.throw(/signature.*hex/)
+    })
+
+    it('requires the string fields to be present and non-empty', function () {
+      ;(function () {
+        Encoding.canonicalBytes(Object.assign({}, FIELDS, { algorithm: '' }))
+      }).should.throw(/algorithm/)
+      ;(function () {
+        Encoding.canonicalBytes(Object.assign({}, FIELDS, { hashAlgorithm: undefined }))
+      }).should.throw(/hashAlgorithm/)
+    })
+
+    it('handles a post-quantum-sized signature', function () {
+      // SLH-DSA signatures run to tens of kilobytes; the u32be length prefix must carry
+      // them without truncation.
+      var big = Object.assign({}, FIELDS, { signature: Buffer.alloc(49856, 0x7f) })
+      var bytes = Encoding.canonicalBytes(big)
+      var sigLenOffset = bytes.length - 8 - 49856 - 4
+      bytes.readUInt32BE(sigLenOffset).should.equal(49856)
+    })
+  })
+
+  describe('proofHash()', function () {
+    it('is SHA-256 of the canonical bytes', function () {
+      Encoding.proofHash(FIELDS).toString('hex')
+        .should.equal(Hash.sha256(Encoding.canonicalBytes(FIELDS)).toString('hex'))
+    })
+
+    it('is 32 bytes', function () {
+      Encoding.proofHash(FIELDS).length.should.equal(32)
+    })
+
+    it('is deterministic', function () {
+      Encoding.proofHash(FIELDS).toString('hex')
+        .should.equal(Encoding.proofHash(Object.assign({}, FIELDS)).toString('hex'))
+    })
+  })
+})