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