From fa20607e35119f5552d5ce76b64dec3d3b217088 Mon Sep 17 00:00:00 2001 From: Siavash Sameni Date: Thu, 26 Mar 2026 20:44:47 +0400 Subject: [PATCH] DESIGN.md: resolve open questions, add transport layer architecture Decisions: Sender Keys for groups, optional onion routing, deniability by default, Bluetooth + LoRa transports, no tokenization. New sections: transport abstraction (HTTPS/WS/BT/LoRa/Wi-Fi Direct/USB), LoRa compact binary format, sealed sender vs onion routing discussion. Co-Authored-By: Claude Opus 4.6 (1M context) --- DESIGN.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 95 insertions(+), 10 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 89925e7..05c7952 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -399,33 +399,118 @@ warzone.wasm # browser client (via wasm-pack) - [ ] Partial sync / resume - [ ] Priority levels - [ ] Mule CLI binary -- [ ] Bluetooth/local transfer mode -### Phase 5 — Polish & Operations +### Phase 5 — Transport Fallbacks +- [ ] Bluetooth mule transfer (phone-to-phone, phone-to-server) +- [ ] LoRa transport layer (low bandwidth, long range, last-resort) +- [ ] mDNS / LAN discovery for local mesh +- [ ] Wi-Fi Direct for nearby device sync + +### Phase 6 — Metadata Protection (Optional Layer) +- [ ] Onion routing between federated servers (opt-in, requires good connectivity) +- [ ] Padding and traffic shaping to resist traffic analysis +- [ ] Sealed sender (server doesn't know who sent a message, only who receives) + +### Phase 7 — Polish & Operations - [ ] ntfy integration for push notifications - [ ] DoH for DNS resolution in censored networks -- [ ] mDNS for LAN discovery - [ ] Admin CLI (manage users, mules, federation) - [ ] Monitoring and health checks - [ ] Rate limiting and abuse prevention - [ ] Audit logging +- [ ] Server-at-rest encryption (optional, manual key on boot) - [ ] Cross-compilation CI (Linux x86/ARM, macOS, Windows, WASM) - [ ] Documentation and protocol specification --- +## Resolved Decisions + +| Question | Decision | Rationale | +|----------|----------|-----------| +| MLS vs Sender Keys | **Sender Keys** (groups ≤ 50) | Simpler, sufficient for target group sizes. MLS revisited if needed later. | +| Metadata protection | **Optional onion layer** | Opt-in when connectivity allows. Not a blocker for core functionality. Sealed sender as a lighter alternative first. | +| Deniability | **Deniability by default** (Signal model) | Safety-first for users in hostile environments. Non-repudiation can be added as opt-in per-conversation later. | +| Server-at-rest encryption | **Optional, not in core** | Nice to have. Implement as a flag: `--encrypt-db` with passphrase on boot. E2E already protects message content. | +| Incentives / tokenization | **Not in scope** | This is an organizational/military tool. Participants cooperate by mandate, not incentive. | +| Transport fallbacks | **Bluetooth + LoRa** | Mules use Bluetooth for device-to-device. LoRa for extreme last-resort (low bandwidth but km range). | + ## Open Questions -1. **MLS vs Sender Keys**: For groups > 50, should we adopt MLS (RFC 9420) instead of Sender Keys? MLS has better forward secrecy but is more complex. +1. **Key transparency**: Should we implement a transparency log for identity keys (like CONIKS)? Prevents server MITM on key exchange. Adds complexity but significantly hardens the trust model. Could be Phase 7+. -2. **Metadata protection**: Even with E2E encryption, the server sees who messages whom. Do we need onion routing or mix networks? This adds latency — problematic in warzone with already-bad connectivity. +2. **LoRa message format**: LoRa has ~250 byte payload limit. Need a compact binary format for LoRa transport — possibly just delivery receipts and tiny text messages, not full media. How much do we invest here vs treating it as emergency-only? -3. **Deniability**: Signal provides deniability (can't prove someone sent a message). Do we want this, or do we want non-repudiation (provable authorship) for warzone accountability? +3. **Legal**: E2E encryption with mule delivery designed for warzone use has significant legal implications in many jurisdictions. Needs legal review before deployment. -4. **Server storage encryption**: Should the server encrypt its queue database at rest? If the server is captured, queued ciphertext is already unreadable (E2E), but metadata (who messaged whom, timestamps) would be exposed. +4. **Sealed sender vs onion routing**: Sealed sender (Signal's approach — server knows recipient but not sender) is lighter than full onion routing. Implement sealed sender first as the default metadata protection, onion routing as Phase 6 upgrade? -5. **Key transparency**: Should we implement a transparency log for identity keys (like CONIKS or Key Transparency)? This prevents the server from silently substituting keys for MITM attacks. Adds complexity but significantly improves trust model. +5. **Multi-device conflict resolution**: When two devices are offline and both send messages, how do we resolve Double Ratchet state conflicts on sync? Signal handles this per-device (each device has its own session). Do we want shared-session across devices (harder, requires device-to-device sync)? -6. **Mule incentives**: In a warzone, why would someone risk being a mule? Is there a crypto-economic incentive model, or is this purely for military/organizational use where participants are ordered to cooperate? +--- -7. **Legal**: End-to-end encryption with mule delivery designed for warzone use has significant legal implications in many jurisdictions. This needs legal review before deployment. +## 8. Transport Layer Architecture + +The protocol is transport-agnostic. The message format is the same regardless of how it travels. Transports are pluggable: + +``` +┌─────────────────────────────────────────────┐ +│ Application Layer │ +│ (Signal Protocol, Message Routing, Queue) │ +├─────────────────────────────────────────────┤ +│ Transport Abstraction │ +│ trait Transport { │ +│ async fn send(&self, endpoint, blob); │ +│ async fn recv(&self) -> blob; │ +│ } │ +├──────┬──────┬──────┬──────┬────────┬────────┤ +│ HTTPS│ WS │ BT │ LoRa │Wi-Fi │ USB │ +│ │ │ │ │Direct │ (file) │ +└──────┴──────┴──────┴──────┴────────┴────────┘ +``` + +### HTTPS (Primary) +- Standard server-to-server and client-to-server +- TLS 1.3, certificate pinning +- HTTP/2 for multiplexing +- SSE or WebSocket for real-time push + +### Bluetooth (Mule + Nearby) +- BLE for discovery, Bluetooth Classic for data transfer +- Range: ~10-100m +- Bandwidth: ~2 Mbps practical +- Use case: mule syncs with server/client in proximity +- Protocol: RFCOMM socket, same message blobs as HTTPS + +### LoRa (Last Resort) +- Range: 2-15 km (line of sight), 1-5 km urban +- Bandwidth: 0.3-50 kbps +- Payload: ~250 bytes per packet +- Use case: delivery receipts, short text, presence beacons +- NOT for files or media — text-only, heavily compressed +- Message format: compact binary (not JSON) + +``` +LoRa packet (250 bytes max): + [1] version + [1] type (text=0x01, receipt=0x02, beacon=0x03) + [8] sender fingerprint (truncated) + [8] recipient fingerprint (truncated) + [4] timestamp (unix, 32-bit) + [12] nonce + [~216] ciphertext (AES-GCM, ~200 chars of text) +``` + +### Wi-Fi Direct (Nearby Mesh) +- Range: ~200m +- Bandwidth: ~250 Mbps +- Use case: local group sync when no internet, ad-hoc mesh +- Devices form a local group, sync message queues peer-to-peer + +### USB / File (Sneakernet) +- Export message queue to encrypted file +- Copy to USB drive +- Import on destination machine +- Same as mule protocol but manual file transfer +- `warzone export --since 24h --to /mnt/usb/messages.wz` +- `warzone import /mnt/usb/messages.wz`