SPB Git

Repository Public

ARCHITECTURE.md 9.2 KB

# Architecture

# 1. What was inspected and chosen (2026-11-18)

Need Choice Reason
Hosting node M4M64c, port 8720, PM2, placed by mld Node 26, pnpm, PostgreSQL 17 present; 64 GB RAM, 255 GB free
Public entry Caddy on BHS64 (MacLustr Tunnel), route message.spboucher.ai → M4M64c:8720 Existing gateway; automatic TLS; WebSocket passes through
Metadata store PostgreSQL 17, database sp_message (local to the node) Already installed; transactions order the group epochs
Ephemeral state In-process (single Node process) One process serves the whole private network; Redis was evaluated and not added: nothing needs to be shared between processes yet. Rate-limit counters, presence and typing state are lost on restart, which is acceptable
Object storage Directory tree behind a four-function interface (server/src/files.ts) Objects are already ciphertext; MinIO/S3 was evaluated and not added: one more service to run for no security or durability gain on a single node. The interface makes the swap local to one file
TURN/STUN coturn 4.6.1 on BHS64 (public IP), UDP/TCP 3478, relay ports 49160–49400 LAN nodes sit behind NAT; only the gateway has a public address
SFU Not deployed, see §6

Nothing existing was modified except additions on BHS64: the coturn package, /etc/turnserver.conf, three ufw allow rules.

# 2. Components

text
Browser (React + engine)  ──HTTPS/WSS──►  Caddy (BHS64)  ──WireGuard──►  Node server (M4M64c:8720)
   IndexedDB: keys, group states,                                         ├─ PostgreSQL: accounts, devices, ciphertext
   decrypted history                                                      └─ ~/sp-message-data/blobs: encrypted chunks
Browser ◄──────── WebRTC media (DTLS-SRTP), direct or via coturn on BHS64 ────────► Browser

The server is a delivery service: it authenticates accounts, stores and orders ciphertext, hands out public key packages, and relays events. It holds no key able to decrypt a message, a file or a call.

# 3. Identity and devices

  • Passkeys (WebAuthn, @simplewebauthn 14): discoverable credentials, user verification required. They only prove who signs in. They never encrypt anything.
  • Identity key (Ed25519), generated in the browser on the first device. Its public half is published.
  • Device key (Ed25519) per browser/device, generated locally. A device is valid only with a certificate: a signature by the identity key over (account id, device id, device public key).
  • Adding a device is never silent:
    • approval: the new device shows a six-digit code derived from its one-time HPKE key; a trusted device shows the same code; on approval it signs the certificate and seals the identity key to the new device (HPKE, RFC 9180). A server substituting keys changes the code.
    • recovery key: 160 random bits shown once; it decrypts a backup of the identity key (HKDF-SHA256 → AES-256-GCM). Other devices are notified.
  • Pinning: each client remembers the identity key of each contact (trust on first use), shows a 60-digit safety number and QR code for verification, and raises a warning when a key changes. A changed key is not used until the person accepts it.

# 4. Messaging protocol

One MLS group per conversation (direct or group). Every device is a leaf, so multi-device, groups, forward secrecy and post-compromise security come from one protocol. Ciphersuite MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519 (all primitives from WebCrypto).

  • Commits (membership changes) are accepted by the server only if built on the current epoch (409 otherwise; the client re-syncs and retries). This gives a total order.
  • Application messages carry a client id (deduplication) and get a per-conversation sequence number.
  • Each device keeps a cursor; after reconnection it fetches everything after it, in order. Unsent messages wait in a persistent outbox.
  • The sender of each message is read from the authenticated MLS content, not from the server envelope.
  • Clients reconcile groups with the directory: they add newly certified devices of accounts already in the group, and remove revoked devices and departed accounts. They never add an account because the server lists it.
  • Edits, deletions, reactions, pins, read receipts, group name, disappearing timer, shared tasks and call signalling are all encrypted application messages. Typing indicators and presence are plain events (metadata only); presence is opt-in.
  • Drafts, private notes and preferences are sealed with a key derived from the identity key and synced between a person's own devices.

# 5. Attachments

Random 256-bit key per file; 1 MiB chunks, AES-256-GCM, nonce = random prefix ‖ chunk index, associated data = index and final-chunk flag (reordering, truncation and substitution fail). Upload is chunked and resumable (the server reports which chunks it holds). Key, name, type, dimensions, thumbnail and waveform travel only inside the encrypted message. Download requires membership of a conversation the file was attached to. Quota is reserved at upload start.

# 6. Calls

WebRTC, full mesh, up to 6 participants. Offers, answers (with DTLS fingerprints) and ICE candidates are MLS application messages, so media keys are authenticated end to end; coturn only relays DTLS-SRTP packets. Screen sharing, mute, camera off, camera switch, speaker selection, picture-in-picture, call waiting, ICE restart on failure, call history.

SFU evaluation. LiveKit and mediasoup were considered. An SFU terminates DTLS, so it sees media unless frames are additionally encrypted (SFrame / insertable streams), which Safari supports only partly. Deploying one without frame encryption would break the end-to-end promise, so none is deployed; group calls are capped at 6 by the mesh.

# 7. Library evaluation

Library Version Licence Role Maturity
ts-mls 1.6.4 MIT MLS RFC 9420 Actively maintained, test vectors, no independent audit (stated by its author)
@hpke/core 1.10 MIT HPKE RFC 9180 Maintained, WebCrypto based
@noble/curves 2.4 MIT Ed25519 public keys Audited family of libraries
@simplewebauthn/* 14 MIT WebAuthn Widely deployed
WebCrypto browser — AES-GCM, HKDF, SHA-256, Ed25519, X25519 Platform

Rejected: @signalapp/libsignal-client (AGPL-3.0, Node native addon, no supported browser build); libsignal-protocol-typescript (GPL-3.0, unmaintained); Matrix vodozemac (audited, but Olm/Megolm has weaker group post-compromise security and its JS binding is tied to the Matrix stack); OpenMLS / mls-rs (Rust, more mature, no published browser package — the natural replacement if ts-mls proves insufficient, and the candidate for native apps). A Signal-style double ratchet for 1:1 plus MLS for groups was considered; a single protocol was preferred to halve the cryptographic surface.

# 8. Phases and acceptance criteria

Phase Criteria Status
1 Foundation bootstrap is single use; no registration without invitation; invitation expiry/limit/revocation/approval enforced Met (integration tests 1–4)
2 Secure messaging no plaintext in the database; sender authenticated; offline delivery in order without duplicates Met (tests 7–9)
3 Media ciphertext at rest; tampering and reordering detected; access limited to members; quota Met (test 17, browser test 5)
4 Multi-device and groups matching codes; forged certificate refused; removed member cannot read; key-change warning Met (tests 10–16)
5 Calls two browsers exchange live video with encrypted signalling; relay-only path works through coturn Met for 1:1 (browser test 7, production relay check). Group mesh implemented, not tested with 3+ real participants
6 Premium search, scheduling, tasks, notes, bookmarks, waveforms, verification QR Implemented; see limits below
7 Hardening review, tests, load, deployment, backup with restore verification Done, see SECURITY-REVIEW.md

# 9. Not implemented, or limited

  • On-device transcription, local translation, semantic search, AI assistance: not implemented. The engine exposes decrypted history only to code running on the device, which is where such features would attach; nothing is sent to any AI provider.
  • Push notifications when the app is closed: not implemented (needs a service worker and Web Push). Notifications appear while a tab or the installed web app is open.
  • History on a new device: starts when the device is added (a consequence of forward secrecy; no history transfer).
  • Scheduled messages are sent by the device that scheduled them, which must be open at that time.
  • Upload resumption survives network loss, not a page reload.
  • Message retention: ciphertext older than 90 days is deleted from the server; devices keep their own history.
  • Browser limits: iOS Safari has no screen sharing and no speaker selection; picture-in-picture and QR scanning depend on the browser; HEIC previews render only where the browser decodes HEIC (Safari), otherwise the file is sent as a document.
Files main
Menu

Theme