@smartledger/bsv 9.2.0 → 9.4.0

package/CHANGELOG.md

@@ -7,6 +7,139 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.4.0] - 2026-09-01
+
+### Fixed — `policy().lockUntil()` did not bind, and `OP_BIN2NUM` used the wrong era's width
+
+Two defects, found together because the second is what stops you fixing the first.
+
+#### `lockUntil` checked one third of a time lock
+
+The compiled script asserted `nLockTime >= floor` and nothing else. A time lock
+is three rules in the node's `CheckLockTime`, and the other two each have a spend
+that walks straight through:
+
+- **Sequence.** `IsFinalTx()` ignores `nLockTime` outright when every input is
+  `0xffffffff`. A spender who set a final sequence satisfied the script with the
+  very locktime it demanded and produced a transaction minable in the next block.
+  The honest `unlock()` helper set `0xfffffffe`, so the covenant looked correct
+  from inside — and the test that covered the early-locktime case set
+  `0xfffffffe` too, which is why nothing caught it.
+- **Units.** Consensus reads `nLockTime` below 500,000,000 as a block height and
+  at or above it as a unix timestamp. A bare `>=` compares the two as plain
+  numbers, so `1500000000 >= 900000` cleared a floor of block 900,000 with a
+  timestamp from July 2017 — a transaction that is final today.
+
+Both are now enforced in script: this input must be non-final, and a height floor
+requires the locktime to be a height. `describe()` reports both, and
+`lockUntil(0)` throws, since consensus reads 0 as "no lock" whatever the
+sequences are.
+
+This is the same defect that removed `Locks.timeLockCLTV` and `Locks.htlc` in
+9.0.0 — a time lock that enforces nothing — reappearing in the DSL that replaced
+them. There, the cause was Genesis reverting `OP_CHECKLOCKTIMEVERIFY` to a NOP.
+Here, it was reimplementing `CHECKLOCKTIMEVERIFY` by hand and reproducing only
+its comparison.
+
+#### `OP_BIN2NUM` capped every era at the pre-Genesis 4 bytes
+
+It range-checked its result with `_isMinimallyEncoded(buf)`, whose `nMaxNumSize`
+argument **defaults to 4**. The node passes `maxScriptNumLength`, which is 4
+before Genesis, 750,000 after it and 32,000,000 after Chronicle.
+
+Any unsigned field whose top byte has the sign bit set needs a fifth byte to read
+as positive, so this rejected:
+
+- **Every perpetual covenant and ownership token holding 21.47 BSV or more**
+  (2³¹ satoshis). Both read the preimage's 8-byte value field through
+  `OP_BIN2NUM`, so the coins were locked in and unspendable.
+- **Every `nLockTime` from 19 Jan 2038**, whose high bit is set.
+
+The node's own corpus did not catch it: all 25 of its `OP_BIN2NUM` vectors run
+under `P2SH,STRICTENC` alone — pre-Genesis, where 4 is the right answer either
+way. 1,483/1,483 passed before the fix and after it. The opcode was covered; the
+*era* was not, and era selection is where both of this library's consensus
+defects have been.
+
+`lockUntil` also needed this: `nLockTime` is unsigned and `OP_BIN2NUM` reads
+signed, so from 2038 the extracted value came back as negative zero and no spend
+could clear the floor. The fix is to sign-pad to five bytes first, and that push
+is only legal once `OP_BIN2NUM` honours the era.
+
+#### Upgrading
+
+`lockUntil` compiles different bytes, so a UTXO locked by 9.3.0 or earlier cannot
+be spent with a script compiled by this version — keep the compiled object, or
+recompile with the old version. Those locks bind nothing, so treat their coins as
+spendable by anyone and move them.
+
+## [9.3.0] - 2026-08-28
+
+### Added
+
+- **Type declarations for every subpath export.** Eleven of the thirteen
+  subpaths — `anchor`, `covenant`, `didweb`, `gdaf`, `ltp`, `script-helper`,
+  `security`, `shamir`, `smartcontract`, `statuslist`, `vcjwt` — shipped with no
+  `types` condition and no declaration file, so
+  `import covenant from '@smartledger/bsv/covenant'` was a TS7016 error under
+  `node16`/`nodenext` resolution and every symbol behind it was `any`. Each now
+  has a declaration; the eight that map onto existing declarations re-export
+  them, and `security` (`SmartMiner`) and `script-helper` (`CustomScriptHelper`)
+  are newly described, having had no types anywhere.
+- `scripts/check-types.js` and `npm run check:types`, wired into
+  `prepublishOnly`. It compiles a fixture of correct usage, then asserts that a
+  fixture of *misuse* still fails — a declaration that quietly degrades to `any`
+  makes those errors vanish, which is the regression this catches. Resolution
+  goes through the real `exports` map rather than tsconfig `paths`.
+- **`buildInscription` can write envelope fields.** `fields` takes tag numbers to
+  values and emits them between the content type and the body, in ascending tag
+  order so identical input always produces identical bytes. Tag 5 is `metadata`,
+  the spec's own home for an object's own record; it previously could not be
+  written at all, so the only way to produce one was to assemble envelope bytes by
+  hand — permanent, already paid for, and unreported by anything local.
+
+  Three tags are refused at build time because each is silent afterwards. Tag 0
+  opens the body, so a field there does not fail — it becomes part of the file.
+  Tag 1 is the content type, and a second one declares it twice. An unrecognized
+  EVEN tag costs the inscription its location everywhere: the spec requires such
+  an inscription to be treated as unbound. Odd tags are ignored by an indexer that
+  does not know them, which is why the spec says it is okay to be odd.
+
+  `allowUnknownEvenFields` overrides the last of those. It exists because the
+  named tag set grows with the protocol, and a library that could never be
+  overridden would eventually be wrong AND unbypassable — sending people back to
+  hand-assembled bytes, which is worse than what the check prevents.
+
+  Tags 1..16 are emitted as opcodes and anything larger as a minimal data push,
+  since OP_16 is the largest numeric opcode. Script numbers carry sign in the high
+  bit of the last byte, so a tag ending >= 0x80 is zero-padded rather than read
+  back negative. Verified by round-tripping through `@smartledger/ordinals`, a
+  separate implementation: a builder agreeing with its own parser proves only that
+  they agree.
+
+### Fixed
+
+- **`@types/node` is now a declared dependency.** `bsv.d.ts` carries
+  `/// <reference types="node" />` and names `Buffer` 150 times, but nothing
+  pulled the types in. A TypeScript consumer without `@types/node` installed got
+  `Buffer` widened to `any`, silently disabling type checking on every `Buffer`
+  parameter in the public API — `Anchor.sha256Hex(12345)` type-checked cleanly.
+- **`SECURITY.md` described a release line three majors old.** Corrected against
+  the code rather than edited in place; every claim below was verified:
+  - Supported versions said `6.x` on a 9.x package, and told readers to upgrade
+    to "the latest 6.x".
+  - The "known residual footgun" section warned that
+    `ECDSA.prototype.verify()` returns the truthy *instance* and is "slated for
+    removal in the next major". That was fixed in **7.0.0** — it returns a strict
+    boolean, `bsv.d.ts` types it `verify(): boolean`, and a contract test locks it
+    closed. The policy was warning about a landmine that no longer exists while
+    contradicting the package's own declarations.
+  - Pinned dependencies were listed as `bn.js@4.12.3` and `bs58@4.0.1`; the
+    actual pin is `bn.js@=4.12.5` and `bs58` is no longer a dependency at all.
+  - It apologised at length for "currently 17, all dev-only" `npm audit`
+    findings. `npm audit` now reports none, dev included.
+- `bsv.d.ts` header advertised "Type definitions for @smartledger/bsv 6.x".
+
 ## [9.2.0] - 2026-08-25
 
 ### Added — RFC 8785 canonicalization is now public API

package/README.md

@@ -2,7 +2,7 @@
 
 Bitcoin SV library with an interpreter-verified script engine.
 
-[![Version](https://img.shields.io/badge/version-9.2.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
+[![Version](https://img.shields.io/badge/version-9.4.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Stability](https://img.shields.io/badge/9.x%20stable%20until-2027--09--01-brightgreen.svg)](STABILITY.md)
 
@@ -155,44 +155,44 @@ const bsv = require('@smartledger/bsv')                 // 128 modules
 ### **Core Modules**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv.min.js** | 1042KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js` |
-| **bsv.bundle.js** | 1042KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.2.0/bsv.bundle.js` |
+| **bsv.min.js** | 1045KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js` |
+| **bsv.bundle.js** | 1045KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.4.0/bsv.bundle.js` |
 
 ### **W3C Verifiable Credentials**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-didweb.min.js` |
-| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-vcjwt.min.js` |
-| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-statuslist.min.js` |
-| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.2.0/bsv-anchor.min.js` |
+| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-didweb.min.js` |
+| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-vcjwt.min.js` |
+| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-statuslist.min.js` |
+| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.4.0/bsv-anchor.min.js` |
 
 ### **Smart Contract & Development**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-smartcontract.min.js** | 140KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.2.0/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.2.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.2.0/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.2.0/bsv-security.min.js` |
+| **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.4.0/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.4.0/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.4.0/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.4.0/bsv-security.min.js` |
 
 ### **Legal & Compliance**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ltp.min.js** | 539KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.2.0/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 1042KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.2.0/bsv-gdaf.min.js` |
+| **bsv-ltp.min.js** | 539KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.4.0/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1045KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.4.0/bsv-gdaf.min.js` |
 
 ### **Advanced Cryptography**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.2.0/bsv-shamir.min.js` |
+| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.4.0/bsv-shamir.min.js` |
 
 ### **Utilities**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.2.0/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.2.0/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.2.0/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.4.0/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.4.0/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.4.0/bsv-mnemonic.min.js` |
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.2.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.4.0/bsv.min.js"></script>
 <script>
   const key = bsv.PrivateKey.fromRandom()
 </script>
@@ -240,4 +240,4 @@ MIT
 
 ---
 
-**SmartLedger-BSV v9.2.0**
+**SmartLedger-BSV v9.4.0**

package/SECURITY.md

@@ -7,14 +7,15 @@ Thank you for helping keep `@smartledger/bsv` and its users safe.
 Security fixes are applied to the latest major release line. Earlier releases
 are not patched; please upgrade. **Versions < 6.0.0 contain four CRITICAL
 fail-open signature/verification bugs and a revocation-bypass (fixed in 6.0.0 —
-see CHANGELOG `## [6.0.0]`); upgrading to the latest 6.x is strongly recommended.**
+see CHANGELOG `## [6.0.0]`); upgrading to the latest 9.x is strongly recommended.**
 Requires **Node.js ≥ 20.19** (the audited crypto dependency `@noble/curves@2` is
 ESM-only).
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 6.x     | :white_check_mark: |
-| < 6.0   | :x: (fail-open verification + revocation-bypass; upgrade to 6.x) |
+| 9.x     | :white_check_mark: |
+| 6.x – 8.x | :x: (no longer patched; upgrade to 9.x) |
+| < 6.0   | :x: (fail-open verification + revocation-bypass; upgrade to 9.x) |
 
 The security model and the adversarial tests that enforce it are documented in
 [`docs/THREAT_MODEL.md`](./docs/THREAT_MODEL.md).
@@ -55,24 +56,18 @@ to remain anonymous.
   forgery, replay, or unauthorized revocation.
 - Bugs in BIP-143 preimage handling, covenant construction, or LTP/GDAF
   signing paths.
-- Supply-chain concerns about pinned runtime dependencies
-  (`bn.js@4.12.3`, `bs58@4.0.1`, `@noble/*`, etc.). The runtime dependency
-  tree carries **no known advisories** (`npm audit --omit=dev` is clean);
-  `elliptic` was dropped from the runtime/bundle path in 5.4.0.
+- Supply-chain concerns about the runtime dependencies: `@noble/ciphers`,
+  `@noble/curves`, `@noble/hashes`, `bn.js` (pinned exactly at `=4.12.5`), and
+  `secrets.js-grempe`. The runtime dependency tree carries **no known
+  advisories** (`npm audit --omit=dev` is clean); `elliptic` was dropped from
+  the runtime/bundle path in 5.4.0, and `bs58` is no longer a dependency.
 
 ## Out of Scope
 
-- Vulnerabilities in development-only dependencies (`webpack 5`, `esbuild`,
-  `standard 12`, `mocha`, `nyc`, `crypto-browserify`, etc.). These never reach
-  installers — the
-  published tarball ships no `node_modules` and none are listed under
-  `dependencies`. The remaining `npm audit` findings (currently 17, all
-  dev-only) are either upstream-blocked — `mocha`/`nyc` are already at their
-  latest releases but still range-pin affected transitives (`diff`,
-  `serialize-javascript`, nested `js-yaml`) — or require the deferred
-  `standard@17` lint migration (`eslint`/`inquirer`/`tmp` chain) and the
-  `crypto-browserify` browser-build chain. They are accepted dev-only risk and
-  tracked separately.
+- Vulnerabilities in development-only dependencies (`esbuild`, `standard`,
+  `mocha`, `nyc`, etc.). These never reach installers — the published tarball
+  ships no `node_modules` and none are listed under `dependencies`. `npm audit`
+  currently reports **no findings at all**, dev included.
 - Issues that require a malicious local environment (compromised Node, browser
   extension, or filesystem) to exploit.
 - Denial-of-service from intentionally malformed inputs that do **not** cross
@@ -100,11 +95,13 @@ return value (an ECDSA *instance*, a stub `{verified:true}`) as if it meant
   feeds each verify path a forged input and asserts rejection as a strict boolean
   or a throw. The CI suite is a merge gate.
 
-**Known residual footgun (mitigated).** `ECDSA.prototype.verify()` still returns
-the *instance* (truthy) with the result on `.verified` — a landmine if read as a
-boolean. It is retained for back-compat, typed to make misuse a compile error
-(`verify(): this` vs `verifyBool(): boolean` in `bsv.d.ts`), and pinned by a
-test; it is slated for **removal in the next major**. Prefer `verifyBool()`.
+**7.0.0 — the trap was closed.** `ECDSA.prototype.verify()` now returns a strict
+`boolean` rather than the ECDSA instance, so `if (ecdsa.verify())` can no longer
+read a truthy object as "valid". The result is still mirrored on `this.verified`;
+only the chained `.verify().verified` idiom is gone. `bsv.d.ts` types it as
+`verify(): boolean`, and a security-contract test locks it closed — a forgery
+must make `verify()` return `false`. `verifyBool()` remains as an explicit alias.
+See [`docs/MIGRATION_7.md`](docs/MIGRATION_7.md).
 
 See [`docs/THREAT_MODEL.md`](./docs/THREAT_MODEL.md) for the full property-by-
 property security model and the tests that enforce each claim, and the
@@ -115,6 +112,9 @@ property security model and the tests that enforce each claim, and the
 Significant security-relevant changes are documented in
 [`CHANGELOG.md`](./CHANGELOG.md). Recent entries of note:
 
+- **7.0.0** — `ECDSA.prototype.verify()` returns a strict `boolean` instead of the
+  (always truthy) ECDSA instance, removing the trap that made `if (ecdsa.verify())`
+  accept forged signatures. A security-contract test now enforces it.
 - **6.0.0** — fixed four CRITICAL fail-open verification bugs (the `ECDSA.verify()`
   returns-the-instance trap at three call sites plus a `//TODO` stub), a StatusList2021
   revocation bypass (unverified list bitstring), an ownership-forgery in

package/anchor-entry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hash anchoring — build and parse the OP_RETURN payload that commits a hash
+ * to chain, and check data against an anchored hash.
+ *
+ * Same surface as `require("@smartledger/bsv").Anchor`.
+ */
+import { Anchor } from '@smartledger/bsv';
+export = Anchor;