yakmesh 2.8.2 → 3.0.0

package/docs/PEERQUANTA-YAKMESH-INTEGRATION.md

@@ -0,0 +1,407 @@
+# PeerQuanta + Yakmesh Integration Design Document
+
+**Version**: 1.0.0  
+**Date**: January 18, 2026  
+**Status**: Draft  
+**Authors**: PeerQuanta Team
+
+---
+
+## Executive Summary
+
+This document outlines the integration strategy between **PeerQuanta** (P2P cryptocurrency marketplace) and **Yakmesh** (post-quantum secure mesh network). The integration creates a privacy-first, decentralized ecosystem where users can trade, communicate, and verify transactions without central authority.
+
+---
+
+## 1. YETI - Yakmesh Encrypted Trustless Index
+
+### 1.1 Overview
+
+**Y**akmesh **E**ncrypted **T**rustless **I**ndex - A private DNS-like system for the mesh.
+
+```
+Traditional:  example.com → DNS → 93.184.216.34 → HTTP Server
+YETI:         merchant.yak → YETI → NodeID:abc123 → Mesh Node → Content
+```
+
+### 1.2 How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         YETI Resolution                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   User types: "alice-crypto.yak"                                │
+│                    │                                            │
+│                    ▼                                            │
+│   ┌─────────────────────────────────────┐                       │
+│   │    Local YETI Cache                 │                       │
+│   │    (Recently resolved names)        │                       │
+│   └─────────────────────────────────────┘                       │
+│                    │ Miss                                       │
+│                    ▼                                            │
+│   ┌─────────────────────────────────────┐                       │
+│   │    SHERPA Discovery                 │                       │
+│   │    Query known peers for name       │                       │
+│   └─────────────────────────────────────┘                       │
+│                    │                                            │
+│                    ▼                                            │
+│   ┌─────────────────────────────────────┐                       │
+│   │    Gossip Propagation               │                       │
+│   │    Flood query to mesh network      │                       │
+│   └─────────────────────────────────────┘                       │
+│                    │                                            │
+│                    ▼                                            │
+│   ┌─────────────────────────────────────┐                       │
+│   │    Response: NodeID + PublicKey     │                       │
+│   │    Signed by name owner             │                       │
+│   └─────────────────────────────────────┘                       │
+│                    │                                            │
+│                    ▼                                            │
+│   Connect via Annex (encrypted) or Nakpak (anonymous)           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 Name Registration
+
+Names are registered by signing a claim with your node's private key:
+
+```javascript
+// YETI Name Record
+{
+  name: "alice-crypto",
+  tld: "yak",
+  nodeId: "abc123...",
+  publicKey: "ML-DSA-65 public key",
+  registered: 1737200000000,
+  expires: 1768736000000,  // 1 year
+  signature: "signed by owner's key",
+  
+  // Optional metadata
+  meta: {
+    description: "Alice's Crypto Shop",
+    avatar: "ipfs://...",
+    services: ["marketplace", "escrow"]
+  }
+}
+```
+
+### 1.4 Conflict Resolution
+
+- First-come-first-served with timestamp proof
+- Name claims propagate through Gossip
+- Mesh consensus determines valid owner
+- Disputes resolved by earliest signed claim
+
+### 1.5 TLD Structure
+
+| TLD | Purpose |
+|-----|---------|
+| `.yak` | General mesh names |
+| `.pq` | PeerQuanta marketplace |
+| `.anon` | Nakpak-only (anonymous) |
+| `.test` | Development/testing |
+
+---
+
+## 2. Mesh-Backed PeerQuanta Tools
+
+### 2.1 Digital Notary → Mesh Attestation
+
+**Current**: Client-side timestamp with SHA-3 hash  
+**Enhanced**: Distributed attestation across mesh nodes
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Mesh-Backed Notarization                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Document → SHA3-256 Hash → Notary Request                     │
+│                                   │                             │
+│                                   ▼                             │
+│   ┌─────────────────────────────────────┐                       │
+│   │         Gossip Broadcast            │                       │
+│   │   "I attest hash X at time T"       │                       │
+│   └─────────────────────────────────────┘                       │
+│              │         │         │                              │
+│              ▼         ▼         ▼                              │
+│         ┌───────┐ ┌───────┐ ┌───────┐                           │
+│         │Node A │ │Node B │ │Node C │                           │
+│         │ Signs │ │ Signs │ │ Signs │                           │
+│         └───────┘ └───────┘ └───────┘                           │
+│              │         │         │                              │
+│              └─────────┼─────────┘                              │
+│                        ▼                                        │
+│   ┌─────────────────────────────────────┐                       │
+│   │       Attestation Certificate       │                       │
+│   │   Hash + Time + N node signatures   │                       │
+│   │   "3 of 5 nodes attested"           │                       │
+│   └─────────────────────────────────────┘                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Implementation File**: `mesh/notary-attestation.js`
+
+### 2.2 Secure Notes → Mesh-Synced Vault
+
+**Current**: Password-encrypted notes stored locally  
+**Enhanced**: Encrypted notes synced across user's nodes
+
+```javascript
+// Secure Note with Mesh Sync
+{
+  id: "note-uuid",
+  encryptedContent: "XChaCha20-Poly1305 ciphertext",
+  owner: "nodeId",
+  syncNodes: ["node1", "node2"],  // User's other devices
+  version: 3,
+  lastModified: 1737200000000,
+  
+  // Sync via Annex (encrypted P2P)
+  // Only owner's nodes can decrypt
+}
+```
+
+### 2.3 Covert Art → Mesh Steganography
+
+**Current**: Hide data in images client-side  
+**Enhanced**: Transmit covert images through Nakpak onion routes
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Covert Art via Nakpak                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Image + Hidden Message                                        │
+│           │                                                     │
+│           ▼                                                     │
+│   ┌─────────────────────────────────────┐                       │
+│   │    Steganographic Encoding          │                       │
+│   │    (LSB, DCT, or ML-based)          │                       │
+│   └─────────────────────────────────────┘                       │
+│           │                                                     │
+│           ▼                                                     │
+│   ┌─────────────────────────────────────┐                       │
+│   │    Nakpak Onion Routing             │                       │
+│   │    Source → Relay1 → Relay2 → Dest  │                       │
+│   └─────────────────────────────────────┘                       │
+│           │                                                     │
+│           ▼                                                     │
+│   Recipient extracts hidden message                             │
+│   (No observer knows source or content)                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.4 QCoA → Mesh Identity Attestation
+
+**Current**: Quantum Certificate of Authenticity for digital assets  
+**Enhanced**: Cross-mesh verified merchant/user identity badges
+
+```javascript
+// QCoA Mesh Badge
+{
+  type: "merchant",
+  name: "alice-crypto.yak",
+  publicKey: "...",
+  reputation: {
+    trades: 150,
+    rating: 4.9,
+    disputes: 0,
+  },
+  attestations: [
+    { nodeId: "node1", signature: "..." },
+    { nodeId: "node2", signature: "..." },
+  ],
+  
+  // Badge verified by multiple mesh nodes
+  // Cannot be faked without controlling majority
+}
+```
+
+### 2.5 Encrypted Wagers → Mesh Escrow
+
+**Current**: Commitment-reveal protocol for wagers  
+**Enhanced**: Mesh-enforced escrow with dispute resolution
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Mesh Escrow Protocol                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Phase 1: COMMITMENT                                           │
+│   ┌─────────┐              ┌─────────┐                          │
+│   │  Alice  │  Commit A    │  Bob    │  Commit B                │
+│   └─────────┘──────────────└─────────┘                          │
+│                    │                                            │
+│                    ▼                                            │
+│   ┌─────────────────────────────────────┐                       │
+│   │         Mesh Escrow Nodes           │                       │
+│   │   Store commitments + stake         │                       │
+│   └─────────────────────────────────────┘                       │
+│                                                                 │
+│   Phase 2: REVEAL                                               │
+│   Alice reveals → Bob reveals → Outcome determined              │
+│                                                                 │
+│   Phase 3: SETTLEMENT                                           │
+│   If dispute: Mesh consensus arbitrates                         │
+│   If clean: Automatic payout                                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. SHERPA Integration with PeerQuanta
+
+### 3.1 PeerQuanta as SHERPA Seed
+
+The peerquanta.com website will expose a beacon endpoint:
+
+```
+https://peerquanta.com/.well-known/yakmesh/beacon
+```
+
+This provides a stable, trusted entry point to the yakmesh network.
+
+### 3.2 Beacon Response
+
+```json
+{
+  "version": "1.0",
+  "nodeId": "peerquanta-primary",
+  "networkName": "yakmesh-mainnet",
+  "timestamp": 1737200000000,
+  "ttl": 3600,
+  "capabilities": {
+    "wsPort": 9001,
+    "httpPort": 443,
+    "supportsAnnex": true,
+    "supportsNakpak": true,
+    "supportsGossip": true,
+    "supportsYETI": true
+  },
+  "peers": [
+    { "nodeId": "node1", "endpoint": "https://node1.yakmesh.dev" },
+    { "nodeId": "node2", "endpoint": "https://node2.yakmesh.dev" }
+  ],
+  "publicKey": "...",
+  "signature": "..."
+}
+```
+
+### 3.3 Implementation Steps
+
+1. **Static Beacon** (v1): JSON file served by Caddy/nginx
+2. **Dynamic Beacon** (v2): Yakmesh node generates live peer list
+3. **Signed Beacon** (v3): Cryptographic proof of authenticity
+
+---
+
+## 4. Protocol Stack (Updated)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Yakmesh Protocol Stack v1.9                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Layer 0: YETI      🏔️  Encrypted Trustless Index (DNS)        │
+│   Layer 1: HTTP API  🌐  Public content delivery                │
+│   Layer 2: Annex     🔐  Encrypted P2P (ML-KEM768)              │
+│   Layer 3: Gossip    📢  Message propagation                    │
+│   Layer 4: Beacon    🚨  Emergency broadcast                    │
+│   Layer 5: Nakpak    🎒  Onion routing                          │
+│   Layer 6: Sherpa    🏔️  Peer discovery                         │
+│   Layer 7: Mesh      🕸️  Core P2P network                       │
+│                                                                 │
+│   Extensions:                                                   │
+│   - Notary Attestation (mesh-backed timestamps)                 │
+│   - Escrow Protocol (commitment-based trades)                   │
+│   - Identity Badges (QCoA verification)                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. Implementation Roadmap
+
+### Phase 1: Foundation (Current - v1.8.x)
+- [x] SHERPA peer discovery
+- [x] NAKPAK onion routing
+- [ ] Beacon endpoint on peerquanta.com
+- [ ] Website updates for v1.8.0
+- [ ] SHERPA tests
+
+### Phase 2: YETI DNS (v1.9.0)
+- [ ] YETI name registration
+- [ ] Gossip-based name resolution
+- [ ] `.yak` TLD support
+- [ ] Browser extension for `.yak` domains
+
+### Phase 3: Tool Integration (v2.0.0)
+- [ ] Mesh-backed Digital Notary
+- [ ] Synced Secure Notes
+- [ ] QCoA mesh badges
+- [ ] Nakpak Covert Art transmission
+
+### Phase 4: Marketplace (v2.1.0)
+- [ ] Mesh escrow protocol
+- [ ] Anonymous trading via Nakpak
+- [ ] Reputation propagation
+- [ ] Dispute resolution consensus
+
+---
+
+## 6. Security Considerations
+
+### 6.1 YETI Name Squatting
+- Require proof-of-stake or proof-of-work for registration
+- Implement name challenges for trademark disputes
+- Rate limit new registrations per node
+
+### 6.2 Sybil Attacks on Consensus
+- Require code proof for participation
+- Weight votes by node age and reputation
+- Implement subnet diversity checks
+
+### 6.3 Eclipse Attacks on SHERPA
+- Maintain diverse peer set across subnets
+- Verify beacon signatures
+- Cross-check peer lists from multiple sources
+
+### 6.4 Timing Attacks on Nakpak
+- Add random delays in onion routing
+- Use constant-time operations
+- Pad messages to fixed sizes
+
+---
+
+## 7. Open Questions
+
+1. **YETI Governance**: Who resolves `.yak` disputes?
+2. **Fee Structure**: Should name registration cost tokens?
+3. **Interoperability**: Can YETI work with ENS/Handshake?
+4. **Mobile Support**: How do mobile apps resolve `.yak` names?
+
+---
+
+## 8. References
+
+- [Yakmesh Whitepaper](https://yakmesh.dev/whitepaper)
+- [SHERPA Implementation](../mesh/sherpa-discovery.js)
+- [NAKPAK Implementation](../mesh/nakpak-routing.js)
+- [PeerQuanta Tools](https://peerquanta.com/tools)
+
+---
+
+*Document Version History*
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-18 | Initial draft |
+
+---
+
+**YAKMESH™** is a trademark of PeerQuanta (USPTO Serial No. 99594620)

package/docs/PRECISION-DISCLOSURE.md

@@ -0,0 +1,96 @@
+# YAKMESH Timing Precision: Technical Disclosure
+
+**Document Purpose:** This document provides accurate, legally-defensible statements about YAKMESH timing capabilities for patent and marketing purposes.
+
+---
+
+## Summary of Capabilities
+
+### What YAKMESH Can Measure (Local Node)
+
+| Method | Resolution | Notes |
+|--------|-----------|-------|
+| `process.hrtime.bigint()` | ~100 nanoseconds | Node.js high-resolution timer |
+| `performance.now()` | ~200 nanoseconds | Browser-compatible |
+| `Date.now()` | 1 millisecond | Standard JavaScript |
+
+### What YAKMESH Can Synchronize (Network)
+
+| Time Source | Typical Network Sync | YAKMESH Tolerance Setting |
+|-------------|---------------------|---------------------------|
+| PCIe Atomic Clock | Microseconds (same datacenter) | ±100 milliseconds |
+| GPS with PPS | 1-10 milliseconds | ±500 milliseconds |
+| IEEE 1588 PTP | 1-100 microseconds | ±500 milliseconds |
+| Standard NTP | 10-100 milliseconds | ±5000 milliseconds |
+
+**Key Distinction:** Local measurement resolution is NOT the same as network synchronization precision.
+
+---
+
+## Accurate Marketing Language
+
+### ✅ CORRECT Statements
+
+- "YAKMESH supports high-precision time sources including PCIe atomic clocks"
+- "YAKMESH adapts timing tolerances based on available hardware"
+- "YAKMESH implements configurable precision from NTP to atomic clock levels"
+- "YAKMESH uses time as a redundancy dimension for data resilience"
+- "With atomic clock hardware, YAKMESH can achieve sub-millisecond synchronization"
+
+### ❌ INCORRECT Statements (Do Not Use)
+
+- ~~"Nanosecond precision"~~ (only achievable with specialized hardware, not yet validated)
+- ~~"Sub-nanosecond alignment"~~ (physically impossible without atomic hardware AND specialized network)
+- ~~"1ns timing"~~ (Node.js minimum is ~100ns local, network adds milliseconds)
+
+---
+
+## Hardware Requirements for Enhanced Precision
+
+To claim sub-millisecond synchronization, the following are required:
+
+1. **PCIe Atomic Clock** (e.g., Jackson Labs CSAC, Microsemi SA.45s)
+2. **PTP-capable Network Interface** (e.g., Mellanox ConnectX, Intel X710)
+3. **Low-latency network** (same datacenter, <1ms RTT)
+4. **Kernel PTP support** (Linux with ptp4l, Windows with Meinberg)
+
+---
+
+## Test Results
+
+### Local Timing Resolution Test (Node.js on Windows)
+
+```
+performance.now() minimum delta: 0.0002 ms (200 nanoseconds)
+process.hrtime.bigint() minimum delta: 100 ns
+```
+
+### Network Synchronization (Pending Hardware Validation)
+
+- NTP sync: Not yet measured on live network
+- PTP sync: Requires PTP hardware
+- Atomic sync: Requires PCIe atomic clock
+
+---
+
+## Patent Claims Supported by Implementation
+
+1. **Temporal Matrix Encoding** - Proven with 50ms slice intervals
+2. **Trust-level adaptive system** - Proven with detection and tolerance adaptation
+3. **Hash-chain temporal binding** - Proven with cryptographic linking
+4. **Configurable precision architecture** - Proven framework, hardware integration pending
+
+---
+
+## Recommendations for Patent Application
+
+1. Claim the **architecture** that supports multiple precision levels
+2. Claim the **method** of temporal encoding regardless of precision
+3. Avoid specific nanosecond claims without hardware validation
+4. Emphasize the **novelty of time-as-redundancy** concept
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** January 2026  
+**Status:** For internal use and patent attorney review

package/docs/README.md

@@ -0,0 +1,76 @@
+# YAKMESH Documentation
+
+> **📚 Full documentation available at [yakmesh.dev](https://yakmesh.dev)**
+
+## Quick Links
+
+| Topic | Web | Specification |
+|-------|-----|---------------|
+| Getting Started | [yakmesh.dev/docs/getting-started](https://yakmesh.dev/docs/getting-started) | — |
+| Configuration | [yakmesh.dev/docs/configuration](https://yakmesh.dev/docs/configuration) | — |
+| API Reference | [yakmesh.dev/docs/api](https://yakmesh.dev/docs/api) | — |
+| CLI Reference | [yakmesh.dev/docs/cli](https://yakmesh.dev/docs/cli) | — |
+| NAMCHE Gateway | [yakmesh.dev/docs/namche](https://yakmesh.dev/docs/namche) | [NAMCHE-SPEC.md](NAMCHE-SPEC.md) |
+| TATTVA Oracle | [yakmesh.dev/docs/tattva](https://yakmesh.dev/docs/tattva) | — |
+| SURAKSHA Security | [yakmesh.dev/docs/trust-security](https://yakmesh.dev/docs/trust-security) | — |
+| Time Sources | [yakmesh.dev/docs/time-sources](https://yakmesh.dev/docs/time-sources) | — |
+| Mesh Networking | [yakmesh.dev/docs/mesh](https://yakmesh.dev/docs/mesh) | — |
+| SHERPA Discovery | [yakmesh.dev/docs/sherpa](https://yakmesh.dev/docs/sherpa) | — |
+| NAKPAK Routing | [yakmesh.dev/docs/nakpak](https://yakmesh.dev/docs/nakpak) | — |
+| ANNEX Channels | [yakmesh.dev/docs/annex](https://yakmesh.dev/docs/annex) | — |
+| YAK:// Protocol | [yakmesh.dev/docs/yak-protocol](https://yakmesh.dev/docs/yak-protocol) | — |
+| Geographic Proof | [yakmesh.dev/docs/geo-proof](https://yakmesh.dev/docs/geo-proof) | — |
+
+## Protocols (v2.5.0)
+
+| Protocol | Purpose | Docs |
+|----------|---------|------|
+| **STUPA** | State consensus | [yakmesh.dev/docs/stupa](https://yakmesh.dev/docs/stupa) |
+| **LAMA** | Lightweight messaging | [yakmesh.dev/docs/lama](https://yakmesh.dev/docs/lama) |
+| **MANI** | Metrics & analytics | [yakmesh.dev/docs/mani](https://yakmesh.dev/docs/mani) |
+| **KARMA** | Trust reputation | [yakmesh.dev/docs/karma](https://yakmesh.dev/docs/karma) |
+| **MANDALA** | Topology management | [yakmesh.dev/docs/mandala](https://yakmesh.dev/docs/mandala) |
+
+## Specifications & Research
+
+These documents provide deep technical details for implementers:
+
+| Document | Description |
+|----------|-------------|
+| [WHITEPAPER.md](WHITEPAPER.md) | Full technical whitepaper |
+| [NAMCHE-SPEC.md](NAMCHE-SPEC.md) | NAMCHE gateway specification |
+| [CRYPTO-AGILITY.md](CRYPTO-AGILITY.md) | Cryptographic algorithm choices |
+| [TME-FAQ.md](TME-FAQ.md) | Temporal Matrix Encoding FAQ |
+| [MTLS-RESEARCH.md](MTLS-RESEARCH.md) | mTLS integration research |
+| [PRECISION-DISCLOSURE.md](PRECISION-DISCLOSURE.md) | Precision timing disclosure |
+
+## Roadmaps
+
+| Version | Status |
+|---------|--------|
+| [ROADMAP-2.5.0.md](ROADMAP-2.5.0.md) | ✅ Released |
+| [ROADMAP-2.4.0.md](ROADMAP-2.4.0.md) | ✅ Released |
+
+## GRANTH: Embedded Documentation Bundle
+
+YAKMESH includes an embedded documentation bundle (**GRANTH**) that ships with the npm package. This enables offline-first, hash-verified documentation access.
+
+```javascript
+// Access embedded docs programmatically
+import { BUNDLE_HASH, BUNDLE_VERSION, FILES } from 'yakmesh/embedded-docs/bundle.js';
+
+console.log(`Docs v${BUNDLE_VERSION} - Hash: ${BUNDLE_HASH.slice(0, 16)}...`);
+```
+
+The bundle contains the same documentation as yakmesh.dev, verified by SHA3-256 hashes. This ensures:
+- **Offline access**: Docs work without internet
+- **Integrity**: Hash verification prevents tampering
+- **Consistency**: Same docs across all nodes running same version
+
+---
+
+<div align="center">
+  <strong><a href="https://yakmesh.dev">yakmesh.dev</a></strong>
+  <br><br>
+  <sub>© 2026 YAKMESH™ Project. Sturdy & Secure.</sub>
+</div>