yakmesh 1.8.0 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,397 @@
 
 All notable changes to YAKMESH will be documented in this file.
 
+## [2.2.0] - 2026-01-18
+
+### ✨ YAK:// Protocol v2.2.0 - Remote Bookmarks, DOKO Revocation & Comprehensive Testing
+
+This release adds mesh-synchronized bookmark sharing, key compromise recovery, and brings test coverage to 352 tests across all modules.
+
+#### 🌐 Remote Bookmarks (Mesh Sync)
+
+Share bookmark lists between nodes via gossip protocol. Subscribe to trusted nodes and receive their bookmarks automatically.
+
+**New Class: `RemoteBookmarkSync`**
+- **Publish**: Share your bookmarks to the mesh (`yakmesh bookmark share <list-name>`)
+- **Subscribe**: Follow other nodes' bookmark lists (`yakmesh bookmark subscribe <node-id>`)
+- **Sync**: Automatic sync via gossip protocol
+- **Priority**: Local bookmarks always override remote ones
+
+**Dashboard UI:**
+- New "Remote Bookmarks" panel with subscription management
+- Subscribe/Unsubscribe buttons
+- Publish your bookmarks to mesh
+- View remote bookmarks from subscribed nodes
+
+**REST API:**
+- `GET /bookmarks/remote/status` - Sync status and stats
+- `GET /bookmarks/remote` - List remote bookmarks
+- `POST /bookmarks/remote/subscribe` - Subscribe to a node
+- `POST /bookmarks/remote/unsubscribe` - Unsubscribe from a node
+- `POST /bookmarks/remote/publish` - Publish your bookmarks
+
+#### 🔑 DOKO Revocation (Key Compromise Recovery)
+
+Emergency revocation system for compromised DOKO identities.
+
+**New Class: `DOKORevocation`**
+- **Self-revocation**: Sign revocation with your own key (if available)
+- **Emergency revocation**: Pre-generated "break-glass" certificates
+- **Verification**: Validate revocation certificates with ML-DSA
+- **Broadcast**: Share revocations via gossip to prevent trust in compromised DOKOs
+
+**Revocation Reasons:**
+- `KEY_COMPROMISED` - Private key leaked or stolen
+- `DOKO_SUPERSEDED` - Replaced by new DOKO
+- `IDENTITY_RETIRED` - Voluntary retirement
+- `LOST_ACCESS` - Lost access to private key
+- `AFFILIATION_ENDED` - Left organization
+
+**Usage:**
+```javascript
+// Generate emergency cert when creating DOKO (store offline!)
+const emergencyCert = DOKORevocation.generateEmergencyCertificate(doko, privateKey);
+
+// Self-revoke if key is compromised but still accessible
+const revocation = DOKORevocation.createSelfRevocation(doko, privateKey, 'key_compromised');
+
+// Activate emergency revocation if key is lost
+DOKORevocation.activateEmergencyRevocation(emergencyCert);
+
+// Check if a DOKO is revoked
+const status = DOKORevocation.isRevoked(dokoId);
+```
+
+#### ✅ Comprehensive Test Coverage
+
+**352 tests across all modules:**
+
+| Suite | Framework | Tests |
+|-------|-----------|-------|
+| Oracle | Node.js test runner | 98 |
+| Protocol | Node.js test runner | 56 |
+| Multi-Node | Node.js test runner | 18 |
+| Security | Vitest | 180 |
+| **Total** | | **352** |
+
+**New Test Files:**
+- `protocol/tests/yak-protocol.test.js` - 56 tests for URL parsing, bookmarks, DOKO integration
+- `tests/multi-node.test.js` - 18 tests for cross-node sync with mock network
+
+#### 🎨 Dashboard Improvements
+
+- **Bookmarks Panel**: Add, list, remove local bookmarks
+- **Remote Bookmarks Panel**: Subscribe, publish, view mesh-synced bookmarks
+- **Version**: Updated to v2.2.0
+
+---
+
+## [2.1.0] - 2026-01-18
+
+### ✨ YAK:// Protocol v2.1.0 - Bookmarks, SSL Binding & Domain Transfers
+
+This release completes Phase 2 of the YAK:// protocol implementation with local bookmarks, SSL/TLS certificate binding, and secure domain transfer workflows.
+
+#### 🔖 Local Bookmarks (Phase 2)
+
+Personal "pet names" for YAK:// addresses. No global registry needed - bookmarks are local to your node.
+
+**Features:**
+- **BookmarkManager**: Manages local bookmarks stored in `data/bookmarks.json`
+- **URL Resolution**: Bookmarks are resolved after builtins, before content hashes
+- **CLI Commands**: Full bookmark management via CLI
+  - `yakmesh protocol bookmark add <name> <target>` - Add bookmark
+  - `yakmesh protocol bookmark list` - List all bookmarks
+  - `yakmesh protocol bookmark get <name>` - Get bookmark details
+  - `yakmesh protocol bookmark rm <name>` - Remove bookmark
+- **REST API**: `/bookmarks` endpoints for programmatic access
+  - `GET /bookmarks` - List all bookmarks
+  - `GET /bookmarks/:name` - Get specific bookmark
+  - `POST /bookmarks` - Add bookmark
+  - `DELETE /bookmarks/:name` - Remove bookmark
+
+**Usage:**
+```bash
+# Add a bookmark
+yakmesh protocol bookmark add docs yak://site/docs
+
+# Use the bookmark
+yakmesh protocol open yak://docs
+
+# Test resolution
+yakmesh protocol test yak://docs
+# → http://localhost:3000/site/docs
+```
+
+#### 🔐 SSL/TLS Certificate Binding
+
+Bind SSL certificates to DOKO identities for enhanced domain verification.
+
+**New Class: `DOKOCertBinding`**
+- `computeFingerprint(cert)` - SHA-256 fingerprint from PEM or DER certificate
+- `createBinding(options)` - Create SSL binding for a domain
+- `addBinding(doko, binding)` - Add binding to DOKO extensions
+- `verifyBinding(binding, cert)` - Verify certificate matches binding
+- `getBindingForDomain(doko, domain)` - Get binding for specific domain
+- `validateBindings(doko)` - Validate all bindings (expiration, etc.)
+
+**Cryptographic Chain:**
+```
+Domain → SSL Certificate → DOKO Identity → Mesh Verification
+```
+
+**19 tests** covering fingerprint computation, binding management, and verification.
+
+#### 🔄 Domain Transfer Workflow
+
+Secure ownership transfer of domains and DOKO-bound assets.
+
+**New Class: `DOKOTransfer`**
+- `createRequest(options)` - Create transfer request with expiration
+- `authorize(request, signature, nodeId)` - Owner authorizes transfer
+- `reject(request, reason)` - Owner rejects transfer
+- `cancel(request)` - Requester cancels pending transfer
+- `verifyAuthorization(transfer, publicKey)` - Verify owner signature
+- `complete(transfer, toNodeId)` - Complete transfer with proof
+- `createProof(completedTransfer)` - Generate mesh-verifiable proof
+
+**Transfer Flow:**
+```
+New Owner → Request → Current Owner → Authorize → 
+Mesh Verifies → Complete → Ownership Updated
+```
+
+**Transfer States:** `pending`, `authorized`, `completed`, `rejected`, `expired`, `cancelled`
+
+**Transfer Types:** `domain`, `website`, `asset`
+
+**19 tests** covering request creation, state transitions, completion, and proof validation.
+
+#### 📊 Test Results
+
+| Test Suite | Tests | Status |
+|------------|-------|--------|
+| Oracle Tests | 98 | ✅ Pass |
+| Security Tests | 152 | ✅ Pass |
+| DOKO Identity | 60 | ✅ Pass |
+| **Total** | **310** | ✅ All Pass |
+
+#### 🔧 Other Changes
+
+- Updated protocol version to 2.1.0
+- Fixed regex in DOKO ID format test (mixed case shortId)
+- Improved BookmarkManager normalization (simple `/` prefix)
+
+---
+
+## [2.0.1] - 2026-01-18
+
+### 🔧 Security Patch & Export Completeness
+
+This patch release fixes critical ML-DSA-65 argument order bugs discovered during post-release audit.
+
+#### 🐛 Bug Fixes
+
+##### ML-DSA-65 Argument Order (CRITICAL)
+Fixed incorrect argument order in two files where the noble-post-quantum API was used incorrectly:
+
+- **`oracle/module-sealer.js`**: Fixed `sign()` and `verify()` argument order
+  - `sign(secretKey, message)` → `sign(message, secretKey)` ✅
+  - `verify(publicKey, message, signature)` → `verify(signature, message, publicKey)` ✅
+
+- **`mesh/nakpak-routing.js`**: Fixed `sign()` and `verify()` argument order
+  - Same corrections as above
+
+**Impact**: Module attestations and NakPak routing signatures were failing validation.
+
+##### JSON Serialization in DOKO Identity
+Fixed `getSignableBytes()` to properly serialize nested objects using recursive key sorting.
+
+#### ✨ New Exports
+
+Added missing module exports to `package.json`:
+
+| Export Path | Module |
+|-------------|--------|
+| `./security/khata-protocol` | KHATA peer endorsement protocol |
+| `./security/mesh-auth` | Mesh authentication |
+| `./identity/node-key` | Node key management |
+| `./mesh/annex` | ANNEX encrypted P2P channels |
+| `./mesh/temporal-encoder` | Temporal encoding utilities |
+
+#### 📋 Release Process
+
+Added `RELEASE_CHECKLIST.md` with pre-release verification steps including:
+- Cryptographic API argument order verification
+- Export file existence checks
+- Documentation accuracy review
+
+---
+
+## [2.0.0] - 2026-01-18
+
+### 🧭 NAMCHE Gateway & 📜 DOKO Identity — The "Sherpa Security Stack"
+
+This major release introduces **mathematical trust** — replacing certificate authorities with cryptographic proof. The mesh now verifies identity through 7 independent gates, eliminating the need to trust any central authority.
+
+> *"The Sherpa does not prove knowledge by certificate. The Sherpa proves knowledge by walking the path."*
+
+---
+
+#### 🧭 NAMCHE: Network Authenticated Mesh Certificate Hub & Exchange
+
+A 7-gate verification gateway inspired by Nepal's Namche Bazaar — the last checkpoint before Everest.
+
+##### The 7 Gates of Verification
+| Gate | Name | Verification |
+|------|------|-------------|
+| 1 | Cryptographic Gate | Valid ML-DSA-65 signature |
+| 2 | Format Gate | DOKO structure compliance |
+| 3 | Temporal Gate | Not expired, within clock tolerance |
+| 4 | Domain Gate | DNS TXT record verification |
+| 5 | Mesh Gate | 3+ peer endorsements (KHATA protocol) |
+| 6 | Behavioral Gate | Historical trust score ≥ threshold |
+| 7 | Freshness Gate | Proof-of-liveliness within 5 minutes |
+
+##### New Module: `security/namche-gateway.js`
+- `NamcheGateway` - Main verification orchestrator
+- `GateResult` - Individual gate pass/fail with evidence
+- `VerificationReport` - Complete 7-gate assessment
+- `TrustDecision` - Final ALLOW/DENY/CHALLENGE decision
+
+##### Trust Levels
+```javascript
+TRUST_LEVELS = {
+  UNTRUSTED: 0,    // Failed critical gates
+  BRONZE: 1,       // Passed gates 1-3 only
+  SILVER: 2,       // Passed gates 1-5
+  GOLD: 3,         // Passed all 7 gates
+  PLATINUM: 4      // Gold + extended history
+}
+```
+
+---
+
+#### 📜 DOKO: Distributed Ownership & Key Object
+
+Self-sovereign identity documents verified by the mesh, not a CA.
+
+##### New Module: `security/doko-identity.js`
+- `DOKODocument` - The identity document structure
+- `DOKOGenerator` - Create new DOKO documents
+- `DOKOValidator` - Validate document structure and signatures
+- `DOKOExtensions` - Optional capability declarations
+
+##### DOKO Structure
+```javascript
+{
+  version: "1.0",
+  type: "node" | "user" | "service" | "device",
+  nodeId: "cryptographic-hash",
+  publicKey: "ML-DSA-65 public key",
+  created: 1737225600000,
+  expires: 1768761600000,
+  claims: {
+    domain: "example.com",
+    name: "My Node"
+  },
+  extensions: {
+    capabilities: ["annex", "nakpak", "sherpa"],
+    tlsBinding: { ... }
+  },
+  endorsements: [...],
+  signature: "self-signature"
+}
+```
+
+---
+
+#### 🔐 mTLS Phase 1: TLS Certificate Binding
+
+Bind DOKO identity to X.509 certificates for TLS-level verification.
+
+##### New Module: `security/tls-binding.js`
+- `DOKOCertificateGenerator` - Create X.509 certs from DOKO
+- `TLSVerifier` - Verify TLS connections against DOKO
+- `TLSCapabilityAdvertiser` - Announce TLS capabilities to mesh
+
+---
+
+#### 🤝 Hybrid Trust Model
+
+Multi-factor trust assessment combining cryptographic proof with behavioral history.
+
+##### New Module: `security/hybrid-trust.js`
+- `TrustEvidence` - Collect evidence from multiple sources
+- `HybridTrustModel` - Calculate weighted trust scores
+- `TrustBasedAccessControl` - Gate features by trust level
+
+##### Trust Factors
+| Factor | Weight | Source |
+|--------|--------|--------|
+| Cryptographic | 40% | NAMCHE gates 1-3 |
+| Social | 25% | Mesh endorsements (KHATA) |
+| Behavioral | 20% | Historical interactions |
+| Temporal | 15% | Identity age, freshness |
+
+---
+
+#### 🌐 Domain Consensus Protocol
+
+Mesh-verified domain ownership without centralized DNS authorities.
+
+##### New Module: `security/domain-consensus.js`
+- `DomainClaim` - Claim domain ownership
+- `DomainConsensus` - Multi-peer verification
+- `DNSVerifier` - Check DNS TXT records
+
+---
+
+#### 📊 Test Coverage
+
+| Module | Tests | Status |
+|--------|-------|--------|
+| NAMCHE Gateway | 37 | ✅ Passing |
+| Domain Consensus | 36 | ✅ Passing |
+| TLS Binding | 26 | ✅ Passing |
+| Hybrid Trust | 30 | ✅ Passing |
+| **Total Security** | **129** | ✅ All Passing |
+
+---
+
+#### 🏔️ The Sherpa Protocol Family
+
+| Protocol | Full Name | Purpose |
+|----------|-----------|---------|
+| **NAMCHE** | Network Authenticated Mesh Certificate Hub & Exchange | 7-gate verification |
+| **DOKO** | Distributed Ownership & Key Object | Self-sovereign identity |
+| **SHERPA** | Secure Hidden Endpoint Resolution Path Architecture | Peer discovery |
+| **NAKPAK** | NAK Protocol for Anonymous Kommunication | Onion routing |
+| **ANNEX** | Autonomous Network Negotiated eXchange | Encrypted P2P channels |
+| **KHATA** | Kryptographic Handshake for Automated Trust Acceptance | Trust distribution |
+
+---
+
+#### Breaking Changes
+
+- `identity.js` replaced by `doko-identity.js` (migration guide in docs)
+- Trust verification now requires NAMCHE gateway for new connections
+- Minimum Node.js version: 18.0.0
+
+#### Migration Guide
+
+```javascript
+// Before (v1.x)
+import { Identity } from 'yakmesh/oracle/identity';
+const id = new Identity();
+
+// After (v2.0)
+import { DOKOGenerator } from 'yakmesh/security/doko-identity';
+const doko = await DOKOGenerator.create({ type: 'node', claims: { name: 'My Node' } });
+```
+
+---
+
 ## [1.8.0] - 2026-01-18
 
 ### 🏔️ SHERPA: Decentralized Peer Discovery

package/README.md

@@ -52,6 +52,15 @@ In an era where traditional ECDSA is increasingly vulnerable and network jitter
 - 🔌 **Plugin Architecture** - Adapters for any database or API
 - 🛡️ **Phase Modulation** - Time-based anti-replay protection
 
+### v2.0 — The Sherpa Security Stack
+
+- 🧭 **NAMCHE Gateway** - 7-gate mathematical verification (no CA required)
+- 📜 **DOKO Identity** - Self-sovereign identity documents verified by mesh
+- 🏔️ **SHERPA Discovery** - Decentralized peer discovery via public web beacons
+- 🎒 **NAKPAK Routing** - Post-quantum onion routing for anonymity
+- 🔐 **ANNEX Channels** - ML-KEM768 encrypted P2P with perfect forward secrecy
+- 🤝 **Hybrid Trust** - Multi-factor trust combining crypto + behavior + social proof
+
 ## Quick Start
 
 ```bash
@@ -90,11 +99,18 @@ Full documentation available at **[yakmesh.dev](https://yakmesh.dev)**
 
 ```
 yakmesh/
+├── security/         # NAMCHE gateway, DOKO identity, trust models
+│   ├── namche-gateway.js    # 7-gate verification
+│   ├── doko-identity.js     # Self-sovereign identity
+│   ├── hybrid-trust.js      # Multi-factor trust scoring
+│   ├── tls-binding.js       # mTLS certificate binding
+│   └── domain-consensus.js  # Mesh-verified domains
 ├── oracle/           # Self-verifying validation engine
 ├── mesh/             # WebSocket P2P networking
+│   ├── sherpa-discovery.js  # Decentralized peer discovery
+│   ├── nakpak-routing.js    # Onion routing
+│   └── annex-channel.js     # Encrypted P2P channels
 ├── gossip/           # Epidemic-style message propagation
-├── identity/         # Post-quantum key management
-├── database/         # SQLite replication engine
 ├── adapters/         # Platform integration plugins
 ├── webserver/        # Embedded Caddy web server
 └── server/           # HTTP/WS server
@@ -143,6 +159,72 @@ class MyAdapter extends BaseAdapter {
 
 - `@yakmesh/adapter-peerquanta` - PeerQuanta phpBB marketplace
 
+## v2.2.0 — YAK:// Protocol & Identity Recovery
+
+### 🔗 YAK:// Protocol
+
+Custom URL protocol for mesh-native addressing. Escape HTTP entirely!
+
+```bash
+# Built-in routes
+yak://dashboard          # Node dashboard
+yak://peers              # Connected peers
+yak://content/<hash>     # Content by hash
+
+# Personal bookmarks (pet names)
+yakmesh bookmark add alice /site/alice-homepage
+yak://alice              # Opens your bookmark
+```
+
+### 📚 Remote Bookmarks
+
+Share bookmark lists between nodes via gossip protocol:
+
+```javascript
+import { getRemoteBookmarkSync } from 'yakmesh/protocol/yak-protocol';
+
+const sync = getRemoteBookmarkSync({ nodeId: 'my-node' });
+
+// Subscribe to another node's bookmarks
+sync.subscribe('trusted-node-id');
+
+// Publish your bookmarks to the mesh
+sync.publish('my-bookmarks', ['project', 'docs', 'friends']);
+
+// Resolve remote bookmarks
+sync.resolveRemote('alice'); // Returns target from subscribed node
+```
+
+### 🔐 DOKO Revocation
+
+Key compromise recovery with self-revocation and emergency "break-glass" certificates:
+
+```javascript
+import { DOKORevocation, REVOCATION_REASONS } from 'yakmesh/security/doko-identity';
+
+const revocation = new DOKORevocation({ generator, nodeId });
+
+// Normal self-revocation
+const cert = revocation.revoke(dokoId, REVOCATION_REASONS.KEY_COMPROMISED, privateKey);
+
+// Emergency revocation (primary key compromised, use backup)
+const emergencyCert = revocation.createEmergencyCertificate(
+  dokoId, 
+  REVOCATION_REASONS.KEY_COMPROMISED, 
+  backupPrivateKey
+);
+
+// Check revocation status
+revocation.isRevoked(dokoId); // true
+```
+
+**Revocation Reasons:**
+- `KEY_COMPROMISED` - Private key was exposed
+- `DOKO_SUPERSEDED` - Replaced with new identity
+- `IDENTITY_RETIRED` - No longer in use
+- `LOST_ACCESS` - Cannot access keys
+- `AFFILIATION_ENDED` - Organization membership ended
+
 ## API Endpoints
 
 | Endpoint | Method | Description |
@@ -155,6 +237,15 @@ class MyAdapter extends BaseAdapter {
 | `/time/status` | GET | Time source detection |
 | `/time/capabilities` | GET | Time oracle eligibility |
 | `/connect` | POST | Connect to a peer |
+| `/bookmarks` | GET | List local bookmarks |
+| `/bookmarks` | POST | Add a bookmark |
+| `/bookmarks/:name` | DELETE | Remove a bookmark |
+| `/bookmarks/remote` | GET | List remote bookmarks |
+| `/bookmarks/remote/subscribe` | POST | Subscribe to node |
+| `/bookmarks/remote/publish` | POST | Publish bookmark list |
+| `/bookmarks/remote/status` | GET | Remote sync status |
+| `/security/doko/stats` | GET | DOKO identity stats |
+| `/security/namche/gates` | GET | Gateway verification status |
 
 ## Pro Features
 

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,115 @@
+# Yakmesh Release Checklist
+
+This checklist ensures releases are complete, accurate, and secure.
+
+## Pre-Release Checklist
+
+### 1. Code Quality
+
+- [ ] **All tests pass** - Run `npm test` and verify 0 failures
+- [ ] **No lint errors** - Run `npm run lint` if available
+- [ ] **No TODO/FIXME in critical paths** - Search security code for unfinished work
+  ```powershell
+  Get-ChildItem -Recurse -Filter "*.js" security,oracle,mesh,identity | Select-String -Pattern "TODO|FIXME"
+  ```
+
+### 2. Cryptographic API Verification
+
+**ML-DSA-65 (Post-Quantum Signatures):**
+- [ ] All `ml_dsa65.sign()` calls use `sign(message, secretKey)` order
+- [ ] All `ml_dsa65.verify()` calls use `verify(signature, message, publicKey)` order
+
+**ML-KEM-768 (Post-Quantum Key Exchange):**
+- [ ] All `ml_kem768.encapsulate()` calls use `encapsulate(publicKey)` order
+- [ ] All `ml_kem768.decapsulate()` calls use `decapsulate(ciphertext, secretKey)` order
+
+**Verification command:**
+```powershell
+Get-ChildItem -Recurse -Filter "*.js" | Select-String -Pattern "ml_dsa65\.(sign|verify)|ml_kem768\.(encapsulate|decapsulate)"
+```
+
+### 3. Exports Verification
+
+- [ ] **All exports exist** - Every path in `package.json exports` resolves to a real file
+  ```powershell
+  # Run from yakmesh-node directory
+  node -e "const pkg = require('./package.json'); Object.values(pkg.exports).flat().forEach(p => { const fs = require('fs'); const path = p.replace('./', ''); if (!fs.existsSync(path)) console.log('MISSING:', path); })"
+  ```
+
+### 4. Documentation
+
+- [ ] **README.md is accurate** - All features, APIs, and examples are current
+- [ ] **API documentation matches implementation** - Check function signatures
+- [ ] **CHANGELOG.md updated** - Version, date, and all changes documented
+- [ ] **Migration guide** (if breaking changes) - Clear upgrade path for users
+
+### 5. Version Management
+
+- [ ] **Version bumped** in `package.json`
+- [ ] **Version tag matches** - `npm version` output matches intended release
+- [ ] **No debug code** - Remove `console.log` from production paths
+- [ ] **Dependencies updated** - Run `npm audit` and address critical issues
+
+## Post-Release Verification
+
+### 1. Installation Test
+
+```powershell
+# Create a test directory
+mkdir test-install && cd test-install
+npm init -y
+npm install yakmesh-node@<version>
+
+# Test basic import
+node -e "const yk = require('yakmesh-node'); console.log('Import successful')"
+```
+
+### 2. Smoke Tests
+
+- [ ] Can generate node identity
+- [ ] Can create and verify signatures
+- [ ] Can establish encrypted channels
+- [ ] Core mesh operations work
+
+### 3. Documentation Deployment
+
+- [ ] Website updated with new version
+- [ ] API docs regenerated
+- [ ] Release notes published
+
+## Critical Files to Review
+
+| File | Purpose | Priority |
+|------|---------|----------|
+| `security/doko-identity.js` | Identity signatures | HIGH |
+| `security/namche-gateway.js` | Gateway security | HIGH |
+| `oracle/module-sealer.js` | Module attestation | HIGH |
+| `mesh/nakpak-routing.js` | Packet signing | HIGH |
+| `identity/node-key.js` | Node authentication | HIGH |
+
+## Known Pitfalls
+
+### ML-DSA-65 Argument Order
+The noble-post-quantum library uses:
+- `sign(message, secretKey)` - **message FIRST**
+- `verify(signature, message, publicKey)` - **signature FIRST**
+
+This is opposite to some other crypto libraries (e.g., sodium). Always verify against the [noble-post-quantum documentation](https://github.com/paulmillr/noble-post-quantum).
+
+### JSON Serialization for Signing
+When creating signable bytes from objects:
+- Use stable/deterministic JSON serialization
+- Sort keys recursively (not just top-level)
+- Use a helper function like `stableStringify()` for nested objects
+
+## Release Types
+
+| Type | Version | When to Use |
+|------|---------|-------------|
+| Major | X.0.0 | Breaking changes, major features |
+| Minor | 0.X.0 | New features, backward compatible |
+| Patch | 0.0.X | Bug fixes, security patches |
+
+---
+
+*Last updated: 2026-01-18 (v2.0.1 preparation)*