@smartledger/bsv 3.3.5 → 3.4.0

package/README.md

@@ -1,47 +1,174 @@
 # SmartLedger-BSV
 
-**🚀 Complete Bitcoin SV Development Framework with Legal Compliance, Digital Identity, and 12 Flexible Loading Options**
+**🚀 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.3.4-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
+[![Version](https://img.shields.io/badge/version-3.4.0-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. Choose from 12 different distribution methods: standalone modules, complete bundle, or mix-and-match approach. Perfect for everything from simple transactions to complex DeFi protocols, smart contracts, legal tokenization, digital identity, and threshold cryptography.
+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.
 
-## 🎯 **12 Loading Options - Choose Your Approach**
+## 🆕 **v3.4.0 - Legally-Recognizable Credentials**
+
+### **Why This Matters**
+- ✅ **W3C Standards**: Full VC-JWT and DID:web compliance for legal recognition
+- ✅ **Enterprise Ready**: ES256 (P-256 NIST curve) for regulated industries
+- ✅ **Blockchain Native**: ES256K (secp256k1) for BSV integration
+- ✅ **Revocation Built-in**: StatusList2021 standard for credential management
+- ✅ **Privacy Preserving**: Hash-only BSV anchoring (no PII on-chain)
+- ✅ **CLI Tools**: Complete command-line interface for credential operations
+
+### **Quick Start - Issue Your First Verifiable Credential**
+
+```bash
+# Install SmartLedger BSV v3.4.0
+npm install @smartledger/bsv@3.4.0
+
+# Initialize DID:web issuer (generates ES256 keys)
+npx smartledger-bsv didweb init --domain example.com --alg ES256
+
+# Issue a credential
+npx smartledger-bsv vc issue \
+  --issuer did:web:example.com \
+  --subject did:example:alice \
+  --types "VerifiableCredential,DriversLicense" \
+  --claims '{"licenseNumber":"DL123456","class":"C"}' \
+  > credential.jwt
+
+# Verify the credential
+npx smartledger-bsv vc verify credential.jwt
+
+# Anchor hash to BSV (privacy-preserving)
+npx smartledger-bsv anchor hash credential.jwt
+
+# Create revocation list
+npx smartledger-bsv status create --issuer did:web:example.com > status-list.jwt
+
+# Revoke a credential
+npx smartledger-bsv status set --list status-list.jwt --index 42 --status revoked
+```
+
+### **Programmatic Usage**
+
+```javascript
+const bsv = require('@smartledger/bsv')
+
+// Generate DID:web issuer keys
+const keys = await bsv.DIDWeb.generateIssuerKeys({ alg: 'ES256' })
+
+// Build DID documents (.well-known/did.json and jwks.json)
+const docs = bsv.DIDWeb.buildDidWebDocuments({
+  domain: 'example.com',
+  p256: { jwk: keys.publicJwk, kid: keys.kid },
+  controllerName: 'Example Corp'
+})
+// Deploy docs.didDocument to https://example.com/.well-known/did.json
+// Deploy docs.jwks to https://example.com/.well-known/jwks.json
+
+// Issue a Verifiable Credential as JWT
+const result = await bsv.VcJwt.issueVcJwt({
+  issuerDid: docs.did,
+  subjectId: 'did:example:alice',
+  types: ['VerifiableCredential', 'AgeCredential'],
+  credentialSubject: {
+    ageOver: 18,
+    country: 'US'
+  },
+  privateJwk: keys.privateJwk,
+  alg: 'ES256',
+  kid: keys.kid
+})
+
+console.log('VC-JWT:', result.jwt)
+
+// Verify the credential
+const verification = await bsv.VcJwt.verifyVcJwt(result.jwt, {
+  didResolver: async (did) => {
+    // In production, fetch https://example.com/.well-known/jwks.json
+    return { jwks: docs.jwks }
+  },
+  expectedIssuerDid: docs.did
+})
+
+console.log('Valid:', verification.valid)
+
+// Anchor hash to BSV (no PII on-chain)
+const hash = bsv.Anchor.sha256Hex(result.jwt)
+const anchorPayload = bsv.Anchor.buildAnchorPayload({
+  kind: 'VC_ANCHOR_SHA256',
+  hash: hash,
+  issuerDid: docs.did
+})
+
+// Include anchorPayload.json in OP_RETURN
+// Later: verify with bsv.Anchor.verifyAnchorHash(originalData, anchorHash)
+
+// Create revocation list (100k credentials)
+const statusList = await bsv.StatusList.createStatusList({
+  issuerDid: docs.did,
+  privateJwk: keys.privateJwk
+})
+
+// Revoke a credential
+const updated = await bsv.StatusList.updateStatusList({
+  listVcJwt: statusList.listVcJwt,
+  index: 42,
+  status: 'revoked',
+  privateJwk: keys.privateJwk
+})
+
+// Check revocation status
+const status = bsv.StatusList.getCredentialStatusEntry({
+  listVcJwt: updated.listVcJwt,
+  index: 42
+})
+
+console.log('Status:', status) // 'revoked'
+```
+
+## 🎯 **16 Loading Options - Choose Your Approach**
 
 ### **Core Modules**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv.min.js** | 449KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js` |
-| **bsv.bundle.js** | 885KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.3.4/bsv.bundle.js` |
+| **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` |
+
+### **🆕 W3C Verifiable Credentials (v3.4.0)**
+| 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` |
 
 ### **Smart Contract & Development**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-smartcontract.min.js** | 451KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.3.4/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 32KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.3.4/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 27KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.3.4/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 290KB | Security enhancements | `unpkg.com/@smartledger/bsv@3.3.4/bsv-security.min.js` |
+| **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` |
 
-### **🆕 Legal & Compliance**
+### **Legal & Compliance**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-ltp.min.js** | 817KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@3.3.4/bsv-ltp.min.js` |
-| **🟢 bsv-gdaf.min.js** | 604KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@3.3.4/bsv-gdaf.min.js` |
+| **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` |
 
-### **🆕 Advanced Cryptography**
+### **Advanced Cryptography**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-shamir.min.js** | 433KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@3.3.4/bsv-shamir.min.js` |
+| **bsv-shamir.min.js** | 433KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@3.4.0/bsv-shamir.min.js` |
 
 ### **Utilities**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.3.4/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.3.4/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 670KB | HD wallets | `unpkg.com/@smartledger/bsv@3.3.4/bsv-mnemonic.min.js` |
+| **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` |
 
 ## ⚡ **2-Minute Quick Start**
 
@@ -52,10 +179,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.3.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.0/bsv.min.js"></script>
 ```
 
-> **🔧 v3.3.4 Update:** Fixed critical browser compatibility issue with mnemonic generation. CDN users can now use HD wallet and mnemonic functionality without `createHmac` errors!
+> **🔧 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!
 
 **Basic Transaction (30 seconds):**
 ```javascript

package/anchor-entry.js

@@ -0,0 +1 @@
+module.exports = require('./lib/anchor')

package/bin/cli.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * SmartLedger BSV CLI
+ * Command-line tools for DID:web, VC-JWT, and StatusList2021
+ */
+
+var fs = require('fs')
+var path = require('path')
+var didweb = require('../lib/didweb')
+var vcjwt = require('../lib/vcjwt')
+var statuslist = require('../lib/statuslist')
+var anchor = require('../lib/anchor')
+
+var args = process.argv.slice(2)
+var command = args[0]
+var subcommand = args[1]
+
+// Helper to parse command-line arguments
+function parseArgs(args) {
+  var opts = {}
+  for (var i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      var key = args[i].slice(2)
+      var value = args[i + 1]
+      opts[key] = value
+      i++
+    }
+  }
+  return opts
+}
+
+// Helper to read JSON file
+function readJsonFile(filepath) {
+  var content = fs.readFileSync(filepath, 'utf8')
+  return JSON.parse(content)
+}
+
+// Helper to write JSON file
+function writeJsonFile(filepath, data) {
+  fs.writeFileSync(filepath, JSON.stringify(data, null, 2))
+}
+
+async function main() {
+  if (!command) {
+    console.log('SmartLedger BSV CLI v3.4.0')
+    console.log('')
+    console.log('Usage:')
+    console.log('  smartledger-bsv didweb <subcommand> [options]')
+    console.log('  smartledger-bsv vc <subcommand> [options]')
+    console.log('  smartledger-bsv status <subcommand> [options]')
+    console.log('  smartledger-bsv anchor <subcommand> [options]')
+    console.log('')
+    console.log('DID:web Commands:')
+    console.log('  didweb init --domain <domain> [--alg ES256|ES256K]')
+    console.log('  didweb rotate --domain <domain> --key <key-file>')
+    console.log('')
+    console.log('VC Commands:')
+    console.log('  vc issue --issuer <did> --subject <did> --types <types> --claims <json>')
+    console.log('  vc verify <jwt-file>')
+    console.log('')
+    console.log('Status List Commands:')
+    console.log('  status create --issuer <did>')
+    console.log('  status set --list <file> --index <n> --status <revoked|suspended|valid>')
+    console.log('  status check --list <file> --index <n>')
+    console.log('')
+    console.log('Anchor Commands:')
+    console.log('  anchor hash <data-file>')
+    console.log('  anchor build --kind <type> --hash <hash> --issuer <did>')
+    process.exit(0)
+  }
+
+  var opts = parseArgs(args.slice(2))
+
+  try {
+    if (command === 'didweb') {
+      await handleDidWeb(subcommand, opts)
+    } else if (command === 'vc') {
+      await handleVc(subcommand, opts)
+    } else if (command === 'status') {
+      await handleStatus(subcommand, opts)
+    } else if (command === 'anchor') {
+      await handleAnchor(subcommand, opts)
+    } else {
+      console.error('Unknown command:', command)
+      process.exit(1)
+    }
+  } catch (error) {
+    console.error('Error:', error.message)
+    process.exit(1)
+  }
+}
+
+async function handleDidWeb(subcommand, opts) {
+  if (subcommand === 'init') {
+    if (!opts.domain) {
+      console.error('--domain is required')
+      process.exit(1)
+    }
+
+    var alg = opts.alg || 'ES256'
+    console.error('Generating ' + alg + ' keys for domain: ' + opts.domain)
+
+    // Generate keys
+    var keys = await didweb.generateIssuerKeys({ alg: alg })
+    
+    // Build DID documents
+    var docs = didweb.buildDidWebDocuments({
+      domain: opts.domain,
+      p256: alg === 'ES256' ? { jwk: keys.publicJwk, kid: keys.kid } : undefined,
+      k1: alg === 'ES256K' ? { jwk: keys.publicJwk, kid: keys.kid } : undefined,
+      controllerName: opts.name || 'SmartLedger Issuer'
+    })
+
+    // Create .well-known directory
+    var wellKnownDir = path.join(process.cwd(), '.well-known')
+    if (!fs.existsSync(wellKnownDir)) {
+      fs.mkdirSync(wellKnownDir, { recursive: true })
+    }
+
+    // Write did.json
+    var didPath = path.join(wellKnownDir, 'did.json')
+    writeJsonFile(didPath, docs.didDocument)
+    console.error('✅ Created:', didPath)
+
+    // Write jwks.json
+    var jwksPath = path.join(wellKnownDir, 'jwks.json')
+    writeJsonFile(jwksPath, docs.jwks)
+    console.error('✅ Created:', jwksPath)
+
+    // Write private key to secure file
+    var keyPath = path.join(process.cwd(), 'issuer-key-' + keys.kid + '.json')
+    writeJsonFile(keyPath, {
+      kid: keys.kid,
+      alg: keys.alg,
+      privateJwk: keys.privateJwk,
+      publicJwk: keys.publicJwk,
+      did: docs.did
+    })
+    console.error('✅ Created private key:', keyPath)
+    console.error('⚠️  KEEP THIS FILE SECURE AND ENCRYPTED!')
+    
+    console.error('')
+    console.error('DID:', docs.did)
+    console.error('')
+    console.error('Next steps:')
+    console.error('1. Host .well-known/did.json and .well-known/jwks.json at https://' + opts.domain)
+    console.error('2. Encrypt and securely store ' + keyPath)
+    console.error('3. Issue credentials with: smartledger-bsv vc issue ...')
+
+  } else if (subcommand === 'rotate') {
+    console.error('Key rotation coming soon')
+  } else {
+    console.error('Unknown didweb subcommand:', subcommand)
+    process.exit(1)
+  }
+}
+
+async function handleVc(subcommand, opts) {
+  if (subcommand === 'issue') {
+    if (!opts.issuer || !opts.subject || !opts.claims) {
+      console.error('--issuer, --subject, and --claims are required')
+      process.exit(1)
+    }
+
+    // Load issuer key
+    var keyFile = opts.key || 'issuer-key.json'
+    if (!fs.existsSync(keyFile)) {
+      console.error('Issuer key file not found:', keyFile)
+      console.error('Use --key to specify the key file')
+      process.exit(1)
+    }
+
+    var keyData = readJsonFile(keyFile)
+    var claims = JSON.parse(opts.claims)
+    var types = opts.types ? opts.types.split(',') : ['VerifiableCredential']
+
+    console.error('Issuing credential...')
+    console.error('  Issuer:', opts.issuer)
+    console.error('  Subject:', opts.subject)
+    console.error('  Types:', types.join(', '))
+
+    var result = await vcjwt.issueVcJwt({
+      issuerDid: opts.issuer,
+      subjectId: opts.subject,
+      types: types,
+      credentialSubject: claims,
+      privateJwk: keyData.privateJwk,
+      alg: keyData.alg || 'ES256',
+      kid: keyData.kid
+    })
+
+    console.log(result.jwt)
+    console.error('✅ Credential issued successfully')
+
+  } else if (subcommand === 'verify') {
+    var jwtFile = opts.jwt || args[2]
+    if (!jwtFile) {
+      console.error('JWT file required')
+      process.exit(1)
+    }
+
+    var jwt = fs.readFileSync(jwtFile, 'utf8').trim()
+    
+    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, ':')
+      var jwksPath = path.join(process.cwd(), '.well-known', 'jwks.json')
+      
+      if (fs.existsSync(jwksPath)) {
+        return readJsonFile(jwksPath)
+      }
+      
+      throw new Error('Cannot resolve DID: ' + did)
+    }
+
+    var result = await vcjwt.verifyVcJwt(jwt, { didResolver: didResolver })
+    
+    if (result.valid) {
+      console.error('✅ Credential is VALID')
+      console.log(JSON.stringify(result.payload, null, 2))
+    } else {
+      console.error('❌ Credential is INVALID')
+      console.error('Error:', result.error)
+      process.exit(1)
+    }
+
+  } else {
+    console.error('Unknown vc subcommand:', subcommand)
+    process.exit(1)
+  }
+}
+
+async function handleStatus(subcommand, opts) {
+  if (subcommand === 'create') {
+    if (!opts.issuer) {
+      console.error('--issuer is required')
+      process.exit(1)
+    }
+
+    var keyFile = opts.key || 'issuer-key.json'
+    if (!fs.existsSync(keyFile)) {
+      console.error('Issuer key file not found:', keyFile)
+      process.exit(1)
+    }
+
+    var keyData = readJsonFile(keyFile)
+    
+    console.error('Creating status list...')
+    
+    var result = await statuslist.createStatusList({
+      issuerDid: opts.issuer,
+      privateJwk: keyData.privateJwk
+    })
+
+    console.log(result.listVcJwt)
+    console.error('✅ Status list created')
+    console.error('List ID:', result.listId)
+
+  } else if (subcommand === 'set') {
+    if (!opts.list || opts.index === undefined || !opts.status) {
+      console.error('--list, --index, and --status are required')
+      process.exit(1)
+    }
+
+    var listJwt = fs.readFileSync(opts.list, 'utf8').trim()
+    var keyFile = opts.key || 'issuer-key.json'
+    var keyData = readJsonFile(keyFile)
+
+    console.error('Updating status list...')
+    console.error('  Index:', opts.index)
+    console.error('  Status:', opts.status)
+
+    var result = await statuslist.updateStatusList({
+      listVcJwt: listJwt,
+      index: parseInt(opts.index),
+      status: opts.status,
+      privateJwk: keyData.privateJwk
+    })
+
+    console.log(result.listVcJwt)
+    console.error('✅ Status list updated')
+
+  } else if (subcommand === 'check') {
+    if (!opts.list || opts.index === undefined) {
+      console.error('--list and --index are required')
+      process.exit(1)
+    }
+
+    var listJwt = fs.readFileSync(opts.list, 'utf8').trim()
+    
+    var status = statuslist.getCredentialStatusEntry({
+      listVcJwt: listJwt,
+      index: parseInt(opts.index)
+    })
+
+    console.log(status)
+    console.error('Status at index', opts.index + ':', status)
+
+  } else {
+    console.error('Unknown status subcommand:', subcommand)
+    process.exit(1)
+  }
+}
+
+async function handleAnchor(subcommand, opts) {
+  if (subcommand === 'hash') {
+    var dataFile = args[2]
+    if (!dataFile) {
+      console.error('Data file required')
+      process.exit(1)
+    }
+
+    var data = fs.readFileSync(dataFile)
+    var hash = anchor.sha256Hex(data)
+    
+    console.log(hash)
+    console.error('SHA-256 hash:', hash)
+
+  } else if (subcommand === 'build') {
+    if (!opts.kind || !opts.hash || !opts.issuer) {
+      console.error('--kind, --hash, and --issuer are required')
+      process.exit(1)
+    }
+
+    var payload = anchor.buildAnchorPayload({
+      kind: opts.kind,
+      hash: opts.hash,
+      issuerDid: opts.issuer,
+      issuedAt: opts.timestamp
+    })
+
+    console.log(payload.json)
+    console.error('✅ Anchor payload created')
+    console.error('Size:', payload.json.length, 'bytes')
+
+  } else {
+    console.error('Unknown anchor subcommand:', subcommand)
+    process.exit(1)
+  }
+}
+
+main().catch(function(error) {
+  console.error('Fatal error:', error)
+  process.exit(1)
+})