SPB Git

Repository Public

README.md 46.8 KB

Logo SP Chat



Icône SP Chat

# SP Chat — macOS natif

Client macOS entièrement natif (Swift 6, SwiftUI + AppKit) de chat.spboucher.ai : même backend, même historique, mêmes modèles vérifiés, connexion par clé d'accès avec Touch ID. Aucun WebView, aucun Electron, aucun HTML/JS.

Auteur : Simon-Pierre Boucher

chat.spboucher.ai version plateforme distribution licence author

Swift SwiftUI Xcode XcodeGen SwiftPM swift-markdown SwiftMath SQLite AuthenticationServices WebView

commits last commit activity language languages size branches tags clones

fichiers Swift lignes Swift écrans de l'espace de travail tests du cœur tests hébergés tests d'interface contrôles du binaire scripts langue

bundle id signature notarisation sandbox hardened runtime binaire cible


# Sommaire


# 🎯 Aperçu

Client macOS entièrement natif (Swift 6, SwiftUI + AppKit) de chat.spboucher.ai : même backend, même historique, mêmes modèles vérifiés, connexion par clé d'accès avec Touch ID. Aucun WebView, aucun Electron, aucun HTML/JS : l'interface, le rendu Markdown / LaTeX / code, le streaming et la persistance sont écrits avec les frameworks d'Apple.

Version 2.0.0 (2) « Next Generation » — construite et vérifiée localement, pas encore signée pour diffusion, notarisée ni publiée (dernière version publiée : 1.0.0)
Système macOS 15 ou plus récent · binaire universel (Apple Silicon et Intel)
Sécurité App Sandbox, Hardened Runtime, session dans le trousseau, aucune clé d'API dans l'app
Tests (2.0) 167 unitaires · 5 d'intégration backend 1.0 (vrai backend, vrais modèles) · 65 hébergés dans l'app · 3 d'interface (XCUITest) — détail et limites dans docs/TEST_REPORT.md

# Famille

Client Plateforme Dépôt Rôle
Chat SPBoucher AI Web · PWA chat-spboucher-ai backend (Next.js, PostgreSQL), API, interface web — conservé tel quel
SP Chat (ce dépôt) macOS 15+ sp-chat second client du même serveur : historique, brouillons, fichiers, mémoire et réglages partagés avec le site
SP Chat pour iOS / iPadOS iOS · iPadOS sp-chat-ios client natif iPhone et iPad du même serveur

L'app ne parle à aucun fournisseur d'IA directement et ne détient aucune clé : elle consomme le registre du serveur (/api/models), qui n'expose que les modèles vérifiés par le banc d'essai. L'identifiant ai.spboucher.spchat est partagé avec l'app iOS (voir docs/UPDATES.md).


# 📦 Installer

Ouvre SPChat-1.0.0.dmg, glisse SP Chat dans Applications, lance-la depuis Applications, puis « Continuer avec ma clé d'accès ». Détails et dépannage : docs/INSTALL.md.

  1. Télécharge SPChat-1.0.0.dmg (release v1.0.0 sur git.spboucher.ai/sp-chat/releases). Empreinte SHA-256 : fichier SPChat-1.0.0.dmg.sha256.
  2. Ouvre l'image disque et glisse SP Chat dans Applications.
  3. Lance SP Chat depuis le dossier Applications (indispensable pour les clés d'accès). Gatekeeper l'accepte sans avertissement : l'app et le DMG sont signés Developer ID et notarisés par Apple (ticket agrafé, vérifiable hors ligne).
  4. Clique « Continuer avec ma clé d'accès » : macOS propose la clé d'accès de chat.spboucher.ai (trousseau iCloud, Touch ID). Tu retrouves l'historique du site.

Configuration requise : macOS 15 ou plus récent, Mac Apple Silicon ou Intel, connexion Internet pour se connecter (l'historique déjà consulté reste lisible hors ligne).

SHA-256 du DMG 1.0.0 : 4fb90defeba390a155678e0f5fa7c48debd6899c6277b42bd72d9d2c1c3310a5 (10,6 Mo).

Sur un autre Mac
  • Même compte iCloud, trousseau activé : la clé d'accès est déjà synchronisée, la connexion fonctionne directement.
  • Autre Mac sans la clé : dans SP Chat, « Première connexion sur ce Mac, ou code de récupération », saisis un code de récupération (Réglages → Sécurité sur un appareil connecté) ou un code créé sur le serveur (pnpm auth bootstrap --recover), puis enregistre une clé d'accès pour ce Mac. Autre possibilité : choisir « un autre appareil » dans la feuille macOS et scanner le code QR avec l'iPhone qui détient la clé.
Désinstaller

Glisse l'app à la corbeille. Données locales : ~/Library/Containers/ai.spboucher.spchat (cache, préférences) et l'élément « ai.spboucher.spchat » du trousseau (jeton de session). « Se déconnecter de ce Mac » efface le cache et révoque la session côté serveur.


# ✨ Fonctions

Nouveautés 2.0 « Next Generation ». Système visuel V2 « Graphite & Iris · Lumen » (logos des fabricants à la place des pastilles de couleur, compositeur en capsule flottante, présence Lumen) ; catalogue OpenRouter complet avec Explorateur de modèles et fiche Live Model Intelligence ; Réglages → Fournisseurs ; recherche web avec cartes de sources ; Smart Follow-Ups ; panneau contextuel (Contexte, Chronologie + relecture, Response Lens, Branches) ; Arena ; Cost Intelligence ; Constellation ; Centre de commandes ⌘K ; synchronisation continue avec le site et l'app iOS. Détail : docs/RELEASE_NOTES.md, captures : docs/img/v2/ (Scripts/screenshots.sh).

Conversation. Streaming en temps réel plafonné à 30 images/s, générations détachées reprises après une coupure, arrêt, régénération (avec un autre modèle), modification d'un message, versions ◀ ▶, branches, approbation d'outils, brouillons partagés avec le site, pièces jointes validées sur leurs octets réels, lecture à voix haute et dictée.

Rendu. Markdown natif (tableaux, listes de tâches, citations), blocs de code colorés avec copie, formules LaTeX en ligne et en bloc composées avec CoreText, raisonnement repliable, appels d'outils, citations, images.

Modèles. Sélecteur des modèles vérifiés par fournisseur (OpenAI, Anthropic, xAI), routage manuel / auto / rapide / qualité / économie, effort de raisonnement, outils, profils d'usage. Le modèle se change par conversation.

Organisation. Historique groupé par date, épingles, favoris, archives, projets, recherche plein texte et sémantique (⌘F), palette de commandes (⌘K), cache local pour lire hors ligne.

Espace de travail. Projets, prompts, profils, fichiers, mémoire, laboratoire de modèles, utilisation (coûts), comparaison de modèles, recherche approfondie, images.

macOS. Fenêtres multiples restaurées, barre de menus complète, inspecteur, chat rapide flottant (⇧⌘Espace, raccourci global optionnel), icône de barre des menus optionnelle, glisser-déposer, collage enrichi, copie RTF, export Markdown / JSON / PDF natif, liens spchat://, notifications optionnelles.

# Parité avec le site (résumé de docs/FEATURE_MATRIX.md)

Légende — ✓ reproduit · ◐ reproduit avec un écart documenté · ✗ non reproduit (justifié) · + propre à macOS.

Domaine État Écart documenté
Passkeys, bootstrap par code, codes de récupération, sessions révocables, ré-authentification, CSRF ✓ transition 0.2 → 0.3 non reprise (✗, fermée côté serveur)
Envoi, streaming SSE, reprise après coupure, idempotence, arrêt, régénération, modification, versions, branches ✓ —
Markdown, tableaux, code coloré (~40 langages), LaTeX ✓ TeX non composable → affiché tel quel
Lecture à voix haute, dictée ◐ implémentées, pas d'essai audio réel
Artefacts HTML / React / Mermaid ◐ écart volontaire : aucun moteur web embarqué — source colorée, copie, enregistrement, « Ouvrir dans le navigateur » ; aperçu natif pour SVG et Markdown
Sélection de texte ◐ par bloc ; « Copier la réponse » copie tout (texte + RTF)
Liste, filtres, renommer, épingler, favori, archiver, déplacer, supprimer, recherche ✓ —
Mode hors ligne ✓ + cache SQLite : liste, fils déjà ouverts, recherche plein texte locale
Modèles vérifiés, routage, effort, outils, profils ✓ laboratoire : onglets « rapport de benchmark » et « routage » non repris (◐)
Projets, fichiers, utilisation, comparer, recherche approfondie, images ◐ sous-fonctions secondaires non reprises (détail dans la matrice)
Prompts, profils, mémoire, réglages, export complet, suppression totale ✓ —
Propre à macOS
  • NavigationSplitView, barre d'outils native, inspecteur, feuilles et popovers, clair / sombre automatique, plein écran.
  • Fenêtres multiples (une conversation par fenêtre, état partagé), restauration des fenêtres.
  • Barre de menus complète et raccourcis.
  • Palette de commandes ⌘K (commandes, modèles, conversations, recherche floue).
  • Chat rapide (panneau flottant, ⇧⌘Espace, raccourci global ⌥⌘Espace optionnel).
  • Icône de barre des menus optionnelle.
  • Glisser-déposer et collage enrichi (fichiers, images) dans le compositeur.
  • Copie enrichie (Markdown + RTF).
  • Export PDF natif paginé (CoreText, texte sélectionnable).
  • Liens profonds spchat://c/<id> et spchat://new?text=… (jamais d'action destructive ni d'envoi).
  • Notifications de fin de réponse (optionnelles, permission demandée à l'activation).
  • Taille du texte (⌘+ / ⌘-), libellés VoiceOver sur tous les boutons-icônes.

# ⌨️ Raccourcis

Raccourci Action Raccourci Action
⌘N nouvelle conversation ⇧⌘N nouvelle fenêtre
⌘F rechercher ⌘K palette de commandes
⌘, réglages ⏎ ou ⌘⏎ envoyer (au choix)
⌘. arrêter ⇧⌘R régénérer
⇧⌘M modèle ⇧⌘I recherche web
⌥⌘I / T / L / B panneau : contexte, chronologie, Lens, branches ⌥⌘E / A / G Explorateur, Arena, Constellation
/ et @ commandes et modèles dans le message ⌘K centre de commandes
⇧⌘E / ⇧⌘P export Markdown / PDF ⌘/ tous les raccourcis
⇧⌘Espace chat rapide ⌘+ / ⌘- taille du texte

# 🏗 Architecture

SP Chat est un client du backend chat.spboucher.ai. Aucun moteur web n'est embarqué : ni WKWebView, ni JavaScriptCore (vérifié par Scripts/verify-release.sh sur le binaire). Détail : docs/ARCHITECTURE.md.

flowchart TB
  subgraph App["Cible SP Chat (MainActor par défaut)"]
    UI["Components · Features<br/>SidebarView, ChatScreen, ComposerView,<br/>MarkdownView, MathView, 10 écrans d'espace de travail"]
    VM["ChatViewModel (un par conversation)<br/>WindowModel (un par fenêtre)"]
    ENV["AppEnvironment<br/>injection de dépendances"]
  end
  subgraph Core["Paquet SwiftPM SPChatCore (aucun import d'interface)"]
    GE["GenerationEngine<br/>tour complet + reprise"]
    SSE["SSEParser · MessageAccumulator"]
    API["APIClient · Endpoints typés<br/>HTTPTransport (URLSession éphémère)"]
    AUTH["AuthService<br/>cérémonies WebAuthn"]
    CACHE["CacheStore<br/>SQLite + FTS5"]
    SEC["SecretStore (trousseau)<br/>FileValidator · Redactor"]
    MD["MarkdownParser · SyntaxHighlighter"]
  end
  UI --> VM --> GE --> SSE --> API
  ENV --> VM
  AUTH --> API
  API --> SEC
  VM --> CACHE
  UI --> MD
  API -- "HTTPS · Origin exact" --> S["chat.spboucher.ai<br/>(dépôt chat-spboucher-ai)"]
  AUTH -. "AuthenticationServices<br/>Touch ID · trousseau iCloud" .-> OS["macOS"]

# Flux d'un tour de conversation

sequenceDiagram
  autonumber
  participant C as ComposerView
  participant V as ChatViewModel
  participant G as GenerationEngine
  participant S as chat.spboucher.ai
  participant K as CacheStore
  C->>V: send()
  V->>G: start(.send, payload)
  G->>S: POST /api/chat (clé d'idempotence, 4 essais)
  S-->>G: SSE (SSEParser → ChatEvent → MessageAccumulator)
  G-->>V: live (≤ 30 Hz)
  Note over G,S: coupure ou silence de 45 s
  G->>S: GET /api/chat/stream?run=…&after=<dernier index>
  S-->>G: rejeu des événements manqués, puis direct
  G->>S: GET /api/conversations/:id?all=1
  G->>K: saveDetail
  K-->>V: liste latérale à jour
  • Le serveur exécute chaque génération détachée de la connexion (il envoie un battement toutes les 15 s). Le flux SSE n'est qu'une vue du run : en cas de coupure le client se rattache avec l'index du dernier événement vu ; si le run n'existe plus, il recharge la conversation, dont les lignes font foi.
  • ChatViewModel.messages (messages stabilisés) et ChatViewModel.live (réponse en cours) sont séparés : le streaming n'invalide jamais les lignes déjà affichées. MessageRow et ChunkView sont Equatable ; le Markdown est découpé en blocs indépendants mis en cache, donc seul le dernier bloc est recalculé pendant le flux.

# Connexion par clé d'accès

sequenceDiagram
  autonumber
  participant A as SP Chat
  participant M as macOS (AuthenticationServices)
  participant S as chat.spboucher.ai
  A->>S: POST /api/auth/login/options
  S-->>A: défi à usage unique + cookie de cérémonie (gardé en mémoire)
  A->>M: demande d'assertion pour webcredentials:chat.spboucher.ai
  M-->>A: assertion signée (Touch ID, vérification utilisateur exigée)
  A->>S: POST /api/auth/login/verify (Origin: https://chat.spboucher.ai)
  S-->>A: jeton de session
  A->>A: jeton rangé dans le trousseau (jamais sur disque en clair)

# Injection et isolation

  • AppEnvironment construit tout une fois (serveur, APIClient, AuthService, CacheStore, GenerationEngine, stores observables) et se transmet par l'environnement SwiftUI. Les tests injectent un HTTPTransport scripté et un authentificateur WebAuthn logiciel : aucun singleton réseau.
  • Cible d'application : isolation MainActor par défaut, concurrence stricte Swift 6. Le cœur est Sendable (acteur pour SQLite, verrous pour le pot de cookies).
  • Un ChatViewModel par conversation, partagé par toutes les fenêtres ; un WindowModel par fenêtre.

# Extensibilité des fournisseurs

Ajouter OpenAI-compatible, un modèle local ou un service privé se fait côté serveur (un adaptateur src/lib/ai/*.ts + une entrée de registre) ; l'app l'affiche sans mise à jour (Provider.label, couleur par défaut). Un nouveau backend (autre serveur) n'exigerait qu'une autre implémentation de HTTPTransport/ServerConfiguration.

# Modifications du backend (dépôt chat-spboucher-ai, commit 52ec509)

  • GET /.well-known/apple-app-site-association (public, liste 3YM54G49SN.ai.spboucher.spchat, surchargeable par APPLE_APP_IDS).
  • Libellé d'appareil « Mac · SP Chat » pour l'agent utilisateur de l'app.

Aucune route existante n'a été modifiée ; le site web fonctionne à l'identique.


# 🧱 Pile technique

Couche Technologie Version Rôle
Langage Swift mode de langage 6.0, SWIFT_STRICT_CONCURRENCY: complete (project.yml) toute l'app
Interface SwiftUI + AppKit système fenêtres, menus, compositeur, rendu
Projet XcodeGen (project.yml) → SPChat.xcodeproj — 3 cibles : SPChat, SPChatTests, SPChatUITests
Cœur paquet SwiftPM SPChatCore (Package.swift, swift-tools 6.0) plateforme minimale du paquet : macOS 14 modèles, réseau, auth, streaming, persistance
Markdown swiftlang/swift-markdown 0.7.3 (épinglée) analyse CommonMark/GFM — analyseur d'Apple (cmark-gfm), robuste sur les entrées hostiles
Mathématiques mgriebling/SwiftMath 1.7.3 (épinglée) composition LaTeX (CoreText), sans moteur web
Persistance SQLite (bibliothèque système sqlite3) + FTS5 système cache local, recherche hors ligne
Frameworks système Security, AuthenticationServices, Network, AVFoundation, Charts, QuickLook, UserNotifications, Carbon (raccourci global), CryptoKit (tests) système trousseau, passkeys, audio, graphiques, aperçus
Outils Xcode 27 (rapport de tests : Xcode 27.2, Swift 6.4) — compilation, tests, archive

# 🗂 Structure du dépôt

123 fichiers suivis, dont 68 fichiers Swift (12 851 lignes).

text
SPChat/
├── App/            6 fichiers — entrée (@main), scènes, commandes de menu, AppDelegate (liens, raccourci global,
│                   notifications), AppEnvironment (injection de dépendances), WindowModel (navigation par fenêtre)
├── Core/           15 fichiers — paquet SwiftPM « SPChatCore » : aucun import d'interface, testable avec `swift test`
│   ├── Models/         DTO du serveur (décodage tolérant : colonnes numériques en chaînes, champs inconnus conservés)
│   ├── Networking/     HTTPTransport (URLSession éphémère), APIClient (cookie → trousseau, Origin, erreurs, ré-auth), Endpoints typés
│   ├── Authentication/ AuthService : cérémonies WebAuthn (options → authentificateur → vérification), sessions, passkeys
│   ├── Streaming/      SSEParser (octets → événements), ChatEvent, MessageAccumulator, GenerationEngine (tour complet + reprise)
│   ├── Persistence/    CacheStore (SQLite + FTS5) : listes, fils complets, catalogues, recherche hors ligne
│   ├── Security/       SecretStore (trousseau), FileValidator (type sur octets réels), Redactor (journaux sans secrets)
│   ├── Markdown/       MarkdownParser (blocs, math protégée, découpage incrémental), SyntaxHighlighter
│   └── Export/         export Markdown / JSON local
├── Features/       26 fichiers — Account · Conversations · Chat · ModelSelector · Attachments · Search · Settings · Workspace
├── Components/     6 fichiers — DesignSystem, SidebarView, MessageView, ComposerView, MarkdownView, MathView
├── Resources/      Info.plist, entitlements (Release / Debug), Assets.xcassets (AppIcon clair + sombre, AccentColor)
└── Tests/          CoreTests (Swift Testing), AppTests (XCTest hébergé), UITests (XCUITest)
Scripts/            build, tests, performance, provisionnement, signature, notarisation
docs/               matrice de parité, architecture, sécurité, tests, installation, mises à jour, notes de version, brand/
project.yml         définition XcodeGen · Package.swift / Package.resolved : paquet SPChatCore

# 🛠 Développer

Il faut Xcode 27 et XcodeGen.

sh
Scripts/build.sh debug          # génère SPChat.xcodeproj et compile en Debug
Scripts/build.sh core-test      # 167 tests du cœur (swift test, ~1 s)
Scripts/build.sh app-test       # 65 tests hébergés dans l'app
Scripts/integration-test.sh     # parcours complet contre le backend de DÉVELOPPEMENT (WebAuthn logiciel, vrais modèles)
Scripts/ui-test.sh              # XCUITest contre le backend de développement
Scripts/run-dev.sh              # lance le build Debug sur le backend de développement (session de dev, sans Touch ID)
Scripts/perf.sh launch|stream   # temps de lancement, mémoire, trace Instruments d'un long streaming
Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh   # archive signée → contrôles → notarisation + DMG

Les builds Debug ont leur propre identifiant (ai.spboucher.spchat.debug) et ne peuvent viser qu'un serveur en boucle locale ; ils n'ont pas le droit « Associated Domains », donc pas de passkey : la session de développement est injectée.

Script Rôle
Scripts/build.sh point d'entrée de développement : generate, debug, core-test, app-test, ui-test
Scripts/check-headers.sh échoue si un fichier source maison n'a pas l'en-tête d'auteur (Author / File / Description)
Scripts/dev-session.sh ouvre un tunnel SSH vers le backend de développement et y crée une session (builds Debug, tests d'interface)
Scripts/integration-test.sh tests de bout en bout du cœur contre le backend de développement (jamais la production)
Scripts/ui-test.sh suite XCUITest sur l'app Debug contre le backend de développement
Scripts/run-dev.sh lance le build Debug avec une session de développement, capture d'écran optionnelle
Scripts/perf.sh temps de lancement, mémoire au repos, trace xctrace Time Profiler d'une longue réponse
Scripts/provision.py · Scripts/asc.py identifiant, capacité Associated Domains et profil Developer ID par l'API App Store Connect (clé existante)
Scripts/release.sh archive Release signée avec l'identité Developer ID existante et le profil de provisionnement
Scripts/verify-release.sh contrôles du binaire signé : signature, runtime durci, bac à sable, droits, profil, absence de moteur web et de secrets
Scripts/notarize.sh notarisation de l'app, agrafage, DMG signé, notarisation et agrafage du DMG, fichier .sha256
Scripts/window-shot.swift capture la fenêtre au premier plan d'une app nommée (preuve des contrôles visuels)

# ⚙️ Configuration

Réglage Valeur Où
Identifiant (Release) ai.spboucher.spchat project.yml
Identifiant (Debug) ai.spboucher.spchat.debug — une copie de développement ne doit jamais masquer l'app installée (macOS résout l'association de domaine par identifiant d'application) project.yml
Équipe 3YM54G49SN project.yml
Version MARKETING_VERSION 2.0.0 · CURRENT_PROJECT_VERSION 2 project.yml
Cible de déploiement macOS 15.0 project.yml
Langue de développement fr project.yml
Serveur chat.spboucher.ai, configuré en dur ; serveur alternatif et session injectée en builds DEBUG uniquement, en boucle locale uniquement (LaunchOptions) docs/SECURITY.md
Domaine associé webcredentials:chat.spboucher.ai (Release seulement) SPChat/Resources/SPChat.entitlements
Schéma d'URL spchat:// SPChat/Resources/Info.plist
Catégorie public.app-category.productivity SPChat/Resources/Info.plist
Flux de mise à jour clé SPChatUpdateFeedURL, vide en 1.0 docs/UPDATES.md
Profil de notarisation profil trousseau notarytool nommé « MacLustr-Notarize » (existant, rien n'est créé) Scripts/notarize.sh

Aucune variable d'environnement ni clé d'API n'est nécessaire à l'exécution : les fournisseurs sont appelés par le serveur.


# 🖥 Écrans

Zone Fichiers Contenu
Fenêtre principale App/MainWindow.swift, Components/SidebarView.swift NavigationSplitView : historique groupé par date, épinglées d'abord, filtres
Conversation Features/Chat/ChatScreen.swift, Components/MessageView.swift, Components/ComposerView.swift transcription, compositeur, inspecteur (⌥⌘I)
Chat rapide Features/Chat/QuickChat.swift panneau flottant
Connexion Features/Account/LoginView.swift clé d'accès, première connexion par code, code de récupération
Sélecteur de modèles Features/ModelSelector/ModelPickerView.swift par fournisseur, recherche, favoris, défaut (⇧⌘M)
Palette Features/Search/CommandPalette.swift commandes, modèles, conversations, recherche floue (⌘K)
Réglages Features/Settings/SettingsView.swift préférences, sécurité (passkeys, appareils, journal), mémoire, dépenses, données

Les 10 écrans de l'espace de travail (Features/Workspace/), aiguillés par LibraryScreen.swift (qui route chaque section de la barre latérale vers son écran natif) :

Écran Fichier Écran Fichier
Projets ProjectsScreen.swift Modèles (laboratoire) ModelsScreen.swift
Prompts PromptsScreen.swift Utilisation (Swift Charts) UsageScreen.swift
Profils d'usage PresetsScreen.swift Comparer CompareScreen.swift
Fichiers FilesScreen.swift Recherche approfondie ResearchScreen.swift
Mémoire MemoryScreen.swift Images ImagesScreen.swift

# 🔌 API consommée

L'app est un client de l'API du dépôt chat-spboucher-ai ; elle n'expose aucun serveur. Les chemins sont typés dans SPChat/Core/Networking/Endpoints.swift (26 préfixes /api/… distincts), les cérémonies d'authentification dans Core/Authentication/AuthService.swift, le streaming dans Core/Streaming/GenerationEngine.swift.

Domaine Chemins
Authentification /api/auth/state, /api/auth/login/options, /api/auth/login/verify, /api/auth/setup, /api/auth/register/options, /api/auth/register/verify, /api/auth/reauth/options, /api/auth/reauth/verify, /api/auth/passkeys, /api/auth/sessions, /api/auth/recovery-codes, /api/auth/events, /api/auth/logout
Conversation /api/chat, /api/chat/stream, /api/chat/cancel, /api/chat/edit, /api/chat/regenerate, /api/chat/approve
Conversations /api/conversations, /api/conversations/:id, /api/search, /api/drafts
Catalogue /api/models, /api/models/refresh, /api/presets, /api/prompts, /api/settings
Contenus /api/attachments, /api/artifacts/:id, /api/images, /api/memories, /api/memories/export, /api/projects
Voix /api/stt, /api/tts
Compte /api/owner, /api/usage, /api/health

Règles respectées par APIClient : Origin: https://chat.spboucher.ai sur chaque mutation ; 401 locked → jeton effacé et retour à l'écran de connexion ; 403 reauth_required → la clé d'accès est demandée une fois puis la requête est rejouée ; HTTPS obligatoire hors boucle locale.


# 🗄 Données locales

Donnée Emplacement Détail
Jeton de session trousseau du Mac, élément « ai.spboucher.spchat » kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, non synchronisé
Cache SQLite dans ~/Library/Containers/ai.spboucher.spchat mode WAL, secure_delete, table virtuelle FTS5 message_fts (unicode61 remove_diacritics 2) : listes, fils complets déjà ouverts, catalogues, recherche hors ligne
Préférences conteneur de l'app persistées sans secret
Cookies de cérémonie mémoire seulement session URLSession éphémère : ni cookies, ni cache, ni identifiants sur disque

À la fin de session (déconnexion, session révoquée ou expirée) : jeton effacé, cache SQLite vidé (secure_delete, VACUUM, troncature du WAL), fichiers en cache supprimés.


# 🛡 Sécurité et vie privée

Détail : docs/SECURITY.md.

Sujet Choix
Bac à sable App Sandbox activé. Droits : réseau sortant, fichiers choisis par l'utilisateur (lecture / écriture), micro (dictée seulement). Pas de serveur réseau, pas de caméra, pas d'accès large au disque
Hardened Runtime activé, aucune exception (disable-library-validation, JIT, mémoire exécutable : absents)
Passkeys AuthenticationServices ; domaine associé webcredentials:chat.spboucher.ai (droit restreint porté par le profil Developer ID) ; vérification utilisateur exigée ; la cryptographie et la biométrie restent dans macOS
Validation serveur inchangée : défi à usage unique, origine et RP id exacts, signature vérifiée par @simplewebauthn/server
TLS validation système, TLS ≥ 1.2, jamais de contournement. HTTP refusé sauf boucle locale (développement)
CSRF Origin exact sur chaque mutation (exigence du serveur)
Fichiers importés type déterminé sur les octets réels, taille et nombre plafonnés, nom assaini avant tout envoi ; HEIC → JPEG ; photos réduites à 2048 px
Contenu des modèles le HTML brut n'est jamais interprété (affiché en texte) ; seuls http, https, mailto sont ouvrables ; les images distantes ne sont jamais chargées automatiquement
Liens profonds spchat://c/<id> (identifiant validé par expression régulière) et spchat://new?text= (pré-remplissage seulement). Aucun lien n'envoie, ne modifie ni ne supprime
Clés d'API aucune dans l'app ni dans le dépôt ; Scripts/verify-release.sh recherche des secrets dans le bundle
Journaux pas de contenu de message ni de jeton ; Redactor masque cookies, jetons et clés
Permissions système micro : demandé à la première dictée. Notifications : demandées quand l'option est activée. Raccourci global : API Carbon, sans permission Accessibilité

# ✅ Tests

Rapport complet, preuves et points non vérifiés : docs/TEST_REPORT.md (17 novembre 2026, MacBook Pro Apple M5 Max, macOS 27.0, Xcode 27.2).

Suite Commande Résultat rapporté
Cœur, unitaires (Swift Testing) Scripts/build.sh core-test 167 / 167 en ~1 s (2.0)
Cœur, intégration bout en bout Scripts/integration-test.sh 1 / 1 (≈ 15–18 s, vrais appels de modèle)
App, tests hébergés (XCTest) Scripts/build.sh app-test 65 / 65 (2.0)
Interface (XCUITest) Scripts/ui-test.sh 2 / 2 (≈ 45 s)
Contrôles du binaire signé Scripts/verify-release.sh 13 contrôles, 0 échec
En-têtes de fichiers Scripts/check-headers.sh OK

Répartition des 73 @Test de SPChat/Tests/CoreTests/ : Markdown 20 · moteur de génération 13 · streaming 11 · décodage des modèles 10 · réseau 10 · authentification et cache 8 · intégration 1. Les 27 tests hébergés sont dans SPChat/Tests/AppTests/ (AppStateTests.swift, ChatFlowTests.swift), les 2 tests d'interface dans SPChat/Tests/UITests/SPChatUITests.swift.

Ce que chaque suite prouve

Unitaires du cœur — décodage des charges réelles du serveur ; analyseur SSE découpé à chaque octet y compris au milieu d'un caractère UTF-8 ; accumulation du message (rejeu après reconnexion sans doublon) ; pot de cookies (jeton dans le magasin secret seulement, rotation, expiration) ; HTTPS obligatoire hors boucle locale ; Origin sur les mutations ; session verrouillée → jeton effacé ; ré-authentification unique sans boucle ; moteur de génération : clé d'idempotence identique sur les nouvelles tentatives, coupure en pleine réponse reprise à after=<index> sans perte ni doublon, run disparu, connexion muette abandonnée, annulation ; cérémonies WebAuthn avec un authentificateur logiciel ; cache SQLite (ordre, filtres, recherche plein texte sans diacritiques, entrée hostile, effacement vérifié dans le fichier, 4 000 messages) ; Markdown (tableaux, math protégée, monnaie ≠ math, $ dans le code, HTML jamais interprété, découpage stable pendant le streaming) ; politique de liens ; coloration ; détection de type de fichier ; rédaction des journaux ; exports.

Intégration (vrai backend de développement) — API verrouillée sans session ; mauvais code refusé ; enrôlement d'une passkey (signature P-256 réellement vérifiée par le serveur) ; déconnexion → l'ancien jeton est refusé ; reconnexion par passkey ; passkeys, appareils, codes de récupération, journal ; catalogue ; téléversement (fichier binaire refusé en 415) ; message réel streamé utilisant la pièce jointe ; régénération et versions ; modification ; arrêt en cours de génération ; renommer, épingler, favori, recherche, brouillon, export ; cache hors ligne ; branche, archive, suppression ; révocation de l'appareil → session terminée.

Hébergés dans l'app — envoi → streaming → état final → cache ; 3 000 événements de jetons ne provoquent pas plus de ~30 mises à jour d'écran par seconde ; texte et fichiers rendus au compositeur quand rien n'est parti ; refus 402 affiché ; arrêt ; régénération avec un autre modèle, versions, modification ; rattachement à une génération encore en cours ; ouverture hors ligne depuis le cache ; approbation d'outil ; préparation des pièces jointes (photo de 3000 × 2000 réduite à 2048 px) ; session expirée ou révoquée → déconnexion et cache vidé ; liens profonds strictement validés ; deux fenêtres partageant une conversation ; palette floue ; PDF paginé à texte sélectionnable ; copie RTF ; composition LaTeX à la bonne taille.

Interface (vraie app, vrais événements clavier) — historique listé ; frappe et envoi par Retour ; réponse streamée puis stabilisée ; commandes de menu activées selon la conversation ; ⌘K → palette → écran Utilisation ; ⌘N ; ⌘F ; ⌘, ; ⇧⌘N ; lancement avec serveur injoignable : app utilisable, indicateur hors ligne, échec expliqué et texte rendu au compositeur.

Validation manuelle sur la production (17 nov. 2026) — connexion par clé d'accès avec Touch ID dans le binaire signé ; historique du site visible dans l'app ; session conservée entre deux lancements ; installation depuis le DMG.


# ⚡ Performances

Mesures du rapport de tests (docs/TEST_REPORT.md).

Mesure Résultat Méthode
Lancement à froid → fenêtre à l'écran 690–715 ms (premier lancement après installation : 1 054 ms) Scripts/perf.sh launch, build Release notarisé, 5 lancements
Empreinte mémoire au repos, connecté 61–65 Mo (RSS 122–126 Mo) footprint, ps
Streaming d'un exposé de 1 500 mots (titres, tableau, code) CPU moyen 29 % d'un cœur, pic 39 % ; mémoire max 154 Mo Scripts/perf.sh stream : build Debug non optimisé avec Instruments attaché (majorant)
Fenêtre présente après arrêt forcé puis relance 10 / 10 boucle kill -9 + open

Lecture : le coût pendant le streaming est celui de la mise en page SwiftUI du dernier bloc, à 30 images/s ; rien n'est recalculé pour les messages et blocs déjà affichés.


# 🚀 Publication

Chaîne reproductible (docs/UPDATES.md) :

sh
# 1. version : MARKETING_VERSION / CURRENT_PROJECT_VERSION dans project.yml
Scripts/build.sh core-test && Scripts/build.sh app-test && Scripts/integration-test.sh && Scripts/ui-test.sh
Scripts/provision.py            # idempotent : identifiant, capacité Associated Domains, profil Developer ID (clé API App Store Connect existante)
Scripts/release.sh              # archive Release signée (identité Developer ID du trousseau + profil), dist/SP Chat.app
Scripts/verify-release.sh       # signature, runtime durci, bac à sable, droits, profil, absence de moteur web et de secrets
Scripts/notarize.sh             # notarytool (profil trousseau « MacLustr-Notarize ») → agrafage → DMG signé → notarisation → agrafage
spctl -a -vv -t exec "dist/SP Chat.app" && spctl -a -vv -t open --context context:primary-signature dist/SPChat-<version>.dmg

Rien n'est créé côté certificats : release.sh échoue s'il n'existe pas d'identité « Developer ID Application ». provision.py remplace le profil si Apple l'a invalidé (c'est le cas dès qu'une capacité de l'identifiant change — l'identifiant ai.spboucher.spchat est partagé avec l'app iOS).

Publication : pousser le dépôt et l'étiquette v<version> sur spbgit, puis déposer SPChat-<version>.dmg et son .sha256 dans M1M32:~/srv/spbgit/data/releases/sp-chat/v<version>/.

État de la 1.0.0 (1)
Étiquette v1.0.0
Identité Developer ID Application: Simon-Pierre Boucher (3YM54G49SN) — certificat existant, aucun créé
Profil « SP Chat Developer ID » (MAC_APP_DIRECT, Associated Domains), embarqué
Notarisation app et DMG Accepted ; stapler validate OK pour les deux
Gatekeeper spctl : accepted, source=Notarized Developer ID (app, DMG, app du DMG monté)
DMG dist/SPChat-1.0.0.dmg, 10,6 Mo

Mettre à jour (1.0) — manuel : télécharger le nouveau DMG et remplacer l'app dans Applications. La session (trousseau) et les préférences sont conservées ; le cache local est reconstruit si son schéma change.


# 🩺 Dépannage

Symptôme Cause Remède
« macOS n'a pas (encore) validé l'association entre cette application et le domaine des clés d'accès » Le service système qui valide le lien app ↔ chat.spboucher.ai n'a pas pu lire l'app. Cas constaté : app lancée depuis un dossier protégé (Bureau, Documents, Téléchargements) ou depuis l'image disque, ou plusieurs copies de l'app enregistrées sur le Mac Mets l'app dans /Applications, supprime les autres copies, relance. La validation demande Internet au premier lancement (quelques secondes)
La feuille Touch ID ne propose aucune clé La clé d'accès n'est pas sur ce Mac Voir « Sur un autre Mac »
« Session terminée » au lancement Session révoquée ou expirée (30 jours d'inactivité, 90 jours au total) Se reconnecter avec la clé d'accès
Bandeau « Hors ligne — cache local » Serveur ou réseau injoignable Les conversations déjà ouvertes restent lisibles ; l'envoi reprend au retour du réseau
Aucune fenêtre après un arrêt forcé — Corrigé en 1.0.0 : une fenêtre principale est toujours rouverte au lancement ; cliquer l'icône du Dock en rouvre une
Pas de passkey en build Debug Les builds Debug n'ont pas le droit « Associated Domains » Normal : utiliser Scripts/run-dev.sh (session de développement injectée)
Le profil de provisionnement est refusé à la signature Apple l'invalide dès qu'une capacité de l'identifiant change Relancer Scripts/provision.py (idempotent)
Le lot de tests d'interface ne se charge pas bundle de test ad hoc + validation de bibliothèque ENABLE_HARDENED_RUNTIME: NO sur la cible SPChatUITests (déjà dans project.yml)

# 🚧 Limites connues et suite prévue

Écarts assumés avec le site (docs/FEATURE_MATRIX.md) :

  1. Aperçus vivants d'artefacts HTML / React / Mermaid : exclus par la règle « aucun WebView ». Remplacés par la source colorée et l'ouverture dans le navigateur.
  2. Sélection continue sur plusieurs blocs : limite de Text SwiftUI ; compensée par la copie de la réponse entière.
  3. Sous-fonctions secondaires de Comparer, Recherche, Images, Projets, Utilisation et du laboratoire de modèles.
  4. Enregistrement d'une clé de sécurité matérielle : la connexion par clé de sécurité est proposée, l'enregistrement se fait pour la clé de plateforme du Mac.
  5. Interface en français uniquement (comme le site).

Limites de sécurité (docs/SECURITY.md) :

  • Le cache SQLite n'est pas chiffré par l'application : il repose sur le bac à sable et FileVault. Il est vidé à la déconnexion.
  • Les fichiers ouverts avec Coup d'œil sont copiés dans le dossier temporaire du conteneur (purgé par le système).
  • L'app fait confiance au serveur configuré en dur (chat.spboucher.ai) ; il n'y a pas d'épinglage de certificat.
Non vérifié (extrait de docs/TEST_REPORT.md)
  • Autre Mac / autre version de macOS : testé sur une seule machine (macOS 27, Apple Silicon). La tranche Intel du binaire universel et macOS 15 / 26 n'ont jamais été exécutés.
  • Écrans de l'espace de travail : compilés et relus, non exercés contre le serveur, sauf Utilisation (ouvert par le test d'interface).
  • Dictée et lecture à voix haute (aucun essai audio), notifications, icône de barre des menus, chat rapide et raccourci global, glisser-déposer et collage d'images, ouverture d'artefact dans le navigateur, Coup d'œil des pièces jointes.
  • Restauration des fenêtres après un redémarrage, plein écran, onglets de fenêtres.
  • VoiceOver : libellés posés sur les contrôles, aucun audit avec le lecteur d'écran.
  • Enrôlement d'une passkey dans le binaire signé (seule la connexion l'a été) ; connexion par clé de sécurité matérielle.
  • Fournisseurs OpenAI et xAI en conversation réelle depuis l'app (tests réels faits avec Anthropic).
  • Instrument Leaks, mesure d'énergie, conversations réelles de plusieurs milliers de messages à l'écran.

Mise à jour automatique (prévue, non livrée) — l'architecture réserve le point d'entrée : clé SPChatUpdateFeedURL d'Info.plist (vide en 1.0) et UpdateChecker (Features/Settings/SettingsView.swift). Conception retenue :

  1. un flux appcast servi en HTTPS par git.spboucher.ai, chaque entrée portant version, URL du DMG, taille et signature EdDSA ;
  2. clé publique EdDSA embarquée dans l'app ; une archive dont la signature ne vérifie pas est refusée, même servie en HTTPS ;
  3. l'archive téléchargée doit en plus être signée par la même équipe Developer ID et notarisée (vérification SecStaticCode avant remplacement) ;
  4. installation par un assistant hors bac à sable (service XPC), comme le fait Sparkle 2 pour les apps sandboxées.

Tant que ces quatre garanties ne sont pas en place, l'app n'installe rien d'elle-même.


# 👤 Auteur

Simon-Pierre Boucher — conception, développement, exploitation

www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai

# 📄 Licence

© 2026 Simon-Pierre Boucher — logiciel privé. Tous droits réservés.

Files main
Menu

Theme