@smartledger/bsv 8.2.0 → 8.3.1

package/lib/notaryhash/script.js

@@ -0,0 +1,261 @@
+'use strict'
+
+var Script = require('../script/script')
+var Opcode = require('../opcode')
+var Hash = require('../crypto/hash')
+var $ = require('../util/preconditions')
+
+/**
+ * BRC-220 on-chain record: an `OP_FALSE OP_RETURN` safe data output.
+ *
+ *   full   (mode 0): "NOTARYHASH" | u8(1) | u8(0) | algorithm | hashAlgorithm |
+ *                    payloadHash | proofHash | publicKey | signature
+ *   hybrid (mode 1): as full, but the last two pushes are SHA-256 of each
+ *   batch  (kind 2): "NOTARYHASH" | u8(1) | u8(2) | merkleRoot(32) | u32be(leafCount)
+ *
+ * NOTE the framing differs from the canonical proof bytes on purpose. Those use
+ * `lp(x) = u32be(len(x)) || x` because they are one flat byte string; here each field is
+ * its own SCRIPT PUSH, and the push opcode already carries the length. Applying `lp()`
+ * again would double-encode every field. Both achieve unambiguous boundaries; only one is
+ * correct in each place.
+ */
+
+var NotaryScript = {}
+
+/** Push index 0. Ten ASCII bytes; the spec states no length, the literal is the spec. */
+NotaryScript.PREFIX = 'NOTARYHASH'
+
+/** Push index 1. */
+NotaryScript.VERSION = 1
+
+/** Push index 2 — the byte that discriminates the layout. */
+NotaryScript.MODE = {
+  FULL: 0,
+  HYBRID: 1,
+  BATCH: 2
+}
+
+function u8 (n) { return Buffer.from([n]) }
+
+function u32be (n) {
+  var b = Buffer.alloc(4)
+  b.writeUInt32BE(n, 0)
+  return b
+}
+
+function requireBytes (value, name, length) {
+  if (!Buffer.isBuffer(value)) {
+    throw new Error(name + ' must be a Buffer of raw bytes, not ' + (typeof value) +
+      '. Decode hex with Buffer.from(hex, \'hex\') first.')
+  }
+  if (length != null && value.length !== length) {
+    throw new Error(name + ' must be exactly ' + length + ' bytes, got ' + value.length)
+  }
+  return value
+}
+
+/**
+ * Read a push that carries a single unsigned byte.
+ *
+ * A 1-byte data push is what this library emits and what the spec's `u8(...)` describes.
+ * `OP_0` and `OP_1`–`OP_16` are ALSO accepted, because a builder that minimally encodes
+ * its pushes — which is the default in several Bitcoin libraries — represents the same
+ * values that way, and rejecting those would reject records that are otherwise perfectly
+ * conformant. Being strict here would buy nothing: the mode byte is a routing hint, and
+ * every field that matters is checked on its own terms further down.
+ *
+ * @private
+ */
+function readU8 (chunk, name) {
+  if (chunk.buf && chunk.buf.length === 1) return chunk.buf[0]
+  if (chunk.opcodenum === Opcode.OP_0) return 0
+  if (chunk.opcodenum >= Opcode.OP_1 && chunk.opcodenum <= Opcode.OP_16) {
+    return chunk.opcodenum - Opcode.OP_1 + 1
+  }
+  throw new Error(name + ' must be a single byte at this push')
+}
+
+function readBuf (chunk, name) {
+  if (!chunk || !chunk.buf) throw new Error(name + ' push is missing or carries no data')
+  return chunk.buf
+}
+
+/**
+ * Build the on-chain record.
+ *
+ * `publicKey` and `signature` are always supplied in FULL form, whatever the mode. In
+ * hybrid mode this function hashes them itself rather than accepting pre-hashed values —
+ * a caller who passed an already-hashed blob would produce a record that looks right and
+ * cannot be reconciled with the certificate, and nothing downstream would notice.
+ *
+ * @param {Object} record
+ * @param {Number} record.mode - NotaryScript.MODE.*
+ * @param {String} record.algorithm - full/hybrid
+ * @param {String} record.hashAlgorithm - full/hybrid
+ * @param {Buffer} record.payloadHash - full/hybrid, 32 bytes
+ * @param {Buffer} record.proofHash - full/hybrid, 32 bytes
+ * @param {Buffer} record.publicKey - full/hybrid, raw bytes
+ * @param {Buffer} record.signature - full/hybrid, raw bytes
+ * @param {Buffer} record.merkleRoot - batch, 32 bytes
+ * @param {Number} record.leafCount - batch
+ * @returns {Script}
+ */
+NotaryScript.build = function (record) {
+  $.checkArgument(record && typeof record === 'object', 'record is required')
+
+  var mode = record.mode
+  $.checkArgument(mode === NotaryScript.MODE.FULL ||
+    mode === NotaryScript.MODE.HYBRID ||
+    mode === NotaryScript.MODE.BATCH,
+  'mode must be 0 (full), 1 (hybrid) or 2 (batch)')
+
+  var script = new Script()
+    .add(Opcode.OP_FALSE)
+    .add(Opcode.OP_RETURN)
+    .add(Buffer.from(NotaryScript.PREFIX, 'ascii'))
+    .add(u8(NotaryScript.VERSION))
+    .add(u8(mode))
+
+  if (mode === NotaryScript.MODE.BATCH) {
+    $.checkArgument(typeof record.leafCount === 'number' && Number.isInteger(record.leafCount) &&
+      record.leafCount >= 0, 'leafCount must be a non-negative integer')
+    script.add(requireBytes(record.merkleRoot, 'merkleRoot', 32))
+    script.add(u32be(record.leafCount))
+    return script
+  }
+
+  $.checkArgument(typeof record.algorithm === 'string' && record.algorithm.length > 0,
+    'algorithm must be a non-empty string')
+  $.checkArgument(typeof record.hashAlgorithm === 'string' && record.hashAlgorithm.length > 0,
+    'hashAlgorithm must be a non-empty string')
+
+  script.add(Buffer.from(record.algorithm, 'utf8'))
+  script.add(Buffer.from(record.hashAlgorithm, 'utf8'))
+  script.add(requireBytes(record.payloadHash, 'payloadHash', 32))
+  script.add(requireBytes(record.proofHash, 'proofHash', 32))
+
+  var publicKey = requireBytes(record.publicKey, 'publicKey')
+  var signature = requireBytes(record.signature, 'signature')
+
+  if (mode === NotaryScript.MODE.HYBRID) {
+    script.add(Hash.sha256(publicKey))
+    script.add(Hash.sha256(signature))
+  } else {
+    script.add(publicKey)
+    script.add(signature)
+  }
+
+  return script
+}
+
+/**
+ * Parse an on-chain record.
+ *
+ * Returns a plain object, or throws with a message naming what was wrong. It never
+ * returns a partially-populated result: a caller that cannot distinguish "parsed" from
+ * "parsed some of it" is the shape that produces confident wrong answers.
+ *
+ * In hybrid mode the returned `publicKeyHash` / `signatureHash` are the on-chain digests;
+ * the full blobs live only in the certificate, and reconciling the two is the caller's
+ * job.
+ *
+ * @param {Script|String} script
+ * @returns {Object}
+ */
+NotaryScript.parse = function (script) {
+  if (typeof script === 'string') script = Script.fromHex(script)
+  $.checkArgument(script instanceof Script, 'script must be a Script or hex string')
+
+  var chunks = script.chunks
+
+  if (chunks.length < 5) {
+    throw new Error('not a NotaryHash record: too few pushes')
+  }
+  if (chunks[0].opcodenum !== Opcode.OP_FALSE && chunks[0].opcodenum !== Opcode.OP_0) {
+    throw new Error('not a NotaryHash record: does not start with OP_FALSE')
+  }
+  if (chunks[1].opcodenum !== Opcode.OP_RETURN) {
+    throw new Error('not a NotaryHash record: no OP_RETURN')
+  }
+
+  var prefix = readBuf(chunks[2], 'prefix')
+  if (prefix.toString('ascii') !== NotaryScript.PREFIX) {
+    throw new Error('not a NotaryHash record: prefix is ' + JSON.stringify(prefix.toString('ascii')))
+  }
+
+  var version = readU8(chunks[3], 'version')
+  if (version !== NotaryScript.VERSION) {
+    throw new Error('unsupported NotaryHash version: ' + version)
+  }
+
+  var mode = readU8(chunks[4], 'mode')
+
+  if (mode === NotaryScript.MODE.BATCH) {
+    if (chunks.length !== 7) {
+      throw new Error('batch record must have exactly 7 pushes, got ' + chunks.length)
+    }
+    var leafCountBuf = readBuf(chunks[6], 'leafCount')
+    if (leafCountBuf.length !== 4) {
+      throw new Error('leafCount must be 4 bytes (u32be), got ' + leafCountBuf.length)
+    }
+    return {
+      mode: mode,
+      version: version,
+      merkleRoot: requireBytes(readBuf(chunks[5], 'merkleRoot'), 'merkleRoot', 32),
+      leafCount: leafCountBuf.readUInt32BE(0)
+    }
+  }
+
+  if (mode !== NotaryScript.MODE.FULL && mode !== NotaryScript.MODE.HYBRID) {
+    throw new Error('unknown NotaryHash mode: ' + mode)
+  }
+
+  if (chunks.length !== 11) {
+    throw new Error('full/hybrid record must have exactly 11 pushes, got ' + chunks.length)
+  }
+
+  var parsed = {
+    mode: mode,
+    version: version,
+    algorithm: readBuf(chunks[5], 'algorithm').toString('utf8'),
+    hashAlgorithm: readBuf(chunks[6], 'hashAlgorithm').toString('utf8'),
+    payloadHash: requireBytes(readBuf(chunks[7], 'payloadHash'), 'payloadHash', 32),
+    proofHash: requireBytes(readBuf(chunks[8], 'proofHash'), 'proofHash', 32)
+  }
+
+  if (mode === NotaryScript.MODE.HYBRID) {
+    parsed.publicKeyHash = requireBytes(readBuf(chunks[9], 'publicKeyHash'), 'publicKeyHash', 32)
+    parsed.signatureHash = requireBytes(readBuf(chunks[10], 'signatureHash'), 'signatureHash', 32)
+  } else {
+    parsed.publicKey = readBuf(chunks[9], 'publicKey')
+    parsed.signature = readBuf(chunks[10], 'signature')
+  }
+
+  return parsed
+}
+
+/**
+ * Does this script look like a NotaryHash record?
+ *
+ * Strictly a cheap filter for scanning outputs — a true result means `parse()` is worth
+ * attempting, NOT that the record is well-formed. Anything that acts on the contents must
+ * call `parse()` and handle its errors.
+ *
+ * @param {Script|String} script
+ * @returns {Boolean}
+ */
+NotaryScript.isNotaryHash = function (script) {
+  try {
+    if (typeof script === 'string') script = Script.fromHex(script)
+    var c = script.chunks
+    return c.length >= 5 &&
+      (c[0].opcodenum === Opcode.OP_FALSE || c[0].opcodenum === Opcode.OP_0) &&
+      c[1].opcodenum === Opcode.OP_RETURN &&
+      !!c[2].buf &&
+      c[2].buf.toString('ascii') === NotaryScript.PREFIX
+  } catch (e) {
+    return false
+  }
+}
+
+module.exports = NotaryScript

package/lib/notaryhash/suites.js

@@ -0,0 +1,172 @@
+'use strict'
+
+var BN = require('../crypto/bn')
+var ECDSA = require('../crypto/ecdsa')
+var Signature = require('../crypto/signature')
+var PublicKey = require('../publickey')
+var Point = require('../crypto/point')
+var $ = require('../util/preconditions')
+
+/**
+ * Signature suites, keyed on the `algorithm` string BRC-220 already carries.
+ *
+ * `ECDSA-secp256k1` is registered here and needs nothing new. ML-DSA and SLH-DSA are NOT
+ * built in, and that is deliberate rather than unfinished:
+ *
+ *   @noble/post-quantum is the one Noble package with no independent audit -- its README
+ *   says so -- and it is 0.x, 669 KB, and does not claim constant-time execution. This
+ *   library's other primitives carry a published Cure53 audit, which is what lets
+ *   docs/AUDIT_SCOPE.md tell a vendor not to price the primitive layer. Making an
+ *   unaudited implementation a hard dependency of a transaction-signing library would
+ *   forfeit that for a capability the spec does not require: ECDSA-secp256k1 is a
+ *   first-class algorithm alongside the post-quantum ones, so an ECDSA-only
+ *   implementation is conformant.
+ *
+ * So post-quantum suites are supplied by the caller -- most obviously from
+ * @smartledger/keys, which already wraps @noble/post-quantum -- and callers who do not
+ * need them pay nothing in bundle size or audit surface. See docs/BRC220_PLAN.md §2.
+ */
+
+var Suites = {}
+
+var registry = {}
+
+/**
+ * Register a signature suite.
+ *
+ * `verify` MUST return a strict boolean. A suite returning a truthy object would make
+ * every signature check pass, which is the single defect class this codebase has had to
+ * fix most often -- so the registry enforces it at call time rather than trusting the
+ * suite.
+ *
+ * @param {String} algorithm - e.g. 'ML-DSA-65'
+ * @param {Object} suite
+ * @param {Function} suite.verify - (payloadHash: Buffer, signature: Buffer, publicKey: Buffer) => boolean
+ */
+Suites.register = function (algorithm, suite) {
+  $.checkArgument(typeof algorithm === 'string' && algorithm.length > 0,
+    'algorithm must be a non-empty string')
+  $.checkArgument(suite && typeof suite.verify === 'function',
+    'suite must provide a verify(payloadHash, signature, publicKey) function')
+  registry[algorithm] = suite
+  return Suites
+}
+
+/** @returns {Object|undefined} */
+Suites.get = function (algorithm) {
+  return registry[algorithm]
+}
+
+/** @returns {Array<String>} registered algorithm identifiers */
+Suites.list = function () {
+  return Object.keys(registry).sort()
+}
+
+/** Test seam. */
+Suites.unregister = function (algorithm) {
+  delete registry[algorithm]
+  return Suites
+}
+
+/**
+ * Verify a signature under the named suite.
+ *
+ * An UNREGISTERED algorithm returns false. It does not fall through to a default, and it
+ * does not throw: a certificate naming an algorithm this process cannot check has not
+ * been verified, and `false` is the honest answer. Falling through to ECDSA for an
+ * `ML-DSA-65` certificate would be catastrophic and is exactly what a default invites.
+ *
+ * The suite's own return value is coerced with `=== true`, so a suite that returns a
+ * truthy object cannot smuggle a pass through.
+ *
+ * @param {String} algorithm
+ * @param {Buffer} payloadHash - the 32 bytes that were signed
+ * @param {Buffer} signature
+ * @param {Buffer} publicKey
+ * @returns {Boolean}
+ */
+Suites.verify = function (algorithm, payloadHash, signature, publicKey) {
+  var suite = registry[algorithm]
+  if (!suite) return false
+  if (!Buffer.isBuffer(payloadHash) || !Buffer.isBuffer(signature) || !Buffer.isBuffer(publicKey)) {
+    return false
+  }
+  try {
+    return suite.verify(payloadHash, signature, publicKey) === true
+  } catch (e) {
+    return false
+  }
+}
+
+/**
+ * ECDSA over secp256k1.
+ *
+ * The signer signs the 32-byte `payloadHash` DIRECTLY (spec §Algorithms: "post-quantum
+ * schemes apply their own internal hashing"). There is no second hash, and no Bitcoin
+ * sighash — this is a detached signature over a digest.
+ *
+ * Signatures are 64 raw bytes, `r || s`, each a 32-byte big-endian integer. DER is
+ * accepted as a length-discriminated fallback for Bitcoin-native signers, because the
+ * certificate's `encoding` field may say so; see docs/BRC220_ENCODING_AMENDMENT.md for
+ * why raw is what new implementations should emit.
+ *
+ * Low-S is REQUIRED. A high-S signature is rejected rather than normalised: normalising
+ * changes the signature bytes, and those bytes are inside `proofHash`, so accepting both
+ * forms would mean two valid certificates exist for one signing act.
+ */
+Suites.register('ECDSA-secp256k1', {
+  verify: function (payloadHash, signature, publicKey) {
+    if (payloadHash.length !== 32) return false
+
+    var sig
+    if (signature.length === 64) {
+      sig = new Signature(
+        BN.fromBuffer(signature.slice(0, 32)),
+        BN.fromBuffer(signature.slice(32, 64))
+      )
+    } else {
+      // DER, for the legacy `encoding: "der"` case.
+      try {
+        sig = Signature.fromDER(signature)
+      } catch (e) {
+        return false
+      }
+    }
+
+    // Low-S, enforced rather than normalised.
+    var halfOrder = Point.getN().div(new BN(2))
+    if (sig.s.gt(halfOrder)) return false
+
+    var pubkey
+    try {
+      pubkey = PublicKey.fromBuffer(publicKey)
+    } catch (e) {
+      return false
+    }
+
+    var ecdsa = new ECDSA()
+    ecdsa.hashbuf = payloadHash
+    // NO endian override. `payloadHash` is the scalar, big-endian, exactly as the
+    // 32 bytes are given — which is what every other ECDSA implementation does and
+    // what BRC-220 means by "signs the payloadHash".
+    //
+    // 8.3.0 set `endian = 'little'` here, which made ECDSA reverse the digest before
+    // reducing it to the scalar. That is Bitcoin's message-signing convention, not
+    // this protocol's, and it is why lib/crypto/ecdsa.js offers the option at all.
+    //
+    // The effect was on the VERIFY side: a signature produced the way BRC-220
+    // specifies was rejected, and the only signatures accepted were ones made with
+    // bsv's own little-endian convention. Every test in this repo signed that way
+    // too, so the module and its tests were self-consistent and wrong together —
+    // the exact failure shape test/notaryhash/encoding.js warns about in its header.
+    //
+    // test/notaryhash/interop.js now pins this against @noble/curves, which shares
+    // no verification code with lib/crypto/ecdsa.js. A second implementation is the
+    // only thing that can catch a defect where the code and its tests agree.
+    ecdsa.pubkey = pubkey
+    ecdsa.sig = sig
+    return ecdsa.verify() === true
+  }
+})
+
+module.exports = Suites

package/lib/util/jcs.js

@@ -0,0 +1,75 @@
+'use strict'
+
+/**
+ * RFC 8785 — JSON Canonicalization Scheme.
+ *
+ * Extracted from lib/gdaf/attestation-signer.js, where it was added in 8.2.0. Two
+ * unrelated things now need it — GDAF credential signatures and BRC-220 certificates —
+ * and a notarization module reaching into the credentials module for it would be the
+ * wrong direction. JCS is a general serialization concern, not a GDAF concept.
+ *
+ * The behaviour is unchanged; `AttestationSigner._canonicalizeJCS` delegates here.
+ *
+ * The point of JCS is that two independent implementations produce identical bytes, so
+ * everything below is fixed by the RFC rather than by local preference:
+ *
+ *   - Object keys sort by UTF-16 code unit, which is what Array.prototype.sort already
+ *     does for strings. The sort is applied DURING serialization rather than by
+ *     rebuilding an object, because V8 orders integer-like own properties numerically
+ *     ahead of string keys and would silently undo it — `{"2":…,"10":…}` where the RFC
+ *     requires `{"10":…,"2":…}`. That was a real defect in this codebase before 8.2.0.
+ *   - JSON.stringify supplies the leaf types deliberately: for finite numbers it produces
+ *     ECMAScript Number::toString, which the RFC mandates, and since ES2019 it emits
+ *     well-formed output for lone surrogates. Both are easy to get subtly wrong by hand.
+ *   - Non-finite numbers throw rather than serializing as `null`, which is what
+ *     JSON.stringify does and which would silently canonicalize a different document than
+ *     the one supplied.
+ */
+
+var JCS = {}
+
+/**
+ * Serialize a value as RFC 8785 canonical JSON.
+ *
+ * @param {*} value
+ * @returns {String}
+ */
+JCS.stringify = function (value) {
+  if (value === null) return 'null'
+
+  var type = typeof value
+
+  if (type === 'boolean') return value ? 'true' : 'false'
+
+  if (type === 'number') {
+    if (!isFinite(value)) {
+      throw new Error('Cannot canonicalize non-finite number: ' + value)
+    }
+    return JSON.stringify(value)
+  }
+
+  if (type === 'string') return JSON.stringify(value)
+
+  if (Array.isArray(value)) {
+    // Arrays are order-significant. `undefined` has no JSON form and becomes null in an
+    // array, matching JSON.stringify.
+    return '[' + value.map(function (item) {
+      return item === undefined ? 'null' : JCS.stringify(item)
+    }).join(',') + ']'
+  }
+
+  if (type === 'object') {
+    // Absent and explicitly-undefined are indistinguishable in JSON, so both are dropped.
+    var keys = Object.keys(value).filter(function (key) {
+      return value[key] !== undefined && typeof value[key] !== 'function'
+    }).sort()
+
+    return '{' + keys.map(function (key) {
+      return JSON.stringify(key) + ':' + JCS.stringify(value[key])
+    }).join(',') + '}'
+  }
+
+  throw new Error('Cannot canonicalize value of type: ' + type)
+}
+
+module.exports = JCS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "8.2.0",
+  "version": "8.3.1",
   "description": "🚀 Complete Bitcoin SV development framework with legally-recognizable DID:web + W3C VC-JWT toolkit, Legal Token Protocol (LTP), Global Digital Attestation Framework (GDAF), StatusList2021 revocation, and 16 flexible loading options. Standards-based credentials with ES256/ES256K support, on-chain BSV anchoring, and comprehensive Bitcoin SV API. Perfect for legal tokens, verifiable credentials, DeFi, smart contracts, and secure Bitcoin applications.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",
@@ -39,6 +39,7 @@
     "./lib/ltp": "./lib/ltp/index.js",
     "./lib/message": "./lib/message/index.js",
     "./lib/mnemonic": "./lib/mnemonic/index.js",
+    "./lib/notaryhash": "./lib/notaryhash/index.js",
     "./lib/ordinals": "./lib/ordinals/index.js",
     "./lib/script": "./lib/script/index.js",
     "./lib/smart_contract": "./lib/smart_contract/index.js",
@@ -64,6 +65,7 @@
     "vectors:sv-tx": "node tools/sv-tx-report.js",
     "vectors:sv-sighash": "node tools/sv-sighash-report.js",
     "conformance:generate": "node conformance/generate.js",
+    "check:readme": "node scripts/check-readme-accuracy.js",
     "lint:ratchet": "node scripts/lint-ratchet.js",
     "lint:ratchet:update": "node scripts/lint-ratchet.js --update",
     "test": "mocha",
@@ -96,7 +98,7 @@
     "test:browser": "echo 'Open tests/standalone-modules-test.html in browser for comprehensive testing'",
     "test:bundle": "echo 'Open tests/bundle-completeness-test.html in browser to verify bundle completeness'",
     "preimage:extract": "node examples/preimage/extract_preimage_bidirectional.js",
-    "prepublishOnly": "npm run build-all",
+    "prepublishOnly": "npm run build-all && npm run check:readme",
     "sync-cdn": "node scripts/sync-cdn-urls.js",
     "version": "node scripts/sync-cdn-urls.js && node scripts/sync-version.js && node scripts/gen-esm-wrapper.js && git add README.md docs version.js index.mjs",
     "test:browser:ci": "node tests/browser-smoke-runner.js"
@@ -231,9 +233,9 @@
     "request": "browser-request"
   },
   "dependencies": {
-    "@noble/ciphers": "2.2.0",
-    "@noble/curves": "2.2.0",
-    "@noble/hashes": "2.2.0",
+    "@noble/ciphers": "^2.3.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
     "bn.js": "=4.12.5",
     "secrets.js-grempe": "^2.0.0"
   },
@@ -277,7 +279,8 @@
       "beforeEach",
       "describe",
       "it",
-      "globalThis"
+      "globalThis",
+      "BigInt"
     ],
     "ignore": [
       "dist/**",