76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
|
# Shade 4.0 — Audit Scope
|
||
|
|
|
||
|
|
A short, structural list a reviewer can scan before opening a single
|
||
|
|
file. Everything here is a pointer to the deeper material in
|
||
|
|
[`REVIEW-BUNDLE.md`](./REVIEW-BUNDLE.md) and the package READMEs.
|
||
|
|
|
||
|
|
## In scope
|
||
|
|
|
||
|
|
- **Protocol primitives**: X3DH, Double Ratchet, sender keys.
|
||
|
|
- **Wire format**: `0x01` PreKeyMessage, `0x02` RatchetMessage, `0x11`
|
||
|
|
StreamChunk. Length prefixes (u32) and AAD bindings.
|
||
|
|
- **Storage encryption** (`@shade/storage-encrypted`): KDF chain,
|
||
|
|
per-(table,column) DEKs, AEAD AAD layout, online re-key.
|
||
|
|
- **Recovery** (`@shade/recovery`): Shamir over GF(2^8),
|
||
|
|
AEAD-authenticated reconstruction, fingerprint gate on guardian
|
||
|
|
release, share-grant / share-decline envelope schema.
|
||
|
|
- **WebRTC P2P** (`@shade/transport-webrtc`): SDP/ICE signaling rides
|
||
|
|
the ratchet; chunk frames AEAD-bound to streamId/laneId/seq; glare
|
||
|
|
resolution determinism.
|
||
|
|
- **Key Transparency** (`@shade/key-transparency`): Merkle log over
|
||
|
|
pre-hashed leaves, address-sorted index, signed STH, witness
|
||
|
|
cross-check, split-view detection.
|
||
|
|
- **Inbox** (`@shade/inbox-server`): TOFU registration, per-PUT signed
|
||
|
|
blobs, idempotent on `(address, msgId)`, replay window.
|
||
|
|
- **Bridge** (`@shade/transport-bridge`): SSE / long-poll / WS
|
||
|
|
carriers; signed-query auth (no headers on `EventSource`).
|
||
|
|
- **Crypto in workers** (`@shade/crypto-web/worker`): key-isolation
|
||
|
|
boundary, postMessage protocol, idle terminate.
|
||
|
|
- **Trust UX gates** (`@shade/sdk` `Shade.beforeFirstLargeFile`,
|
||
|
|
`beforeBackupImport`, `beforeNewDeviceTrust`).
|
||
|
|
|
||
|
|
## Out of scope
|
||
|
|
|
||
|
|
- **Voice / Video / Broadcast** (`@shade/voice` etc.) — V5.0; reviewed
|
||
|
|
when the package ships.
|
||
|
|
- **Build system** (Vite, Rollup, Gradle wiring) — out of crypto scope.
|
||
|
|
- **App-level UI** (`@shade/widgets`) — re-renders the primitives
|
||
|
|
above; the cryptographic decisions are in the SDK / core packages
|
||
|
|
the widgets consume.
|
||
|
|
- **Browser / native WebRTC stacks** — we ride the platform's
|
||
|
|
`RTCPeerConnection` and `SubtleCrypto`.
|
||
|
|
- **Operating system / hardware threat model** — filesystem
|
||
|
|
encryption, secure-enclave key storage, swap-encryption, coredump
|
||
|
|
handling. Operator responsibility.
|
||
|
|
|
||
|
|
## Methodology suggestions
|
||
|
|
|
||
|
|
1. Start with [`THREAT-MODEL.md`](../../THREAT-MODEL.md) — every entry
|
||
|
|
has a `[tests:]` footnote. Toggle each test off, confirm it fails;
|
||
|
|
toggle the corresponding mitigation off, confirm it fails.
|
||
|
|
2. Re-derive every KDF label from the spec; check
|
||
|
|
[`scripts/generate-vectors.ts`](../../scripts/generate-vectors.ts) and
|
||
|
|
the recorded vectors in [`test-vectors/`](../../test-vectors/) match.
|
||
|
|
3. Run the cross-platform suite on **both** TS (bun) and Kotlin
|
||
|
|
(gradle) — divergence is a vector-format bug.
|
||
|
|
4. Audit the AEAD AAD construction at every layer:
|
||
|
|
- Ratchet: header bytes (counter + DH pub) → AES-GCM AAD.
|
||
|
|
- Streams: `streamId || laneId || seq || isLast` → AES-GCM AAD.
|
||
|
|
- Storage: `(table, column, pk)` → AES-GCM AAD.
|
||
|
|
5. Trace the boundary between the worker-side crypto thread and the
|
||
|
|
main thread — confirm that no handle to a wrapped DEK or a
|
||
|
|
ratcheted chain key crosses over.
|
||
|
|
|
||
|
|
## Open questions for reviewer commentary
|
||
|
|
|
||
|
|
- The witness gossip channel for V3.12 is currently in-band over the
|
||
|
|
ratchet; should we cross-pin against an out-of-band log mirror in
|
||
|
|
4.x, or wait for a federated relay tier?
|
||
|
|
- WebRTC peer-glare is resolved by lexicographic address compare — a
|
||
|
|
reviewer could confirm the equivalent constructions in libsignal or
|
||
|
|
Matrix and flag if our edge cases match.
|
||
|
|
- Storage encryption uses AES-GCM with a per-row IV. The IV is
|
||
|
|
random, not deterministic; reviewers should confirm the
|
||
|
|
combinatorial-collision threshold matches the per-column row count
|
||
|
|
bounds.
|