Sovereign Communications

A decentralized, end-to-end encrypted mesh networking communication platform that works across Web, Android, and iOS with no central servers.

🌟 Features

• End-to-End Encryption: All messages encrypted with Ed25519 signing and ChaCha20-Poly1305 encryption
• Mesh Networking: Direct peer-to-peer communication with automatic message relay
• Multi-Platform: Works on Web (PWA), Android, and iOS
• No Servers: Completely decentralized with no reliance on central infrastructure
• Perfect Forward Secrecy: Session keys rotate automatically to protect past communications
• Multi-Transport: Uses WebRTC, Bluetooth Low Energy, and local network discovery

📊 V1.0 Status

Current Version: 0.1.0 → 1.0.0 (Release Candidate)

Component	Status	Tests	Notes
Core Library	✅ Ready	786/786 passing	All cryptographic and networking primitives complete
Web App	✅ Ready	~90% passing	File transfer implemented, E2E tests being finalized
Android App	⚙️ Configured	Pending	Builds successfully, needs SDK setup
iOS App	⏸️ Pending	Pending	Needs Xcode configuration
Documentation	✅ Complete	N/A	API docs, architecture, and guides complete

See V1.0 Release Checklist for detailed status.

🏗️ Architecture

The project is organized as a monorepo with the following structure:

SC/
├── core/           # Shared cryptography and protocol implementation
│   ├── src/
│   │   ├── crypto/       # Cryptographic primitives
│   │   ├── protocol/     # Binary message format
│   │   ├── mesh/         # Routing and peer management
│   │   └── transport/    # Transport abstractions
├── web/            # Web application (Vite + React + TypeScript)
├── android/        # Android application (Kotlin)
├── ios/            # iOS application (Swift)
└── docs/           # Documentation

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• For Android: Android Studio with Kotlin support
• For iOS: Xcode with Swift support

Installation

1. Clone the repository:

git clone https://github.com/Treystu/SC.git
cd SC

2. Install dependencies:

npm install

3. Build the core library:

cd core
npm run build
npm test

4. Run the web application:

cd ../web
npm install
npm run dev

The web app will be available at http://localhost:3000

📦 Core Library

The @sc/core library provides the foundational cryptography and networking primitives used across all platforms.

Cryptographic Primitives

import { 
  generateIdentity, 
  signMessage, 
  verifySignature,
  encryptMessage,
  decryptMessage 
} from '@sc/core';

// Generate identity keypair
const identity = generateIdentity();

// Sign a message
const message = new TextEncoder().encode('Hello, mesh!');
const signature = signMessage(message, identity.privateKey);

// Verify signature
const isValid = verifySignature(message, signature, identity.publicKey);

// Encrypt/decrypt messages
import { generateSessionKey } from '@sc/core';
const sessionKey = generateSessionKey();
const ciphertext = encryptMessage(message, sessionKey.key, sessionKey.nonce);
const plaintext = decryptMessage(ciphertext, sessionKey.key, sessionKey.nonce);

Message Protocol

import { MessageType, encodeMessage, decodeMessage } from '@sc/core';

const message = {
  header: {
    version: 0x01,
    type: MessageType.TEXT,
    ttl: 10,
    timestamp: Date.now(),
    senderId: identity.publicKey,
    signature: messageSignature,
  },
  payload: encryptedContent,
};

// Encode to binary
const encoded = encodeMessage(message);

// Decode from binary
const decoded = decodeMessage(encoded);

Mesh Routing

import { RoutingTable, Peer } from '@sc/core';

const routingTable = new RoutingTable();

// Add a peer
const peer: Peer = {
  id: 'peer-id',
  publicKey: peerPublicKey,
  lastSeen: Date.now(),
  connectedAt: Date.now(),
  transportType: 'webrtc',
  connectionQuality: 100,
  bytesSent: 0,
  bytesReceived: 0,
};

routingTable.addPeer(peer);

// Find route to destination
const nextHop = routingTable.getNextHop('destination-id');

// Message deduplication
if (!routingTable.hasSeenMessage(messageHash)) {
  routingTable.markMessageSeen(messageHash);
  // Process message
}

🌐 Web Application

Built with Vite, React, and TypeScript, the web app provides a modern PWA experience.

Features Implemented

• ✅ Basic UI layout with conversation list and chat view
• ✅ Connection status indicator
• ✅ Message input and display
• ✅ Dark theme with responsive design
• 🚧 IndexedDB persistence (in progress)
• 🚧 WebRTC peer connections (in progress)
• 🚧 Service worker for offline support (planned)

Development

cd web
npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build

📱 Mobile Applications

Android ✅ Foundation Complete

• ✅ Kotlin with Jetpack Compose UI (Material 3)
• ✅ Room database for persistence
• ✅ Foreground service for persistent connectivity
• ✅ Conversation list, contact list, and settings UI
• ✅ Modern Material 3 theming (light/dark)
• 🚧 BLE mesh networking (in progress)
• 🚧 WebRTC peer connections (in progress)
• 🚧 Chat UI with message bubbles (planned)
• 🚧 Notifications with actions (planned)

Build: cd android && ./gradlew assembleDebug

iOS (Planned)

• Swift with SwiftUI
• Core Data for persistence
• Background modes for connectivity
• CoreBluetooth for BLE mesh
• WebRTC peer connections

🔒 Security

Cryptographic Stack

• Identity: Ed25519 public-key cryptography for signing
• Key Exchange: ECDH (X25519) for establishing shared secrets
• Encryption: XChaCha20-Poly1305 AEAD cipher
• Hashing: SHA-256 for fingerprints and message hashes
• Libraries: @noble/curves and @noble/ciphers - audited, minimal dependencies

Message Format

Each message has a fixed 109-byte header:

• Version (1 byte): Protocol version
• Type (1 byte): Message type
• TTL (1 byte): Time-to-live for routing
• Reserved (1 byte): Future use
• Timestamp (8 bytes): Unix timestamp in ms
• Sender ID (32 bytes): Ed25519 public key
• Signature (65 bytes): Compact Ed25519 signature

Payload is encrypted with session keys that rotate automatically for perfect forward secrecy.

🧪 Testing

# Run core library tests
cd core
npm test

# With coverage
npm test -- --coverage

# Run all tests
npm test

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

Current test coverage:

• ✅ Cryptographic primitives (38 tests)
• ✅ Message encoding/decoding
• ✅ Routing table and peer management
• ✅ Message queue prioritization

🚀 CI/CD

The project uses comprehensive GitHub Actions workflows for continuous integration and deployment across all platforms.

Automated Testing & Building

Every push and pull request triggers:

• Linting: ESLint (TypeScript), ktlint (Kotlin), SwiftLint (Swift)
• Building: Web, Android, and iOS applications
• Unit Tests: Core library (Node 18, 20, 22)
• Integration Tests: Cross-platform functionality
• E2E Tests: Playwright tests across browsers
• Security Audit: Dependency vulnerability scanning

Release Automation

Tagged releases automatically:

• Build production artifacts for all platforms
• Run full test suite
• Create GitHub releases with changelogs
• Attach platform-specific installers:
  • Web: web-{version}.tar.gz
  • Android: sovereign-communications-{version}.apk
  • iOS: Build artifacts

Release Types:

• v1.0.0 - Production release
• v1.0.0-beta.1 - Beta release
• v1.0.0-alpha.1 - Alpha release

For detailed CI/CD documentation, see docs/ci-cd.md.

Documentation

• Documentation Index
• Architecture
• API Reference
• V1 Rollout Tasks 🚀

📖 Protocol Specification

Peer Discovery

1. Local Network: mDNS/Bonjour broadcasting
2. QR Code: Encode public key + optional connection info
3. Audio Pairing: DTMF tone encoding (proximity pairing)
4. BLE: Bluetooth Low Energy RSSI-based discovery
5. Manual Entry: Direct IP:port input
6. Mesh Introduction: Existing peers introduce new peers

Mesh Routing

• Flood Routing: Messages forwarded to all peers except sender
• TTL Decrement: Each hop decrements TTL; message expires at 0
• Deduplication: SHA-256 hash cache prevents duplicate processing
• Priority Queue: Control > Voice > Text > File transfers
• Fragmentation: Large messages split for transmission

Transport Priority

1. WebRTC Data Channels (lowest latency, NAT traversal)
2. Bluetooth Low Energy (mobile mesh, no internet required)
3. Local Network (direct connections on same network)

🗺️ Roadmap

Phase 1: Foundation ✅ Complete

• Core cryptography library
• Binary message protocol
• Mesh routing basics
• Web UI foundation
• IndexedDB persistence
• WebRTC implementation
• Peer health monitoring
• Peer discovery mechanisms
• Android application foundation NEW

Phase 2: Core Functionality (In Progress)

• Android UI (conversation list, contacts, settings)
• Android Room database
• Android foreground service
• Android chat UI with message bubbles
• Android notifications with actions
• Android BLE integration
• Complete web UI features
• File transfer protocol
• Voice messages (Opus encoding)
• iOS application

Phase 3: Advanced Features

• BLE mesh networking (mobile)
• Whisper.cpp integration (voice-to-text)
• Multi-device sync
• Group messaging
• Message search
• QR code scanner UI

Phase 4: Polish

• UI/UX refinement
• Performance optimization
• Battery optimization (mobile)
• Comprehensive testing
• Security audit

🤝 Contributing

This is currently a development project implementing a comprehensive feature set. Contributions welcome once the initial implementation is complete.

📄 License

MIT License - See LICENSE file for details

🔗 Resources

• Protocol Specification (coming soon)
• Security Model (coming soon)
• API Documentation (coming soon)

⚠️ Status

Alpha Development: Core infrastructure complete with Android app foundation. Not ready for production use.

Progress: 67/285 tasks (23.5%)

What Works

• ✅ Complete cryptographic library (Ed25519, X25519, ChaCha20-Poly1305)
• ✅ Binary message protocol with fragmentation
• ✅ Mesh routing with flood algorithm and TTL
• ✅ WebRTC transport layer
• ✅ Peer health monitoring with heartbeats
• ✅ Peer discovery (QR, manual, introduction)
• ✅ Web UI with mesh integration
• ✅ IndexedDB persistence (web)
• ✅ Android app with Room database and Compose UI NEW
• ✅ Android foreground service NEW

In Progress

• 🚧 Chat UI implementation (Android)
• 🚧 Notification system (Android)
• 🚧 BLE mesh networking (Android)
• 🚧 iOS application

Testing

• ✅ 38 unit tests passing (100%)
• ✅ Zero security vulnerabilities (CodeQL)
• ✅ Web app builds successfully
• ⏳ Android APK builds (not yet tested)
• ⏳ Integration tests (planned)

Completed Tasks

Foundation - Protocol & Crypto (10 tasks)

• ✅ 1. Define binary message format
• ✅ 2. Implement ECDH key exchange protocol
• ✅ 3. Implement Ed25519 for message signing
• ✅ 4. Implement ChaCha20-Poly1305 for message encryption
• ✅ 5. Generate and store identity keypair on device
• ✅ 6. Implement message encryption/decryption
• ✅ 7. Implement message signing/verification
• ✅ 8. Create secure key storage (IndexedDB Web, Memory for Node)
• ✅ 9. Implement perfect forward secrecy with session keys
• ✅ 10. Create session key rotation logic

Mesh Networking Core (12 tasks) ✅ 11/12 (92%)

• ✅ 11. Implement in-memory routing table
• ✅ 12. Create peer registry (connected peers)
• ✅ 13. Implement message TTL decrement and expiration
• ✅ 14. Create message deduplication cache (hash-based)
• ✅ 15. Implement flood routing (forward to all peers except sender)
• ✅ 16. Create message relay logic
• ✅ 17. Implement peer health monitoring (heartbeat) NEW
• ⏳ 18. Create peer timeout and removal (partial - implemented in health monitor)
• ✅ 19. Implement message fragmentation (for large messages)
• ✅ 20. Create message reassembly logic
• ✅ 21. Implement message priority queue (control > voice > text > file)
• ⏳ 22. Create bandwidth-aware message scheduling (planned)

WebRTC Peer-to-Peer (10 tasks) ✅ COMPLETE

• ✅ 23. Initialize WebRTC PeerConnection
• ✅ 24. Implement data channel creation (unreliable for real-time, reliable for messages)
• ✅ 25. Create SDP offer/answer exchange via existing peer (mesh signaling)
• ✅ 26. Implement ICE candidate exchange via mesh
• ✅ 27. Create signaling through already-connected peers
• ✅ 28. Implement data channel message handlers
• ✅ 29. Create WebRTC connection state monitoring
• ✅ 30. Implement automatic reconnection on failure
• ✅ 31. Create graceful peer disconnection
• ✅ 32. Implement NAT traversal without STUN/TURN (rely on mesh relay)

Peer Discovery (10 tasks) ✅ 7/10 (70%)

• ⏳ 47. Implement local network mDNS/Bonjour broadcasting (planned)
• ⏳ 48. Create mDNS service discovery (planned)
• ✅ 49. Implement QR code identity exchange (encoded public key + IP) NEW
• ⏳ 50. Create QR code scanner (UI - planned)
• ⏳ 51. Implement audio tone pairing (DTMF encoding/decoding) (planned)
• ⏳ 52. Create proximity pairing via BLE RSSI (planned)
• ✅ 53. Implement manual IP:port peer entry NEW
• ✅ 54. Create "introduce peer" relay (A tells B about C's existence) NEW
• ✅ 55. Implement peer announcement broadcast through mesh NEW
• ✅ 56. Create peer reachability verification NEW

Web Application (31 tasks) 🚧 9/31 (29%)

• ✅ 123. Set up Vite + React + TypeScript
• ✅ 124. Implement IndexedDB for messages/contacts
• ✅ 136. Implement main app layout
• ✅ 137. Create conversation list component
• ✅ 138. Implement chat component
• ✅ 139. Create message input component
• ✅ 153. Create basic theme (dark theme)
• ✅ React hook for mesh network integration
• ✅ Live connection status display
• ⏳ 125-152: Advanced features (in progress)

Android Application (33 tasks) ✅ 11/33 (33%) NEW

• ✅ 57. Set up Android project (Kotlin)
• ✅ 58. Implement Room database for messages/contacts
• ✅ 59. Create message persistence
• ✅ 60. Implement contact persistence
• ✅ 61. Create conversation persistence
• ✅ 62. Implement foreground service for persistent connectivity
• ✅ 73. Create main activity with navigation
• ✅ 74. Implement conversation list UI (LazyColumn)
• ✅ 78. Implement contact list UI
• ✅ 82. Implement settings screen
• ✅ 89. Create basic theme (light/dark)
• ⏳ 63-65: Notifications (planned)
• ⏳ 66-67: WebRTC Android SDK (planned)
• ⏳ 68-72: BLE integration (planned)
• ⏳ 75-77, 79-81, 83-88: Additional UI features (planned)

Testing (8 tasks)

• ✅ 250. Create unit tests for crypto functions
• ✅ 251. Implement unit tests for message routing
• ⏳ 252-257: Integration and E2E tests (planned)

Documentation (7 tasks)

• ✅ 259. Write README with quick start
• ✅ 260. Create setup instructions per platform
• ⏳ 261-265: Additional documentation (in progress)

Build & Release (10 tasks)

• ✅ 266. Set up Git repository
• ✅ 267. Create .gitignore files
• ⏳ 268-275: CI/CD and release process (planned)

Progress: 67/285 tasks completed (23.5%)