smartledger-bsv 3.4.0 → 3.4.4

package/README.md

@@ -2,15 +2,17 @@
 
 **🚀 Complete Bitcoin SV Development Framework with W3C Verifiable Credentials, DID:web, Legal Compliance, and 16 Flexible Loading Options**
 
-[![Version](https://img.shields.io/badge/version-3.4.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
+[![Version](https://img.shields.io/badge/version-3.4.4-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![BSV](https://img.shields.io/badge/BSV-Compatible-orange.svg)](https://bitcoinsv.com/)
 [![Modular](https://img.shields.io/badge/Loading-Modular-purple.svg)](#loading-options)
 [![W3C](https://img.shields.io/badge/W3C-Compliant-blueviolet.svg)](#verifiable-credentials)
 
-The most comprehensive and flexible Bitcoin SV library available. **NEW in v3.4.0**: Legally-recognizable DID:web + VC-JWT toolkit with ES256/ES256K support, StatusList2021 revocation, and BSV anchoring. Choose from 16 different distribution methods: standalone modules, complete bundle, or mix-and-match approach.
+The most comprehensive and flexible Bitcoin SV library available. **In v3.4.x**: Legally-recognizable DID:web + VC-JWT toolkit with ES256/ES256K support, StatusList2021 revocation, and BSV anchoring. Choose from 16 different distribution methods: standalone modules, complete bundle, or mix-and-match approach.
 
-## 🆕 **v3.4.0 - Legally-Recognizable Credentials**
+> **v3.4.1 (bugfix)**: credential bundles now actually ship to npm consumers, `prepublishOnly` builds the full set, and `Transaction.shuffleOutputs()` uses a CSPRNG. See [CHANGELOG](./CHANGELOG.md#341---2026-05-18).
+
+## 🆕 **v3.4.x - Legally-Recognizable Credentials**
 
 ### **Why This Matters**
 - ✅ **W3C Standards**: Full VC-JWT and DID:web compliance for legal recognition
@@ -23,8 +25,8 @@ The most comprehensive and flexible Bitcoin SV library available. **NEW in v3.4.
 ### **Quick Start - Issue Your First Verifiable Credential**
 
 ```bash
-# Install SmartLedger BSV v3.4.0
-npm install @smartledger/bsv@3.4.0
+# Install SmartLedger BSV v3.4.4
+npm install @smartledger/bsv@3.4.4
 
 # Initialize DID:web issuer (generates ES256 keys)
 npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -133,42 +135,42 @@ console.log('Status:', status) // 'revoked'
 ### **Core Modules**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv.min.js** | 449KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@3.4.0/bsv.min.js` |
-| **bsv.bundle.js** | 885KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.0/bsv.bundle.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.4/bsv.bundle.js` |
 
-### **🆕 W3C Verifiable Credentials (v3.4.0)**
+### **🆕 W3C Verifiable Credentials (v3.4.x)**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-didweb.min.js** | 418KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@3.4.0/bsv-didweb.min.js` |
-| **🟢 bsv-vcjwt.min.js** | 418KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@3.4.0/bsv-vcjwt.min.js` |
-| **🟢 bsv-statuslist.min.js** | 486KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@3.4.0/bsv-statuslist.min.js` |
-| **🟢 bsv-anchor.min.js** | 417KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@3.4.0/bsv-anchor.min.js` |
+| **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-didweb.min.js` |
+| **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-vcjwt.min.js` |
+| **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-statuslist.min.js` |
+| **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-anchor.min.js` |
 
 ### **Smart Contract & Development**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-smartcontract.min.js** | 451KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.4.0/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 32KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 27KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.0/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 290KB | Security enhancements | `unpkg.com/@smartledger/bsv@3.4.0/bsv-security.min.js` |
+| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.4.4/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.4/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.4/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@3.4.4/bsv-security.min.js` |
 
 ### **Legal & Compliance**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ltp.min.js** | 817KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@3.4.0/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 604KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@3.4.0/bsv-gdaf.min.js` |
+| **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@3.4.4/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@3.4.4/bsv-gdaf.min.js` |
 
 ### **Advanced Cryptography**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-shamir.min.js** | 433KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@3.4.0/bsv-shamir.min.js` |
+| **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@3.4.4/bsv-shamir.min.js` |
 
 ### **Utilities**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.0/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.0/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 670KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.0/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.4/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.4/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.4/bsv-mnemonic.min.js` |
 
 ## ⚡ **2-Minute Quick Start**
 
@@ -179,10 +181,10 @@ Get started with Bitcoin SV development in under 2 minutes:
 npm install @smartledger/bsv
 
 # Or include in HTML
-<script src="https://unpkg.com/@smartledger/bsv@3.4.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
 ```
 
-> **🔧 v3.4.0 Update:** Added legally-recognizable W3C Verifiable Credentials with DID:web + VC-JWT toolkit. ES256/ES256K support, StatusList2021 revocation, and privacy-preserving BSV anchoring. Complete CLI tooling included!
+> **🔧 v3.4.x:** Legally-recognizable W3C Verifiable Credentials with DID:web + VC-JWT toolkit. ES256/ES256K support, StatusList2021 revocation, and privacy-preserving BSV anchoring. Complete CLI tooling included! v3.4.1 ensures these bundles ship to npm consumers; see CHANGELOG.
 
 **Basic Transaction (30 seconds):**
 ```javascript
@@ -247,7 +249,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 - 🌐 [Digital Identity Guide](docs/GDAF_DIGITAL_ATTESTATION_GUIDE.md)
 - � [Threshold Cryptography Guide](docs/SHAMIR_SECRET_SHARING_GUIDE.md)
 - �️ [UTXO Manager Guide](docs/UTXO_MANAGER_GUIDE.md)
-- 💡 [Examples Directory](examples/)
+- 💡 [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
 
 ## 🔧 **API Reference**
 
@@ -265,28 +267,28 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 | **Debug Tools** | `SmartContract.examineStack()` | Analyze script | `SmartContract.examineStack(script)` |
 | | `interpretScript()` | Execute script | `SmartContract.interpretScript(script)` |
 | | `getScriptMetrics()` | Performance data | `SmartContract.getScriptMetrics(script)` |
-| **Security** | `SmartVerify.verify()` | Enhanced verification | `SmartVerify.verify(sig, hash, pubkey)` |
-| | `EllipticFixed.sign()` | Secure signing | `EllipticFixed.sign(hash, privateKey)` |
+| **Security (opt-in)** | `SmartVerify.verify()` | Hardened verify with strict input validation — call explicitly; default `signature.verify()` does NOT route through this | `SmartVerify.verify(sig, hash, pubkey)` |
+| | `EllipticFixed.sign()` | Canonicalized signing wrapper around elliptic | `EllipticFixed.sign(hash, privateKey)` |
 
 > 💡 **Tip:** All methods include comprehensive error handling and validation. See [documentation links](#documentation) for detailed guides.
 
 ## 📚 **Quick Start Examples**
 
-### 🔧 **Basic Development** (476KB total)
+### 🔧 **Basic Development** (~963KB total)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-script-helper.min.js"></script>
 <script>
   const privateKey = new bsv.PrivateKey();
   const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
 </script>
 ```
 
-### 🔒 **Smart Contract Development** (932KB total)
+### 🔒 **Smart Contract Development** (~2.7MB total — each bundle re-embeds core BSV)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-smartcontract.min.js"></script>
 <script>
   const covenant = bsv.SmartContract.createCovenantBuilder()
     .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -294,11 +296,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 </script>
 ```
 
-### 🆕 **Legal & Identity Development** (1.87MB total)
+### 🆕 **Legal & Identity Development** (~3.2MB total — each bundle re-embeds core BSV)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-gdaf.min.js"></script>
 <script>
   // Legal Token Protocol
   const propertyToken = bsv.createPropertyToken({
@@ -310,11 +312,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 </script>
 ```
 
-### 🆕 **Security & Cryptography** (1.17MB total)
+### 🆕 **Security & Cryptography** (~1.4MB total)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-shamir.min.js"></script>
 <script>
   // Threshold Cryptography
   const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -324,9 +326,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 </script>
 ```
 
-### 🎯 **Everything Bundle** (885KB)
+### 🎯 **Everything Bundle** (937KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.bundle.js"></script>
 <script>
   // Everything available immediately
   const shares = bsv.splitSecret('secret', 5, 3);           // Shamir Secret Sharing
@@ -346,7 +348,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ### 💼 **Core Library Excellence**
 - ✅ **Complete BSV API**: Full Bitcoin SV blockchain operations → [API Reference](#api-reference)  
-- ✅ **Security Hardened**: SmartLedger elliptic curve fixes and enhanced validation → [Security Features](#security-features)
+- ✅ **Opt-in security helpers**: `bsv.SmartVerify` and `bsv.EllipticFixed` add input validation and low-`s` canonicalization on top of standard verification — **not on the default verify path**, see [Security](#-security)
 - ✅ **Browser + Node.js**: Universal compatibility with proper polyfills → [Loading Options](#12-loading-options--choose-your-approach)
 - ✅ **TypeScript Ready**: Complete type definitions included
 - ✅ **Ultra-Low Fees**: 0.01 sats/byte configuration (91% fee reduction)
@@ -354,14 +356,14 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 ### 🛠️ **Advanced Development Tools**
 - 🔧 **JavaScript-to-Script**: High-level covenant development with 121 opcode mapping → [Covenant Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
 - 🔧 **UTXO Generator**: Create authentic test UTXOs for development → [UTXO Guide](docs/UTXO_MANAGER_GUIDE.md)
-- 🔧 **Preimage Parser**: Complete BIP-143 field extraction and manipulation → [Preimage Tools](examples/preimage/)
-- � **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](tests/smartcontract-test.html)
+- 🔧 **Preimage Parser**: Complete BIP-143 field extraction and manipulation → [Preimage Tools](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/preimage)
+- � **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
 - � **PUSHTX Integration**: nChain techniques for advanced covenant patterns → [PUSHTX Insights](docs/pushtx-key-insights.md)
 
 ### 📦 **Flexible Architecture** 
-- 📦 **12 Modular Options**: Load only what you need (27KB to 885KB) → [Loading Strategy](#loading-strategy-examples)
-- 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](tests/standalone-modules-test.html)
-- 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](tests/bundle-demo.html)
+- 📦 **16 Modular Options**: Load only what you need (26KB to 1184KB) → [Loading Strategy](#loading-strategy-examples)
+- 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/standalone-modules-test.html)
+- 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/bundle-demo.html)
 - 📦 **CDN Ready**: All modules available via unpkg and jsDelivr
 - 📦 **Webpack Optimized**: Tree-shakeable and build-tool friendly
 
@@ -404,21 +406,21 @@ const contractTx = covenant.createCovenantTransaction({
 
 ### Browser CDN (Choose Your Loading Strategy)
 
-#### 1. **Minimal Setup** - Core + Script Helper (476KB)
+#### 1. **Minimal Setup** - Core + Script Helper (~963KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-script-helper.min.js"></script>
 <script>
   const tx = new bsv.Transaction();
   const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
 </script>
 ```
 
-#### 2. **DeFi Development** - Core + Covenants + Debug (932KB)
+#### 2. **DeFi Development** - Core + Covenants + Debug (~2.7MB — each bundle re-embeds core BSV)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-smartcontract.min.js"></script>
 <script>
   const covenant = new bsvCovenant.CovenantInterface();
   const debugInfo = SmartContract.interpretScript(script);
@@ -426,19 +428,19 @@ const contractTx = covenant.createCovenantTransaction({
 </script>
 ```
 
-#### 3. **Security First** - Core + Enhanced Security (739KB)
+#### 3. **Security First** - Core + Enhanced Security (~963KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-security.min.js"></script>
 <script>
   const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
   const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
 </script>
 ```
 
-#### 4. **Everything Bundle** - One File Solution (764KB)
+#### 4. **Everything Bundle** - One File Solution (937KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.bundle.js"></script>
 <script>
   // Everything available under bsv namespace
   const keys = bsv.SmartLedgerBundle.generateKeys();
@@ -696,11 +698,37 @@ const timelockScript = helper.createTimelockScript(
 
 ## 🔐 Security
 
-### Enhanced Security Features
-- **Elliptic Curve Fix**: Updated to secure elliptic@6.6.1
-- **Parameter Fixing**: Public key, ephemeral key, sighash flag validation
-- **DER Canonicalization**: Transaction malleability prevention  
-- **Preimage Validation**: Complete BIP143 structure verification
+### What's actually in the box
+
+| Surface | Status | Notes |
+|---------|--------|-------|
+| `elliptic@6.6.1` (pinned) | upstream-patched | All known CVEs through 6.6.1 are fixed by elliptic itself. SmartLedger does not patch elliptic's source. |
+| Default `transaction.verify()` / `signature.verify()` / `Message().verify()` | uses BSV's own `lib/crypto/ecdsa.js` | This path does **not** import elliptic and is **not** routed through `SmartVerify` or `EllipticFixed`. |
+| `bsv.SmartVerify` (opt-in helper) | available | Hardened standalone verify: rejects `r=0`, `s=0`, `r≥n`, `s≥n`; canonicalizes `s` to low half. Built on BSV's own `BN`/`ECDSA`. You must call it explicitly. |
+| `bsv.EllipticFixed` (opt-in helper) | available | Wraps the elliptic `secp256k1` instance with the same input checks + low-`s` on sign. Only matters if you use elliptic directly. |
+| `signature.validate()` / `isCanonical()` / `toCanonical()` | available | Real methods on `bsv.Signature`. |
+| DER canonicalization on TX signing | available | BSV's signature path produces low-`s` DER by default. |
+| BIP143 preimage utilities | available | `lib/smart_contract/preimage.js` and `examples/preimage/`. |
+
+### Using the opt-in helpers
+
+```js
+const bsv = require('@smartledger/bsv')
+
+// Hardened verify (recommended if you accept signatures from untrusted sources):
+const ok = bsv.SmartVerify.smartVerify(msgHashBuffer, derSigBuffer, publicKey)
+
+// Or call BSV's own ECDSA via the standard API (no SmartVerify hardening):
+const okDefault = bsv.crypto.ECDSA.verify(msgHashBuffer, signature, publicKey)
+```
+
+### What this library does **not** claim
+
+- It does not silently route every `verify()` call through `SmartVerify`. If you want the strict input validation on every verification, call `SmartVerify` explicitly or wrap `bsv.Signature.prototype.verify`.
+- It does not patch the elliptic library's source — the patches in `lib/crypto/elliptic-fixed.js` add input validation on top of an already-upstream-patched `elliptic@6.6.1`.
+- It does not turn `bsv.isHardened = true` into an automatic guarantee. That property indicates the hardening helpers ship; whether they're used is up to your code.
+
+A planned 3.5.0 will offer an opt-in flag to route the default verify path through `SmartVerify` so the protection is on by default for new users.
 
 ## 📝 Changelog
 
@@ -749,18 +777,18 @@ const timelockScript = helper.createTimelockScript(
 
 ### 🔧 **Technical Resources**
 - **[SmartContract Integration](SMARTCONTRACT_INTEGRATION.md)** - Debug tools and analysis
-- **[Examples Directory](examples/)** - Working code samples
-- **[Test Suite](tests/)** - Comprehensive testing examples
+- **[Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)** - Working code samples
+- **[Test Suite](https://github.com/codenlighten/smartledger-bsv/tree/main/tests)** - Comprehensive testing examples
 - **[Build System](build/)** - Webpack configurations
 
 ### 🌐 **Loading Strategy Examples**
 
 | **Use Case** | **Recommended Load** | **Size** | **Features** |
 |--------------|---------------------|----------|--------------|
-| **Simple Transactions** | `bsv.min.js` | 449KB | Core BSV + SmartContract |
-| **DeFi Development** | Core + Covenant + Debug | 932KB | Advanced contracts + tools |
-| **Enterprise Apps** | `bsv.bundle.js` | 764KB | Everything included |
-| **Mobile/Lightweight** | Core + Script Helper | 476KB | Essential tools only |
+| **Simple Transactions** | `bsv.min.js` | 937KB | Core BSV + SmartContract |
+| **DeFi Development** | Core + Covenant + Debug | ~2.7MB | Advanced contracts + tools (bundles re-embed core BSV) |
+| **Enterprise Apps** | `bsv.bundle.js` | 937KB | Everything included |
+| **Mobile/Lightweight** | Core + Script Helper | ~963KB | Essential tools only |
 | **Research/Analysis** | Core + SmartContract | 900KB | Full debug capabilities |
 
 ### 🔗 **Cross-References**
@@ -771,19 +799,19 @@ const timelockScript = helper.createTimelockScript(
 - [API Reference](#api-reference) → [Method Documentation](docs/)
 
 **From Examples → Implementation:**
-- [Covenant Examples](examples/covenants/) → [Production Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
-- [Script Examples](examples/scripts/) → [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
-- [Test Files](tests/) → [Integration Examples](examples/)
+- [Covenant Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) → [Production Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
+- [Script Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/scripts) → [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
+- [Test Files](https://github.com/codenlighten/smartledger-bsv/tree/main/tests) → [Integration Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
 
 **From Concepts → Code:**
-- [PUSHTX Theory](docs/pushtx-key-insights.md) → [Covenant Implementation](examples/covenants/advanced_covenant_demo.js)
+- [PUSHTX Theory](docs/pushtx-key-insights.md) → [Covenant Implementation](https://github.com/codenlighten/smartledger-bsv/blob/main/examples/covenants/advanced_covenant_demo.js)
 - [Security Features](#smart-security) → [Implementation](lib/crypto/smartledger_verify.js)
-- [Debug Tools](#debug-tools) → [Usage Examples](tests/smartcontract-test.html)
+- [Debug Tools](#debug-tools) → [Usage Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
 
 ### 🎓 **Learning Path**
 
 1. **Start**: [2-Minute Quick Start](#2-minute-quick-start)
-2. **Practice**: [Examples Directory](examples/) 
+2. **Practice**: [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples) 
 3. **Build**: [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
 4. **Advanced**: [Covenant Development](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
 5. **Deploy**: [Production Guidelines](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
@@ -811,11 +839,11 @@ const timelockScript = helper.createTimelockScript(
 - [🔧 **Integration Guide**](SMARTCONTRACT_INTEGRATION.md) - Smart contract integration
 
 ### 📋 **Examples & Demos**
-- [� **Interactive Demos**](demos/) - **NEW!** HTML & Node.js smart contract demos
-- [�📁 **Examples Directory**](examples/) - Working code examples
-- [🎯 **Basic Examples**](examples/basic/) - Simple transactions & addresses
-- [🔒 **Covenant Examples**](examples/covenants/) - Smart contract patterns  
-- [📊 **Advanced Examples**](examples/covenants2/) - Production patterns
+- [� **Interactive Demos**](https://github.com/codenlighten/smartledger-bsv/tree/main/demos) - **NEW!** HTML & Node.js smart contract demos
+- [�📁 **Examples Directory**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples) - Working code examples
+- [🎯 **Basic Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/basic) - Simple transactions & addresses
+- [🔒 **Covenant Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) - Smart contract patterns  
+- [📊 **Advanced Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants2) - Production patterns
 
 **🎮 Try the Interactive Demos:**
 ```bash

package/SECURITY.md

@@ -0,0 +1,88 @@
+# Security Policy
+
+Thank you for helping keep `@smartledger/bsv` and its users safe.
+
+## Supported Versions
+
+Security fixes are applied to the latest minor release line. Earlier releases
+are not patched; please upgrade.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 3.4.x   | :white_check_mark: |
+| < 3.4   | :x:                |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues,
+discussions, or pull requests.**
+
+Report privately via either of:
+
+- **GitHub Security Advisories** (preferred):
+  <https://github.com/codenlighten/smartledger-bsv/security/advisories/new>
+- **Email:** `hello@smartledger.technology`
+
+When reporting, please include as much of the following as you can:
+
+- Affected version(s) and platform (Node.js version, browser, CDN vs. npm)
+- A minimal reproduction (code snippet, transaction hex, or test vector)
+- Impact assessment — what an attacker can do with the bug
+- Any suggested mitigation
+
+We aim to acknowledge new reports within **3 business days** and to provide a
+remediation timeline within **10 business days**. Coordinated disclosure is
+appreciated; we will credit reporters in the release notes unless you prefer
+to remain anonymous.
+
+## In Scope
+
+- Cryptographic correctness bugs in `lib/crypto/` (ECDSA, BN, Hash, Random,
+  Point, Signature, Shamir).
+- Signature/transaction malleability or forgery affecting the default verify
+  path (`lib/crypto/ecdsa.js`) or the opt-in helpers (`SmartVerify`,
+  `EllipticFixed`).
+- Key-generation, HD-derivation (BIP-32), or mnemonic (BIP-39) flaws that
+  weaken entropy or leak material.
+- Issues in DID:web, VC-JWT, StatusList2021, or Anchor modules that allow
+  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
+  (`elliptic@6.6.1`, `bn.js@4.11.9`, `bs58@4.0.1`, etc.).
+
+## Out of Scope
+
+- Vulnerabilities in development-only dependencies (`webpack 4`, `standard 12`,
+  `mocha 8`, etc.). These are tracked separately and addressed in the planned
+  3.5.0 toolchain upgrade.
+- 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
+  a trust boundary (e.g., feeding garbage to a library function in your own
+  process and observing it throw).
+- Stylistic, naming, or documentation issues unrelated to security claims —
+  please open a regular issue or PR for those.
+
+## Security Posture
+
+`@smartledger/bsv` ships **opt-in** hardening helpers — `bsv.SmartVerify`,
+`bsv.EllipticFixed`, and `signature.toCanonical()` — that you must call
+explicitly. The default `transaction.verify()` / `signature.verify()` /
+`Message().verify()` paths use BSV's own pure-JS ECDSA in
+`lib/crypto/ecdsa.js` and are **not** routed through `SmartVerify`.
+
+See the [Security section of the README](./README.md#-security) for the full
+"what's in the box" table and usage examples for the opt-in helpers. A
+planned 3.5.0 will offer an opt-in flag to route the default verify path
+through `SmartVerify` so the protection is on by default for new users.
+
+## Disclosure History
+
+Significant security-relevant changes are documented in
+[`CHANGELOG.md`](./CHANGELOG.md). Recent entries of note:
+
+- **3.4.2 / 3.4.3** — corrected documentation overclaims about which
+  hardening is on by default vs. opt-in.
+- **3.4.1** — `Transaction.shuffleOutputs()` now draws entropy from
+  `bsv.crypto.Random` (CSPRNG) instead of `Math.random`.

package/bin/cli.js

@@ -8,6 +8,7 @@
 
 var fs = require('fs')
 var path = require('path')
+var pkg = require('../package.json')
 var didweb = require('../lib/didweb')
 var vcjwt = require('../lib/vcjwt')
 var statuslist = require('../lib/statuslist')
@@ -43,8 +44,13 @@ function writeJsonFile(filepath, data) {
 }
 
 async function main() {
-  if (!command) {
-    console.log('SmartLedger BSV CLI v3.4.0')
+  if (command === '--version' || command === '-v') {
+    console.log(pkg.version)
+    process.exit(0)
+  }
+
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    console.log('SmartLedger BSV CLI v' + pkg.version)
     console.log('')
     console.log('Usage:')
     console.log('  smartledger-bsv didweb <subcommand> [options]')
@@ -205,15 +211,14 @@ async function handleVc(subcommand, opts) {
     
     console.error('Verifying credential...')
     
-    // Simple resolver that reads from .well-known
-    var didResolver = async function(did) {
-      var domain = did.replace('did:web:', '').replace(/%3A/g, ':')
+    // Simple resolver that reads from .well-known. lib/vcjwt expects
+    // `{ jwks: { keys: [...] } }`; jwks.json on disk is the raw JWKS,
+    // so wrap it.
+    var didResolver = async function (did) {
       var jwksPath = path.join(process.cwd(), '.well-known', 'jwks.json')
-      
       if (fs.existsSync(jwksPath)) {
-        return readJsonFile(jwksPath)
+        return { jwks: readJsonFile(jwksPath) }
       }
-      
       throw new Error('Cannot resolve DID: ' + did)
     }