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>
124 lines
3.2 KiB
Markdown
124 lines
3.2 KiB
Markdown
# Shade V3.6 — Async Store-and-Forward (Inbox)
|
||
|
||
**Status:** Done
|
||
**Effort:** L (4–8 uker)
|
||
**Forrige:** V3.4
|
||
**Adresserer:** V2.2 §2
|
||
**Implementert:** se `docs/inbox.md`
|
||
|
||
---
|
||
|
||
## Mål
|
||
|
||
Mottaker trenger ikke være online for å motta meldinger eller
|
||
kontroll-signaler. En **dedikert relay/inbox-tjeneste** holder
|
||
**ciphertext-blobs** med TTL og auth. Server ser aldri plaintext;
|
||
prekey-server forblir public-keys-only.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### Inn
|
||
|
||
- Ny pakke: `@shade/inbox` (klient) + `@shade/inbox-server` (server).
|
||
- HTTP API:
|
||
- `POST /v1/inbox/:address` — signed PUT av blob (med TTL).
|
||
- `GET /v1/inbox/:address/since/:cursor` — auth'd fetch.
|
||
- `DELETE /v1/inbox/:address/:msgId` — leasing/ack.
|
||
- Replay-beskyttelse på applikasjonslag (`msgId = sha256(ciphertext)`).
|
||
- Push-hook (vendor-nøytral): `inbox.onMessageQueued(handler)`-callback.
|
||
- Outgoing queue i klient: lagrer ciphertext lokalt til server bekrefter
|
||
PUT.
|
||
- Idempotent PUT (samme `msgId` returnerer 200, ikke 409).
|
||
|
||
### Ut
|
||
|
||
- Mobile push (FCM / APNs) — utenfor scope; vi eksponerer hook'en.
|
||
- Federation mellom inbox-servere — egen sak senere.
|
||
- Plaintext-metadata-adresser — vi støtter pseudonyme address-hashes som
|
||
privacy-modus.
|
||
|
||
---
|
||
|
||
## Design
|
||
|
||
### Auth
|
||
|
||
- PUT er **signed** med avsenders Ed25519 (samme som prekey).
|
||
- GET krever signed challenge fra mottaker (pull, ikke push).
|
||
- Replay-window ±5 min, samme som prekey.
|
||
|
||
### Wire
|
||
|
||
- Eksisterende `@shade/proto`-envelope, transportert som body.
|
||
- Server lagrer **kun**:
|
||
`address || msgId || ciphertext-bytes || expires_at`.
|
||
|
||
### Lifecycle
|
||
|
||
1. Avsender encrypter via `Shade.send` → får envelope.
|
||
2. Avsender PUT'er envelope til mottaker-inbox med TTL (default 7 dager).
|
||
3. Mottaker poller (eller får push-trigger) — fetcher alle siden cursor.
|
||
4. Mottaker decrypter; ack'er via DELETE for tidlig prune.
|
||
|
||
### Storage
|
||
|
||
- SQLite + Postgres backends (samme mønster som prekey).
|
||
- Indeks: `(address, expires_at)`.
|
||
- Cron prune.
|
||
|
||
---
|
||
|
||
## Leveranser
|
||
|
||
### Pakker
|
||
|
||
- `@shade/inbox` — klient + queue.
|
||
- `@shade/inbox-server` — Hono routes + storage adapter.
|
||
|
||
### Tester
|
||
|
||
- Unit: signed PUT/GET, replay-window, idempotency.
|
||
- Integration: full lifecycle 100 msgs, restart server, msgs persisterer.
|
||
- Tamper: bit-flip ciphertext → klient-side decrypt feiler (server vet
|
||
ikke).
|
||
|
||
### Dokumentasjon
|
||
|
||
- `docs/inbox.md` — setup, threat model "what the relay sees", deploy-guide.
|
||
- `THREAT-MODEL.md` — ny seksjon om relay.
|
||
|
||
---
|
||
|
||
## Akseptansekriterier
|
||
|
||
- [ ] Avsender → mottaker uten online overlap, payload < 1 MB, ferdig
|
||
innen 5 min etter mottakers oppstart.
|
||
- [ ] Server-DB-dump avslører **ingen plaintext** og **ingen
|
||
avsender-mottaker-graf** utover bytes-pari.
|
||
- [ ] Replay av PUT med samme `msgId` returnerer 200 uten å lagre dobbel.
|
||
|
||
---
|
||
|
||
## Avhengigheter
|
||
|
||
- V3.4 — observability hooks for å måle inbox-bruk uten lekkasje.
|
||
|
||
---
|
||
|
||
## Risiko
|
||
|
||
- **Metadata-lekkasje.** Server ser hvem snakker med hvem. Dokumenter klart;
|
||
pek på adress-hash som mitigasjon.
|
||
- **Storage-DoS.** Ondsinnet avsender fyller mottakers inbox. Mitiger med
|
||
per-sender quota + per-address-quota.
|
||
- **Privacy-modell.** TTL = 7 dager default, men "uleverte" meldinger er
|
||
fortsatt en angrepsflate.
|
||
|
||
---
|
||
|
||
## Migrasjon
|
||
|
||
Ny pakke; ingen breaking change i eksisterende.
|