yakmesh 2.0.0 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,490 @@
 
 All notable changes to YAKMESH will be documented in this file.
 
+## [2.5.0] - 2026-01-20
+
+### 🌍 Geographic Exclusion — Physics Don't Lie
+
+*Theme: "Speed of light is the ultimate validator. We prove where you CANNOT be."*
+
+#### 🎯 Core Principles
+
+- **Unforgeable Distance** - Speed of light provides cryptographic lower bound on distance
+- **Exclusion Zones** - Prove where nodes CANNOT be, not precise location
+- **No GPS Required** - RTT + physics = provable geography
+- **Network Overhead is Safe** - Latency only inflates RTT, making zones always valid
+
+#### ✅ Implemented Features
+
+**Geographic Proof Core** (`security/geo-proof.js`)
+- Speed-of-light distance calculation (fiber = 0.67c)
+- LandmarkRegistry for known geographic reference points
+- RTTMeasurement with jitter handling and averaging
+- ExclusionZone creation from RTT measurements
+- GeographicProof with confidence scoring
+- GeoProofService for full lifecycle management
+- **59 tests**
+
+**KHATA Gossip Integration** (`security/khata-trust-integration.js`)
+- 6 new message types for geo-proof gossip:
+  - GEO_PROOF_ANNOUNCE, GEO_PROOF_REQUEST, GEO_PROOF_RESPONSE
+  - LANDMARK_ANNOUNCE, LANDMARK_REQUEST, LANDMARK_VERIFY
+- Geo-proof announcement and request handling
+- Landmark discovery via gossip
+- **14 new tests** (36 total)
+
+**CLI Commands** (`cli/index.js`)
+- `yakmesh geo status` - Show geographic proof status
+- `yakmesh geo landmarks` - List known landmarks
+- `yakmesh geo zones` - List exclusion zones
+- `yakmesh geo prove` - Generate geographic proof
+- `yakmesh geo verify <nodeId>` - Verify another node
+- `yakmesh geo add-landmark <name>` - Add landmark manually
+- `yakmesh geo physics` - Show speed-of-light constants
+
+**Server API Endpoints** (`server/index.js`)
+- `GET /geo/status` - Geographic proof status and physics constants
+- `GET /geo/landmarks` - List registered landmarks
+- `POST /geo/landmarks` - Add a landmark
+- `GET /geo/zones` - List exclusion zones
+- `POST /geo/prove` - Generate geographic proof
+- `POST /geo/verify` - Verify another node's claims
+
+**SHERPA Beacon Integration** (`mesh/sherpa-discovery.js`)
+- RTT measurement during beacon fetch (performance.now())
+- Geographic coordinates in BeaconMessage (lat, lon, name, accuracyKm, timeTier)
+- Automatic landmark discovery from geo-enabled beacons
+- RTT sample averaging with configurable window
+- Protocol version bumped to 1.1 for geo support
+- New SherpaDiscovery methods:
+  - `setGeoCoordinates()` - Configure this node as landmark
+  - `setGeoProofService()` - Connect to GeoProofService
+  - `getGeoLandmarks()` - List discovered landmarks
+  - `getRttMeasurements()` - Get RTT data for proof generation
+- **31 tests**
+
+#### ⚡ Speed-of-Light Physics
+
+| RTT | Minimum Distance |
+|-----|------------------|
+| 1 ms | ≥100 km |
+| 5 ms | ≥500 km |
+| 10 ms | ≥999 km |
+| 50 ms | ≥4,997 km |
+| 100 ms | ≥9,993 km |
+| 200 ms | ≥19,986 km |
+
+**Formula:** `minDistance = (RTT / 2) × fiberSpeed`
+- Vacuum speed: 299,792.458 km/s
+- Fiber speed (0.67c): 199,861.639 km/s
+
+#### 📊 Test Summary
+
+| Module | Tests | Status |
+|--------|-------|--------|
+| Geo Proof Core | 59 | ✅ |
+| KHATA Geo Integration | 14 | ✅ |
+| SHERPA Geo Integration | 31 | ✅ |
+| **v2.5 Total** | **104** | ✅ |
+
+#### 🔮 Implementation Notes
+
+- Dashboard visualization skipped (privacy concern - CLI provides same data)
+- SHERPA beacons now serve as geographic landmarks automatically
+- RTT measured using high-resolution `performance.now()` timing
+
+---
+
+## [2.4.0] - 2026-01-19 (Internal)
+
+### 🤝 Mathematical Trust — No Simulation
+
+*Theme: "You can't fake physics. Atomic time and real silicon are your credentials."*
+
+> **Note**: This version was developed internally and released as part of v2.5.0.
+
+#### 🎯 Core Principles
+
+- **No Simulation** - Must prove real AES-NI hardware through timing analysis
+- **Atomic Precision** - Highest trust requires physical time sources
+- **Mathematical Consensus** - Revocation through signature counting, not voting
+
+#### ✅ Implemented Features
+
+**Mesh-Consensus Revocation** (`security/mesh-revocation.js`)
+- 2/3 threshold attestation-based revocation
+- Post-quantum signed attestations (ML-DSA-65)
+- Revocation certificates with threshold proof
+- **41 tests**
+
+**Hardware Attestation** (`security/hardware-attestation.js`)
+- AES-NI timing verification to prove real silicon
+- Challenge-response protocol for peer verification
+- Bot farms and VMs fail timing checks
+- **5 tests**
+
+**Trust Tier System** (`security/trust-tier.js`)
+- ORACLE (2.0x): Atomic clock + AES-NI + 30 days
+- ANCHOR (1.5x): GPS+PPS + AES-NI + 14 days  
+- SENTINEL (1.25x): PTP + AES-NI + 7 days
+- PARTICIPANT (1.0x): NTP + AES-NI
+- OBSERVER (0.25x): Unverified
+- **35 tests**
+
+**Silicon Parity** (`security/silicon-parity.js`)
+- "One Silicon = One Vote" anti-ASIC/farm defense
+- Weight division: `tierMax / coreCount`
+- 100-core rig = same weight as 1-core
+- AES-NI fingerprint as unique silicon identity
+- **36 tests**
+
+**Sybil Graph Analysis** (`security/sybil-graph.js`)
+- Clustering coefficient detection (>0.7 = suspicious)
+- Edge cut ratio analysis (<0.1 = insular cluster)
+- Component analysis for cluster isolation
+- Behavior correlation (uptime, activity patterns)
+- **44 tests**
+
+**KHATA Trust Integration** (`security/khata-trust-integration.js`)
+- Gossip layer for trust messages over KHATA protocol
+- 8 new message types for attestation/challenge routing
+- Deduplication and hop limit enforcement
+- Trust synchronization between peers
+- **22 tests**
+
+**Strike System** (`security/strike-system.js`)
+- "Three Strikes — Then Math Speaks"
+- Hardware fingerprint tracks identity across fresh starts
+- Strike 1: Fresh start allowed, recorded
+- Strike 2: 7-day probation, reduced trust (0.5x)
+- Strike 3: Permanent network ban
+- Revocation bridge for automated strike issuance
+- **31 tests**
+
+#### 📊 Test Summary
+
+| Module | Tests | Status |
+|--------|-------|--------|
+| Mesh Revocation | 41 | ✅ |
+| Hardware Attestation | 5 | ✅ |
+| Trust Tiers | 35 | ✅ |
+| Silicon Parity | 36 | ✅ |
+| Sybil Graph | 44 | ✅ |
+| KHATA Integration | 22 | ✅ |
+| Strike System | 31 | ✅ |
+| **v2.4 Total** | **214** | ✅ |
+
+**Project Total**: 598 + 214 = **812 tests**
+
+See [ROADMAP-2.4.0.md](docs/ROADMAP-2.4.0.md) for full details.
+
+---
+
+## [2.3.0] - 2026-01-20
+
+### 🧪 Testing Expansion, BYOND Adapter & Bug Fixes
+
+This release expands test coverage from 352 to 598 tests with comprehensive mesh module testing and adds the BYOND game server adapter.
+
+#### 📊 Test Coverage
+
+| Module | Tests | Status |
+|--------|-------|--------|
+| **Oracle** | 98 | ✅ All passing |
+| **Protocol** | 56 | ✅ All passing |
+| **Multi-Node** | 18 | ✅ All passing |
+| **BYOND Adapter** | 36 | ✅ All passing |
+| **Security (Vitest)** | 390 | ✅ All passing (55 skipped) |
+| **Total** | **598** | **543 passing, 55 skipped** |
+
+#### 🎮 BYOND Game Server Adapter
+
+New adapter for integrating BYOND games (Space Station 13, Pondera, etc.) with Yakmesh:
+
+- **Topic Protocol** - Native BYOND wire protocol implementation
+- **HTTP Bridge** - REST API for DreamDaemon communication
+- **Server Discovery** - Find BYOND servers via mesh gossip
+- **World Persistence** - Save/load world data to mesh storage
+- **DOKO Integration** - Cryptographic identity for game servers
+- **DMAPI Library** - Drop-in DM code for game developers
+
+**Files:**
+- `adapters/adapter-byond/index.js` - Main adapter
+- `adapters/adapter-byond/topic-client.js` - Wire protocol
+- `adapters/adapter-byond/http-bridge.js` - HTTP server
+- `adapters/adapter-byond/security.js` - DOKO verification
+- `adapters/adapter-byond/dmapi/` - DM library
+
+#### ✅ New Test Files
+
+- `mesh/tests/nakpak-routing.test.js` - 52 tests for NAKPAK onion routing
+- `mesh/tests/sherpa-discovery.test.js` - 57 tests for SHERPA peer discovery
+- `mesh/tests/annex.test.js` - 64 tests for ANNEX encrypted channels
+- `security/tests/khata-protocol.test.js` - 38 tests for KHATA trust protocol
+- `security/tests/mesh-auth.test.js` - 54 tests for WebSocket authentication
+- `adapters/adapter-byond/tests/*.test.js` - 36 tests for BYOND integration
+
+#### 🐛 Bug Fixes
+
+- **Fixed ML-KEM768 cipherText capitalization** - `ml_kem768.encapsulate()` returns `{cipherText}` with capital T, not `{ciphertext}`. Fixed in `nakpak-routing.js` and `annex.js`
+- **Fixed mesh-auth.js import** - Changed `@noble/hashes/sha3` to `@noble/hashes/sha3.js` for proper ESM resolution
+- **Fixed oracle path normalization** - Consistent cross-platform path handling
+
+#### 🤖 YakBot Updates
+
+- Updated to v2.3.0 with current features
+- Enhanced AI context with NAMCHE/DOKO, adapters, 598 tests
+- New FAQ entry for security features
+- Added YakBot deployment package to build system
+
+#### 📝 Notes
+
+Some tests are skipped pending full key exchange implementation or complex async mocking requirements. These represent edge cases that work correctly in production but need specialized test infrastructure.
+
+## [2.2.0] - 2026-01-18
+
+### ✨ YAK:// Protocol v2.2.0 - Remote Bookmarks, DOKO Revocation & Comprehensive Testing
+
+**This release includes all features from v2.0.1, v2.1.0, and v2.2.0 (combined release).**
+
+#### 📋 Complete v2.2.0 Feature Summary
+
+| Category | Features Added |
+|----------|----------------|
+| **YAK:// Protocol** | Custom URL scheme, builtin routes, content addressing |
+| **Local Bookmarks** | Pet names, CLI commands, REST API, dashboard UI |
+| **Remote Bookmarks** | Mesh gossip sync, subscribe/publish, priority resolution |
+| **DOKO Revocation** | Self-revocation, emergency certificates, reason codes |
+| **SSL/TLS Binding** | Certificate fingerprints, domain binding, verification |
+| **Domain Transfers** | Request/authorize workflow, completion proofs |
+| **TypeScript** | Full `.d.ts` type definitions |
+| **Testing** | 352 tests (Oracle 98, Protocol 56, Multi-Node 18, Security 180) |
+| **Developer Experience** | Vitest config, npm scripts, expanded README |
+| **Bug Fixes** | ML-DSA-65 argument order, beacon signature verification |
+
+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"

package/README.md

@@ -51,15 +51,30 @@ In an era where traditional ECDSA is increasingly vulnerable and network jitter
 - ⏱️ **Precision Timing** - Support for atomic clocks, GPS, PTP, NTP
 - 🔌 **Plugin Architecture** - Adapters for any database or API
 - 🛡️ **Phase Modulation** - Time-based anti-replay protection
+- 🌍 **Geographic Exclusion** - Speed-of-light physics prove where nodes CANNOT be
 
-### v2.0 — The Sherpa Security Stack
+### v2.5 — The Complete Stack
 
+**Identity & Trust:**
 - 🧭 **NAMCHE Gateway** - 7-gate mathematical verification (no CA required)
 - 📜 **DOKO Identity** - Self-sovereign identity documents verified by mesh
+- 🏆 **Trust Tiers** - ORACLE/ANCHOR/SENTINEL/PARTICIPANT hierarchy
+- 🔬 **Hardware Attestation** - AES-NI timing proves real silicon
+- ⚖️ **Silicon Parity** - "One silicon = one vote" anti-farm defense
+- ⚠️ **Strike System** - Three strikes with hardware fingerprint tracking
+
+**Networking:**
 - 🏔️ **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
+- 🔗 **YAK:// Protocol** - Mesh-native URL scheme with bookmarks
+
+**Advanced:**
+- 🌍 **Geographic Proof** - Speed-of-light exclusion zones
+- 🕵️ **Sybil Detection** - Graph analysis for fake identity clusters
+- 📡 **ECHO Ranging** - Privacy-preserving topology discovery
+- 💓 **PULSE Heartbeat** - Liveness detection and partition recovery
+- 🚨 **BEACON Alerts** - Priority emergency broadcast
 
 ## Quick Start
 
@@ -104,7 +119,8 @@ yakmesh/
 │   ├── 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
+│   ├── domain-consensus.js  # Mesh-verified domains
+│   └── geo-proof.js         # Speed-of-light geographic exclusion
 ├── oracle/           # Self-verifying validation engine
 ├── mesh/             # WebSocket P2P networking
 │   ├── sherpa-discovery.js  # Decentralized peer discovery
@@ -159,6 +175,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 |
@@ -171,6 +253,20 @@ 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 |
+| `/geo/status` | GET | Geographic proof status |
+| `/geo/landmarks` | GET/POST | List or add landmarks |
+| `/geo/zones` | GET | List exclusion zones |
+| `/geo/prove` | POST | Generate geographic proof |
+| `/geo/verify` | POST | Verify another node's claims |
 
 ## Pro Features