chore: adopter Scaffold plan-kontrakt

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-09 19:04:48 +02:00
parent 3243647aa1
commit 306bf08452
6 changed files with 61 additions and 0 deletions
--- a/.scaffold/archive/android/shade-android/ROADMAP-ANDROID.md
+++ b/.scaffold/archive/android/shade-android/ROADMAP-ANDROID.md
@@ -0,0 +1,137 @@
+# Shade Android — Roadmap & Parity Status
+
+This document tracks the M-Cross milestones from `docs/V3.5.md` and the
+status of every cross-platform parity sjekkpunkt. The Kotlin port must be
+**byte-for-byte compatible** with the TypeScript implementation; this is
+verified continuously by `test-vectors/*.json` consumed by both runners.
+
+> **No "production" label** is allowed on Android until M-Cross 2 is green
+> (ratchet + wire 0x02 + storage encryption) and M-Cross 3 is green
+> (streams 0x11). See `docs/V3.5.md` §Akseptansekriterier.
+
+## Milestones
+
+### M-Cross 1 — Scaffold ✅
+
+Foundation primitives. All passing in CI.
+
+| Sjekkpunkt | Vector | TS test | Kotlin test |
+|---|---|---|---|
+| 1. KDF chain (root + chain ratchet) | `kdf-chain.json` | ✅ | ✅ |
+| 2. HKDF labels | `hkdf.json` | ✅ | ✅ |
+| 3. X3DH initial root key (3 + 4 DH outputs) | `x3dh.json` | ✅ | ✅ |
+| 5. Fingerprint (60-digit safety number) | `fingerprint.json` | ✅ | ✅ |
+
+### M-Cross 2 — Ratchet & Wire 0x02 ✅
+
+Full ratchet step + binary envelope encoding for both message types.
+
+| Sjekkpunkt | Vector | TS test | Kotlin test |
+|---|---|---|---|
+| 4. Ratchet step (encrypt deterministic) | `ratchet-step.json` | ✅ | ✅ |
+| 4. Ratchet step (decrypt roundtrip) | `ratchet-step.json` | ✅ | ✅ |
+| 6. Wire 0x02 RatchetMessage | `wire-format.json` | ✅ | ✅ |
+| 6. Wire 0x02 PreKeyMessage (with OTPK) | `wire-format.json` | ✅ | ✅ |
+| 6. Wire 0x02 PreKeyMessage (no OTPK, 0xFFFFFFFF marker) | `wire-format.json` | ✅ | ✅ |
+
+The ratchet-step vector exercises every layer that contributes to a
+ratchet message's wire bytes: `kdfRootKey` → `kdfChainKey` → 40-byte header
+AAD → AES-256-GCM with deterministic nonce. Both implementations recompute
+each layer and compare against the recorded hex. The decrypt half feeds
+the recorded ciphertext back through `aesGcmDecrypt(messageKey, nonce, aad)`
+and checks the plaintext recovers — proving the AEAD agrees in both
+directions.
+
+### M-Cross 3 — Streams 0x11 ✅
+
+Multi-lane chunk encryption (`@shade/streams`) ported. KDF labels with
+embedded NULs match TS byte-for-byte; deterministic
+`(laneId, seq)`-derived nonces and the 29-byte chunk AAD agree across
+runners; wire 0x11 encode/decode is roundtrip-verified.
+
+| Sjekkpunkt | Vector | TS test | Kotlin test |
+|---|---|---|---|
+| `deriveStreamKey` (HKDF, info `shade-stream/v1\0master`) | `streams.json` | ✅ | ✅ |
+| `deriveLaneKey` (HKDF, info `shade-stream/v1\0lane\0` ‖ u32_be laneId) — incl. laneId 0xFFFFFFFF | `streams.json` | ✅ | ✅ |
+| `buildChunkNonce(laneId, seq)` — incl. seq = 2^64 - 2 | `streams.json` | ✅ | ✅ |
+| `buildChunkAad(streamId, laneId, seq, isLast)` | `streams.json` | ✅ | ✅ |
+| Chunk AES-256-GCM encrypt + decrypt (deterministic nonce + AAD) | `streams.json` | ✅ | ✅ |
+| Wire 0x11 envelope encode + decode + type-tag inspector | `streams.json` | ✅ | ✅ |
+
+Sequence numbers are unsigned u64 on the wire; the Kotlin port accepts
+them as `Long` for the bit pattern (negative-signed-long for values past
+2^63 - 1) — this matches the JVM `ByteBuffer.putLong` behavior and the
+`java.lang.Long.parseUnsignedLong` JSON-decoder used in tests.
+
+Pending end-to-end interop test (TS server → Kotlin client over an actual
+socket) — not gated by vectors but recommended before flipping the
+"production" label.
+
+### M-Cross 4 — Backup, Group, Storage HKDF ✅ (cryptographic layer)
+
+The cryptographic primitives that Kotlin needs to share with TS are now
+covered. The remaining work is the high-level glue (BackupBlob JSON
+schema, full SenderKey/GroupSession state-tracking, Android-Keystore
+storage adapter, scrypt password-KDF) — all per-platform plumbing that
+doesn't gate vector parity.
+
+| Sjekkpunkt | Vector | TS test | Kotlin test |
+|---|---|---|---|
+| 7. Backup v1 HKDF (`info="ShadeBackupKey"`) | `backup.json` | ✅ | ✅ |
+| 7. Backup v1 AES-GCM roundtrip (no AAD) | `backup.json` | ✅ | ✅ |
+| Group sender header AAD (u16/u16/u32 length prefixes) | `group.json` | ✅ | ✅ |
+| Group sender-key step: `kdfChainKey` + AES-GCM + Ed25519 sign(aad ‖ ct) | `group.json` | ✅ | ✅ |
+| Storage HKDF: `storageKey` (`info="shade-storage-v1"`) | `storage-hkdf.json` | ✅ | ✅ |
+| Storage HKDF: `fieldKey` (`info="shade-field-v1:{table}:{column}"`) | `storage-hkdf.json` | ✅ | ✅ |
+| Storage HKDF: `rowNonce` (`info="shade-row-nonce-v1:{table}:{pk}"`) | `storage-hkdf.json` | ✅ | ✅ |
+
+Pending sub-tasks (don't gate vector parity):
+
+- **scrypt master-key derivation**: `test-vectors/storage-encryption.json`
+  pins `scrypt(N=1024, r=8, p=1, dkLen=32)` for unit-test config; Tink
+  doesn't ship scrypt. Add Bouncy Castle (`org.bouncycastle:bcprov-jdk18on`)
+  to the Kotlin module, wrap as `CryptoProvider.scrypt(...)`, then a follow-up
+  vector consumes the full storage-encryption.json end to end.
+- **argon2id**: Both backup.ts and the threat-model docs flag HKDF as a
+  placeholder for a real password KDF. When `argon2id` is added to
+  `CryptoProvider`, both ports swap together and the backup vector gets
+  re-pinned.
+- **Android KeystoreStorage adapter**: lives in a sibling Android Library
+  Gradle module that depends on this JVM module. Binds Tink to the Android
+  Keystore + EncryptedSharedPreferences.
+
+## Build & Test
+
+This module compiles as a **pure-JVM** Kotlin library (`kotlin("jvm")`)
+so the parity gate can run without an Android SDK installation in CI.
+The protocol code uses `tink:1.15.0` (JVM JAR), `java.nio.ByteBuffer`,
+and `javax.crypto` — no `android.*` imports.
+
+The Android-specific storage adapter (KeystoreStorage,
+EncryptedSharedPreferences) will land as a sibling Gradle module
+(`shade-android-keystore`) in M-Cross 4 and depend on this one.
+
+```bash
+# From repo root
+cd android
+./gradlew :shade-android:test
+```
+
+Requires JDK 17. The Gradle wrapper downloads Gradle 8.10.2 on first run.
+
+## Compatibility contract
+
+The Kotlin implementation must produce byte-identical output to the TS
+reference for:
+
+- KDF chain derivations (root key ratchet, chain key ratchet)
+- X3DH shared secrets (3- and 4-DH variants)
+- Ratchet message keys + AES-GCM ciphertext (given the same key/plaintext/AAD/nonce)
+- Header AAD encoding (40 bytes: `dhPublicKey(32) || u32_be(prevCounter) || u32_be(counter)`)
+- Fingerprints (12 × 5-digit groups)
+- Binary wire format 0x02 (RatchetMessage + PreKeyMessage)
+- Binary wire format 0x11 (StreamChunk) — M-Cross 3
+- Storage encryption KDF chain — M-Cross 4
+
+Each is covered by a vector file in `/test-vectors/`. Adding a new
+sjekkpunkt: see `docs/cross-platform.md`.
--- a/.scaffold/archive/docs/ROADMAP.md
+++ b/.scaffold/archive/docs/ROADMAP.md
@@ -0,0 +1,116 @@
+# Shade Roadmap — V3.1 → V5.0
+
+Indeks over versjonsplanene fra V3.1-grunnsteinen via **Shade 4.0 GA** og
+videre til **Shade 5.0** (Voice & Video).
+
+- **V4.0 GA** ✅ — alt fra V2.1 / V2.2 / V2.3 og bonus-tracket (sosial
+  recovery, P2P WebRTC, Pub/Sub, Key Transparency) er merget, testet,
+  dokumentert og pakket for ekstern review. Wire-formatet er låst.
+- **V5.0** = den dedikerte sanntids-releasen. *Alt* VOIP og videostreaming
+  ligger her — implementert oppå den frosne 4.0-stacken.
+
+Alle V3.x-planer ligger nå under [`docs/archive/`](./archive/) med
+`Status: Done`. Aktive planer: [`V5.0.md`](./V5.0.md).
+
+---
+
+## Faser
+
+### Fase 1 — Documentation & Hardening Foundation ✅
+
+| Plan | Tittel | Effort | Status |
+|------|--------|--------|--------|
+| [V3.1](./archive/V3.1.md) | Documentation & Hardening Foundation | S | **Done** |
+
+### Fase 2 — Sikkerhetsmodning ✅
+
+| Plan | Tittel | Effort | Status |
+|------|--------|--------|--------|
+| [V3.2](./archive/V3.2.md) | At-Rest Storage Encryption | L | **Done** |
+| [V3.3](./archive/V3.3.md) | Fingerprint Gates & Trust UX | M | **Done** |
+| [V3.4](./archive/V3.4.md) | Observability v2 (OpenTelemetry) | M | **Done** |
+| [V3.5](./archive/V3.5.md) | Android Parity & Cross-Platform CI | XL | **Done** |
+
+### Fase 3 — Plattformutvidelse ✅
+
+| Plan | Tittel | Effort | Status |
+|------|--------|--------|--------|
+| [V3.6](./archive/V3.6.md) | Async Store-and-Forward (Inbox) | L | **Done** |
+| [V3.7](./archive/V3.7.md) | Transport Bridge (SSE / long-poll) | M | **Done** |
+| [V3.8](./archive/V3.8.md) | Web Workers Crypto | M-L | **Done** |
+| [V3.9](./archive/V3.9.md) | Rich File Metadata & Previews | M | **Done** |
+
+### Fase 4 — Tillit og P2P-transport ✅
+
+| Plan | Tittel | Effort | Status |
+|------|--------|--------|--------|
+| [V3.10](./archive/V3.10.md) | Social Key Recovery | L | **Done** |
+| [V3.11](./archive/V3.11.md) | WebRTC P2P Transport | XL | **Done** |
+| [V3.12](./archive/V3.12.md) | Key Transparency | XXL | **Done** |
+
+### Fase 5 — General Availability ✅
+
+| Plan | Tittel | Effort | Status |
+|------|--------|--------|--------|
+| [V4.0](./archive/V4.0.md) | External Audit, Consolidation, GA | M | **Done** |
+
+### Fase 6 — Sanntid (post-GA)
+
+| Plan | Tittel | Effort | Avhenger av |
+|------|--------|--------|-------------|
+| [V5.0](./V5.0.md) | Voice & Video | XXL | V4.0 GA + V3.11 |
+
+---
+
+## Effort-nøkkel
+
+| Symbol | Tid |
+|--------|-----|
+| **S** | 1–2 uker |
+| **M** | 2–4 uker |
+| **L** | 4–8 uker |
+| **XL** | 2–4 måneder |
+| **XXL** | 4+ måneder / multi-quarter |
+
+---
+
+## Avhengighetsgraf
+
+```text
+V3.1 ────┬──► V3.2 ──┐
+         ├──► V3.3 ──┼──► V3.10 ──┐
+         ├──► V3.4 ──┘            │
+         ├──► V3.5 ───────────────┼──► V3.12 ──┐
+         ├──► V3.6 ──► V3.7 ──► V3.11 ─────────┤
+         ├──► V3.8                              ├──► V4.0 GA ──► V5.0 (Voice & Video)
+         └──► V3.9 ─────────────────────────────┘
+```
+
+---
+
+## Status-konvensjon
+
+Hver plan har et `Status:`-felt øverst. Lov verdier:
+
+- `Idea` — ikke startet, design fortsatt åpent.
+- `Design` — designnotat under arbeid eller approved.
+- `IMP` — implementasjon pågår.
+- `Done` — merget i main, dekket av tester.
+
+Når en plan blir `Done`, flytt fila til `docs/archive/` og oppdater denne tabellen.
+
+---
+
+## Versjonering
+
+- **V3.1 → V3.12** ble trinnvise minor-releases på `0.4.x`-linjen.
+- Wire-format-endringer akkumulerte til **V4.0**, men endte med å være
+  uendret fra 0.4.x — major-bumpen til 4.0 markerer audit-cycle ferdig
+  og GA-frosset kjerne, ikke en wire-bump.
+- **V4.0** er GA — låst kjerne, pakket for ekstern review, ingen
+  voice/video.
+- **V5.0** legger sanntid (voice/video/broadcast) oppå den frosne
+  4.0-stacken. Bygger på reserverte envelope-typer slik at 4.0-klienter
+  ignorerer 5.0-trafikk gracefully — ikke breaking.
+- Hver `V*`-merge oppdaterer `CHANGELOG.md` og bumper alle pakker via
+  `bun run version`.
--- a/.scaffold/log.md
+++ b/.scaffold/log.md
@@ -0,0 +1,13 @@
+# Logg — Shade
+
+## 2026-07-09 — Adoptert Scaffold plan-kontrakt
+Migrerte `docs/ROADMAP.md` og `android/shade-android/ROADMAP-ANDROID.md` til `.scaffold/`: nåbildet destillert inn i `plan.md`, originalene arkivert under `.scaffold/archive/` med opprinnelig mappestruktur. Versjonsdesigndokumentene (`docs/V5.0.md`, `docs/archive/V*.md`) er bevisst latt stå — de er spesifikasjoner, ikke planfiler.
+
+## 2026-05-15 — v4.11: streaming Double-Ratchet sub-sessions
+Siste post-GA-økning på 4.x-linjen: `ShadeStream` gir in-memory sub-sessions (seal/open uten keystore-I/O per frame) med nye wire-typer 0x31–0x33. Låst beslutning: stream-ratchets persisteres aldri — en droppet stream gjenåpnes, aldri gjenopptas.
+
+## 2026-05-09 — Android M-Cross 1–4 fullført + Keystore-adapter
+All kryptografisk paritet TS↔Kotlin grønn via delte test-vektorer: KDF-kjede, HKDF-labels, X3DH, ratchet-steg, fingerprint, wire 0x02 og 0x11 (streams), backup-HKDF, group sender-keys og storage-HKDF. Etterslepet fra Android-roadmapen landet samme dag: scrypt + argon2id via Bouncy Castle og `shade-android-keystore`-modulen (hardware-backed master key + `KeystoreStorage`). Gjenstår: socket-interop-test og instrumenterte Keystore-tester.
+
+## 2026-05-03 — V4.0 GA: V3.x-konsolidering og audit-pakking
+Alle fasene V3.1–V3.12 ferdige og merget: dokumentasjon/hardening, at-rest storage-kryptering, trust-UX, observability (OTel), Android-paritet, inbox (store-and-forward), transport-bridge, web workers-krypto, filmetadata, social key recovery, WebRTC P2P og key transparency. Wire-formatet låst — uendret fra 0.4.x, så 4.0-peers interopererer byte-for-byte med 0.4.x. Kjernen pakket for ekstern review. Låst beslutning: alt VOIP/video skilt ut til V5.0, bygget oppå den frosne 4.0-stacken via reserverte envelope-typer (ikke breaking).
--- a/.scaffold/plan.md
+++ b/.scaffold/plan.md
@@ -0,0 +1,27 @@
+---
+project: "Shade"
+phase: "Post-4.x GA — V5.0 (Voice & Video) i idéfase"
+updated: 2026-07-09
+focus: "4.x-kjernen er GA-frosset og revisjonsklar; neste løft er V5.0 sanntid oppå den låste stacken"
+blockers: []
+---
+
+# 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/`.
+- GA-frosset, revisjonsklar 4.0-kjerne som fundament; nye kapabiliteter (sanntid i V5.0) bygges oppå uten å røre kjernekrypto-revisjonen.
+
+## Nå
+- [ ] V5.0 fra `Idea` til `Design`: designnotatet `docs/V5.0.md` (SFrame-style frame encryption, `@shade/voice` / `@shade/video` / `@shade/broadcast`) må modnes og godkjennes
+- [ ] Ende-til-ende interop-test TS-server ↔ Kotlin-klient over ekte socket (anbefalt før «production»-label på Android)
+- [ ] Instrumenterte tester for `KeystoreStorage` (krever Android-emulator/enhet — utsatt i v4.9/v4.10-porten)
+
+## Neste
+- V5.0-implementasjon: `@shade/voice` (1:1 voice) → `@shade/video` → `@shade/broadcast` (1:N med relay-helper)
+- «Production»-label på Android når interop-testen er grønn
+
+## Senere
+- Re-pinne backup-vektoren når begge porter bytter til argon2id som passord-KDF (HKDF-placeholder flagget i threat-model; `deriveMasterKeyArgon2id` finnes allerede i Kotlin)
+- Versjonsdesigndokumentene bor fortsatt i `docs/V5.0.md` og `docs/archive/V*.md` — de er spesifikasjoner, ikke planfiler
--- a/.scaffold/tasks.yaml
+++ b/.scaffold/tasks.yaml
@@ -0,0 +1,17 @@
+# Scaffold kanban-kort. Skjema per kort:
+#   - id: kort-slug              # unik i fila
+#     title: ""
+#     description: ""
+#     status: todo               # todo | doing | done | blocked
+#     column: todo               # speiler status (kanban-kolonne)
+#     priority: medium           # low | medium | high
+#     assignee: human            # cursor | claude | human | any
+#     context: ""                # valgfri: hvorfor/hvor i koden
+#     acceptance: ""             # valgfri: hva «ferdig» betyr
+#     todos:
+#       - text: "Underoppgave"
+#         done: false
+#     created: 2026-07-09
+#     updated: 2026-07-09
+#     completed_at: null
+tasks: []