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.
|