SP Message
Private, invitation-only, end-to-end encrypted messaging — MLS (RFC 9420) for every conversation, passkey sign-in, client-side encrypted attachments and WebRTC calls through a self-hosted TURN relay. The server is a delivery service that holds no key able to decrypt anything.
Author: Simon-Pierre Boucher
Table of contents
- Overview
- Features
- Architecture
- Stack
- Repository layout
- Getting started
- Configuration
- API
- Data model
- Security and privacy
- Testing
- Deployment and operations
- Incidents and gotchas
- Status, limits and open items
- Documentation
- Author
- License
🎯 Overview
SP Message is a private messaging service — https://message.spboucher.ai — for a small circle of invited people.
Self-hosted on MacLustr: custom TypeScript backend (Fastify, PostgreSQL, WebSocket), custom React interface, passkey sign-in (WebAuthn), MLS (RFC 9420) encryption for every conversation, client-side encrypted attachments, WebRTC calls through a self-hosted TURN relay.
- Invitation only. No account exists without an invitation or the one-time administrator bootstrap.
- 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.
- Authentication and encryption are separate. Passkeys only prove who signs in; they never encrypt anything. Encryption identities are generated on the device.
- Honest about its limits. The MLS library has had no independent audit, and a web-delivered E2EE application trusts the server that serves its code — both are stated plainly in
docs/THREAT-MODEL.md.
The SP Message family
| Piece | spbgit repository | Role |
|---|---|---|
| Backend, web application, client engine | sp-message (this repository) | https://message.spboucher.ai |
| macOS and iOS apps | sp-message-apple | SwiftUI interface around the same client engine, hosted by native/core.ts |
✨ Features
| Area | What the code does |
|---|---|
| Accounts | one-time administrator bootstrap, invitations (single or limited use, expiry, revocation, approval), passkey sign-in with discoverable credentials and required user verification, revocable sessions |
| Identity and devices | Ed25519 identity key generated on the first device; one Ed25519 device key per browser, valid only with a certificate signed by the identity key; adding a device is never silent (six-digit code comparison, or recovery key) |
| Messaging | one MLS group per conversation (direct or group), every device a leaf; forward secrecy and post-compromise security; total order of epochs enforced by the server; per-conversation sequence numbers; persistent outbox |
| Encrypted application messages | edits, deletions, reactions, pins, read receipts, group name, disappearing timer, shared tasks, call signalling |
| Attachments | random 256-bit key per file, 1 MiB chunks, AES-256-GCM, resumable chunked upload, tamper / reorder / truncation detection, membership-checked download, quota |
| Calls | WebRTC full mesh up to 6 participants; offers, answers and ICE candidates travel as MLS messages; screen sharing, mute, camera off / switch, speaker selection, picture-in-picture, call waiting, ICE restart, call history |
| Verification | pinned identity keys (trust on first use), 60-digit safety number and QR code, warning when a key changes — a changed key is not used until accepted |
| Self-sync | drafts, private notes and preferences sealed with a key derived from the identity key and synced between a person's own devices |
| Premium | search, scheduling, tasks, notes, bookmarks, waveforms, verification QR |
| Administration | overview (accounts, devices, connections, storage, TURN), people, invitations, sessions, audit log, reset encryption identity, disable account |
| Native host | native/core.ts runs the same engine inside the Apple apps: HTTP, WebSocket and storage are provided by Swift through a message bridge |
| Operations | operator CLI, migrations applied at start, encrypted backup with restore verification, health endpoints |
🏗 Architecture
flowchart LR
subgraph Clients
W["Browser — React + engine<br/>IndexedDB: keys, group states,<br/>decrypted history"]
N["Apple apps — SwiftUI<br/>same engine via native/core.ts"]
end
subgraph GW["Gateway BHS64"]
C["Caddy · HTTPS / WSS<br/>message.spboucher.ai"]
T["coturn 4.6.1<br/>TURN / STUN 3478"]
end
subgraph NODE["MacLustr node M4M64c"]
S["sp-message · port 8720<br/>Fastify API · WebSocket gateway · web"]
PG[("PostgreSQL 17 · sp_message<br/>accounts, devices, ciphertext")]
B[("blobs/<br/>encrypted chunks")]
K["sp-message-backup<br/>daily 03:25"]
end
W -->|HTTPS / WSS| C
N -->|HTTPS / WSS| C
C -->|WireGuard| S
S --- PG
S --- B
K --> PG
W <-.->|"WebRTC media (DTLS-SRTP), direct or relayed"| T
N <-.-> T
What was chosen, and what was evaluated and left out
| Need | Choice | Reason |
|---|---|---|
| Hosting node | M4M64c, port 8720, PM2, placed by mld |
Node, pnpm and PostgreSQL 17 present |
| Public entry | Caddy on the gateway (MacLustr Tunnel) | automatic TLS; WebSocket passes through |
| Metadata store | PostgreSQL 17, database sp_message (local to the node) |
transactions order the group epochs |
| Ephemeral state | in-process (single Node process) | 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. The interface makes the swap local to one file |
| TURN/STUN | coturn 4.6.1 on the gateway, UDP/TCP 3478, relay ports 49160–49400 | LAN nodes sit behind NAT; only the gateway has a public address |
| SFU | not deployed | an SFU terminates DTLS and would see media without frame encryption; group calls are capped at 6 by the mesh |
Sending a message
sequenceDiagram
autonumber
participant A as Device A (engine)
participant S as Server (delivery service)
participant B as Device B (engine)
A->>A: MLS encrypt (application message, client id)
A->>S: POST /api/conversations/:id/messages (ciphertext)
S->>S: membership check, sequence number, store ciphertext
S-->>A: sequence number
S-->>B: WebSocket event
B->>S: GET /api/sync (everything after the device cursor)
S-->>B: ordered ciphertext
B->>B: MLS decrypt, sender read from authenticated content
B->>S: POST /api/conversations/:id/ack
Note over S: ciphertext older than 90 days is deleted
Adding a device by approval
sequenceDiagram
autonumber
participant N as New device
participant S as Server
participant T as Trusted device
N->>N: generate device key + one-time HPKE key
N->>S: POST /api/devices (public keys)
N->>N: show six-digit code derived from the HPKE key
S-->>T: device link request
T->>T: show the same code — the person compares
T->>S: POST /api/devices/:id/approve (certificate + identity key sealed with HPKE)
S-->>N: certificate + sealed identity key
N->>N: open the seal, upload key packages
Note over T,N: a server substituting keys changes the code
Protocol notes
- Ciphersuite
MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519(all primitives from WebCrypto). - Commits (membership changes) are accepted only if built on the current epoch (
409otherwise; the client re-syncs and retries). - 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.
- Typing indicators and presence are plain events (metadata only); presence is opt-in.
- Recovery key: 160 random bits shown once; it decrypts a backup of the identity key (HKDF-SHA256 → AES-256-GCM).
- Attachments: nonce = random prefix ‖ chunk index, associated data = index and final-chunk flag. Key, name, type, dimensions, thumbnail and waveform travel only inside the encrypted message.
🧱 Stack
| Layer | Technology | Version (read in the repository) | Role |
|---|---|---|---|
| Server | Fastify · @fastify/cookie · @fastify/static |
^5.12.8 · ^11.1.5 · ^10.1.11 | API, sessions, web bundle |
| Realtime | ws |
^8.23.0 | WebSocket gateway (/ws) |
| Database | PostgreSQL · postgres |
17 · ^4.1.1 | accounts, devices, ciphertext |
| Validation | Zod | ^4.6.7 | request bodies |
| Auth | @simplewebauthn/server · /browser |
^14.1.0 · ^14.0.0 | passkeys |
| MLS | ts-mls |
^1.6.4 | RFC 9420 |
| HPKE | @hpke/core |
^1.10.1 | RFC 9180, device approval |
| Primitives | @noble/curves · @noble/hashes · @noble/ciphers |
^2.4.0 | Ed25519 and helpers |
| Web | React · react-dom · qrcode |
^19.3.1 · ^1.5.4 | interface, verification QR |
| Tooling | TypeScript · Vite · esbuild · tsx | ^7.0.2 · ^8.3.8 · ^0.28.2 · ^4.23.15 | typecheck, web bundle, server bundle |
| Tests | node:test · Playwright |
— · ^1.65.1 | integration, browser |
| Relay | coturn | 4.6.1 | TURN/STUN |
| Runtime | Node.js | ≥ 22 | engines |
Library evaluation (docs/ARCHITECTURE.md § 7)
| Library | Licence | Role | Maturity |
|---|---|---|---|
ts-mls |
MIT | MLS RFC 9420 | actively maintained, test vectors, no independent audit (stated by its author) |
@hpke/core |
MIT | HPKE RFC 9180 | maintained, WebCrypto based |
@noble/curves |
MIT | Ed25519 public keys | audited family of libraries |
@simplewebauthn/* |
MIT | WebAuthn | widely deployed |
| WebCrypto | — | 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). A Signal-style double ratchet for 1:1 plus MLS for groups was considered; a single protocol was preferred to halve the cryptographic surface.
🗂 Repository layout
server/src/ Fastify API, WebSocket gateway, WebAuthn, blob store, operator CLI — 11 files, 1 628 lines
index.ts server start, security headers, WebSocket upgrade (/ws)
auth.ts session.ts passkeys, bootstrap, invitations, sessions
messaging.ts conversations, commits, messages, key packages, sync
files.ts encrypted object store (four-function interface)
hub.ts WebSocket hub (events, presence, typing)
admin.ts cli.ts administration routes, operator CLI
config.ts db.ts util.ts
web/src/core/ client engine, no DOM — 9 files, 2 592 lines
engine.ts mls.ts crypto.ts identity, MLS, sync, outbox
media.ts calls.ts attachments, WebRTC calls
store.ts transport.ts bytes.ts types.ts
web/src/ui/ React interface — 8 files, 2 639 lines (shell, chat, details, callui, settings, admin, app, bits)
web/src/styles.css the design system (376 lines)
web/public/ icon.svg, manifest.webmanifest (installable web app)
native/core.ts engine host for the native Apple apps (315 lines)
db/migrations/ 001_init.sql, 002_operator_invitations.sql — applied at start
scripts/ build.mjs, node-setup.sh, backup.sh (with restore verification), restore.sh
tests/ integration.test.ts, e2e/ (Playwright), load.ts, native-peer.ts, harness.ts
docs/ ARCHITECTURE, THREAT-MODEL, SECURITY-REVIEW, OPERATIONS + brand/🚀 Getting started
pnpm install
pnpm build # server bundle + web bundle into dist/
pnpm test # 20 integration tests: real server, real PostgreSQL, simulated devices with software passkeys
pnpm test:e2e # 9 browser tests (Chromium, virtual passkey authenticators, real WebRTC call)
pnpm test:load # 16 accounts, 480 group messages, ordering check
pnpm audit --prod # dependency vulnerabilities
node dist/cli.mjs bootstrap|invite|status|revoke-sessionsTests refuse to run against a database whose name does not end in _test.
pnpm script |
Effect |
|---|---|
dev:server · dev:web |
tsx watch server/src/index.ts · Vite |
build |
scripts/build.mjs (esbuild → dist/server.mjs, dist/cli.mjs) then vite build |
start · cli |
node dist/server.mjs · node dist/cli.mjs |
typecheck |
tsc -p . |
test · test:e2e · test:load |
integration · browser · load |
audit |
pnpm audit --prod |
Operator CLI
node dist/cli.mjs status
node dist/cli.mjs bootstrap --ttl 60 # first administrator, single use
node dist/cli.mjs bootstrap --recover # additional administrator when all admin passkeys are lost
node dist/cli.mjs invite --for "Name" --hours 72
node dist/cli.mjs revoke-sessions <handle>
node dist/cli.mjs migrate⚙️ Configuration
Names only — values live in the mld manifest, never in this repository.
| Variable | Role |
|---|---|
HOST, PORT |
listening address (8720 in production) |
DATABASE_URL |
PostgreSQL |
SPM_ORIGIN, SPM_RP_ID |
site origin and WebAuthn relying-party id |
SPM_TRUST_PROXY |
trusted reverse proxy |
SPM_DATA_DIR |
encrypted object store |
SPM_WEB_DIR |
web bundle directory |
SPM_TURN_URLS, SPM_TURN_SECRET |
TURN relay and its shared secret |
SPM_MAX_FILE_BYTES |
attachment size limit (default 4 GiB) |
SPM_MESSAGE_RETENTION_DAYS |
server-side ciphertext retention (default 90) |
SPM_APPLE_APP_IDS |
app ids served by /.well-known/apple-app-site-association |
SPM_RATE_SCALE |
rate-limit multiplier |
SPM_LOG_LEVEL, SPM_VERSION |
logging, reported version |
🔌 API
61 HTTP routes (counted in server/src) plus the WebSocket endpoint /ws, refused with 401 without a session.
Accounts, passkeys, sessions
| Route | Role |
|---|---|
POST /api/invitations/check |
validate an invitation or bootstrap token (sent in the body, never in a path) |
POST /api/register/options · /verify |
create an account with a passkey |
POST /api/login/options · /verify · POST /api/logout |
sign in, sign out |
GET /api/me · PATCH /api/profile |
session and profile |
GET /api/passkeys · POST /api/passkeys/options · /verify · DELETE /api/passkeys/:id |
passkey management |
GET /api/sessions · DELETE /api/sessions/:id · POST /api/session/device |
sessions, binding a session to a device |
Identity, devices, key packages
| Route | Role |
|---|---|
POST /api/identity |
publish the public identity key |
GET/POST /api/devices · POST /api/devices/:id/approve · DELETE /api/devices/:id |
device list, link request, approval, removal |
GET/PUT /api/backup |
identity-key backup (encrypted with the recovery key) |
POST /api/keypackages · POST /api/keypackages/claim · GET /api/keypackages/count |
MLS key packages (capped at 120 per device) |
GET /api/directory · POST /api/users/lookup |
directory of accounts and their certified devices |
Conversations, sync, self-sync
| Route | Role |
|---|---|
POST /api/conversations |
create a direct or group conversation |
POST /api/conversations/:id/commit |
MLS commit, accepted only on the current epoch (409 otherwise) |
GET/POST /api/conversations/:id/messages |
ciphertext, ordered |
POST /api/conversations/:id/ack · /leave · /resync |
acknowledgement, leaving, resync request |
POST /api/welcomes/ack |
welcome messages |
GET /api/sync |
everything after the device cursor |
GET /api/self · PUT/DELETE /api/self/:key |
sealed blobs synced between a person's own devices (200 blobs of 256 KB) |
Files, calls, administration, health
| Route | Role |
|---|---|
POST /api/files · PUT/GET /api/files/:id/chunks/:n · POST /api/files/:id/complete |
resumable chunked upload, download |
GET /api/files/:id · POST /api/files/:id/share · DELETE /api/files/:id |
status, attach to a conversation, delete |
GET /api/turn |
ICE servers and TURN credentials for a call |
GET /api/admin/stats · /users · /users/:id/sessions · /invitations · /audit |
administration views |
POST /api/admin/invitations · DELETE /api/admin/invitations/:id |
invitations |
PATCH /api/admin/users/:id · POST /api/admin/users/:id/reset-identity · DELETE /api/admin/sessions/:id |
disable, reset encryption identity, end a session |
GET /api/health/live · GET /api/health/ready |
process; database and data directory writable |
GET /.well-known/apple-app-site-association · GET /robots.txt |
Apple association file, crawlers |
🗄 Data model
20 PostgreSQL tables (db/migrations/001_init.sql, 209 lines; 002_operator_invitations.sql). The server stores public keys and ciphertext only.
| Group | Tables |
|---|---|
| Accounts | users, passkeys, sessions, challenges, bootstrap_tokens, invitations |
| Devices and keys | devices, key_packages, key_backups |
| Conversations | conversations, conversation_members, messages, welcomes, device_cursors, resync_requests |
| Files | files, file_access |
| Self-sync and settings | self_blobs, settings |
| Audit | audit_log |
erDiagram
users ||--o{ passkeys : has
users ||--o{ sessions : opens
devices ||--o{ sessions : binds
users ||--o{ devices : certifies
users ||--o{ invitations : issues
users ||--o{ key_backups : keeps
users ||--o{ self_blobs : syncs
users ||--o{ files : uploads
devices ||--o{ key_packages : uploads
conversations ||--o{ conversation_members : lists
users ||--o{ conversation_members : joins
conversations ||--o{ messages : orders
conversations ||--o{ welcomes : delivers
devices ||--o{ welcomes : receives
conversations ||--o{ device_cursors : positions
devices ||--o{ device_cursors : tracks
conversations ||--o{ resync_requests : repairs
files ||--o{ file_access : grants
conversations ||--o{ file_access : scopes
🔐 Security and privacy
| Adversary | Can | Cannot |
|---|---|---|
| Network attacker | see that a device talks to the site and to the TURN relay; volume and timing | read or alter anything: TLS to the gateway, WireGuard gateway→node, MLS inside, DTLS-SRTP for calls |
| Curious server administrator / database or backup thief | read accounts, usernames, public keys, membership, timestamps, sizes, acknowledgements, typing and presence events, IP addresses in session and audit records | read message text, reactions, read receipts, group names, file content, file names, thumbnails, call media |
| Malicious server (actively lying) | withhold, delay or drop messages; refuse service; list a false member (ignored for key distribution); advertise a false device (refused: no certificate); advertise a new identity key (warning, not used until accepted) | add a reader without a visible key-change warning; forge a message; replace a working group state; substitute keys during device approval without changing the code |
| Malicious server delivering altered web code | everything — the main residual risk of any web-delivered E2EE application | native apps with signed binaries remove it |
| TURN relay operator | see which IP addresses exchange media and how much | decrypt media |
| Removed member / revoked device | keep what it already decrypted | decrypt anything sent after the commit that removed it; fetch ciphertext |
| Thief of a passkey alone | sign in, see the conversation list, request a device link | read any message: needs approval from a trusted device or the recovery key |
Full table: docs/THREAT-MODEL.md.
Design decisions
- Tokens (session, invitation, bootstrap) are random 256-bit values stored only as SHA-256; invitation and bootstrap tokens travel in the URL fragment and in request bodies, never in a path or query string, so proxies do not log them.
- CSRF: SameSite=Strict cookie + Origin check + custom header; WebSocket origin and session checks; security headers; CSP without inline script.
- Logs record method, path and status. The audit log records administrative and security events with no content.
- Notifications never include message text.
- Disappearing messages are deleted on the server at expiry as well as on devices (a recipient can still copy them).
- Rate limiting: fixed-window, in-memory, single process.
Security review (2026-11-18, before public exposure) — performed by the author of the code; this is not an independent audit. Seven findings, all fixed: two High (a client extended a group to any account the server listed; a welcome could replace a working group state), two Medium, two Low, one Info. Details, tests and evidence: docs/SECURITY-REVIEW.md.
Residual risks, stated plainly
ts-mlshas had no independent security audit.- Web delivery trust: altered JavaScript served by the origin could exfiltrate keys.
- Metadata is visible to the server by design (membership, timing, sizes). No sealed sender, no padding policy beyond the library default.
- Local history in IndexedDB is stored decrypted (secrets are wrapped, messages are not).
- Trust on first use until two people compare safety numbers.
- One-time key packages can run out; the last-resort package is then reused.
- Denial of service by the server or a flooding member is only rate-limited.
- No protection against screenshots, compromised browsers or malicious extensions.
🧪 Testing
| Suite | Command | Count | What it uses |
|---|---|---|---|
| Integration | pnpm test |
20 | real server, real PostgreSQL, simulated devices with software passkeys |
| Browser | pnpm test:e2e |
9 | Chromium, virtual passkey authenticators, a real WebRTC call |
| Load | pnpm test:load |
16 accounts, 480 group messages | ordering check — 7 200 decryptions in 1.2 s, identical order on every device (2026-11-18) |
| Dependencies | pnpm audit --prod |
— | no known vulnerabilities (2026-11-18) |
The 20 integration tests
- bootstrap: one-time administrator creation with a passkey
- registration is impossible without an invitation
- invitations: single use, revocation, expiry, approval
- passkey sign-in, counters, sessions
- CSRF and transport checks
- identity creation on the client; the server only receives public keys
- direct conversation: end-to-end encrypted, authenticated sender, no plaintext on the server
- edits, deletions, reactions, pins, read receipts; only the author can edit
- offline delivery, ordering and deduplication after reconnection
- group conversation: add, remove, removed member loses access
- concurrent commits: the server orders epochs and the loser recovers
- second device by approval: same code on both sides, joins every conversation
- device approval rejects a forged certificate; recovery key restores the identity
- a server-injected device without a valid certificate is never added to a group
- an account the server adds to the member list on its own is never given the group keys
- identity key change raises a warning instead of being trusted silently
- attachments: client-side encryption, resumable chunks, tamper detection, access control, quota
- disappearing messages are removed from the server
- administration: disabling an account cuts sessions and removes its devices from groups
- rate limiting on sign-in
The 9 browser tests
- sign-in page, and an invalid invitation link
- administrator bootstrap with a passkey and client-side key generation
- invitation dashboard, onboarding of an invited person, first encrypted conversation
- reply, reaction, edit, typing indicator, delivery and read state
- encrypted attachment: image upload, preview, download
- contact verification shows the same safety number on both sides
- audio/video call between two browsers with authenticated signalling
- second device: approval with matching codes, then messages arrive on both
- settings, admin people view, mobile navigation, sign-out and sign-in again
📦 Deployment and operations
| Item | Location |
|---|---|
| Application (git clone, source of truth) | M4M64c:~/apps/sp-message (origin: spbgit sp-message.git) |
| Processes | PM2 sp-message (API, WebSocket, web), sp-message-backup (03:25 daily) |
| Database | PostgreSQL 17, sp_message, local |
| Encrypted objects | ~/sp-message-data/blobs on the node |
| Backups | ~/backups/sp-message on the node (14 database archives + mirror of objects) |
| Backup key | ~/.config/sp-message/backup.key on the node — copy it off the node; without it backups cannot be read |
| Manifest | mld manifest on the gateway M1M32 (environment, TURN secret) |
| TURN relay | coturn on BHS64 |
| Public route | Caddy on BHS64, managed by mld |
Do not
mld movethis app: the database and the objects do not follow.
ssh M4M64c
cd ~/apps/sp-message && git pull # or edit here
pnpm install --frozen-lockfile && node scripts/build.mjs && node_modules/.bin/vite build
pm2 restart sp-message # migrations run at start; clients reconnect by themselves
git add -A && git commit -m "…" && git push origin mainRun pnpm test and pnpm test:e2e on a machine with a sp_message_test database before a release.
Health and monitoring
GET /api/health/live(process),GET /api/health/ready(database and data directory writable).mld status --live;mld healrestarts the process and the route every 5 minutes if needed.- Logs:
pm2 logs sp-message(method, path, status; no bodies). Backup log:pm2 logs sp-message-backup. - Admin → Overview shows accounts, devices, connections, storage and whether TURN is configured.
- TURN:
ssh BHS64 systemctl status coturn,journalctl -u coturn.
Backup and recovery — scripts/backup.sh dumps the database, encrypts it (AES-256, PBKDF2, key file), mirrors the objects, then restores the archive into a scratch database and compares row counts; it fails loudly otherwise. Recovery on a fresh node:
mld deploy sp-message --node <node>(creates an empty database),pm2 stop sp-message.- Copy
backup.keyto~/.config/sp-message/, the archive andblobs/to~/backups/sp-message/. dropdb sp_message && createdb sp_message && zsh scripts/restore.sh ~/backups/sp-message/db-<stamp>.dump.encpm2 start sp-message.
A restore brings back accounts, passkeys, devices, conversations, undelivered ciphertext and files. It cannot bring back messages already delivered and purged, nor anything that only lived on a lost device.
🧯 Incidents and gotchas
| Situation | Action |
|---|---|
| A person lost one device | They remove it in Settings → Devices from another device |
| A person lost every device, has the recovery key | They sign in with their passkey on a new device and choose “Use my recovery key” |
| A person lost every device and the recovery key | Admin → People → Manage → Reset encryption identity; the person enrols again; contacts see a key-change warning and must accept and add them back |
| A person lost every passkey | Their account cannot sign in; disable it and invite them again |
| Administrator lost every passkey | node dist/cli.mjs bootstrap --recover on the node |
| Suspected compromise of an account | Admin → People → Disable (sessions end, devices are removed from all groups) |
| TURN secret leaked | New secret in /etc/turnserver.conf and in the manifest (SPM_TURN_SECRET), restart coturn, mld deploy sp-message |
- Tests need a
_testdatabase: they refuse to run otherwise. - Never
mld move: data does not follow the app. - History on a new device starts when the device is added — a consequence of forward secrecy, not a bug.
- 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.
- Safari may evict IndexedDB after 7 days without use in a tab; installing the site to the Home Screen avoids the eviction policy.
- Calls on restrictive networks: TURN listens on UDP/TCP 3478 without TLS; networks that only allow 443 will not connect calls.
- Restart loses ephemeral state: rate-limit counters, presence and typing state are in-process.
🧭 Status, limits and open items
| Phase | Criteria | Status |
|---|---|---|
| 1 Foundation | bootstrap is single use; no registration without invitation; invitation rules 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 | Met for 1:1. Group mesh implemented, not tested with 3+ real participants |
| 6 Premium | search, scheduling, tasks, notes, bookmarks, waveforms, verification QR | Implemented, with the limits below |
| 7 Hardening | review, tests, load, deployment, backup with restore verification | Done |
Not implemented, or limited
- On-device transcription, local translation, semantic search, AI assistance: not implemented; nothing is sent to any AI provider.
- Push notifications when the app is closed: not implemented (needs a service worker and Web Push).
- 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.
Open items (not fixed)
- Independent audit of
ts-mlsand of this integration: not done. - Real Face ID / Touch ID and real iPhone / iPad / Mac Safari: not tested (virtual authenticator in Chromium only).
- Group calls with three or more real participants: not tested.
- The gateway access log records request paths; no secret is ever placed in a path.
- No
turns:listener on 443. - Backups stay on the hosting node; an off-node copy is not configured.
- No step-up passkey check for administrative actions.
📚 Documentation
| Document | Content |
|---|---|
| docs/ARCHITECTURE.md | Components, protocol design, library evaluation, phases and acceptance criteria, platform limits |
| docs/THREAT-MODEL.md | Assets, adversaries, what each one can and cannot do, residual risks |
| docs/SECURITY-REVIEW.md | Review performed before exposure: findings, fixes, tests, open items |
| docs/OPERATIONS.md | Deployment, operator commands, backups, recovery, monitoring |
👤 Author
Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 License
UNLICENSED (package.json, private repository) — all rights reserved © 2026 Simon-Pierre Boucher.