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.