Repository Public
1<!--2SP Mail — native Apple clients3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7<div align="center">89<img src="docs/brand/logo.svg" alt="SP Mail logo" width="560">1011<br><br>1213<img src="docs/brand/icon.png" alt="SP Mail icon" width="112" height="112">1415# SP Mail — macOS and iOS / iPadOS1617**Native clients (Swift 6, SwiftUI) of the self-hosted SP Mail platform: two apps, three extensions each, two UI-free packages — passkey sign-in, JMAP delta sync, encrypted offline cache, a rich-text composer with undo send, labels, snooze and follow-ups, operator search, a Command Center, optional intelligence, notifications, widgets and a share extension.**1819**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**2021[](https://mail.spboucher.ai)22232425262728293031323334353637383940[](https://git.spboucher.ai/sp-mail-apple/commits)41[](https://git.spboucher.ai/sp-mail-apple/commits)42[](https://git.spboucher.ai/sp-mail-apple/insights)43[](https://git.spboucher.ai/sp-mail-apple)44[](https://git.spboucher.ai/sp-mail-apple/insights)45[](https://git.spboucher.ai/sp-mail-apple)46[](https://git.spboucher.ai/sp-mail-apple/branches)47[](https://git.spboucher.ai/sp-mail-apple/tags)48[](https://git.spboucher.ai/sp-mail-apple)495051525354555657585960616263646566676869</div>7071---7273## Table of contents7475- [Overview](#-overview)76- [Features per platform](#-features-per-platform)77- [What 2.0 adds — « SP Mail Next »](#-what-20-adds--sp-mail-next-)78- [Architecture](#-architecture)79- [Stack](#-stack)80- [Repository layout](#-repository-layout)81- [Configurations](#-configurations)82- [Build, develop and test](#-build-develop-and-test)83- [Keyboard shortcuts](#-keyboard-shortcuts)84- [Server routes used](#-server-routes-used)85- [Local data model and at-rest decisions](#-local-data-model-and-at-rest-decisions)86- [Security model](#-security-model)87- [Sending states](#-sending-states)88- [Sync and background behaviour](#-sync-and-background-behaviour)89- [Testing](#-testing)90- [Release](#-release)91- [The App Group situation](#-the-app-group-situation)92- [Never verified on a physical device](#-never-verified-on-a-physical-device)93- [Gotchas](#-gotchas)94- [Not implemented / partial](#-not-implemented--partial)95- [Author](#-author)96- [License](#-license)9798---99100## 🎯 Overview101102Native clients (Swift 6, SwiftUI) of the self-hosted SP Mail platform (`https://mail.spboucher.ai`). Two apps, six extensions, two packages:103104- **SP Mail for macOS** — `ai.spboucher.spmail`, App Sandbox + hardened runtime, Developer ID.105- **SP Mail for iOS / iPadOS** — `ai.spboucher.spmail.ios`, iPhone and iPad (`TARGETED_DEVICE_FAMILY 1,2`), distributed through App Store Connect / TestFlight.106- **Three extensions per app** — widgets (WidgetKit), a share extension, a notification service extension.107- **`SPMailCore`** — a UI-free Swift package (macOS 15 / iOS 18, **no third-party dependency**): API and JMAP clients, sync engine, sealed cache, the SP Mail Next client (`NextAPI`) and its offline store (`NextStore`), the composer's rich-text model.108- **`SPMailSystem`** — a UI-free package shared by the apps **and** the extensions: deep links, notification routing / categories / dedup, badge maths, APNs environment detection, the sealed shared state and share queue.109110The apps speak standard JMAP and the platform's REST routes to the SP Mail backend gateway, never to the mail server, and hold no mailbox password: sign-in is a passkey, the session is a bearer token in the Keychain. Every SP Mail Next surface is **capability-gated** (`GET /api/next/capabilities`): against an older server the Next entries stay hidden and the composer sends as 1.1 did.111112### The SP Mail family113114| Piece | spbgit repository | Role |115|---|---|---|116| Backend, webmail, REST API, MCP server, SDKs | [sp-mail](https://git.spboucher.ai/sp-mail) | `https://mail.spboucher.ai` (Stalwart mail server + Fastify backend) |117| macOS and iOS / iPadOS apps | **[sp-mail-apple](https://git.spboucher.ai/sp-mail-apple)** (this repository) | native clients |118119Administration (addresses and aliases, API keys, approvals, webhooks, API explorer) is **web only**: Settings › Comptes › « Administration (web) » opens `https://mail.spboucher.ai/admin` in the default browser. Creating Sieve filters and automation rules is web only too (the apps list them, switch rules on and off and show their history).120121## ✨ Features per platform122123| Area | macOS | iPhone | iPad |124|---|---|---|---|125| Sign-in | passkeys (RP `mail.spboucher.ai`), enrollment from a pasted `/enroll#token` link | same | same |126| Layout | three columns + inspector, one window per message / composer / studio, menu bar extra, Dock menu | stack navigation, swipe actions, floating compose button | split view, several scenes (Stage Manager), hardware-keyboard commands |127| Mail | threads, flags, archive, junk, delete, move, drag and drop, Quick Look, `.eml` export, `mailto:` handler, Services menu « Nouveau message SP Mail avec la sélection » | same actions, swipe and context menus | same |128| Reader | isolated web view (JavaScript off, every load blocked, remote images on request through the backend proxy), link prompt with the real destination, three themes (light, dark, midnight) | same | same |129| Composer | rich text on every OS version (TextKit): headings, lists, quotes, links (⇧⌘K), inline images with size presets, attachment tray with Quick Look and reorder, recipient tokens with autocomplete and groups, managed signatures, `;shortcut` snippets, templates, split send button (send · send later · send and remind), server-side **undo send**, honest draft states | same, formatting bar as keyboard accessory, photo picker | same as macOS, sheet presentation |130| Writing assistant | improve, fix spelling and grammar, shorten, expand, change tone, translate, suggest subject lines — on the selection or the authored text, preview then accept / cancel; hidden when intelligence is off | same | same |131| Organise | labels (colour dots, filter = `label:` search), pin (pinned first across the whole folder), snooze (server-side), « Me le rappeler » follow-ups, saved searches / smart folders | same | same |132| Search | operator search across mailboxes (`from:` `label:` `is:` `before:` … evaluated in the device's time zone), chips from the server's parse, optional search by meaning | same | same |133| Unified inbox | « Toutes les boîtes »: inbox, unread, flagged, drafts, sent across mailboxes, bulk actions on a multi-selection | same | same |134| Outbox | local drafts and queued messages, **server-tracked sends** (held, scheduled, accepted, delivered, deferred, bounced, failed — per recipient with the SMTP reply), unsent items of a removed mailbox (export `.eml` / delete) | same | same |135| Contacts · attachments | contacts (favourites, VIP, groups, duplicates, vCard import / export, history), attachment gallery (filters, ZIP download, drag out) | same, without drag out | same |136| Command Center | dashboard widgets (inboxes, needs attention, scheduled sends, awaiting replies, recent attachments, important contacts, storage, delivery problems, sync status), layout synchronised between devices; never the default screen | same | same |137| Intelligence (optional, **off by default**) | summary, reply suggestions, writing assistant, smart triage, semantic index; provider « MacLustr local » or Anthropic with explicit consent; every surface names its provider | same | same |138| Settings | accounts and devices, signatures, composing, appearance, privacy, security, intelligence, out of office (vacation responder through Sieve), filters and rules (read, enable / disable), storage, notifications | same | same |139| Template studio | library with live thumbnails, « Créer avec l'IA », editor, versions, export, send a template (its own window) | tabs | split |140| System | notifications with actions (reply, mark as read, archive, snooze a reminder), widgets, share extension, Spotlight (opt-in), Handoff, App Shortcuts (4 intents), Services and Dock menus | notifications with actions, widgets (Home and Lock Screen), share extension, Spotlight, App Shortcuts, background refresh | same as iPhone |141| App lock | Touch ID with passcode fallback, idle auto-lock, every window gated | Face ID / Touch ID, content hidden in the app switcher | same |142| Languages | French (development language) and English — 1 420 strings in three catalogs, all translated | same | same |143144## 🆕 What 2.0 adds — « SP Mail Next »1451462.0.0 (1) is the merge of three branches developed in parallel on the Next design foundation (tokens, per-window `MailScene`, command palette, message windows):147148**Productivity and intelligence** (`Sources/Shared/Next/`) — `NextServices` (one `NextAPI` + `NextStore` per session, mirrors of labels, saved searches, snoozes, reminders, AI settings, dashboard), labels, pin, snooze and reminders, operator search and saved searches, bulk actions in the unified inbox, contacts, attachment gallery, Command Center, the optional intelligence layer, Settings › Intelligence / Absence / Règles / Stockage.149150**Composer** (`Sources/Shared/Compose/` + `Compose.swift`) — a TextKit rich-text editor on every OS version (semantic attributes ⇄ e-mail-safe HTML + text alternative; the quoted original is an untouched block, kept byte for byte), inline images as `cid:` parts, attachment tray, token recipients, managed signatures and snippets, sending through `POST /api/v1/messages/send` under an Idempotency-Key with the server-side undo hold, send later, send and remind; offline the message goes through the durable JMAP outbox (no undo window). Settings › Rédaction.151152**System** (`Sources/Shared/System/`, `Packages/SPMailSystem`, the extensions) — push registration lifecycle, notification categories / actions / routing / dedup, deep links and Handoff, Spotlight, background tasks, Settings › Notifications, App Intents, widgets, share and notification-service extensions, signing scripts for the nested bundles.153154**Integration work done at the merge** —155156- *One store per session.* The composer (`ComposeCenter`) reads and writes the `NextStore` of `NextServices`; its former private directory (`…/next-compose`) is deleted at launch. Sign-out and a revoked session wipe the store, the composer's mirrors and the tracked sends.157- *AI → composer.* A reply suggestion opens the composer through `AppModel.openReply(to:body:all:in:)` with the text inserted for review — nothing is sent. The **writing assistant** lives in the composer (formatting bar and « Plus » menu): `POST /api/next/ai/write` on the selection or on what was written above the signature — never the quoted original, never the signature —, a preview sheet labelled with the provider, « Remplacer » / « Annuler », one undoable edit.158- *Delivery follow-up.* A message sent through `/api/v1` has no local item once the server took it; « Boîte d'envoi » now lists what the server tracks (`GET /api/v1/messages/outbound`): « Envoi dans N s » with « Annuler l'envoi », « Programmé pour le … », « Accepté pour livraison », « Remis au serveur du destinataire », deferred / bounced / failed per recipient with the SMTP reply. Refreshed when the outbox opens, after a sync, and on a schedule derived from the rows (when a hold ends, 15 s then 60 s for a fresh send, 2 min for a deferred one) — never a tight poll. « Remis » is shown only for the server's `delivered`.159- *Undo send keeps the draft.* `NextAPI.undoSend(id:)` uses `POST /api/next/compose/undo/:id` (the draft and its attachments stay in Drafts); the former fetch-then-`DELETE` implementation destroyed them.160- *Search time zone.* `SearchQuery`, `parseQuery` and `AttachmentQuery` carry `tz` (the device's IANA identifier): `before:` / `after:` / `today` are evaluated in the user's zone.161- *Shortcuts.* ⌘K is the command palette; the composer's link is ⇧⌘K on every platform. The template studio moved from ⌥⌘M (the system's « Minimize All ») to ⇧⌘M. `Scripts/check-shortcuts.py` fails when a combination is declared twice or belongs to the system.162- *Template + sensitive recipient.* A template sent from the composer that the server answers with `confirmation_required` goes through the composer's « Destinataires sensibles » confirmation, like any send.163- *Mailbox removal.* Unsent drafts and queued messages of a mailbox that disappears from `/api/me` are kept sealed on the device and listed in the outbox as « Boîte retirée », with « Exporter en .eml… » and « Supprimer ».164- *Pins across the folder.* Pinned conversations are asked from the server (`Email/query` with `hasKeyword: "$pinned"` in the mailbox) and merged above the loaded window, so a pinned old conversation is never buried.165166<details>167<summary><b>What 1.1 added (template studio, unified inbox, sender identities)</b></summary>168169**Template studio — « Modèles »** (sidebar entry, menu « Modèles », ⇧⌘M; its own window on macOS, full screen on iOS / iPadOS): library with live thumbnails, « Créer avec l'IA » (brief, brand kit stored under `templateBrand`, progress as the server reports it, cancel closes the stream), editor (desktop / phone and light / dark preview, variables with a debounced live preview, « Retoucher avec l'IA », HTML and text source, versions, export), send a template (`template_id` + `variables` through `POST /api/v1/messages/send`, layout kept), previews in the same isolated renderer as message bodies.170171**Unified inbox** — « Toutes les boîtes » (⌘0) from `GET /api/v1/messages`, each row with the receiving address as a coloured chip; a row opens in the regular reader through the sync engine of ITS mailbox; offline, the merge of the local caches.172173**Sender identities** — the From picker lists every mailbox and its sendable aliases (`GET /api/v1/addresses`), grouped by mailbox; a reply starts from the address the message was sent to; an alias message leaves with the alias in `From`.174175</details>176177## 🏗 Architecture178179```mermaid180flowchart TB181 subgraph Apps["Two app targets (project.yml)"]182 MAC["SPMail — macOS<br/>Sources/macOS · windows, menus, Dock"]183 IOS["SPMail-iOS — iPhone + iPad<br/>Sources/iOS · scenes, background tasks"]184 end185 subgraph Ext["Three extensions per app — never open the mail database"]186 W["Widgets"]187 SE["Share extension"]188 NS["Notification service"]189 end190 SH["Sources/Shared — SwiftUI<br/>AppModel · MailScene · Reader · Compose/ · Next/ · System/ · Studio/ · SelfTest"]191 subgraph Core["Packages/SPMailCore — UI-free, no dependency"]192 API["APIClient<br/>sessions, passkey routes, /api/v1"]193 JMAP["JMAPClient + EventSource"]194 SYNC["SyncEngine + Outbox"]195 STORE[("MailStore<br/>system SQLite · AES-256-GCM")]196 NEXT["Next/ — NextAPI (typed /api/next/*)<br/>NextStore (sealed offline cache + mutation queue)"]197 RICH["Next/ — rich-text model ⇄ HTML · NextCompose · SieveConfig"]198 end199 subgraph Sys["Packages/SPMailSystem — shared with the extensions"]200 DL["DeepLink · NotificationRouting · Dedup · BadgeMath"]201 SS[("SharedStore · ShareQueue<br/>sealed files, shared keychain group")]202 end203 KC[("Keychain<br/>bearer token · cache key · shared group")]204 BE["SP Mail backend<br/>https://mail.spboucher.ai"]205 MS["Stalwart mail server<br/>(never reached by the apps)"]206 APNS["APNs"]207 MAC --> SH208 IOS --> SH209 SH --> Core210 SH --> Sys211 Ext --> Sys212 SE -->|"send directly when it must"| API213 SYNC --> JMAP214 SYNC --> STORE215 NEXT --> API216 API --> KC217 STORE --> KC218 SS --> KC219 API -->|HTTPS, bearer token, no Origin| BE220 JMAP -->|"/api/jmap/{mailbox}/…"| BE221 BE --> MS222 BE -->|push pipeline| APNS223 APNS --> NS224```225226**Session wiring** — `AppModel` owns the session (token, mailboxes, one `SyncEngine` per mailbox) and four services passed explicitly: `next` (`NextServices`: the one `NextAPI` + `NextStore` of the session), `compose` (`ComposeCenter`: signatures, snippets, compose preferences and autocomplete read from that same store; undo holds), `outbound` (`OutboundTracker`: server-tracked sends), `system` (`SystemServices`: push, notifications, shared state, Spotlight, deep links, background work). Everything a window navigates lives in its own `MailScene`.227228**Extensions** — app and extensions share two channels written by the app only: the keychain access group `3YM54G49SN.group.ai.spboucher.spmail[.dev]` (session token, extension state, key of the sealed snapshot) and an App Group container (sealed widget snapshot, share queue). See [The App Group situation](#-the-app-group-situation) and `docs/SYSTEM-INTEGRATION.md`.229230### Sending from the composer231232```mermaid233sequenceDiagram234 autonumber235 participant C as Composer236 participant O as Local outbox (sealed)237 participant B as Backend238 participant T as OutboundTracker239 C->>O: save the draft (always first)240 alt online and the server has the Next API241 C->>B: GET /api/next/compose/prefs (undo delay, read now)242 C->>B: POST /api/v1/files (attachments)243 C->>B: POST /api/v1/messages/send + Idempotency-Key244 B-->>C: scheduled + undo_until (held) · sent · queued245 C->>O: discard the local draft246 T->>B: GET /api/v1/messages/outbound (on open, after sync, when a hold ends…)247 Note over T: « Envoi dans N s » → « Accepté » → « Remis » per recipient248 else the server was not reached249 C->>O: queue (JMAP, client Message-ID) — no undo window250 end251```252253Passkey sign-in and the offline JMAP replay are unchanged from 1.1: `POST /api/login/options` → platform assertion → `POST /api/login/verify` → bearer token in the Keychain; queued messages leave through `Email/set` + `EmailSubmission/set` when the network returns, and « Remis » comes from `EmailSubmission/get → deliveryStatus`.254255## 🧱 Stack256257| Layer | Technology | Version (read in the repository) | Role |258|---|---|---|---|259| Language | Swift | 6.0 (`SWIFT_VERSION`, tools 6.0) | apps, extensions, packages |260| UI | SwiftUI (+ TextKit for the composer, WebKit for bodies) | macOS 15 / iOS 18 SDK | `Sources/Shared` |261| Project | XcodeGen | `project.yml`, `xcodeVersion: 16.0` | project generated, never committed |262| Core | Swift packages `SPMailCore`, `SPMailSystem` | `.macOS(.v15)`, `.iOS(.v18)` | API, JMAP, cache, sync, Next client; system logic |263| Storage | system `sqlite3` (linked library) | — | local cache |264| Crypto | AES-256-GCM (CryptoKit), Keychain | system frameworks | cache at rest, token, shared state |265| Auth | AuthenticationServices | — | passkeys |266| System | UserNotifications, WidgetKit, AppIntents, CoreSpotlight, BackgroundTasks | — | notifications, widgets, shortcuts, Spotlight, refresh |267| Tests | Swift Testing (`@Test`) | — | `SPMailCoreTests`, `SPMailSystemTests` |268| Tooling | Node.js (`.mjs` dev scripts), Python (`provision.py`, `asc.py`, `make-strings.py`, `check-shortcuts.py`) | — | dev stack, provisioning, strings, shortcut check |269270## 🗂 Repository layout271272```273project.yml XcodeGen: SPMail (macOS), SPMail-iOS, 3 extensions per platform, SPMailSystemUITests274Config/ Info plists and entitlements (app / extensions × macOS / iOS × Release / Dev / iOS App Group)275Packages/SPMailCore/ UI-free package — 30 source files, 9 800 lines276 Sources/SPMailCore/ APIClient · JMAPClient · EventSource · MailStore · SyncEngine · Outbox · SyncStatus · OfflineReading277 HTMLSanitizer · AuthResults · Compose · OutgoingEML · Templates · TemplateGeneration · Unified · SenderIdentity278 Next/ NextAPI · NextStore · NextModels* · NextHelpers (PinOrder…) · NextError · SharedContainer279 NextRichText · NextCompose · SieveConfig280 Tests/SPMailCoreTests/ unit (in-memory JMAP double `FakeMailServer`, stub URLProtocol) and integration suites281Packages/SPMailSystem/ UI-free package shared with the extensions — 9 source files, 925 lines282Sources/Shared/ SwiftUI shared by both apps — 63 files, 20 100 lines283 AppModel.swift session, engines, mailboxes, outbox, composers284 Model/ MailScene (per-window state) · OutboundTracker · AppServices · SceneStates285 Compose.swift Compose/ ComposeModel · ComposeCenter · RichTextEditor · FormatBar · RecipientTokens · ComposeViews286 ComposeManagers (signatures, snippets, templates, settings) · WritingAssistant287 Next/ NextServices · MailScene+Next · Organize / Search / Contacts / Dashboard / Intelligence views288 AttachmentGallery · RemoteListView · NextSettings · NextFixtures · NextSelfTest289 System/ SystemServices · PushRegistrar · NotificationCoordinator · NotificationSettings · DeepLinkRouter290 SharedStateWriter · SpotlightIndex · BackgroundWork · SystemShare291 Studio/ StudioModel · StudioViews · StudioEditor · StudioPreview292 Design/ tokens (SPColor, SPMetrics…) and components293 SelfTest*.swift the DEBUG end-to-end scenario (base, +Compose, +System, +Integration, Next/NextSelfTest)294Sources/macOS/ Sources/iOS/ app entry points, menu bar extra, Dock menu, touch observer295Sources/Intents/ App Intents and App Shortcuts (compiled into the apps)296Sources/Widgets/ ShareExtension/ NotificationService/ ExtensionShared/ the extensions and their shared catalog297Resources/ Assets.xcassets, Localizable.xcstrings, AppShortcuts.xcstrings298Tests/SystemUITests/ simulator-only UI automation behind Scripts/system-shots.sh299Scripts/ build, dev stack, self-test launchers, strings, shortcut check, provisioning, release, archive300docs/ SYSTEM-INTEGRATION.md, brand/301```302303The Xcode project is generated (`xcodegen generate`) and not committed. Build products live outside `~/Desktop`, in `~/Library/Developer/SPMail/` (`SPMAIL_DD` overrides the derived-data path).304305## 🔀 Configurations306307- **Debug = « SP Mail Dev »** (`…spmail.dev` / `…spmail.ios.dev`, extensions `….dev.widgets` …): no Associated Domains, no push entitlement, its own shared group and the URL scheme `spmail-dev`, plain HTTP to a local backend allowed, DEBUG launch arguments compiled in (`-spmBaseURL`, `-spmDevToken`, `-spmSelfTest YES`, `-spmNoPrompts YES`, `-spmDemo YES`, `-spmScene …`, `-spmComposeDemo …`, `-spmOpenSettings YES`, `-spmSettingsTab n`, `-spmFakePushToken YES`). It never makes Apple's CDN look up the AASA file, so it can be launched at any time. Passkeys cannot work in this variant.308- **Release = « SP Mail »**: App Sandbox, hardened runtime, `webcredentials:mail.spboucher.ai`, keychain groups, push entitlement. Server fixed to production; `Scripts/verify-release.sh` checks that no development switch is in the binaries (app and extensions).309310| | Debug | Release |311|---|---|---|312| Display name | SP Mail Dev | SP Mail |313| macOS bundle id | `ai.spboucher.spmail.dev` | `ai.spboucher.spmail` |314| iOS bundle id | `ai.spboucher.spmail.ios.dev` | `ai.spboucher.spmail.ios` |315| Compilation conditions | `DEBUG SPM_DEV` (+ `SPM_EXTENSION` in extensions) | whole-module |316| App Transport Security | `NSAllowsLocalNetworking` added by a post-build script | no exception |317| macOS signing | manual, Developer ID Application | + `--timestamp`, one Developer ID profile per bundle |318319## 🚀 Build, develop and test320321```bash322# ONE dev stack: a private backend from the shared sp-mail checkout, with the scripted AI stub as its « local » provider and its push323# pipeline pointed at a local fake APNs. Nothing leaves the Mac (no AI call, no push).324Scripts/dev-backend.sh start # idempotent; run-dev.sh, run-sim.sh and test-core.sh --integration call it themselves325node Scripts/dev-bootstrap.mjs up # admin + two apple-*@stg.spboucher.ai mailboxes + one alias + native tokens → Build/dev-env.sh326Scripts/test-core.sh # SPMailCore unit tests, then SPMailSystem unit tests327Scripts/test-core.sh --integration # + integration tests against the dev backend and the real staging mail server328Scripts/check-shortcuts.py # no key combination declared twice in the menus, none taken from the system329Scripts/build.sh mac Debug && Scripts/run-dev.sh --selftest --shot Build/selftest.png # app self-test on macOS (JSON report)330Scripts/build.sh ios Debug && Scripts/run-sim.sh --device <udid> --shot Build/ios.png # the same in an iPhone or iPad simulator331node Scripts/dev-bootstrap.mjs fresh # new pair of mailboxes (the mail server allows ~25 messages per sender per hour)332node Scripts/dev-bootstrap.mjs purge # delete the test mailboxes and their mail333Scripts/make-strings.py --sync # re-extract UI strings from the Debug builds, apply English; exit 1 if a key has no English334```335336Test mail only ever travels between the `apple-*@stg.spboucher.ai` mailboxes and alias created by the bootstrap script. The self-tests talk to `Scripts/dev-replay-proxy.mjs`: it relays everything to the dev backend except `POST /api/templates/generate`, which it answers by replaying a recorded stream.337338**Environment overrides**339340| Variable | Default | Used by |341|---|---|---|342| `SPMAIL_DEV_PORT` · `SPMAIL_DEV_DB` | `8821` · `postgres://127.0.0.1/sp_mail_apple2dev` | dev-backend, dev-bootstrap, replay proxy |343| `SPMAIL_REPLAY_PORT` | `8822` | run-dev, run-sim (the app talks to this port during a self-test) |344| `SPMAIL_AI_STUB_PORT` · `SPMAIL_AI_STUB=0` · `SPMAIL_AI_STUB_MODE` | `8853` · stub on · `ok` | dev-backend, dev-ai-stub (`down`, `slow`) |345| `SPMAIL_FAKE_APNS_PORT` · `SPMAIL_FAKE_APNS=0` | `8857` · fake on | dev-backend, dev-fake-apns (requests logged in `Build/fake-apns.jsonl`) |346| `SPMAIL_BACKEND_DIR` | `~/Desktop/Cluster/projets/sp-mail` | where the backend's `dist/` is run from |347| `SPMAIL_DD` | `~/Library/Developer/SPMail/DerivedData` | build, run, strings, release scripts |348| `SPMAIL_SPM_SCRATCH` | `~/Library/Developer/SPMail/spm-build` | test-core (one scratch path per concurrent run) |349| `SPMAIL_TEST_SHARED_TOKENS=1` | private tokens per run | test-core `--integration` |350| `SPMAIL_TEST_REAL_AI=1` | off | ONE real generation + revision (costs money) |351| `SPMAIL_IOS_APP_GROUP=1` | off | ios-archive: sign with the App Group container entitlement |352353| Script | Purpose |354|---|---|355| `build.sh [mac\|ios] [Debug\|Release]` | `xcodegen generate` + `xcodebuild` (app and its three extensions), errors only on the console, log in `Build/` |356| `run-dev.sh` · `run-sim.sh` | launch the Dev app on macOS / in a simulator, optional self-test and stage captures (its own window / the simulator screen only) |357| `test-core.sh` | package tests (unit, `--integration`, `--filter`) |358| `dev-backend.sh` · `dev-ai-stub.mjs` · `dev-fake-apns.mjs` · `dev-bootstrap.mjs` · `dev-replay-proxy.mjs` | the dev stack and its fixtures |359| `system-shots.sh` | simulator captures of banners, widget gallery and share sheet (drives `Tests/SystemUITests`) |360| `make-strings.py` · `check-shortcuts.py` | three string catalogs; shortcut clash check |361| `window-shot.swift` | captures one window of a named app (`smallest`, or by title) |362| `make-icon.sh` · `make-icon.swift` | app icon set |363| `provision.py` (`--check` = dry run) · `asc.py` | bundle ids, capabilities, one Developer ID profile per macOS bundle; App Store Connect helper |364| `release.sh` · `verify-release.sh` · `notarize.sh` | macOS release pipeline (nested bundles handled) |365| `ios-archive.sh archive\|export\|upload` + `ExportOptions.plist` | iOS archive, export (`app-store-connect`), upload |366367## ⌨️ Keyboard shortcuts368369Declared in `Sources/Shared/Commands.swift` (menus) and `Sources/Shared/Compose/FormatBar.swift` (menu « Format »); the same commands are listed on iPad while ⌘ is held. `Scripts/check-shortcuts.py` verifies that none is declared twice and none belongs to the system.370371| Shortcut | Command |372|---|---|373| ⌘N · ⌘O | Nouveau message · Ouvrir dans une nouvelle fenêtre (macOS) |374| ⌘K · ⌘F | Palette de commandes · Rechercher dans le courrier |375| ⌥⌘↓ · ⌥⌘↑ | Conversation suivante · précédente |376| ⌘R · ⇧⌘R · ⇧⌘F | Répondre · Répondre à tous · Transférer |377| ⇧⌘L · ⇧⌘U · ⇧⌘P | Drapeau · Marquer comme lu / non lu · Épingler / désépingler |378| ⌃⌘Z · ⌃⌘R | Mettre en veille… · Me le rappeler… |379| ⌃⌘A · ⇧⌘J · ⌘⌫ | Archiver · Indésirable · Supprimer |380| ⇧⌘N | Relever le courrier |381| ⌘0 · ⌘1…⌘9 | Toutes les boîtes · Dossier *n* |382| ⇧⌘C · ⌥⌘C · ⌥⌘J | Centre de commande · Contacts · Pièces jointes |383| ⇧⌘M · ⌥⌘G | Studio de modèles · Créer un modèle avec l'IA… |384| ⌘S | Enregistrer le brouillon (a composer in front) · Enregistrer le modèle (otherwise) |385| ⌥⌘0 | Corps (a composer in front) · Fenêtre principale (otherwise, macOS) |386| ⌥⌘S | Partager le message… |387| ⌃⌘L | Verrouiller SP Mail |388| ⌘B · ⌘I · ⌘U · ⇧⌘X | Gras · Italique · Souligné · Barré |389| ⌥⌘1…3 · ⇧⌘7 · ⇧⌘8 · ⌘] · ⌘[ · ⌘' | Titre / Sous-titre / Intertitre · Liste numérotée · Liste à puces · retrait · Citation |390| ⇧⌘K · ⌘\ | Lien… · Effacer la mise en forme |391| ⌥⌘I · ⇧⌘A · ⌥⌘E · ⌃⌘T | Insérer une image… · Joindre un fichier · Insérer un extrait… · Insérer un modèle… |392| ⇧⌘D · ⌥⇧⌘Z | Envoyer · Annuler l'envoi (while the countdown is shown) |393394Moved in 2.0: link ⌘K → ⇧⌘K (⌘K is the palette), template studio ⌥⌘M → ⇧⌘M (system « Minimize All »), Command Center ⌥⌘D → ⇧⌘C (system « Show / Hide Dock »), snooze ⌃⌘S → ⌃⌘Z and share ⌃⌘S → ⌥⌘S (⌃⌘S is « Show / Hide Sidebar »), insert template ⌥⌘T → ⌃⌘T (⌥⌘T is « Show / Hide Toolbar »).395396## 🔌 Server routes used397398All on `https://mail.spboucher.ai`; contracts live in the sister repository ([sp-mail](https://git.spboucher.ai/sp-mail): `docs/api-contract.md`, `docs/templates-api.md`, `docs/API.md`, `docs/next/ARCHITECTURE-NEXT.md`).399400| Route | Used for |401|---|---|402| `/api/login/*`, `/api/enroll/*` | passkey sign-in, enrollment from a pasted link |403| `GET /api/me`, `PATCH /api/prefs` | session, mailboxes, preferences (`templateBrand`, `dashboard`) |404| `/api/jmap/{mailbox}/…` | JMAP session, API, upload, download, EventSource (mail, drafts, keywords `$pinned` / `lbl_…`, Sieve, quota) |405| `GET /api/img` | remote images, on request, with the bearer token |406| `/api/templates…` | template studio, live preview, generation stream |407| `GET /api/v1/messages`, `GET /api/v1/addresses` | unified inbox, sender identities |408| `POST /api/v1/files`, `POST /api/v1/messages/send` | attachments of a send; send with `undo_seconds`, `send_at`, reminder, `confirm_sensitive`, or a template |409| `GET /api/v1/messages/outbound[/{id}]` | server-tracked sends: status and per-recipient delivery with SMTP replies |410| `GET /api/v1/messages/scheduled` (+ `DELETE`) | « Programmés » |411| `GET /api/next/capabilities` | which Next features this server has |412| `/api/next/labels`, `/searches`, `/snoozes`, `/reminders` | labels, saved searches, snooze, follow-ups |413| `/api/next/search`, `/search/parse`, `/attachments` (+ `/zip`) | operator search (with `tz`), parse for chips, attachment gallery |414| `/api/next/contacts…`, `/contact-groups` | contacts, suggestions, groups, vCard, duplicates |415| `/api/next/compose/prefs`, `/compose/undo/:id`, `/signatures`, `/snippets` | undo delay and warnings, undo send keeping the draft, signatures, snippets |416| `/api/next/dashboard`, `/inbox/insights` | Command Center, model-free inbox insights |417| `/api/next/ai/*` | settings and consent, summarize, replies, write, triage, semantic search and index, usage |418| `/api/next/rules…` | automation rules (list, enable / disable, history) |419| `POST /api/push/register`, `/api/next/push/*` | APNs token, devices, notification preferences, status, test |420421## 🗄 Local data model and at-rest decisions422423`MailStore` is a system-SQLite cache inside the app container, with a versioned schema (`PRAGMA user_version` + ordered migrations). The decisions below are explicit and tested (`StoreTests.previewsBodiesAndOutboxAreSealedAtRest`, `SchemaTests.clearTextColumnsAreExactlyTheDocumentedOnes`); the header of `MailStore.swift` is the reference.424425| Data | At rest |426|---|---|427| Previews, bodies, the outbox (drafts, queued messages and their attachments), key/value blobs (identities, tracked-send subjects…), cached attachments | sealed with AES-256-GCM under a per-install key kept in the Keychain, each value bound to its row |428| `emails.search_text` (subject + sender / recipient names and addresses, lower-cased), `emails.meta` (header-level summary: subject, addresses, ids, keywords, dates), mailbox names, correspondents, pending patches | **clear** inside the app container |429| `NextStore` (labels, saved searches, signatures, snippets, favourite contacts, suggestions, compose / push / AI preferences, dashboard, queued mutations) | sealed files in `…/next`, same key; ONE store per session |430| Widget snapshot, share queue | sealed files in the shared container, key in the shared keychain group |431| Bearer token, cache key | Keychain (`AfterFirstUnlockThisDeviceOnly`) |432433Why headers are not sealed: offline search is a SQL `LIKE` over `search_text`, and list / thread queries sort and group on indexed columns. AES-GCM values are randomised, so a sealed column can be neither searched nor indexed; a searchable encryption scheme would be new cryptography, which this project does not invent. The trade-off: headers readable by whoever can read the app container, content never.434435File protection (iOS): the database, its `-wal` / `-shm` files and the cache directory carry `completeUntilFirstUserAuthentication`. `complete` and `completeUnlessOpen` are deliberately not used for the database — background refresh and the silent-push path open the store while the device is locked, and SQLite cannot recreate its WAL files under those classes. Decrypted attachment files handed to Quick Look or the share sheet are short-lived, written with `completeUnlessOpen`, and removed by every wipe.436437## 🔐 Security model438439- **Auth**: passkeys → `/api/login/*`; enrollment from a pasted `/enroll#token` link. The bearer token is kept in the Keychain, never in preferences or logs. Requests carry no `Origin` header.440- **401** (session revoked elsewhere): back to sign-in, synced mail and the Next store removed, unsent drafts and queued messages kept sealed for the same person's next sign-in (another user signing in on the device does not inherit them). **Sign-out**: session revoked and push device deleted on the server; cache files, cache key, Next store, shared token, widget snapshot, share queue and Spotlight items destroyed.441- **No web UI.** The only web views render a message body or a template preview: JavaScript off, non-persistent store, a content rule list that blocks every load, CSP `default-src 'none'`, HTML sanitised by an allow-list first.442- **Intelligence is off by default.** Nothing is sent to a model until the owner picks a provider and a feature; the external provider requires an explicit, recorded consent; every AI surface names the provider; a model only proposes — it never sends, moves or deletes.443- **Notifications and widgets** follow the account's preview level; while SP Mail is locked they never show the sender or the subject. Reply and delete actions require the device to be unlocked.444- **Sensitive recipients**: the server refuses to queue a message (or a template) to a listed address or domain until the person confirms.445- **App lock** (optional): Touch ID / Face ID with passcode fallback, idle auto-lock, every window gated.446447## 📤 Sending states448449Two paths, one rule: the interface only claims what a server said.450451- **Through `/api/v1` (online, Next server)** — the composer shows « Envoi au serveur… », then the countdown « Envoi dans N s » while the server holds the message (« Annuler l'envoi » takes it back with its draft and attachments). Afterwards the outbox section « Suivi par le serveur » carries the server's status: `queued` → `sent` (« Accepté pour livraison ») → `delivered` (« Remis au serveur du destinataire ») or `deferred` / `bounced` / `failed`, per recipient, with the SMTP reply when delivery did not succeed. An answer that never comes is asked again under the same Idempotency-Key; the draft stays locked until the server has said what it did.452- **Through the JMAP outbox (offline, or an older server)** — `OutboxState`: `draft` → `queuedOffline` (« En attente (hors ligne) ») → `sending` → `accepted` (only after `EmailSubmission/set` created the submission) or `failed`; « remis » per recipient only from `EmailSubmission/get → deliveryStatus`. No undo window.453454## 🔄 Sync and background behaviour455456- JMAP delta sync (`Email/changes`, `Mailbox/changes`) with anchor paging for older pages, a joinable sync pass, pending-operation classification (a refused operation is dropped and recorded, a burst of 5xx keeps the queue), lossless drafts with conflict detection (both versions kept), idempotent submission (client Message-ID: a resubmission after a lost answer never sends twice), body prefetch and a sealed attachment cache with a budget.457- EventSource while the app is active (reconnect with exponential backoff, woken by `NWPathMonitor`). Flag / move / keyword operations are applied locally at once and replayed when offline — the server's answer always wins.458- The Next collections refresh on launch, on return to the foreground and after a sync (throttled); mutations made offline are queued in `NextStore` and replayed. Snooze and reminders are server-side and are never queued silently.459- The mailbox list is re-read on return to the foreground: a new mailbox gets its engine; a removed one is detached — its cache is wiped, its unsent items are kept (see the outbox).460- **Push**: the APNs token is registered once a session exists; with an active server pipeline the app posts no local notification (one notification per message, deduplicated against a ledger and Notification Centre). Without server credentials the app announces new mail itself, while it runs or during a background refresh.461- **iOS background**: `BGAppRefreshTask` / `BGProcessingTask` are registered and rescheduled, but iOS alone decides if and when they run; nothing stays connected while the app is suspended.462463## 🧪 Testing464465| Suite | Where | Count (run on 2026-11-20) | Needs |466|---|---|---|---|467| Core unit tests | `Packages/SPMailCore/Tests` (in-memory JMAP double, stub URLProtocol, recorded AI stream) | 209 (the runner reports 248 with the 39 integration tests, skipped without the dev backend) | nothing |468| Core integration tests | same target, enabled by `Scripts/test-core.sh --integration` | 39 | dev backend + real staging mail server |469| System unit tests | `Packages/SPMailSystem/Tests` | 26 | nothing |470| App self-test, macOS | `Scripts/run-dev.sh --selftest` | 146 steps | Debug build + dev stack |471| App self-test, iPhone / iPad simulator | `Scripts/run-sim.sh --device <udid>` | 145 steps (one system step is macOS only) | Debug build + dev stack |472| Shortcut clash check | `Scripts/check-shortcuts.py` | 58 menu shortcuts | nothing |473| String catalogs | `Scripts/make-strings.py --sync` | 1 420 keys, all with English | Debug builds |474475The self-test (`-spmSelfTest YES`, Debug only, JSON report) is one scenario in one pass: the 1.1 base (launch, compose, send, receive, reader, renderer isolation, studio, unified inbox, lock, cache at rest, sign-out), the Next design foundation (themes, windows, palette, scenes), the composer steps (`SelfTest+Compose.swift`), the feature steps (`Next/NextSelfTest.swift`), the integration steps (`SelfTest+Integration.swift`: shared store, writing assistant, outbox follow-up, template + sensitive recipient, removed mailbox) and the system steps (`SelfTest+System.swift`: push registration against the fake APNs stack, notification routing and actions, widgets per privacy level, share hand-off, Spotlight, sign-out).476477## 📦 Release478479```bash480python3 Scripts/provision.py --check # dry run: what would be registered481python3 Scripts/provision.py # bundle ids (app + 3 extensions per platform), capabilities, one Developer ID profile per macOS bundle482Scripts/release.sh # universal Developer ID build → dist/SP Mail.app (app + three extensions, each with its profile)483Scripts/verify-release.sh # signatures, entitlements, versions, no dev switch — app and extensions484Scripts/notarize.sh # notarytool (keychain profile MacLustr-Notarize), staple, DMG485Scripts/ios-archive.sh archive # archive (automatic signing; SPMAIL_IOS_APP_GROUP=1 adds the container entitlement)486Scripts/ios-archive.sh export # .ipa (ExportOptions.plist: app-store-connect)487Scripts/ios-archive.sh upload # sends it to App Store Connect488```489490| | macOS | iOS / iPadOS |491|---|---|---|492| Bundle ids | `ai.spboucher.spmail` + `.widgets` `.share` `.notifications` | `ai.spboucher.spmail.ios` + `.widgets` `.share` `.notifications` |493| Version | 2.0.0 (1) | 2.0.0 (1) |494| Deployment target | macOS 15.0 | iOS 18.0 |495| Signing | manual, Developer ID Application, hardened runtime, App Sandbox | automatic |496| Distribution | notarized, stapled DMG | App Store Connect / TestFlight |4974982.0.0 (1) has been built, signed and verified (`release.sh`, `verify-release.sh`, `ios-archive.sh archive` + `export`); it has **not** been notarised nor uploaded at the time of writing.499500Before launching a build that carries the Associated Domains entitlement, check Apple's view of the AASA file: `nscurl -i https://app-site-association.cdn-apple.com/a/v1/mail.spboucher.ai` (a failed lookup is cached for about an hour).501502## 🧩 The App Group situation503504App and extensions share a keychain access group **and** an App Group container (decision D-N10, `docs/SYSTEM-INTEGRATION.md`).505506- **macOS** — the Team-ID-prefixed group `3YM54G49SN.group.ai.spboucher.spmail` needs no registration under Developer ID: the container works.507- **iOS** — `group.ai.spboucher.spmail` must be registered and attached to the four App IDs. The App Store Connect API key used by `provision.py` and automatic signing can enable the capability but **cannot create or attach the group**. Until that manual step is done in the Apple Developer account, the iOS Release build ships on the **shared keychain group only**: token, extension state and widget snapshot go through the keychain (widgets, notification service and share extension all work); the one loss is that a share **with files** cannot be queued for the app — the share extension sends it directly through the API (text-only drafts can still be queued). Once the group is registered: `SPMAIL_IOS_APP_GROUP=1 Scripts/ios-archive.sh archive`.508509## 📵 Never verified on a physical device510511Everything above was exercised on a Mac (Debug build) and in iPhone / iPad **simulators**, against a local dev backend with staging mailboxes. Never verified, by anyone, on real hardware:512513- sign-in with a real Touch ID / Face ID passkey (the Dev variant signs in with a development token; the Release build was built and verified, never launched);514- real APNs delivery (token, environment, topic) — the self-test registers against a local fake APNs, and a simulator cannot receive those pushes;515- the notification service extension on a device (it is not launched for `simctl push`), widgets on a real Home or Lock Screen, Handoff between devices, Siri phrases;516- background refresh timing, behaviour under Low Power Mode, real memory pressure;517- touch gestures, the software keyboard with the formatting accessory, the photo picker, VoiceOver and Dynamic Type beyond simulator captures;518- the macOS Release build launched from a notarised copy, and the iOS build installed from TestFlight.519520## 🧯 Gotchas521522- **AASA lookups are cached by Apple's CDN**: a failed lookup sticks for about an hour. Use the Dev variant (no Associated Domains) for everyday work.523- **Passkeys cannot work in the Dev variant** — it signs in with a development token (`-spmDevToken`).524- **Mail-server rate limit**: about 25 messages per sender per hour (`452 4.4.5` beyond). One full self-test sends roughly that much: run `node Scripts/dev-bootstrap.mjs fresh` between runs.525- **Run one self-test at a time** against a dev stack (two at once made a session drop).526- **The dev backend runs from the shared `sp-mail` checkout**: rebuild its `dist/` (`pnpm build` there) when it is older than its last commit.527- **Build products must stay outside `~/Desktop`**: `Scripts/build.sh` uses `~/Library/Developer/SPMail/DerivedData`.528- **`make-strings.py --sync` reads the Debug intermediates only** (macOS and simulator): build both first.529- **A Release build without the provisioning profiles** (`Build/profiles/*.provisionprofile`, created by `Scripts/provision.py`) is built unsigned, only to check that it compiles.530- **The Xcode project is generated**: edit `project.yml`, never `SPMail.xcodeproj`.531- **Headless undo grouping**: without a text view in front (self-test), the undo manager groups everything since the last event; in the interface each command is its own event.532- **Screen locked during a macOS capture**: WebKit stops painting message bodies — a blank body in a capture taken then is not a rendering bug.533- **A real AI generation costs money**: tests and self-tests use the scripted stub and a recorded stream; only `SPMAIL_TEST_REAL_AI=1` calls a model.534535## 🧭 Not implemented / partial536537- Creating or editing Sieve filters and automation rules, and administration, are web only.538- Template studio and « Programmés » need the server; sending a template is online only.539- The server's outbound object carries no subject: a tracked send shows the subject this device noted when it sent the message (or the stored copy in the local cache), else its recipients.540- A conversation is « pinned » by its newest message: a reply arriving in a pinned thread shows the thread unpinned until it is pinned again.541- English outside the three Next blocks of `make-strings.py` (the 1.1 strings) still uses title case in places.542- The writing assistant replaces text as plain text (formatting inside the replaced range is not kept); over an inline image it inserts under the text instead.543- Unified « Non lus » / « Avec drapeau » leave out Trash, Junk (and Drafts / Sent for unread) on the client, so a page can hold fewer rows than asked.544- The HTML source editor of the studio has no syntax colouring.545- iOS Release without the registered App Group: shares with files are sent directly instead of being queued (see above). Communication notifications (sender avatar) need a capability the API key cannot enable.546- Universal links (`applinks:`) are not used: the server's AASA lists `webcredentials` only.547548## 👤 Author549550<div align="center">551<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>552553**Simon-Pierre Boucher** — design, development, operations<br>554[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai555556</div>557558## 📄 License559560All rights reserved © 2026 Simon-Pierre Boucher (`NSHumanReadableCopyright` in `project.yml`). No license file is published in this repository.561