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>
138 lines
3.9 KiB
Markdown
138 lines
3.9 KiB
Markdown
Start implementasjon, og ikke gi deg før 100% av planen er implementert, alle tester er validert og grønne, samt å ha oppdatert dokumentasjon.
|
||
# Shade V3.9 — Rich File Metadata & Previews
|
||
|
||
**Status:** Implementert (se `docs/streams.md` § Rich file metadata)
|
||
**Effort:** M
|
||
**Forrige:** V3.1
|
||
**Adresserer:** V2.2 §3
|
||
|
||
---
|
||
|
||
## Mål
|
||
|
||
Rikere fil-UX uten å lekke sensitivt innhold til server. Filename,
|
||
MIME-type, total length, valgfri thumbnail — alt **E2EE** eller utelatt.
|
||
Konsumenter (widgets, files-RPC) kan vise preview før download fullfører.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### Inn
|
||
|
||
- Utvid `stream-init` (kontroll-envelope) med valgfrie felt:
|
||
- `filename: string` (E2EE, opt-in).
|
||
- `mimeType: string` (E2EE, opt-in).
|
||
- `totalBytes: number` (alltid OK — bytes-binnet i obs).
|
||
- `thumbnailHash: Uint8Array` (sha256 av separat thumbnail-stream).
|
||
- Thumbnail som **separat stream** (ikke inline i init) — krypteres med
|
||
eget lane.
|
||
- Format-hardening på klient: max-size, sandbox i UI.
|
||
- Widget-støtte: `<TransferRow showThumbnail />`.
|
||
|
||
### Ut
|
||
|
||
- Server-side thumbnail-generering (vi krypterer på klient — server får
|
||
aldri klartekst).
|
||
- Video preview — separat sak; krever frame-extraction og sandbox.
|
||
|
||
---
|
||
|
||
## Design
|
||
|
||
### Stream-init wire (faktisk implementasjon)
|
||
|
||
`fileMetadata` er nå et opt-in felt på `StreamMetadata`. Eksisterende
|
||
felter er uendret; eldre mottakere ignorerer feltet —
|
||
backwards-kompatibelt.
|
||
|
||
```jsonc
|
||
{
|
||
"kind": "shade.stream-init/v1",
|
||
"streamId": "...",
|
||
"streamSecret": "...",
|
||
"metadata": {
|
||
"chunkSize": 1048576,
|
||
"sentAt": 1730000000000,
|
||
"userMetadata": { ... }, // eksisterer (V0.3)
|
||
"fileMetadata": { // NYTT (V3.9)
|
||
"filename": "report.pdf",
|
||
"mimeType": "application/pdf",
|
||
"thumbnailStreamId": "Ej1z...",
|
||
"thumbnailHash": "9a7c...",
|
||
"thumbnailMime": "image/webp",
|
||
"thumbnailBytes": 18342
|
||
}
|
||
},
|
||
"lanes": [ /* ... */ ]
|
||
}
|
||
```
|
||
|
||
### Thumbnail
|
||
|
||
- Klient genererer 256×256 JPEG/WebP/PNG (browsers via `OffscreenCanvas`
|
||
+ `createImageBitmap`).
|
||
- Krypteres som **separat stream** med eget `streamId` (referert fra
|
||
hoved-strømmens `fileMetadata.thumbnailStreamId`). Den symbolske
|
||
konvensjonen `mainStreamId + ".thumb"` er en hjelper; det reelle
|
||
streamId er en uavhengig 16-byte verdi.
|
||
- Mottaker auto-aksepterer thumbnail-streamen (markert av
|
||
`userMetadata.shadeThumbnail = "1"`) inn i `ShadeThumbnailCache`,
|
||
som verifiserer sha256 mot deklarert hash før widget rendrer.
|
||
|
||
---
|
||
|
||
## Leveranser
|
||
|
||
### Kode
|
||
|
||
- `@shade/streams` — utvid `StreamInitMessage`-schema.
|
||
- `@shade/sdk` — `Shade.upload({ ..., generateThumbnail: true })`.
|
||
- `@shade/widgets` — `<TransferRow />` med thumbnail-prop.
|
||
|
||
### Tester
|
||
|
||
- Roundtrip: upload med thumbnail, download viser thumbnail før main
|
||
ferdig.
|
||
- Backwards: 0.3.x-mottaker får stream uten thumbnail og fungerer.
|
||
- Format-fuzzing: ondsinnet bilde-fil rendres ikke uten sandbox.
|
||
|
||
### Dokumentasjon
|
||
|
||
- `docs/streams.md` utvidet.
|
||
- `docs/files.md` — referer til metadata-utvidelsen.
|
||
|
||
---
|
||
|
||
## Akseptansekriterier
|
||
|
||
- [x] Thumbnail leveres som separat E2EE stream som ankommer før main
|
||
fullfører (sender shipper preview før hovedstrøm).
|
||
- [x] Eldre klient (uten V3.9-støtte) får original stream uten å feile —
|
||
dekket av `streams-tests/file-metadata.test.ts` og
|
||
`sdk-tests/thumbnail.test.ts` (legacy receiver).
|
||
- [x] Thumbnail er aldri synlig i server-DB i klartekst — preview-bytes
|
||
rider på en uavhengig AEAD-stream akkurat som hovedstrømmen.
|
||
|
||
---
|
||
|
||
## Avhengigheter
|
||
|
||
- V3.1 — wire-format-utvidelser dokumentert.
|
||
|
||
---
|
||
|
||
## Risiko
|
||
|
||
- **Thumbnail-format-angrep.** Ondsinnet bilde-fil kan kompromittere
|
||
preview-renderer. Mitiger ved sandbox-iframe + max-size + format-allowlist.
|
||
- **UX-feil.** "Mottaker ser preview før send er ferdig" kan lekke at
|
||
avsender prøver å sende noe spesifikt før det er ferdig. Dokumenter for
|
||
høy-stakes flows.
|
||
|
||
---
|
||
|
||
## Migrasjon
|
||
|
||
Backwards-kompatibel — alle nye felt er valgfrie.
|