SPB Git

Repository Public

README.md 25.1 KB

SP Message logo



SP Message icon

# 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

message.spboucher.ai version platform encryption license author

Swift SwiftUI XcodeGen AuthenticationServices WebKit CryptoKit SQLite URLSession engine dependencies

commits last commit activity language languages size branches tags clones

Swift files Swift lines engine operations bridge operations targets languages automated tests

bundle macOS bundle iOS signing sandbox TestFlight associated domains


# Table of contents


# 🎯 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 party message.spboucher.ai through Associated Domains.
  • Encryption engine: the client engine of the web application (MLS, identity, sync, attachments — TypeScript, native/core.ts in the server repository) is bundled into the app as Resources/core.js and 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

text
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 README

Ignored by git: *.xcodeproj, build/, DerivedData/, *.entitlements (generated from project.yml), Resources/core.js.

# 🚀 Build

bash
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.js is 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 (ITSAppUsesNonExemptEncryption is set to NO).

# 🧯 Gotchas

  • Build the engine first. Resources/core.js is not committed; without Scripts/build-core.sh the app has no engine. release-ios.sh archive runs it for you.
  • The engine comes from another repository. build-core.sh reads the server repository at ~/Desktop/Cluster/projets/sp-message unless SPM_WEB_REPO says otherwise; it needs that checkout's node_modules (esbuild).
  • Rebuild the apps when the engine changes on the server: the bundled core.js is a snapshot, not a live copy.
  • Entitlements files are generated by XcodeGen from project.yml and ignored by git — edit project.yml.
  • Script headers still say Scripts/release.sh: the macOS release script is Scripts/release-mac.sh (the error message of notarize.sh also names release.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: ITSAppUsesNonExemptEncryption is 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.

Files main
Menu

Theme