SPB Git

Repository Public

ARCHITECTURE.md 9.2 KB 127 lines markdown

1# Architecture23## 1. What was inspected and chosen (2026-11-18)45| Need | Choice | Reason |6|---|---|---|7| Hosting node | **M4M64c**, port 8720, PM2, placed by `mld` | Node 26, pnpm, PostgreSQL 17 present; 64 GB RAM, 255 GB free |8| Public entry | Caddy on BHS64 (MacLustr Tunnel), route `message.spboucher.ai → M4M64c:8720` | Existing gateway; automatic TLS; WebSocket passes through |9| Metadata store | PostgreSQL 17, database `sp_message` (local to the node) | Already installed; transactions order the group epochs |10| 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 |11| 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 |12| 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 |13| SFU | **Not deployed**, see §6 | |1415Nothing existing was modified except additions on BHS64: the `coturn` package, `/etc/turnserver.conf`, three `ufw` allow rules.1617## 2. Components1819```20Browser (React + engine)  ──HTTPS/WSS──►  Caddy (BHS64)  ──WireGuard──►  Node server (M4M64c:8720)21   IndexedDB: keys, group states,                                         ├─ PostgreSQL: accounts, devices, ciphertext22   decrypted history                                                      └─ ~/sp-message-data/blobs: encrypted chunks23Browser ◄──────── WebRTC media (DTLS-SRTP), direct or via coturn on BHS64 ────────► Browser24```2526The server is a *delivery service*: it authenticates accounts, stores and orders ciphertext, hands out public key27packages, and relays events. It holds no key able to decrypt a message, a file or a call.2829## 3. Identity and devices3031- **Passkeys** (WebAuthn, `@simplewebauthn` 14): discoverable credentials, user verification required. They only prove32  who signs in. They never encrypt anything.33- **Identity key** (Ed25519), generated in the browser on the first device. Its public half is published.34- **Device key** (Ed25519) per browser/device, generated locally. A device is valid only with a *certificate*: a35  signature by the identity key over (account id, device id, device public key).36- **Adding a device** is never silent:37  - *approval*: the new device shows a six-digit code derived from its one-time HPKE key; a trusted device shows the same38    code; on approval it signs the certificate and seals the identity key to the new device (HPKE, RFC 9180). A server39    substituting keys changes the code.40  - *recovery key*: 160 random bits shown once; it decrypts a backup of the identity key (HKDF-SHA256 → AES-256-GCM).41    Other devices are notified.42- **Pinning**: each client remembers the identity key of each contact (trust on first use), shows a 60-digit safety43  number and QR code for verification, and raises a warning when a key changes. A changed key is not used until the44  person accepts it.4546## 4. Messaging protocol4748One MLS group per conversation (direct or group). Every *device* is a leaf, so multi-device, groups, forward secrecy and49post-compromise security come from one protocol. Ciphersuite `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` (all50primitives from WebCrypto).5152- Commits (membership changes) are accepted by the server only if built on the current epoch (`409` otherwise; the53  client re-syncs and retries). This gives a total order.54- Application messages carry a client id (deduplication) and get a per-conversation sequence number.55- Each device keeps a cursor; after reconnection it fetches everything after it, in order. Unsent messages wait in a56  persistent outbox.57- The sender of each message is read from the authenticated MLS content, not from the server envelope.58- Clients *reconcile* groups with the directory: they add newly certified devices of accounts **already in the group**,59  and remove revoked devices and departed accounts. They never add an account because the server lists it.60- Edits, deletions, reactions, pins, read receipts, group name, disappearing timer, shared tasks and call signalling are61  all encrypted application messages. Typing indicators and presence are plain events (metadata only); presence is62  opt-in.63- Drafts, private notes and preferences are sealed with a key derived from the identity key and synced between a64  person's own devices.6566## 5. Attachments6768Random 256-bit key per file; 1 MiB chunks, AES-256-GCM, nonce = random prefix ‖ chunk index, associated data = index69and final-chunk flag (reordering, truncation and substitution fail). Upload is chunked and resumable (the server reports70which chunks it holds). Key, name, type, dimensions, thumbnail and waveform travel only inside the encrypted message.71Download requires membership of a conversation the file was attached to. Quota is reserved at upload start.7273## 6. Calls7475WebRTC, full mesh, up to 6 participants. Offers, answers (with DTLS fingerprints) and ICE candidates are MLS76application messages, so media keys are authenticated end to end; coturn only relays DTLS-SRTP packets. Screen sharing,77mute, camera off, camera switch, speaker selection, picture-in-picture, call waiting, ICE restart on failure, call78history.7980**SFU evaluation.** LiveKit and mediasoup were considered. An SFU terminates DTLS, so it sees media unless frames are81additionally encrypted (SFrame / insertable streams), which Safari supports only partly. Deploying one without frame82encryption would break the end-to-end promise, so none is deployed; group calls are capped at 6 by the mesh.8384## 7. Library evaluation8586| Library | Version | Licence | Role | Maturity |87|---|---|---|---|---|88| `ts-mls` | 1.6.4 | MIT | MLS RFC 9420 | Actively maintained, test vectors, **no independent audit** (stated by its author) |89| `@hpke/core` | 1.10 | MIT | HPKE RFC 9180 | Maintained, WebCrypto based |90| `@noble/curves` | 2.4 | MIT | Ed25519 public keys | Audited family of libraries |91| `@simplewebauthn/*` | 14 | MIT | WebAuthn | Widely deployed |92| WebCrypto | browser | — | AES-GCM, HKDF, SHA-256, Ed25519, X25519 | Platform |9394Rejected: `@signalapp/libsignal-client` (AGPL-3.0, Node native addon, no supported browser build);95`libsignal-protocol-typescript` (GPL-3.0, unmaintained); Matrix vodozemac (audited, but Olm/Megolm has weaker group96post-compromise security and its JS binding is tied to the Matrix stack); OpenMLS / mls-rs (Rust, more mature, **no97published browser package** — the natural replacement if `ts-mls` proves insufficient, and the candidate for native98apps). A Signal-style double ratchet for 1:1 plus MLS for groups was considered; a single protocol was preferred to99halve the cryptographic surface.100101## 8. Phases and acceptance criteria102103| Phase | Criteria | Status |104|---|---|---|105| 1 Foundation | bootstrap is single use; no registration without invitation; invitation expiry/limit/revocation/approval enforced | Met (integration tests 1–4) |106| 2 Secure messaging | no plaintext in the database; sender authenticated; offline delivery in order without duplicates | Met (tests 7–9) |107| 3 Media | ciphertext at rest; tampering and reordering detected; access limited to members; quota | Met (test 17, browser test 5) |108| 4 Multi-device and groups | matching codes; forged certificate refused; removed member cannot read; key-change warning | Met (tests 10–16) |109| 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** |110| 6 Premium | search, scheduling, tasks, notes, bookmarks, waveforms, verification QR | Implemented; see limits below |111| 7 Hardening | review, tests, load, deployment, backup with restore verification | Done, see SECURITY-REVIEW.md |112113## 9. Not implemented, or limited114115- **On-device transcription, local translation, semantic search, AI assistance**: not implemented. The engine exposes116  decrypted history only to code running on the device, which is where such features would attach; nothing is sent to117  any AI provider.118- **Push notifications when the app is closed**: not implemented (needs a service worker and Web Push). Notifications119  appear while a tab or the installed web app is open.120- **History on a new device**: starts when the device is added (a consequence of forward secrecy; no history transfer).121- **Scheduled messages** are sent by the device that scheduled them, which must be open at that time.122- **Upload resumption** survives network loss, not a page reload.123- **Message retention**: ciphertext older than 90 days is deleted from the server; devices keep their own history.124- **Browser limits**: iOS Safari has no screen sharing and no speaker selection; picture-in-picture and QR scanning125  depend on the browser; HEIC previews render only where the browser decodes HEIC (Safari), otherwise the file is sent126  as a document.127
Files main
Menu

Theme