Stian/Shade
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3243647aa1d7f4b8c90d3162bf1bdca3821507d1
Shade/docs/archive/V3.1.md
Sterister e6fdf31b49
Some checks failed
Test / test (push) Has been cancelled
Details
Cross-platform vectors / TypeScript vectors (bun) (push) Has been cancelled
Details
Cross-platform vectors / Kotlin vectors (gradle) (push) Has been cancelled
Details
Docker build and publish / docker (push) Has been cancelled
Details
Publish / publish (push) Has been cancelled
Details
release(v4.0.0): Shade GA — V3.x consolidation + audit prep 
V3.1 → V3.12 consolidated and tagged for the first GA release. Wire
format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers
byte-for-byte. The version bump is semantic: audit-cycle complete,
opt-in surface fully exposed, threat model refreshed for every new
surface.

Highlights:
- All 24 @shade/* packages bumped to 4.0.0 in lockstep.
- CHANGELOG 4.0.0 section is the canonical manifest of what landed.
- THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12
  Web-Worker boundary) + residual-risks table refreshed.
- OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox,
  bridge, observer, /metrics, /healthz, /ready.
- MIGRATION 0.3.x → 4.0 documented + smoke-tested against
  shade migrate-storage on a real SQLite DB.
- docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer.
- scripts/soak.ts harness for the GA-stable 2-week soak window.
- All V*.md plans archived under docs/archive/ with Status: Done.
- Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen
  non-realtime stack.

Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green.
Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports
  version 4.0.0 on /health.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 18:35:35 +02:00

2.9 KiB
Raw Blame History

Shade V3.1 — Documentation & Hardening Foundation

Status: Done Effort: S (1–2 uker) Forrige: V2.3 Neste: V3.2 / V3.3 / V3.4 (kan kjøres parallelt)

Mål

Lukke "lav-friksjon"-gjelden fra V2.1, V2.2 og V2.3 før vi tar fatt på de tunge sikkerhetsløftene. Dette er pre-arbeidet som låser opp resten av roadmapen: operatører skal kunne deploye trygt, transfer-konsumenter skal ha klare grenser, og OpenAPI skal dekke hele HTTP-flaten.

Ingen ny kjernekode — kun docs, OpenAPI-utvidelser, retention-defaults og en test-/threat-matrise.

Scope

Inn

  • README + @shade/server-README: eksplisitt "keys vs payloads"-narrativ med diagram + lenke til THREAT-MODEL.md.
  • Ny docs/PRODUCTION-CHECKLIST.md: TLS, backup, observer-token-rotering, SQLite vs PG, log-nivå, stale-params, secret-rotering.
  • Hardening-seksjon i docs/streams.md: max stream-size, TTL, quota-mønstre — peker mot @shade/files-hooks som referanse.
  • openapi.yaml utvidet med /v1/transfer/* (chunk, state, health) + sikkerhetsskjema for ShadeTransferAuthenticator.
  • Retention-defaults i docs/streams.md + SDK-template: pruneStreamStates-cron som default — "ferdige streams ryddes etter N dager".
  • SECURITY.md-utvidelse: review-status, "hvordan rapportere", lenking fra THREAT-MODEL.md-rader → tests/security/* (test-/threat-matrise).

Ut

  • Faktisk crypto-review (det er V4.0).
  • Endringer i krypto- eller wire-format.
  • Ny kode utenfor SDK-templates.

Leveranser

Dokumentasjon

  • docs/PRODUCTION-CHECKLIST.md — ny.
  • docs/streams.md — utvidet med "Hardening" og "Retention".
  • README.md — diagram-justering + "Hva som ikke går via Shade-server".
  • packages/shade-server/README.md — speile narrativet.
  • SECURITY.md — review-status + threat-/test-matrise.
  • THREAT-MODEL.md — krysslenker til konkrete tester.

Kode (kun konfig + templates)

  • packages/shade-server/openapi.yaml — /v1/transfer/*-paths, ShadeTransferAuthenticator securityScheme.
  • packages/shade-cli/templates/bun-server — default pruneStreamStates-cron.

Tester

  • Lint-test: OpenAPI-spec validerer fortsatt mot OpenAPI 3.1-skjema.
  • Smoke-test for cron i template.

Akseptansekriterier

  • Ny utvikler kan lese README + PRODUCTION-CHECKLIST.md og deploye prod-klar Shade uten å lese hele kodebasen.
  • Generert klient (Python eller Go) fra openapi.yaml dekker både prekey- og transfer-flate uten manuelle fixes for happy path.
  • THREAT-MODEL.md linker hver "Mitigations"-rad til minst én test-fil.
  • Default SDK-template bun-server prune'r resumable streams uten manuell konfig.

Avhengigheter

Ingen.

Risiko

Lav. Verste utfall er foreldet docs hvis V3.2+ endrer overflater. Mitiger ved å skrive små, oppdaterbare seksjoner heller enn lange narrative kapitler.

Migrasjon

Ingen — alt er additivt.

Reference in New Issue View Git Blame Copy Permalink