Shade/docs/audit/REVIEW-BUNDLE.md

Shade 4.0 — External Crypto Review Bundle

This document is the entrypoint for an external cryptographic review of Shade 4.0. It collects, in one place, every artifact a reviewer needs to audit the protocol implementation without rooting around the codebase first.

Tag under review

• Version: 4.0.0
• Tag: v4.0.0
• Date: 2026-05-03
• Repo: https://gt.zyon.no/Stian/Shade (mirror at the consumer-app repos that vendor this code)
• Out-of-scope: Voice / Video / Broadcast — moved to V5.0 and reviewed separately.

What's in scope

Reviewers focus on the protocol-cryptographic core. Each scope cell maps to one or more packages plus the spec / threat-model section that describes its design.

A — Protocol core (highest priority)

Surface	Spec	Code
X3DH initial key agreement	docs/archive/V3.1.md, THREAT-MODEL.md §1, §2	packages/shade-core/src/x3dh.ts
Double Ratchet	docs/archive/V3.1.md, THREAT-MODEL.md §3	packages/shade-core/src/ratchet.ts
Sender keys (group ratchet)	docs/archive/V3.10.md § Group send	packages/shade-core/src/sender-keys.ts
Wire envelopes 0x01, 0x02, 0x11	packages/shade-proto/README.md	packages/shade-proto/src/
At-rest storage encryption	docs/storage-encryption.md, THREAT-MODEL.md §4	packages/shade-storage-encrypted/src/
Social recovery (Shamir + AEAD-gated reconstruction)	docs/recovery.md, THREAT-MODEL.md §8	packages/shade-recovery/src/

B — Trust + transport

Surface	Spec	Code
WebRTC P2P transport binding	docs/webrtc.md, THREAT-MODEL.md §11	packages/shade-transport-webrtc/src/
Key Transparency log + verifier	docs/key-transparency.md, docs/archive/V3.12-DESIGN.md, THREAT-MODEL.md §2 (mitigated-by-V3.12)	packages/shade-key-transparency/src/
Fingerprint gates	docs/trust-ux.md, THREAT-MODEL.md §10	packages/shade-sdk/src/fingerprint-gates.ts

C — Lower-priority surfaces

Surface	Spec	Code
Inbox store-and-forward	docs/inbox.md, THREAT-MODEL.md §6	packages/shade-inbox-server/src/, packages/shade-inbox/src/
Bridge transports (SSE / long-poll / WS)	docs/transport.md	packages/shade-transport-bridge/src/
Web Workers crypto	docs/web-workers.md, THREAT-MODEL.md §12	packages/shade-crypto-web/src/worker*
Files RPC	docs/files.md	packages/shade-files/src/
Streams (chunked AEAD over ratchet)	docs/streams.md	packages/shade-streams/src/, packages/shade-transfer/src/
Observability	docs/observability.md	packages/shade-observability/src/

Threat model

The full threat model is at THREAT-MODEL.md. Every numbered "Mitigations" entry ends with a [tests:] footnote linking to the file(s) that holds the mitigation in place. Reviewers can re-run any individual test in isolation:

bun test packages/shade-core/tests/ratchet.test.ts
bun test packages/shade-streams/tests/aead.test.ts
bun test packages/shade-key-transparency/tests/manager.test.ts

Cross-platform parity

The wire format and KDF-label corpus are byte-identical between TS (bun) and Kotlin (gradle). The CI gate that enforces this lives at .gitea/workflows/cross-vectors.yml. Vectors are generated by scripts/generate-vectors.ts; hand-edits to test-vectors/ are rejected by CI.

# Re-run the cross-platform vector suite locally:
bun run test:vectors
cd android && ./gradlew :shade-android:test

Build instructions (reproducible)

git clone https://gt.zyon.no/Stian/Shade
cd Shade
git checkout v4.0.0
bun install --frozen-lockfile

# TS suite
bun test

# Kotlin / vector suite
cd android && ./gradlew :shade-android:test

Container image (prekey + transfer + bridge + KT):

docker pull gt.zyon.no/stian/shade-prekey:4.0.0
docker run --rm -p 3900:3900 \
  -e SHADE_PREKEY_PG_URL=postgres://… \
  gt.zyon.no/stian/shade-prekey:4.0.0

The Dockerfile is at packages/shade-server/Dockerfile. Multi-stage; the runtime stage uses a non-root user.

Assumptions and known limitations

1. The runtime is honest. A malicious Bun / browser engine can defeat any JS library; we ride the platform's SubtleCrypto / @noble/curves for primitives and trust them.
2. THREAT-MODEL.md section "Assumptions" is the canonical list; review the residual-risks table at the bottom of the same file for intentional gaps.
3. We do not claim resistance to power-analysis or fault-injection side channels.
4. Memory zeroization is best-effort. V8 / JSC may retain freed buffers; we zero what we can synchronously reach.

How to report findings

• Severity-prioritized (CVSS 3.1 if you can, otherwise plain language).
• Reproducer in repo style — a failing bun test is preferred over prose.
• Email the maintainer (Sterister@live.no); see SECURITY.md for PGP / age key arrangement.

Timeline

The 4.0 audit window is open immediately after tag. We aim for a 4–8-week review cycle (see V4.0 plan). Any critical or high severity finding pauses the GA-stable announcement until the fix ships. Findings ship as 4.0.x patch releases — wire-format unchanged.

Out-of-scope (deferred to V5.0)

• Voice (@shade/voice) — SFrame-style frame keys, key-rotation policies.
• Video (@shade/video) — codec edges (AV1/VP9/H.264).
• Broadcast (@shade/broadcast) — relay-helper threat model.

These will get their own review window when V5.0 is ready.