SPB Git

Repository Public

README.md 37.9 KB

SP Message logo



SP Message icon

# 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

message.spboucher.ai version platform encryption license author

Fastify ws React TypeScript Vite PostgreSQL postgres.js Node.js ts-mls HPKE noble WebAuthn WebRTC coturn Zod esbuild Playwright pnpm

commits last commit activity language languages size branches tags clones

HTTP routes WebSocket tables migrations integration tests browser tests load test audit TypeScript files TypeScript lines

node port PM2 TURN deploy tunnel


# Table of contents


# 🎯 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 (409 otherwise; 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

text
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

bash
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-sessions

Tests 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

bash
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

  1. ts-mls has had no independent security audit.
  2. Web delivery trust: altered JavaScript served by the origin could exfiltrate keys.
  3. Metadata is visible to the server by design (membership, timing, sizes). No sealed sender, no padding policy beyond the library default.
  4. Local history in IndexedDB is stored decrypted (secrets are wrapped, messages are not).
  5. Trust on first use until two people compare safety numbers.
  6. One-time key packages can run out; the last-resort package is then reused.
  7. Denial of service by the server or a flooding member is only rate-limited.
  8. 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
  1. bootstrap: one-time administrator creation with a passkey
  2. registration is impossible without an invitation
  3. invitations: single use, revocation, expiry, approval
  4. passkey sign-in, counters, sessions
  5. CSRF and transport checks
  6. identity creation on the client; the server only receives public keys
  7. direct conversation: end-to-end encrypted, authenticated sender, no plaintext on the server
  8. edits, deletions, reactions, pins, read receipts; only the author can edit
  9. offline delivery, ordering and deduplication after reconnection
  10. group conversation: add, remove, removed member loses access
  11. concurrent commits: the server orders epochs and the loser recovers
  12. second device by approval: same code on both sides, joins every conversation
  13. device approval rejects a forged certificate; recovery key restores the identity
  14. a server-injected device without a valid certificate is never added to a group
  15. an account the server adds to the member list on its own is never given the group keys
  16. identity key change raises a warning instead of being trusted silently
  17. attachments: client-side encryption, resumable chunks, tamper detection, access control, quota
  18. disappearing messages are removed from the server
  19. administration: disabling an account cuts sessions and removes its devices from groups
  20. rate limiting on sign-in
The 9 browser tests
  1. sign-in page, and an invalid invitation link
  2. administrator bootstrap with a passkey and client-side key generation
  3. invitation dashboard, onboarding of an invited person, first encrypted conversation
  4. reply, reaction, edit, typing indicator, delivery and read state
  5. encrypted attachment: image upload, preview, download
  6. contact verification shows the same safety number on both sides
  7. audio/video call between two browsers with authenticated signalling
  8. second device: approval with matching codes, then messages arrive on both
  9. 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 move this app: the database and the objects do not follow.

bash
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 main

Run 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 heal restarts 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:

  1. mld deploy sp-message --node <node> (creates an empty database), pm2 stop sp-message.
  2. Copy backup.key to ~/.config/sp-message/, the archive and blobs/ to ~/backups/sp-message/.
  3. dropdb sp_message && createdb sp_message && zsh scripts/restore.sh ~/backups/sp-message/db-<stamp>.dump.enc
  4. pm2 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 _test database: 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)

  1. Independent audit of ts-mls and of this integration: not done.
  2. Real Face ID / Touch ID and real iPhone / iPad / Mac Safari: not tested (virtual authenticator in Chromium only).
  3. Group calls with three or more real participants: not tested.
  4. The gateway access log records request paths; no secret is ever placed in a path.
  5. No turns: listener on 443.
  6. Backups stay on the hosting node; an off-node copy is not configured.
  7. 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.

Files main
Menu

Theme