Shade/docs/archive/V3.9.md

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.

{
  "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

• Thumbnail leveres som separat E2EE stream som ankommer før main fullfører (sender shipper preview før hovedstrøm).
• 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).
• 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.