Sterister
e6fdf31b49
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>
5.6 KiB
Shade by scenario — modular E2EE toolkit
This page is for builders, not cryptography specialists. Shade is packaged so you can drop in small pieces per project instead of importing a heavy “everything” stack.
Plain-language mental model
-
Identity & session (the hard crypto): Shade establishes a secret channel between two parties using the same kind of cryptographic core as Signal (initial setup + ongoing “ratchet” updates). You mostly call high-level APIs (
send,receive, fingerprints) rather than assembling primitives by hand. -
Who is “the server”?
The prekey server only helps with public key material (so Alice can fetch Bob’s public bundle before the first message). It is not your general-purpose message relay unless you build that separately. Normal message payloads and file chunks typically flow over your transport (your HTTP routes, websocket, bridge, queue, etc.). -
Small vs large payloads:
Short messages ride the usual ratchet envelopes. Very large payloads use Streams + Transfer: secrets are negotiated over the ratchet; ** ciphertext chunks** ship over optimized HTTP/WebSocket transports with parallelism and resume. -
Trust: Strong encryption does not replace verifying who you are talking to. For high-stakes use, compare safety numbers out-of-band (see THREAT-MODEL.md).
Scenario → minimum packages
Pull in one row that matches your project; add optional columns only when needed.
| Scenario | What you need | Minimum packages / surface | Where to start |
|---|---|---|---|
| Backend or Bun service — encrypted messages between users | Session storage + crypto provider + prekey URL | @shade/sdk + sqlite: or @shade/storage-postgres |
createShade() → send / receive |
| Browser / frontend — same, in the client | Web crypto + durable or memory storage | @shade/sdk or @shade/core + @shade/crypto-web (+ storage you provide) |
Same APIs; ensure prekeyServer is reachable from the browser (CORS, etc.) |
| Large files — resumable E2EE upload/download | Above + stream protocol + HTTP (or WS) transport | @shade/sdk (re-exports transfer) + mount transfer routes on your HTTP server |
shade.upload / onIncomingTransfer — see streams.md |
| React UI — upload/download widgets | Runtime from SDK + widgets | @shade/sdk + @shade/widgets |
ShadeRuntimeProvider, useShadeUpload / useShadeDownload |
| Prekey hosting only — one container per product | No app crypto in the container | Docker image / @shade/server |
Deploy prekey image; point prekeyServer at it from apps |
| Offline-tolerant messaging — recipient may be offline | Above + a relay that holds ciphertext blobs | @shade/inbox (client) + @shade/inbox-server (or the prekey container, which bundles both) |
Register address, inbox.send() to peer, inbox.onIncoming(handler) — see inbox.md |
| "What if I lose my phone?" — survive device loss without a recovery agent | Above + Shamir-split shares to n guardians; threshold k reconstruct |
@shade/recovery + @shade/widgets (<RecoverySetup />, <RecoveryRequest />, <RecoveryApprove />) |
setupRecovery / attachGuardian / requestRecovery — see recovery.md |
| Maximum control — custom wire, custom transport | Wire + session manager | @shade/core + @shade/proto (+ your storage + crypto provider) |
ShadeSessionManager, encode/decode envelopes yourself |
| HTTP or WebSocket convenience | Auto-wrap application bytes | @shade/transport on top of your stack |
Use when you want transport helpers, not a new protocol |
| Android | Byte-compatible with TS (cross-vector gated in CI) | shade-android module |
See android/shade-android/README.md. Cross-platform vectors live in test-vectors/ and are exercised by both runners. |
You can mix rows: e.g. backend with @shade/sdk + SQLite for sessions, separate service mounting transfer routes, browser clients using @shade/widgets.
New project checklist (lightweight)
- Run a prekey server (Docker or embedded
@shade/server) for your environment. - Pick storage (
sqlite:…, Postgres, or project-specific adapter implementing the core storage interfaces). - Choose surface: usually
@shade/sdkunless you truly need@shade/coreonly. - For files: enable transfer routes and authenticate chunk uploads using the patterns in the SDK (see streams doc).
- Run
shade doctorwhen something fails in production-ish setups (install the CLI as in repository Quick start); the gates that fire are documented in trust-ux.md and PRODUCTION-CHECKLIST.md.
Related docs & roadmap
| Topic | Doc |
|---|---|
| File transfer architecture | streams.md |
| Deployment & operations | DEPLOYMENT.md |
| Threat model | THREAT-MODEL.md |
| Planned improvements | ROADMAP — V3.x archive under archive/, next milestone V5.0 |
Version note
This file describes how Shade is intended to be composed. Package names and re-exports may gain small aliases over time; the scenario table should remain the source of truth for “what to install for what job.” Update this page when adding major surfaces (new transport bridges, richer shade init templates, etc.).