yakmesh 1.7.1 → 2.0.0

package/CHANGELOG.md

@@ -2,7 +2,225 @@
 
 All notable changes to YAKMESH will be documented in this file.
 
-## [1.7.0] - 2026-01-18
+## [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
+
+This release implements SHERPA, a novel peer discovery mechanism that uses the public web as a decentralized DHT.
+
+#### New Feature: SHERPA Discovery
+
+##### The Innovation: "The Web IS the DHT"
+- Each node exposes `/.well-known/yakmesh/beacon` with its peer list
+- Discovery crawls known endpoints to find new peers
+- No central authority - truly decentralized bootstrap
+- Works with existing CDN infrastructure
+
+##### New Module: `mesh/sherpa-discovery.js`
+- `SherpaDiscovery` - Main discovery engine with peer crawling
+- `BeaconMessage` - Signed beacon format for peer advertisement
+- `PeerRegistry` - Scored peer management with decay
+- `createBeaconMiddleware` - Express middleware for beacon endpoint
+
+##### New Endpoints
+- `GET /.well-known/yakmesh/beacon` - Advertise this node and known peers
+- `GET /sherpa/status` - Discovery statistics
+- `GET /sherpa/candidates` - Get connection candidates
+
+##### Configuration
+```javascript
+// yakmesh.config.js
+export default {
+  sherpa: {
+    enabled: true,
+    selfEndpoint: 'https://mynode.example.com',
+    wsEndpoint: 'wss://mynode.example.com:9001',
+    seeds: ['https://peer1.example.com', 'https://peer2.example.com'],
+  },
+};
+```
+
+##### Beacon Response Format
+```json
+{
+  "version": "1.0",
+  "nodeId": "abc123...",
+  "networkName": "mobius-rabi-junction",
+  "timestamp": 1737225600000,
+  "capabilities": { "wsPort": 9001, "supportsAnnex": true },
+  "peers": [{ "nodeId": "...", "endpoint": "https://..." }],
+  "publicKey": "...",
+  "signature": "..."
+}
+```
+
+---
+
+## [1.7.1] - 2026-01-18
 
 ### 🦬 NAKPAK & SHERPA: Yak-Themed Protocol Naming
 

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

package/SECURITY.md

@@ -47,6 +47,89 @@ YAKMESH implements multiple layers of security:
 - **Replay Protection**: Phase-epoch based message validation
 - **Code Integrity**: Self-verifying oracle with module sealing
 
+---
+
+## 🔒 Protected Architectural Elements
+
+> **WARNING**: The following architectural decisions are FOUNDATIONAL.
+> They MUST NOT be changed without explicit cryptographic review.
+
+### NodeID Generation (CRITICAL)
+
+**Location**: `identity/node-key.js`
+
+The NodeID is a **two-part composite**:
+
+```
+node-[networkName]-[instanceId]
+```
+
+| Component | Derived From | Purpose |
+|-----------|--------------|---------|
+| `networkName` | Codebase hash via iO | Proves nodes run identical code |
+| `instanceId` | Public key hash via iO | Unique per node instance |
+
+**Security Properties**:
+1. **Codebase Integrity** - Network name proves nodes run identical code
+2. **Instance Uniqueness** - Instance ID is deterministically tied to keypair
+3. **Human Verifiability** - Word-based names can be verified verbally
+4. **Network Segmentation** - Different code versions form separate networks
+
+**Rejected Simplifications**:
+
+| Proposal | Status | Reason |
+|----------|--------|--------|
+| `NodeID = SHA3-256(publicKey)` | ❌ REJECTED | Removes codebase verification |
+| `NodeID = base64(publicKey)` | ❌ REJECTED | Same as above, plus loses readability |
+| `NodeID = UUID` | ❌ REJECTED | Breaks deterministic derivation |
+| Remove codebase hash | ❌ REJECTED | Destroys network segmentation |
+
+### iO Oracle Integration (CRITICAL)
+
+**Location**: `oracle/`
+
+The indistinguishability obfuscation (iO) oracle provides:
+- Deterministic codebase hashing
+- Network identity derivation  
+- Phase modulation for replay protection
+
+**DO NOT**:
+- Bypass the oracle for "faster" identity generation
+- Cache identities without oracle verification
+- Accept identities that don't match expected network name
+
+### Security Anti-Pattern Examples
+
+```javascript
+// ❌ WRONG: Simplified NodeID (NEVER DO THIS)
+const nodeId = sha3_256(publicKey);
+
+// ✅ CORRECT: Full iO-based derivation
+const nodeId = generateNodeId(publicKey, codebaseHash);
+```
+
+---
+
+## 📋 Security Review Checklist
+
+Before merging any identity/crypto changes:
+
+- [ ] Does it maintain the two-part NodeID structure?
+- [ ] Does it preserve codebase hash in identity derivation?
+- [ ] Does it use ML-DSA-65 (not classical crypto)?
+- [ ] Does it verify signatures before trusting data?
+- [ ] Does it respect the iO oracle's role?
+
+---
+
+## 🕒 Security Incident Log
+
+| Date | Description | Resolution |
+|------|-------------|------------|
+| 2026-01-18 | NAMCHE spec draft proposed `NodeID = SHA3-256(publicKey)` | Rejected. Spec corrected to document actual two-part design. Security warnings added to codebase. |
+
+---
+
 ## Known Limitations
 
 - NTP time sources are not suitable for oracle operations (use GPS/PTP/Atomic)