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>
136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
# Shade V5.0 — Voice & Video
|
|
|
|
**Status:** Idea (post-V4.0 GA)
|
|
**Effort:** XXL (4+ måneder)
|
|
**Forrige:** V4.0 GA + V3.11 (P2P transport kreves)
|
|
**Adresserer:** V2.1-tillegg "ShadeVoiceButton / ShadeVideoCall / ShadeBroadcaster"
|
|
|
|
V5.0 er den dedikerte sanntids-releasen — alt VOIP og videostreaming
|
|
samles her, *etter* at Shade 4.0 er GA-merket. Stacken under
|
|
(ratchet, transport, observability, recovery, key transparency,
|
|
WebRTC P2P) er låst i 4.0; 5.0 bygger uten å røre kjernekrypto-
|
|
revisjonen.
|
|
|
|
---
|
|
|
|
## Mål
|
|
|
|
E2EE sanntidskommunikasjon på Shade-stack: voice-calls, video-calls,
|
|
broadcast/streaming — alt som "magic drop-in"-komponenter for konsumerende
|
|
apper.
|
|
|
|
```tsx
|
|
<ShadeVoiceButton to={peerAddress} />
|
|
<ShadeVideoCall to="device:server-admin" />
|
|
<ShadeBroadcaster streamKey="game-stream-1" />
|
|
<ShadeViewer streamKey="game-stream-1" />
|
|
```
|
|
|
|
---
|
|
|
|
## Scope
|
|
|
|
### Inn
|
|
|
|
- Ny pakke `@shade/voice` — 1:1 voice over WebRTC P2P.
|
|
- Ny pakke `@shade/video` — 1:1 video, deler kjerne med voice.
|
|
- Ny pakke `@shade/broadcast` — 1:N broadcast med relay-helper.
|
|
- SFrame-style frame encryption — payload-keys ratchet'es per call,
|
|
derivert fra Shade-session.
|
|
- Codec: Opus (audio), AV1/VP9 (video) — WebRTC standard.
|
|
- Widget-komponenter for hvert use case.
|
|
- Key-rotation under loss: forward-secrecy per X frames eller hvert N
|
|
sekund.
|
|
|
|
### Ut
|
|
|
|
- Group-calls (≥ 3 deltakere) som første milestone — krever SFU + group
|
|
key agreement; egen sak.
|
|
- Replacement for native phone-app — vi tilbyr in-app calls.
|
|
- Codec-implementasjon — vi bruker browser/native WebRTC.
|
|
|
|
---
|
|
|
|
## Design
|
|
|
|
### Frame-key derivasjon
|
|
|
|
```text
|
|
callKey = X3DH(A, B) → HKDF("shade-call-v1") → callRatchetKey
|
|
frameKey[i] = HKDF(callRatchetKey, "frame" || u64(i))
|
|
```
|
|
|
|
`callRatchetKey` ratcheter forward hver N millisekund eller hver M frames;
|
|
kompromittert frame = bare det vinduet eksponert.
|
|
|
|
### SFrame
|
|
|
|
Følger IETF MLS/SFrame-mønstre:
|
|
|
|
- Header er klartekst (codec-metadata).
|
|
- Payload er AES-GCM med deterministisk nonce.
|
|
- Mottaker dropper frames med out-of-window seq.
|
|
|
|
### Topologi
|
|
|
|
- 1:1: P2P via V3.11.
|
|
- Broadcast: relay-helper i `@shade/broadcast-relay` distribuerer
|
|
ciphertext til subscribers — relay ser aldri plaintext.
|
|
|
|
---
|
|
|
|
## Leveranser
|
|
|
|
### Pakker
|
|
|
|
- `@shade/voice` + `@shade/video` (delt kjerne i `@shade/realtime-core`).
|
|
- `@shade/broadcast` + `@shade/broadcast-relay`.
|
|
- Widgets: `<ShadeVoiceButton />`, `<ShadeVideoCall />`,
|
|
`<ShadeBroadcaster />`, `<ShadeViewer />`.
|
|
|
|
### Tester
|
|
|
|
- Unit: SFrame encrypt/decrypt + tamper.
|
|
- Integration: 1:1 video 30 fps i 60 s; > 99 % frames levert; key rotation
|
|
observert.
|
|
- Loss recovery: 30 % packet loss → quality grace.
|
|
- Adversarial: relay-DB-dump avslører ingen plaintext.
|
|
|
|
### Dokumentasjon
|
|
|
|
- `docs/voice-video.md` — setup, codec-tradeoffs, broadcast-arkitektur.
|
|
|
|
---
|
|
|
|
## Akseptansekriterier
|
|
|
|
- [ ] 1:1 video 60 fps + 1080p mellom to klienter samme LAN.
|
|
- [ ] Frame-key kompromittering blokkerer maks 1 sekund forward data.
|
|
- [ ] Broadcast 1:50 viewers fungerer med < 2 s end-to-end latency.
|
|
|
|
---
|
|
|
|
## Avhengigheter
|
|
|
|
- **V4.0 GA** — kjerne-stacken må være ekstern-revidert og frosset før
|
|
vi legger sanntid-protokoll oppå.
|
|
- V3.11 — P2P transport (kommer i V4.0-vinduet).
|
|
- V3.5 — Android-paritet hvis voice/video skal funke på mobile.
|
|
|
|
---
|
|
|
|
## Risiko
|
|
|
|
- **Codec-quirks.** AV1 vs VP9 vs H.264 har ulik browser-støtte.
|
|
- **Frame-key sync under loss.** Avansert; SFrame-spec er fortsatt under
|
|
standardisering.
|
|
- **Latency vs sikkerhet.** Hver ratchet-step legger på µs.
|
|
|
|
---
|
|
|
|
## Migrasjon
|
|
|
|
Nye pakker. Ikke breaking — wire-formatene fra V4.0 holdes uendret;
|
|
voice/video legger til egne envelope-typer i et reservert range som
|
|
4.0-clients ignorerer.
|