SP Message — macOS and iOS apps
Native SwiftUI clients of the private, end-to-end encrypted SP Message service: same account, same passkeys, same conversations — with the MLS client engine shipped inside the signed app instead of being delivered by the server.
Author: Simon-Pierre Boucher
Table of contents
- Overview
- Features
- Not in the apps
- Architecture
- Stack
- Repository layout
- Build
- Configuration
- Screens
- Engine bridge
- Local data
- Security and privacy
- Testing
- Release
- State on 2026-11-18
- Gotchas
- Author
- License
🎯 Overview
Native SwiftUI clients of https://message.spboucher.ai (same account, same passkeys, same conversations).
- Interface: SwiftUI, one code base for macOS 15+ and iOS/iPadOS 18+ (
Sources/Views). - Sign-in: system passkeys (
AuthenticationServices), relying partymessage.spboucher.aithrough Associated Domains. - Encryption engine: the client engine of the web application (MLS, identity, sync, attachments — TypeScript,
native/core.tsin the server repository) is bundled into the app asResources/core.jsand runs in an isolated script context (Sources/Core/EngineHost.swift). That context loads nothing from the network: HTTPS, WebSocket and storage are provided by Swift (Net.swift,KV.swift). The engine code is therefore part of the signed app, not delivered by the server. - Local data: SQLite in Application Support, excluded from backups; device keys and group states sealed with AES-256-GCM under a key held in the Keychain (this device only).
Why it matters. The main residual risk of any web-delivered end-to-end encrypted application is a server that serves altered JavaScript. Here the engine is inside a signed (and, on macOS, notarized) binary, which removes that risk for these clients.
The SP Message family
| Piece | spbgit repository | Role |
|---|---|---|
Backend, web application, client engine, native/core.ts |
sp-message | https://message.spboucher.ai |
| macOS and iOS / iPadOS apps | sp-message-apple (this repository) | native clients |
✨ Features
| Area | What the apps do |
|---|---|
| Sign-in and onboarding | « Sign in with a passkey »; join with an invitation link (name, handle, « Create my passkey »); first device creates the encryption keys and shows the recovery key once |
| Linking a device | « Approve from another device » with a code compared on both sides, or « Enter your recovery key »; a trusted device shows the approval sheet (« Codes match: approve » / « Refuse ») |
| Conversations | list with search of messages and people, new direct conversation or group (« Create group », group name), leave a group, mute notifications |
| Messages | send, reply (quoted), edit, « Delete for everyone », reactions, pin, copy, typing indicator, states Sending → Sent → Delivered → Read and Not sent; « Forwarded from » is displayed |
| Offline | « Offline. Messages are kept and sent on reconnection. » |
| Attachments | file or « Photo or video », encrypted on the device before they leave it; optional reduction of large photos; files above 200 MB must be sent from the web application |
| Disappearing messages | per-conversation timer |
| Verification | safety number per contact, « Mark as verified » / « Remove verification », identity key fingerprint; key-change warning with « Accept new key » and « Add them back » |
| Details | MLS epoch and device count of the conversation, members, security section |
| Settings | name shown to contacts, privacy (read receipts, notifications that never show message text), trusted devices (remove), « Generate a new recovery key », « Sign out », « Sign out and erase this device » |
| Notifications | local notifications while the app runs; they never include message text |
| Languages | English and French, chosen from the system language (L(en, fr) helper) |
🚫 Not in the apps (use the web application)
Calls, administration (invitations, accounts), voice messages, scheduled messages, shared tasks and notes, message forwarding, QR verification (the safety number is shown), push notifications when the app is closed.
🏗 Architecture
flowchart TB
subgraph APP["SP Message.app — signed bundle"]
UI["SwiftUI — Sources/Views<br/>RootView · MainView · ChatView · Theme"]
MODEL["AppModel<br/>state, engine calls"]
subgraph HOST["EngineHost — isolated WKWebView (1×1, non-persistent store)"]
JS["Resources/core.js<br/>engine: identity · MLS · sync · attachments"]
end
NET["Net.swift<br/>URLSession HTTPS + WebSocket"]
KV[("KV.swift<br/>SQLite store.sqlite · AES-256-GCM")]
PK["Passkey.swift<br/>AuthenticationServices"]
end
KC[("Keychain<br/>wrapping key, this device only")]
SRV["https://message.spboucher.ai<br/>delivery service — ciphertext only"]
UI --> MODEL
MODEL -->|"host.call(op, args)"| JS
JS -->|"bridge: http · ws-* · kv-*"| NET
JS --> KV
MODEL --> PK
KV --> KC
NET -->|HTTPS / WSS| SRV
PK -->|"/api/login/* · /api/register/*"| SRV
The engine context loads nothing from the network. Every request it makes is a bridge message answered by Swift; every piece of state it keeps goes through KV.
Sending a message
sequenceDiagram
autonumber
participant V as ChatView
participant M as AppModel
participant E as Engine (core.js)
participant S as Swift bridge (Net / KV)
participant B as message.spboucher.ai
V->>M: send(text)
M->>E: host.call("send", …)
E->>E: MLS encrypt on this device
E->>S: kv-set (outbox, group state — sealed)
E->>S: http POST /api/conversations/:id/messages
S->>B: HTTPS (ciphertext)
B-->>S: sequence number
S-->>E: status + body
E->>S: changed
S->>M: onChanged → snapshot
M-->>V: state « Sent », then « Delivered » / « Read »
Adding this device to an existing account
sequenceDiagram
autonumber
participant N as New device (this app)
participant B as Server
participant T as Trusted device (app or web)
N->>B: sign in with the passkey
N->>B: requestLink (device public keys)
N->>N: show the code
B-->>T: « A new device wants to join your account »
T->>T: compare the code — « Codes match: approve »
T->>B: approve (certificate + sealed identity key)
N->>B: pollLink
B-->>N: certificate + sealed identity key
Note over N: messages sent before this device was added stay on the other devices
🧱 Stack
| Layer | Technology | Version (read in the repository) | Role |
|---|---|---|---|
| Language | Swift | SWIFT_VERSION: "5.0" |
apps |
| UI | SwiftUI | macOS 15.0 / iOS 18.0 deployment targets | one code base |
| Project | XcodeGen | project.yml |
project and entitlements generated |
| Passkeys | AuthenticationServices | — | relying party message.spboucher.ai |
| Engine host | WebKit (WKWebView, WKScriptMessageHandlerWithReply) |
— | isolated script context |
| Engine | TypeScript bundled by esbuild | format: iife, target: safari17, minified |
MLS (RFC 9420), identity, sync, attachments |
| Networking | URLSession | — | HTTPS and WebSocket |
| Storage | SQLite3 (system), CryptoKit, Security | — | sealed key-value store |
| Tooling | zsh / bash scripts, Python (provision.py, asc.py) |
— | build, provisioning, release |
🗂 Repository layout
project.yml XcodeGen: targets SPMessage (macOS) and SPMessage-iOS, entitlements, Info.plist keys
Sources/ 12 Swift files, 1 555 lines
App.swift app entry point
AppModel.swift observable state, engine calls, sign-in / join / recover / sign-out, notifications
Core/
Config.swift server origin (fixed in Release), relying-party id, device label
EngineHost.swift isolated script context + bridge
Net.swift URLSession HTTP and WebSocket
KV.swift SQLite key-value store, AES-256-GCM sealing, Keychain key
Passkey.swift passkey registration and assertion
Models.swift decoded engine snapshots
Views/
RootView.swift sign-in, join, first device, recovery key, link device, pending approval
MainView.swift conversation list, new conversation, device approval, settings
ChatView.swift conversation, message rows, attachments, details
Theme.swift avatar, buttons, logo
Resources/Assets.xcassets AppIcon (macOS sizes + 1024 px iOS)
Resources/core.js engine bundle — generated by Scripts/build-core.sh, not committed
Scripts/
build-core.sh bundle the engine from the server repository
provision.py · asc.py bundle ids, Associated Domains, Developer ID profile (App Store Connect API)
release-mac.sh Release archive signed with the existing Developer ID identity → dist/SP Message.app
notarize.sh notarytool, staple, DMG
release-ios.sh archive / export / upload to App Store Connect
ExportOptions.plist method app-store-connect
window-shot.swift window screenshot helper
dist/ committed release artifacts of 1.0.0 (2): SP Message.app, SPMessage-1.0.0.dmg (+ .sha256),
ios-export/ (SP Message.ipa, DistributionSummary, Packaging.log)
docs/brand/ logo and icon used by this READMEIgnored by git: *.xcodeproj, build/, DerivedData/, *.entitlements (generated from project.yml), Resources/core.js.
🚀 Build
Scripts/build-core.sh # bundle the engine from ~/Desktop/Cluster/projets/sp-message into Resources/core.js
xcodegen generate
Scripts/provision.py # bundle ids + Associated Domains + Developer ID profile (App Store Connect API)
Scripts/release-mac.sh && Scripts/notarize.sh # dist/SP Message.app and dist/SPMessage-<version>.dmg
Scripts/release-ios.sh all && Scripts/release-ios.sh upload # TestFlight (app 6836555570, bundle ai.spboucher.spmessage.ios)Scripts/build-core.sh runs esbuild on native/core.ts of the server repository (sp-message), copies the result to Resources/core.js and prints the first 16 hex digits of its SHA-256 with the server commit it came from. Set SPM_WEB_REPO to build from another checkout.
Debug builds accept -SPMDevCookie, -SPMDevRecovery, -SPMDevSend, -SPMTrace launch arguments for automated runs with throwaway accounts (tests/native-peer.ts in the server repository plays the other participant). Release builds ignore them.
⚙️ Configuration
No secret lives in this repository. Names only:
| Name | Where | Role |
|---|---|---|
SPM_WEB_REPO |
Scripts/build-core.sh |
path of the server repository checkout |
NOTARY_PROFILE |
Scripts/notarize.sh |
notarytool keychain profile (default MacLustr-Notarize) |
ASC_KEY_ID, ASC_ISSUER_ID |
Scripts/release-ios.sh |
App Store Connect API key identifiers (the private key stays in ~/.appstoreconnect/private_keys/) |
-SPMBase |
launch argument, Debug only | another server origin (local test server) |
-SPMDevCookie, -SPMDevRecovery, -SPMDevSend, -SPMTrace |
launch arguments, Debug only | automated runs with throwaway accounts, bridge tracing |
In Release the server origin is fixed to https://message.spboucher.ai (Sources/Core/Config.swift).
🖥 Screens
| Screen | View | File |
|---|---|---|
| Sign in | SignInView |
Views/RootView.swift |
| Join with an invitation | JoinSheet |
Views/RootView.swift |
| First device — key creation | FirstDeviceView |
Views/RootView.swift |
| Recovery key (shown once) | RecoveryKeyView |
Views/RootView.swift |
| Add this device | LinkDeviceView |
Views/RootView.swift |
| Waiting for administrator confirmation | PendingView |
Views/RootView.swift |
| Conversation list | MainView, ConvRow |
Views/MainView.swift |
| New conversation / group | NewChatSheet |
Views/MainView.swift |
| Approve a new device | DeviceApprovalSheet |
Views/MainView.swift |
| Settings | SettingsSheet |
Views/MainView.swift |
| Conversation | ChatView, MessageRow, AttachmentView, Banner |
Views/ChatView.swift |
| Conversation details and verification | DetailsSheet |
Views/ChatView.swift |
Keyboard: ⌘↩ sends the message; ↩ confirms the sign-in button.
🔌 Engine bridge
Swift → engine — host.call(op, …), 34 operations used by the apps:
boot, snapshot, setActive, signOut · createIdentity, recover, newRecoveryKey, myFingerprint · requestLink, pollLink, cancelLink, approve, reject, devices, removeDevice · directory, search, create, leave, remove, reAdd · send, edit, react, pin, typing, setTtl, setMuted, setPref · sendFile, fetchFile · safety, setVerified, acceptKey
Engine → Swift — 13 bridge operations handled by EngineHost.handle:
| Operation | Provided by | Role |
|---|---|---|
loaded |
EngineHost |
the engine is ready (reports whether WebCrypto is available) |
http |
Net |
one HTTPS request to the server origin (JSON or binary body) |
ws-open · ws-send · ws-close |
Net |
the WebSocket; incoming frames are pushed back with __spmSocket |
kv-get · kv-set · kv-del · kv-list · kv-clear |
KV |
local storage |
log |
system log | engine script errors (never message content) |
changed |
AppModel |
state changed — take a new snapshot |
notify |
AppModel |
local notification (title and conversation id, no text) |
🗄 Local data
| Item | Detail |
|---|---|
| Database | Application Support/SPMessage/store.sqlite, one table kv (k text primary key, v blob), WAL |
| Sealed values | keys containing /secret/ (device keys, group states, key packages): AES-256-GCM |
| Wrapping key | 256-bit, Keychain generic password (service ai.spboucher.spmessage.store), data-protection keychain, this device only, never synchronised |
| Backups | the database file is excluded from backups — secrets are useless without the Keychain key, and history must not leave the device in a backup |
| iOS file protection | completeUntilFirstUserAuthentication |
| Engine web view | non-persistent website data store |
If the encrypted store cannot be opened, the app shows the reason instead of starting.
🔐 Security and privacy
- The engine is part of the signed app.
core.jsis bundled at build time; the script context has no page loaded from the network. - The server sees ciphertext only. Messages and files are encrypted on the device before they leave it (MLS, RFC 9420); the details sheet shows the epoch and the number of devices holding the keys.
- Passkeys prove who signs in; they never encrypt anything. A stolen passkey alone cannot read a message: the device still needs approval from a trusted device or the recovery key.
- Adding a device is never silent: a code is compared on both sides, and conversations show « A new device was added for … ».
- Key changes are not trusted silently: a contact whose identity key changed is not used until « Accept new key ».
- The recovery key is shown only once and the server cannot read it.
- Notifications never show message text.
- macOS entitlements: App Sandbox, outgoing network client, user-selected files read-write, Associated Domains
webcredentials:message.spboucher.ai, keychain access group; hardened runtime on. - « Sign out and erase this device » wipes the local store.
The protocol, the threat model and the security review live in the server repository: sp-message (docs/ARCHITECTURE.md, docs/THREAT-MODEL.md, docs/SECURITY-REVIEW.md). The MLS library (ts-mls) has had no independent audit.
🧪 Testing
No automated tests exist for the apps themselves. Verification so far is by scripted and manual runs:
| What | How |
|---|---|
| Scripted runs with throwaway accounts | Debug launch arguments (-SPMDevCookie, -SPMDevRecovery, -SPMDevSend, -SPMTrace); tests/native-peer.ts in the server repository plays the other participant |
| Engine | covered by the server repository's suites (20 integration tests, 9 browser tests, load test) — the same engine code runs here |
| Screenshots | Scripts/window-shot.swift |
📦 Release
| macOS | iOS / iPadOS | |
|---|---|---|
| Bundle id | ai.spboucher.spmessage |
ai.spboucher.spmessage.ios |
| Version | 1.0.0 (2) | 1.0.0 (2) |
| Deployment target | macOS 15.0 | iOS 18.0, iPhone + iPad |
| Signing | manual, Developer ID Application, profile « SP Message Developer ID », hardened runtime, App Sandbox | automatic |
| Script | Scripts/release-mac.sh then Scripts/notarize.sh |
Scripts/release-ios.sh archive|export|upload|all (all = archive + export) |
| Output | dist/SP Message.app, dist/SPMessage-1.0.0.dmg (+ .sha256) |
dist/ios-export/SP Message.ipa |
| Distribution | notarized, stapled DMG | App Store Connect / TestFlight (app 6836555570) |
| Category | public.app-category.social-networking |
— |
release-mac.sh creates no certificate: it fails if no Developer ID Application identity exists, or if the provisioning profile made by Scripts/provision.py is missing (the profile carries the restricted Associated Domains entitlement). notarize.sh never creates, prints or modifies credentials, and prints "notarized" only when Apple answered Accepted.
📌 State on 2026-11-18
- macOS 1.0.0 (2): Developer ID signed, notarised, stapled; installed in /Applications.
- iOS 1.0.0 (2): uploaded to App Store Connect, build VALID, internal TestFlight group "Interne".
- Verified: Mac app and iOS simulator app against production with throwaway accounts (device enrolment by recovery key, group join, send, quoted reply, reaction, read state). The owner signed in to the Mac app with a real passkey and approved it from another device the same day.
- Not verified: iOS on a real iPhone/iPad (passkey, Face ID, photo picker), attachments from the native apps, iPad layout, VoiceOver. No automated tests exist for the apps themselves.
- Before an App Store submission: review the export-compliance answer (
ITSAppUsesNonExemptEncryptionis set to NO).
🧯 Gotchas
- Build the engine first.
Resources/core.jsis not committed; withoutScripts/build-core.shthe app has no engine.release-ios.sh archiveruns it for you. - The engine comes from another repository.
build-core.shreads the server repository at~/Desktop/Cluster/projets/sp-messageunlessSPM_WEB_REPOsays otherwise; it needs that checkout'snode_modules(esbuild). - Rebuild the apps when the engine changes on the server: the bundled
core.jsis a snapshot, not a live copy. - Entitlements files are generated by XcodeGen from
project.ymland ignored by git — editproject.yml. - Script headers still say
Scripts/release.sh: the macOS release script isScripts/release-mac.sh(the error message ofnotarize.shalso namesrelease.sh). - History starts when the device is added: messages sent before stay on the other devices — a consequence of forward secrecy.
- Files above 200 MB must be sent from the web application.
- Passkeys need the Associated Domains association: the server lists the app ids in
/.well-known/apple-app-site-association. - Export compliance:
ITSAppUsesNonExemptEncryptionis set to NO; review it before an App Store submission.
👤 Author
Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 License
All rights reserved © 2026 Simon-Pierre Boucher (NSHumanReadableCopyright in project.yml). No license file is published in this repository.