Shade/.scaffold/plan.md

---
project: "Shade"
phase: "Post-4.x GA — hardening til revisjonsklar (G0–G4) før V5.0-design"
updated: 2026-08-14
focus: "GCM-nonce-fiksen er levert (2026-08-13) og @shade/vault står ferdig og testet (2026-08-14), men er IKKE deployet eller publisert. De tre gjenstående G0-P0-ene er publiserings- og CI-saker. Historikk: G0 fikk en andre bestiller: @shade/vault (server-side kryptert fillager, bestilt 2026-08-13 av Scaffold-backupen) bygger på at-rest-stacken, og skal ikke reise seg på en kjent GCM-svakhet. Nonce-fiksens migreringssti er verifisert gratis — aeadOpen leser alltid nonce fra prefiks, så eksisterende blobber åpnes uendret."
blockers:
  - "P0: @shade/observer@4.11.1 tomt på registry (outDir=dist-build, publish shipper dist/)"
  - "P0: @shade/cli bin dingler etter publish (bin ikke omskrevet til dist/)"
---

# Plan — Shade

## Mål
- E2EE-bibliotek som implementerer Signal-protokollen (X3DH + Double Ratchet) for TypeScript/Bun — drop-in for frontend, backend og mobil, med forward secrecy og post-compromise recovery.
- Byte-for-byte kryssplattform-paritet: Kotlin/Android-porten verifiseres kontinuerlig mot TS-referansen via delte test-vektorer i `test-vectors/`.
- Reelt revisjonsklar 4.x-kjerne som fundament (G0–G4 grønne); sanntid (V5.0) bygges oppå den låste stacken uten å røre kjernekrypto-revisjonen.

## Nå
Gated hardening — hard utgangsport per steg (full plan + funn: helsesjekk-artifact 2026-07-10, se log.md).
- [ ] **G0 — Stopp blødningen (P0):** ~~tilfeldig nonce per skriving i
      storage-encrypted~~ (gjort 2026-08-13 — 9 nye tester, ingen migrering nødvendig,
      Android var aldri rammet; se `logs/2026-08-13-gcm-nonce-reuse-fikset.md`.
      **Ikke publisert** — Prism er pinnet på 4.12.0); observer `outDir→dist` +
      republiser 4.11.2 + gitignore `dist-build/`; ~~pin `typescript` + typecheck i CI~~
      (gjort 2026-08-14 — pinnet 7.0.2, `typecheck-all.ts` bruker lokal binær i
      stedet for `bunx` latest, steg lagt i `test.yml`; `baseUrl` var allerede
      borte og alle 26 pakker er grønne); fiks `bin`-omskriving + tarball-verifisering i publish.
      Port: typecheck grønn i CI, nonce-negativtest grønn, `bun pm pack` inneholder
      main-fil for alle pakker.
- [ ] **G1 — Revisjonsklar kjerne (P1):** peer-signeringsnøkkel per sesjon → symmetrisk safety-number; argon2id i backup-KDF (TS+Kotlin); hono ≥4.12.18; håndhevende §4 at-rest-tuklingstest; bestill ekstern krypto-review + pentest. Port: `alice.verify(bob, bob.getIdentityFingerprint())`===true, `bun audit` ren.
- [ ] **G2 — CI som mur:** biome + coverage-terskel + soak:smoke i CI; fjern/synk `.github/workflows`; publish kjører `prepublish:check`; bryt server↔inbox-server-syklus; rydd sdk/cli/files-deps; `dashboard: private`; pin bun. Port: PR blokkeres ved brudd, alle 8 examples grønne i CI.

## Neste
- **V4.13 — `@shade/vault`: server-side kryptert fillager.** Klient, ruter,
  `MemoryVaultStore`, `SqliteVaultStore`, ruting i `standalone.ts` og
  `docs/vault.md` er levert natt til 2026-08-14 (auto-mode); 16 + 7 tester
  grønne, og kjeden er kjørt mot en ekte HTTP-server med et ekte workspace:
  491 filer bit-identiske etter gjenoppretting, andre push sendte 0 KB.
  Gjenstår: Postgres-store, rate limiting på vault-rutene, GC av objekter
  ingen manifest lenger refererer — og deploy. Bestilt 2026-08-13 av
  Scaffold-backupen, men er en generell mangel: Shade kan flytte filer mellom peers
  (`@shade/files`) og lagre én liten profil-blob per konto (`/v1/blob/<slotId>`, V4.9),
  men har ingen **alltid-på lagring av krypterte filer på relayen**. Hver konsument
  docs/files.md nevner (Dispatch, Mail, Drive-style apps) trenger det samme, så det
  hører i Shade og ikke i den enkelte appen.
  - *Form:* innholdsadressert lager — klienten krypterer og navngir etter hash av
    ciphertext, serveren ser aldri klartekst og trenger ingen forståelse av innholdet.
  - *Historikk:* append-only oplog per samling gir versjonering og rollback gratis;
    det er «mini github»-halvdelen av Scaffold-bestillingen.
  - *Nøkler:* egen HKDF-gren ved siden av `shade-blob-*-v1`, så et vault-kompromiss
    ikke rører profil-slotten. Recovery er kontocredentials, som blob-primitivet —
    med det forbeholdet at gjenopprettingsstyrken da er passordstyrken (se G1s
    argon2id-punkt, som løfter nettopp den).
  - *Gated på G0:* lageret bygger på at-rest-stacken, og skal ikke reise seg på en
    kjent GCM forbidden attack.
- **G3 — Paritetslås:** ShadeStream-vektorer (3-DH, wire 0x31–0x33) konsumert av begge sider; Kotlin-port av v4.11; utvid cross-vectors path-filter; `PARITY-VERSION`-sjekk; symmetriser alle 14 vektorfiler; Robolectric-tester for KeystoreStorage; E2E socket-interop TS↔Kotlin. Port: begge sider verifiserer alle vektorer, minor-bump uten Android-ack ⇒ rød CI. Vilkår for «production»-label på Android.
- **G4 — Docs = sannhet:** README/MIGRATION/CHANGELOG/CONTRIBUTING → 4.11.x; fiks brutte lenker + riktig remote; legg indexeddb/ShadeStream/broadcast i README+SHADE-BY-SCENARIO; Postgres at-rest quick-start + salt-livssyklus; per-pakke README for de 6 viktigste.

## Senere
- **G5 — V5.0 (Voice/Video):** implementasjon gated på G0–G4 grønne. `docs/V5.0.md` er i dag idéskisse (135 linjer) — modnes parallelt: wire-type-allokering reconciled mot 0x31–0x33 (nå tatt av ShadeStream), browser-SFrame-mekanisme (RTCRtpScriptTransform/Insertable Streams), ratchet-parametre, API-flate, milepæler, intern konsistens (60fps/1080p vs 30fps-test). Godkjennes i diskusjon (Stian + Fable) før koding.
- Versjonsdesigndokumentene bor fortsatt i `docs/V5.0.md` og `docs/archive/V*.md` — de er spesifikasjoner, ikke planfiler.