Sterister
e6fdf31b49
Some checks failed
Test / test (push) Has been cancelled
Cross-platform vectors / TypeScript vectors (bun) (push) Has been cancelled
Cross-platform vectors / Kotlin vectors (gradle) (push) Has been cancelled
Docker build and publish / docker (push) Has been cancelled
Publish / publish (push) Has been cancelled
V3.1 → V3.12 consolidated and tagged for the first GA release. Wire format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers byte-for-byte. The version bump is semantic: audit-cycle complete, opt-in surface fully exposed, threat model refreshed for every new surface. Highlights: - All 24 @shade/* packages bumped to 4.0.0 in lockstep. - CHANGELOG 4.0.0 section is the canonical manifest of what landed. - THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12 Web-Worker boundary) + residual-risks table refreshed. - OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox, bridge, observer, /metrics, /healthz, /ready. - MIGRATION 0.3.x → 4.0 documented + smoke-tested against shade migrate-storage on a real SQLite DB. - docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer. - scripts/soak.ts harness for the GA-stable 2-week soak window. - All V*.md plans archived under docs/archive/ with Status: Done. - Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen non-realtime stack. Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green. Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports version 4.0.0 on /health. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# Shade V3.11 — WebRTC P2P Transport
|
||
|
||
**Status:** Done — landet med `@shade/transport-webrtc` 0.4.0,
|
||
`MultiTransportFallback` i `@shade/transfer`, og
|
||
`shade.configureWebRTC()` i `@shade/sdk`. Se [docs/webrtc.md](../webrtc.md).
|
||
**Effort:** XL (2–4 måneder)
|
||
**Forrige:** V3.7
|
||
**Adresserer:** V2.1-tillegg "P2P WebRTC transport"
|
||
|
||
---
|
||
|
||
## Mål
|
||
|
||
Direct peer-to-peer datakanal mellom Shade-klienter når NAT/firewall
|
||
tillater. Primær gevinst: massiv throughput for `@shade/transfer`
|
||
(filer, store payloads) og lav-latens for messaging når begge peere
|
||
er online samtidig. E2EE bevart: WebRTC DTLS-SRTP er **transport** —
|
||
payload er fortsatt Shade ratchet-krypto.
|
||
|
||
V3.11 lander i V4.0-vinduet og er foundation-only — sanntidsbruken
|
||
(voice, video, broadcast) ligger i [V5.0](../V5.0.md) som downstream
|
||
konsumer av denne datakanalen.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### Inn
|
||
|
||
- Ny pakke `@shade/transport-webrtc`.
|
||
- Signaling via Shade control plane (eksisterende kanal — `Shade.send`).
|
||
- ICE/STUN: bruk offentlige STUN-servere som default.
|
||
- TURN: konfigurerbar TURN-relay som fallback.
|
||
- DataChannel for `@shade/transfer`-chunks.
|
||
- Auto-fallback: P2P → HTTP (eksisterende stack).
|
||
|
||
### Ut
|
||
|
||
- SFU/MCU (mange-til-mange topologi) — broadcast/video er V5.0.
|
||
- Voice/video media-tracks — V3.11 er ren datakanal (DataChannel);
|
||
audio/video over RTP er V5.0.
|
||
- DTLS-fingerprint-binding til Shade-fingerprint (vurderes som hardening,
|
||
men ikke krav).
|
||
|
||
---
|
||
|
||
## Design
|
||
|
||
### Connection-flow
|
||
|
||
```text
|
||
A initierer:
|
||
1. createOffer() → SDP
|
||
2. shade.send(B, { kind: "webrtc-offer", sdp })
|
||
3. B mottar over Shade-kanal, createAnswer()
|
||
4. shade.send(A, { kind: "webrtc-answer", sdp })
|
||
5. ICE-candidates exchange (samme kanal)
|
||
6. DataChannel åpen
|
||
```
|
||
|
||
### Wrapping
|
||
|
||
DataChannel sender ferdige `@shade/transfer`-chunks (allerede E2EE).
|
||
WebRTC's egen DTLS-SRTP fungerer som transport-secrecy lag.
|
||
|
||
### Topologi
|
||
|
||
- 1:1 P2P direkte når mulig.
|
||
- TURN-relay når NAT'er er for strenge (transport-only, ser ikke plaintext).
|
||
|
||
---
|
||
|
||
## Leveranser
|
||
|
||
### Pakker
|
||
|
||
- `@shade/transport-webrtc` — Connection, DataChannel-wrapper, ICE-config.
|
||
- `@shade/transfer` utvides: `WebRTCTransferTransport` som drop-in.
|
||
- `FallbackTransferTransport` får ny ledd: P2P → WS → HTTP.
|
||
|
||
### Tester
|
||
|
||
- Loopback unit: offer/answer/ICE i Bun via `node-datachannel` eller
|
||
`wrtc`.
|
||
- Integration: 100 MB transfer over P2P vs HTTP — P2P skal vinne på samme
|
||
nettverk.
|
||
- Failover: TURN-relay påtvinger relay-modus.
|
||
- NAT-emulering (loopback med ulike NAT-typer hvis mulig).
|
||
|
||
### Dokumentasjon
|
||
|
||
- `docs/webrtc.md` — setup, STUN/TURN-config, NAT-traversal-håp og
|
||
-realiteter.
|
||
|
||
---
|
||
|
||
## Akseptansekriterier
|
||
|
||
- [ ] To klienter på samme LAN: P2P direct uten TURN, throughput > 5x
|
||
HTTP-baseline.
|
||
- [ ] To klienter bak strenge NAT'er: TURN-relay aktiveres automatisk.
|
||
- [ ] Failover P2P-død → HTTP innen 5 s uten meldingstap.
|
||
|
||
---
|
||
|
||
## Avhengigheter
|
||
|
||
- V3.7 — bridge-mønstre + fallback-arkitektur.
|
||
|
||
---
|
||
|
||
## Risiko
|
||
|
||
- **NAT-traversal-helvete.** Mange edge-cases. Mitiger med tidlige
|
||
integration-tester på faktiske NAT-konfigurasjoner.
|
||
- **Browser-kompatibilitet.** Safari har sine egne RTC-quirks.
|
||
- **TURN-koster.** TURN-relay = ekte trafikk gjennom server. Operatør må
|
||
vite det.
|
||
|
||
---
|
||
|
||
## Migrasjon
|
||
|
||
Opt-in. Eksisterende HTTP/WS-transport fungerer uendret.
|