SP Drive pour iPhone et iPad
Client natif (Swift 6, SwiftUI, UIKit là où il le faut) de SP Drive, le stockage documentaire privé hébergé sur le cluster MacLustr : explorateur, emplacement dans l'app Fichiers, hors ligne, synchronisation et conflits sans écrasement. Aucune vue web.
Author: Simon-Pierre Boucher
Sommaire
- SP Drive Next (2.0)
- Aperçu
- Fonctions
- Architecture
- Décisions qui comptent
- Pile technique
- Arborescence du dépôt
- Construire et tester
- Configuration
- API consommée
- Écrans
- Modèle de données local
- Sécurité et confidentialité
- Tests
- Publication
- Backend
- Parité web, macOS, iPhone, iPad
- Pièges connus
- Reste à faire et limites connues
- Auteur
- Licence
🚀 SP Drive Next (2.0) — branche next
Mise à niveau majeure, pas une réécriture : File Provider, moteur, authentification, signature et identifiants sont ceux de la 1.0. La 2.0 n'est ni archivée ni envoyée à Apple : la version publiée sur TestFlight reste la 1.0.0 (1). Tout ce qui suit a été vérifié sur simulateur seulement (aucun appareil réel), contre un serveur 2.0 jetable, jamais la production ; l'IA a été exercée contre un faux point d'accès compatible OpenAI (aucun vrai modèle).
| Document | Contenu |
|---|---|
docs/next/PHASE2-iOS.md |
écrans 2.0, ce qui dépend de GET /meta, ce que le paquet partagé ne couvre pas, anglais : ce qui reste en français |
docs/next/DELIVERY-CHECKLIST.md |
ce qu'il faut créer dans le portail développeur et App Store Connect, et les vérifications avant l'archive |
docs/next/PHASE1-iOS.md |
moteur 2.0, design, iPad, conflits, numériseur, annotation, partage, widgets |
docs/next/AUDIT-iOS.md |
audit de la 1.0, mesures, ce que prouvent les tests, arrière-plan : ce qu'iOS ne garantit pas |
docs/TESTS.md |
suites, mesures, « construit, non vérifié » |
docs/next/shots/ |
captures des simulateurs |
Phase 1 : moteur de synchronisation 2.0 (Wi-Fi seulement, données réduites, économie d'énergie, batterie, parallélisme adaptatif, priorités, reprise après arrêt brutal, épinglage cohérent), design iPhone (cartes, feuille d'actions, pastille de transferts, zooms), iPad (inspecteur, fenêtres, raccourcis), conflits côte à côte, numériseur avec OCR sur l'appareil, annotation PDF enregistrée comme nouvelle version, extension de partage durcie, cinq widgets.
Phase 2 (paquet partagé SPDriveNext du dépôt macOS, lié en paquet local ../SPDrive) : flux d'évènements du serveur branché
sur le moteur (repli sur l'interrogation), recherche dans le contenu avec passages surlignés et recherche par le sens, SP Drive AI
(interroger un document, un dossier ou tout le Drive ; réponse en flux, passages cités numérotés qui ouvrent le fichier ; choix du
modèle qui distingue son créateur de la route qui le sert ; consentement aux fournisseurs externes ; suggestions de rangement à
confirmer une à une), étiquettes, collections intelligentes avec constructeur de règle, activité, versions (chronologie,
restauration, comparaison : texte ligne à ligne, images et PDF côte à côte, simple constat sinon), centre de stockage (par type,
par dossier, croissance, doublons — jamais de suppression automatique), membres et rôles, « Partagés avec moi » selon le rôle,
appareils connectés, vue d'infrastructure pour les administrateurs, code QR d'un lien, limite de débit. Chaque écran ou
commande 2.0 n'existe que si le serveur annonce la fonction : devant un serveur 1.0, l'app se présente comme la 1.0.
Cibles : app, File Provider, partage, widgets (ai.spboucher.spdrive.ios.widgets), tests unitaires et d'interface. Le reste
de ce README décrit l'architecture d'origine et reste exact pour ce qui n'a pas changé.
📖 Aperçu
SP Drive pour iPhone et iPad est le client natif de SP Drive, le stockage documentaire privé hébergé sur le cluster MacLustr. Aucune vue web : chaque écran est natif, les transferts et la synchronisation sont écrits en Swift. L'app apporte ce que le site ne peut pas offrir sur un téléphone : SP Drive comme emplacement de l'app Fichiers, des fichiers et dossiers gardés hors ligne, des modifications faites sans réseau puis rejouées, et une résolution de conflits qui n'écrase jamais rien.
| Identifiants | ai.spboucher.spdrive.ios (+ .fileprovider, .share) · groupe d'apps group.ai.spboucher.spdrive.ios · équipe 3YM54G49SN |
| Cible | iOS / iPadOS 18.0 et plus, iPhone + iPad |
| Version | 1.0.0 (1) — sur TestFlight depuis le 2026-11-18 (build VALID, test interne) |
| Fiche App Store Connect | 6836524538 (SKU spdrive-ios-001) |
| Langue | français seulement (l'anglais reste à faire) |
| Code | 66 fichiers Swift, 11 312 lignes, aucune dépendance externe |
Documents du dépôt : état réel, fonction par fonction — docs/TESTS.md ; audit du système existant et
matrice de parité — docs/AUDIT.md.
Famille SP Drive
| Dépôt | Rôle | Plateforme |
|---|---|---|
| sp-drive | Backend (Fastify, PostgreSQL, worker) + site web, drive.spboucher.ai |
web |
| sp-drive-macos | Client natif macOS (File Provider Finder, paquets SPDriveCore / SPDriveSync) |
macOS |
| sp-drive-ios | Client natif iPhone et iPad (ce dépôt) | iOS / iPadOS |
✨ Fonctions
| Domaine | Ce qui est construit |
|---|---|
| Explorateur | Mon Drive, Récents, Favoris, Partagés, Hors ligne, Transferts, Corbeille, Recherche, Paramètres. Liste ou grille, tri, filtres par type, sélection multiple, menus contextuels, balayages, glisser-déposer, retours haptiques. iPhone : barre d'onglets. iPad : barre latérale + colonnes, raccourcis clavier. |
| App Fichiers | Extension File Provider répliquée : SP Drive est un emplacement de Fichiers ; listage paginé, téléchargement à la demande vérifié, création, renommage, déplacement, corbeille, suppression, envoi des modifications, vignettes. |
| Hors ligne | Fichiers et dossiers « gardés hors ligne » dans Application Support (jamais purgés par le système) ; un dossier gardé suit ce qu'on y ajoute. Créer, renommer, déplacer, supprimer, ajouter et modifier hors ligne : tout est journalisé et rejoué à la reconnexion, y compris après un redémarrage. |
| Synchronisation | Flux de changements incrémental du serveur (révisions, pas de dates), journal persistant des opérations locales, identifiants stables, comparaison par version et empreinte SHA-256. |
| Conflits | Une nouvelle version nomme toujours la version dont elle part ; si le serveur a avancé, rien n'est écrasé : conflit affiché, trois choix (garder les deux, garder la mienne, garder celle du serveur). Dans Fichiers, l'édition en conflit devient une copie « (conflit …) ». |
| Transferts | File persistante, priorités, parallélisme selon le réseau (Wi-Fi, cellulaire, mode données réduites), pause, reprise, annulation, nouvel essai avec délai croissant. Envoi par blocs de 8 Mio avec empreinte par bloc et vérification finale par le serveur ; téléchargement repris par Range et vérifié avant d'être installé. URLSession en arrière-plan, relance de l'app prise en charge. |
| Import | Fichiers, Photos (sélecteur système, aucun accès global à la photothèque), appareil photo, numériseur de documents (PDF assemblé avec PDFKit), feuille de partage (extension : jusqu'à 50 fichiers, 50 images, 10 vidéos), glisser-déposer. |
| Aperçu et édition | QuickLook (images, PDF, vidéo, audio, texte, bureautique) avec annotations enregistrées comme nouvelle version ; éditeur de texte natif ; « Ouvrir dans une autre app ». |
| Partage | Liens de partage (lecture seule ou téléchargement, mot de passe, expiration, plafonds, usage unique, rotation, révocation, journal d'accès) et liens de dépôt (dossier cible, limites, mot de passe, expiration, pause, soumissions reçues). Toutes les règles sont appliquées par le serveur. |
| Versions | Liste, téléchargement d'une version, restauration (crée une nouvelle version), suppression. |
| Compte et sécurité | Connexion par clé d'accès (passkey) native, liaison par code en secours, session d'appareil dans le trousseau (groupe partagé avec les extensions), verrou Face ID / Touch ID optionnel, appareils connectés, déconnexion. |
| Stockage | Quota MacLustr, espace hors ligne, cache, transferts en attente, fichiers volumineux ; « Retirer de cet appareil » ne touche jamais au Drive. |
| Notifications | Locales : conflit, transfert interrompu, espace insuffisant, dépôt reçu, transferts terminés en arrière-plan. Désactivables une à une. |
Raccourcis clavier (iPad, clavier matériel)
| Raccourci | Action |
|---|---|
| ⇧⌘N | Nouveau dossier |
| ⌘O | Importer des fichiers… |
| ⌘R | Synchroniser maintenant |
| ⌘F | Rechercher |
| ⌘1 / ⌘2 | Afficher en liste / en grille |
| ⌘S | Enregistrer (éditeur de texte) |
🧭 Architecture
Core/ et Sync/ sont compilés dans l'app et dans les deux extensions ; Package.swift les expose aussi comme
bibliothèque (SPDriveKit) pour les tester sur le Mac en quelques secondes.
Trois processus, trois responsabilités : l'app a sa base (Application Support/SPDrive/drive.sqlite) et son moteur ;
l'extension File Provider a sa propre base dans le conteneur du groupe (aucune base n'est ouverte par deux
processus) ; l'extension de partage n'a pas d'état. Le seul élément partagé est le jeton de session, dans le trousseau.
flowchart TB
subgraph Device["iPhone / iPad"]
subgraph AppProc["App SP Drive"]
UI["Features (SwiftUI)<br/>9 sections + recherche"]
ENG["SyncEngine (acteur)<br/>changements, journal, conflits"]
TQ["TransferQueue<br/>UploadManager · DownloadManager"]
DB1[("drive.sqlite<br/>Application Support")]
end
subgraph FP["Extension File Provider"]
FPE["FileProviderExtension<br/>Enumerator · Item · Manager"]
DB2[("base du domaine<br/>conteneur du groupe")]
end
subgraph SH["Extension de partage"]
SVC["ShareViewController<br/>sans état"]
end
KC["Trousseau partagé<br/>jeton de session d'appareil"]
FILES["App Fichiers / apps tierces"]
end
subgraph Cluster["MacLustr"]
TUN["MacLustr Tunnel<br/>Caddy + WireGuard"]
API["sp-drive · API /api/v1<br/>m5ma:8660"]
PG[("PostgreSQL 17")]
OBJ["objets chiffrés au repos"]
end
UI --> ENG --> TQ
ENG --> DB1
FILES --> FPE --> DB2
SVC -. "ShareInbox" .-> ENG
AppProc --> KC
FP --> KC
SH --> KC
TQ -- "HTTPS · Bearer" --> TUN
FPE -- "HTTPS · Bearer" --> TUN
TUN --> API --> PG
API --> OBJ
Envoi résumable d'un fichier
sequenceDiagram
autonumber
participant U as UploadManager
participant S as API sp-drive
U->>S: POST /uploads (nom, taille, baseVersionId)
S-->>U: identifiant d'envoi
loop blocs de 8 Mio
U->>U: découpe + SHA-256 du bloc (IntegrityVerifier)
U->>S: PATCH /uploads/:id?offset= (X-Chunk-SHA256)
S-->>U: nouveau décalage
Note over U,S: bloc coupé → le serveur renvoie le décalage réel, reprise à cet endroit
end
U->>S: POST /uploads/:id/complete (SHA-256 du fichier)
alt le serveur a avancé
S-->>U: 409 version_conflict
U->>S: PATCH /uploads/:id/options {asNewFile} — copie de conflit, sans renvoyer les octets
else version acceptée
S-->>U: élément mis à jour (nouvelle version)
end
Synchronisation hors ligne puis reconnexion
sequenceDiagram autonumber participant A as App (hors ligne) participant J as Journal ops (SQLite) participant S as API sp-drive A->>J: créer / renommer / déplacer / modifier (appliqué tout de suite en local) Note over A,J: redémarrage possible — le journal est persistant A->>S: retour du réseau — rejouer les opérations dans l'ordre S-->>A: confirmations ou 409 (conflit affiché, rien d'écrasé) A->>S: GET /sync/changes?since=rev S-->>A: éléments modifiés + pierres tombales A->>J: miroir local à jour
🧱 Décisions qui comptent
- Deux mécanismes de conservation, distincts. Les copies « gardées hors ligne » par l'app vivent dans Application Support et sont à elle. Les fichiers matérialisés par l'app Fichiers appartiennent au système, qui peut les évincer ; l'extension ne promet rien de plus.
- Suppression. Supprimer = corbeille du Drive (restaurable), y compris depuis Fichiers. La suppression définitive n'existe que depuis la corbeille, avec confirmation et serveur joignable. Libérer de l'espace local est une autre action, qui ne touche jamais au Drive.
- Rien d'écrasé en silence. Une copie locale modifiée et pas encore envoyée n'est jamais remplacée ni supprimée par une synchronisation, un nettoyage de cache ou un désépinglage.
- Arrière-plan. iOS décide quand les transferts en arrière-plan tournent ; l'app les reprend là où ils en sont, sans promettre de continuité.
- Chiffrement. TLS en transit, chiffrement au repos côté serveur, protection des fichiers iOS sur l'appareil. Ce n'est pas du chiffrement de bout en bout et l'app le dit.
- Un seul contrat serveur. La couche iOS est écrite derrière le protocole
DriveRemote(Core/API/DriveRemote.swift) ; c'est le point de raccord prévu avecSPDriveCorede l'app macOS.
🧰 Pile technique
| Couche | Technologie | Version | Rôle |
|---|---|---|---|
| Langage | Swift | 6.0, SWIFT_STRICT_CONCURRENCY: complete |
tout le code |
| Interface | SwiftUI (+ UIKit ponctuel) | système | tous les écrans |
| Cible | iOS / iPadOS | 18.0 et plus, familles 1,2 |
iPhone + iPad ; ni Catalyst, ni « Designed for iPad » sur Mac, ni visionOS |
| Système de fichiers | FileProvider (extension répliquée) | système | emplacement SP Drive dans Fichiers |
| Partage entrant | extension de partage (UIKit) | système | « Envoyer vers SP Drive » |
| Persistance | SQLite 3 (enveloppe Core/Persistence/SQLite.swift) |
user_version = 1 |
miroir, journal, transferts, conflits |
| Réseau | URLSession (dont session d'arrière-plan) | système | API, blocs, Range |
| Authentification | AuthenticationServices | système | passkeys WebAuthn |
| Verrou | LocalAuthentication | système | Face ID / Touch ID |
| Session | Trousseau, groupe partagé | système | jeton Bearer d'appareil |
| Aperçu | QuickLook, PDFKit | système | aperçus, annotations, numériseur |
| Arrière-plan | BackgroundTasks (fetch, processing) |
système | rafraîchissement et synchronisation |
| Paquet | Swift Package Manager | tools 6.0 ; iOS 18, macOS 15 | SPDriveKit (Core + Sync) pour les tests Mac |
| Projet | XcodeGen | project.yml |
génère SPDrive.xcodeproj (non versionné) |
| Tests | Swift Testing + XCUITest | — | moteur, hébergés, interface |
📁 Arborescence du dépôt
sp-drive-ios/
├── project.yml XcodeGen : app, extension File Provider, extension de partage, tests unitaires et d'interface
├── Package.swift paquet SPDriveKit (Core + Sync) pour les tests sur le Mac
├── App/ (7) point d'entrée, modèle d'app, passkeys, verrou, tâches d'arrière-plan, notifications
├── Core/ (12) API (client HTTP, modèles), base locale SQLite, trousseau, réseau — sans interface, compatible extensions
├── Sync/ (12) moteur : tirage des changements, journal, transferts, conflits, intégrité, fichiers locaux
├── FileProviderExtension/ (4) emplacement SP Drive dans l'app Fichiers
├── ShareExtension/ (1) « Envoyer vers SP Drive » depuis la feuille de partage
├── Features/ (22) écrans SwiftUI par domaine : Account, Home, MyDrive, Offline, Recent, Search, Settings, Shared, Transfers, Trash
├── Components/ (1) identité visuelle et vues réutilisables
├── Resources/ Info.plist, droits, PrivacyInfo, Assets.xcassets (icône claire / sombre / teintée)
├── KitTests/ (2) tests d'intégration de Core + Sync (sur le Mac, contre un vrai backend)
├── Tests/ (3) tests hébergés dans l'app (File Provider, WebAuthn)
├── UITests/ (1) tests d'interface (simulateur)
├── Design/ sources SVG de l'icône (claire, sombre, teintée) et de la marque
├── Scripts/ build.sh, release.sh, test-server.sh, asc.py, ExportOptions.plist
└── docs/ AUDIT.md, TESTS.md, brand/ (logo.svg, icon.png)Lignes Swift par dossier : App 762 · Core 1 575 · Sync 1 962 · Features 5 106 · Components 135 · FileProviderExtension 495 · ShareExtension 207 · KitTests 521 · Tests 217 · UITests 313.
Les 12 fichiers du moteur Sync/
| Fichier | Rôle |
|---|---|
SyncEngine.swift |
acteur central : tirage du flux de changements, rejeu du journal |
MirrorSync.swift |
tirage incrémental du flux de changements vers une base ; partagé par l'app et l'extension File Provider |
ChangeDetector.swift |
ce qu'un changement venu du serveur implique pour les copies locales (comparaison par empreinte et version, jamais par date) |
ConflictResolver.swift |
garder les deux / la mienne / celle du serveur |
TransferQueue.swift |
file persistante, priorités, parallélisme selon le réseau |
UploadManager.swift |
envoi par blocs de 8 Mio |
DownloadManager.swift |
téléchargement repris par Range |
DirectTransfer.swift |
envoi et téléchargement directs pour les extensions : bloc par bloc, vérifiés, reprenables |
BackgroundSession.swift |
URLSession d'arrière-plan, relance de l'app |
IntegrityVerifier.swift |
SHA-256 de fichiers et de tranches, lus en flux (un gros fichier n'est jamais chargé en mémoire) |
LocalFiles.swift |
emplacements des contenus : Application Support (hors ligne, en attente d'envoi), Caches (copies ouvertes une fois) ; noms assainis |
ShareInbox.swift |
relais extension de partage → app : ce que l'extension n'a pas pu envoyer attend dans le conteneur du groupe |
🚀 Construire et tester
Prérequis : Xcode, XcodeGen, un accès SSH au nœud qui héberge le backend jetable.
Scripts/test-server.sh up # backend jetable sur m5ma:8663 (clone, base et données à part) + tunnel + identifiants de test
Scripts/build.sh core # tests d'intégration Core + Sync sur le Mac
Scripts/build.sh debug # build simulateur (SPDRIVE_SIM="SPDrive iPad" pour la tablette)
Scripts/build.sh release # build Release pour simulateur générique
Scripts/build.sh test # tests hébergés dans l'app (dont le File Provider par le système de fichiers)
Scripts/build.sh uitest # tests d'interface ; captures dans build/shots/
Scripts/build.sh device # build signé pour un appareil réel
Scripts/release.sh archive|export|validate|upload
Scripts/test-server.sh down- Le projet Xcode est généré par
xcodegen(project.yml) ;Scripts/build.sh generatecrée aussi lesInfo-Debug.plist(réseau local autorisé pour joindre le backend de test par tunnel — jamais en Release,release.shle vérifie).SPDrive.xcodeprojet lesInfo-Debug.plistne sont pas versionnés. - Simulateurs dédiés : « SPDrive iPhone » (défaut) et « SPDrive iPad » ;
SPDRIVE_SIMchoisit. Scripts/test-server.sh:up(clone ou rafraîchit le backend, base et données neuves, démarrage, tunnel, identifiants),creds(deux comptes neufs avec jeton d'appareil),tunnel(rouvre le tunnel),down. Il ne touche jamais à la production ni au banc d'essai de la session macOS.- Les tests du simulateur utilisent le second compte de test (les tests du moteur remplissent le premier de centaines de dossiers).
- Incrémenter
CURRENT_PROJECT_VERSIONavant chaque envoi à App Store Connect.
Le test File Provider par le système de fichiers exige que l'emplacement SP Drive ait été ouvert une fois dans Fichiers sur le simulateur (iOS laisse un nouvel emplacement désactivé jusque-là). Lancer d'abord :
Scripts/build.sh uitest -only-testing:SPDriveUITests/DriveUITests/testFilesAppShowsSPDriveLocation.
🔧 Configuration
Rien de secret ne vit dans le dépôt. Noms seulement :
| Nom | Où | Rôle |
|---|---|---|
SPDriveAppGroup, SPDriveKeychainGroup |
Info.plist |
groupe d'apps et groupe de trousseau partagés avec les extensions |
SPDRIVE_SIM |
Scripts/build.sh |
simulateur utilisé |
SPDRIVE_TEST_NODE, SPDRIVE_BACKEND_REF |
Scripts/test-server.sh |
nœud du backend jetable (défaut m5ma), branche du backend (défaut native-clients) |
SPDRIVE_TEST_URL, SPDRIVE_TEST_TOKEN, SPDRIVE_TEST_TOKEN_B |
~/.config/spdrive-ios-test/credentials.env (hors dépôt) |
adresse et jetons des deux comptes de test |
SPDRIVE_BASE_URL, SPDRIVE_RESET |
environnement du lanceur de tests | l'app démarre connectée au backend de test, depuis un état local propre |
ASC_KEY_ID, ASC_ISSUER_ID |
Scripts/release.sh |
clé d'API App Store Connect (fichier .p8 hors dépôt) |
Réglages du bundle : domaine associé webcredentials:drive.spboucher.ai, tâches d'arrière-plan
ai.spboucher.spdrive.ios.refresh et ai.spboucher.spdrive.ios.sync, modes fetch et processing, ATS strict en
Release.
🔌 API consommée
L'app appelle 52 opérations (méthode + chemin) de l'API « clients natifs » du backend
sp-drive, sous /api/v1, avec un jeton Bearer d'appareil. Code :
Core/API/DriveAPI.swift, DriveAPI+Sharing.swift, DriveAPI+Account.swift.
Tableau des routes
| Domaine | Méthode et chemin |
|---|---|
| Authentification | GET /auth/state · POST /auth/login/options · POST /auth/login/verify · POST /auth/reauth/options · POST /auth/reauth/verify · POST /auth/device/start · POST /auth/device/poll · POST /auth/logout |
| Compte | GET /account/passkeys · POST /account/passkeys/options · POST /account/passkeys/verify · GET /account/sessions · DELETE /account/sessions/:id |
| Synchronisation | GET /sync/changes · GET /sync/cursor · POST /sync/items |
| Arborescence | GET /folders/:id/children · POST /folders · PATCH /folders/:id · GET /files/:id · PATCH /files/:id · POST /move · POST /copy · GET /search |
| Corbeille | POST /trash · POST /restore · POST /purge |
| Contenu | GET /files/:id/content (Range, If-Range, ETag = SHA-256) · GET /files/:id/preview/thumb |
| Versions | POST /files/:id/versions/:v/restore · DELETE /files/:id/versions/:v |
| Envois | POST /uploads · GET /uploads/:id · PATCH /uploads/:id?offset= · PATCH /uploads/:id/options · POST /uploads/:id/complete · DELETE /uploads/:id |
| Liens de partage | GET /shares · POST /shares · PATCH /shares/:id · DELETE /shares/:id · POST /shares/:id/rotate · GET /shares/:id/events |
| Liens de dépôt | GET /requests · POST /requests · PATCH /requests/:id · DELETE /requests/:id · POST /requests/:id/rotate · GET /requests/:id/submissions · GET /submissions/:id |
| Notifications | GET /notifications · POST /notifications/read |
📱 Écrans
Les 9 sections de la navigation (Features/Home/RootView.swift) : barre d'onglets sur iPhone, barre latérale sur iPad.
| Section | Fichier | Contenu |
|---|---|---|
| Mon Drive | Features/MyDrive/FolderScreen.swift (+ ItemViews, ItemActions, ItemDetailsView, FolderPicker, Importers, Thumbnails, FilePreview) |
explorateur, détails et versions, import, aperçu, éditeur de texte |
| Récents | Features/Recent/RecentScreen.swift |
fichiers récents |
| Partagés | Features/Shared/SharedScreen.swift (+ ShareLinkEditor, DepositLinkEditor) |
liens de partage et de dépôt que l'on a créés |
| Favoris | Features/Recent/RecentScreen.swift (FavoritesScreen) |
éléments marqués d'une étoile |
| Hors ligne | Features/Offline/OfflineScreen.swift |
fichiers et dossiers gardés hors ligne |
| Transferts | Features/Transfers/TransfersScreen.swift |
file, pause, reprise, annulation |
| Corbeille | Features/Trash/TrashScreen.swift |
restaurer, purger, vider |
| Conflits et problèmes | Features/Settings/ProblemsScreen.swift |
résolution des conflits |
| Paramètres | Features/Settings/SettingsScreen.swift, StorageScreen.swift, Features/Account/AccountScreen.swift |
stockage, compte, appareils, verrou, notifications |
Hors section : connexion (Features/Account/SignInView.swift — passkey ou liaison par code) et recherche
(Features/Search/SearchScreen.swift).
L'onglet « Partagés » liste les liens que l'on a créés : le partage entre comptes n'existe pas côté serveur.
💾 Modèle de données local
Core/Persistence/DriveStore.swift crée 8 tables (migration unique, PRAGMA user_version = 1). L'extension File
Provider utilise le même schéma dans sa propre base.
| Table | Clé | Rôle |
|---|---|---|
items |
id |
miroir des fichiers et dossiers du serveur : parent, nom, clé de nom, taille, SHA-256, version, rev, corbeille, favori, état d'analyse, vignette, extension |
local_state |
item_id |
état local d'un élément : épinglé, emplacement, empreinte et version de base, taille locale, modifié (dirty), dates |
ops |
id auto |
journal des opérations faites hors ligne : type, cible, nom, état, essais, code d'erreur |
transfers |
id |
file des transferts : sens, taille, progression, état, priorité, identifiant d'envoi, chemin local, empreinte |
conflicts |
id auto |
conflits détectés : élément, nom, raison, envoi concerné |
tombstones |
id |
suppressions connues, par révision |
recent_searches |
text |
recherches récentes |
meta |
key |
curseur de synchronisation et autres valeurs |
erDiagram
items ||--o| local_state : "copie locale"
items ||--o{ ops : "opérations en attente"
items ||--o{ transfers : "transferts"
items ||--o{ conflicts : "conflits"
ops ||--o{ transfers : "op_id"
items {
TEXT id PK
INTEGER is_folder
TEXT parent_id
TEXT name
TEXT sha256
TEXT version_id
INTEGER rev
REAL trashed_at
INTEGER starred
}
local_state {
TEXT item_id PK
INTEGER pinned
TEXT base_sha
TEXT base_version_id
INTEGER dirty
}
ops {
INTEGER id PK
TEXT kind
TEXT item_id
TEXT state
INTEGER attempts
}
transfers {
TEXT id PK
TEXT kind
TEXT item_id
INTEGER op_id
TEXT state
INTEGER priority
TEXT upload_id
}
conflicts {
INTEGER id PK
TEXT item_id
TEXT reason
TEXT upload_id
}
Index : items_parent, items_name, items_updated, items_rev, transfers_state, tombstones_rev.
🔒 Sécurité et confidentialité
- Connexion : passkey native (domaine associé
webcredentials:drive.spboucher.ai) ; en secours, liaison par code approuvée dans un navigateur. - Session d'appareil : jeton
Bearerrangé dans le trousseau, dans un groupe partagé avec les deux extensions ; révocable depuis la liste des appareils connectés. - Verrou Face ID / Touch ID optionnel.
- Chiffrement : TLS en transit, chiffrement au repos côté serveur, protection des fichiers iOS sur l'appareil. Ce n'est pas du chiffrement de bout en bout : le serveur détient les clés, et l'app ne prétend pas autre chose.
- Intégrité : chaque bloc envoyé porte son SHA-256, le serveur vérifie celui du fichier entier ; un téléchargement est vérifié avant d'être installé — un fichier partiel de bonne taille mais au contenu faux n'est jamais installé.
- Photos : sélecteur système, aucun accès global à la photothèque.
- Release :
release.sh archiverefuse une archive qui contiendrait un commutateur de test ou qui autoriserait le réseau local ; il affiche les droits de l'app et de chaque extension. - Isolation : aucune base n'est ouverte par deux processus.
| Autorisation | Texte affiché |
|---|---|
| Face ID | « SP Drive utilise Face ID pour déverrouiller tes fichiers sur cet appareil. » |
| Appareil photo | « SP Drive utilise l'appareil photo pour prendre une photo ou numériser un document et l'envoyer dans ton Drive. » |
Chaque cible (app, File Provider, partage) embarque son PrivacyInfo.xcprivacy.
🧪 Tests
« Vérifié » = commande exécutée, résultat observé. Aucun résultat n'est simulé : les tests parlent à un vrai backend
SP Drive (clone jetable de la branche native-clients, PostgreSQL réel, m5ma:8663), jamais à un double.
| Suite | Commande | Où | Résultat (2026-11-18) |
|---|---|---|---|
| Moteur (Core + Sync) | Scripts/build.sh core |
Mac, 2 à 3 « appareils » simulés (base et stockage séparés) | 12 / 12 |
| Tests hébergés dans l'app | Scripts/build.sh test |
simulateur iPhone | 6 / 6 (1 File Provider + 5 unitaires) |
| Interface iPhone | Scripts/build.sh uitest |
« SPDrive iPhone » (iPhone 17 Pro, iOS 27.2) | 4 / 4 |
| Interface iPad | SPDRIVE_SIM="SPDrive iPad" Scripts/build.sh uitest |
« SPDrive iPad » (iPad Pro 11 po) | 4 / 4 (3 dans la suite complète ; le test Fichiers relancé seul après correction du test) |
| Build Release + signature | Scripts/release.sh archive |
appareil générique | archive produite, droits vérifiés |
| Validation Apple | Scripts/release.sh export puis validate |
App Store Connect | « VERIFY SUCCEEDED with no errors » |
| Envoi TestFlight | Scripts/release.sh upload |
App Store Connect | 1.0.0 (1) VALID, en test interne |
Les 12 tests du moteur — KitTests/SyncTests.swift
- Session d'appareil et dossier racine.
- Créer, renommer, déplacer, mettre en favori, corbeille, restauration : visibles tout de suite en local, puis sur le serveur et sur un deuxième appareil.
- Noms : doublon refusé, nom invalide refusé (
../…), nom libre choisi à la création. - Envoi puis téléchargement sur un autre appareil, empreinte SHA-256 identique, copie réutilisée sans nouveau transfert.
- Fichier de 20 Mio en trois blocs, deuxième bloc coupé deux fois : reprise au décalage du serveur ; téléchargement
coupé puis repris ; reprise
Rangeà partir d'un fichier partiel de 11 Mo. - Intégrité : un fichier partiel de bonne taille mais au contenu faux n'est jamais installé ; le vrai contenu est récupéré.
- Hors ligne + redémarrage + reconnexion : fichier gardé hors ligne modifié, dossier créé, fichier ajouté dedans, dossier renommé, le tout sans réseau ; nouvelle instance du moteur sur le même stockage ; retour du réseau ; tout est sur le serveur, l'ancienne version reste dans l'historique.
- Conflits : même fichier modifié hors ligne ici et en ligne ailleurs, trois fois ; rien n'est écrasé ; « garder les deux » (copie « (conflit …) »), « garder la mienne » (3 versions sur le serveur), « garder celle du serveur ».
- Modifié ici, supprimé définitivement ailleurs : la modification est conservée, puis renvoyée comme nouveau fichier.
- Dossier gardé hors ligne : nouveaux fichiers et nouvelles versions récupérés seuls ; lecture hors ligne ; libérer l'espace ne supprime rien sur le Drive.
- Annulation d'un envoi jamais parti, cache vidé sans toucher au Drive, pause et reprise d'un téléchargement.
- Recherche locale hors ligne (accents, type, extension, taille, caractères
%et_littéraux) et recherche serveur.
File Provider — Tests/FileProviderTests.swift. Par le système de fichiers du domaine, avec coordination de
fichiers, comme le fait une app tierce ; chaque effet est vérifié sur le serveur par un second client : domaine
enregistré, listage, téléchargement à la demande (contenu identique), document créé par une autre app envoyé,
modification devenue nouvelle version (l'ancienne dans l'historique), renommage, changement distant visible,
suppression = corbeille du Drive. Tests/WebAuthnTests.swift ajoute 5 tests unitaires (base64url, options d'assertion et d'enregistrement lues du JSON du serveur, forme de la réponse d'assertion, noms de fichiers qui ne sortent jamais de leur dossier).
Interface — UITests/DriveUITests.swift (4 tests) :
| Test | Parcours |
|---|---|
testSignedOutShowsPasskeyAndDeviceLink |
écran de connexion ; liaison par code (le code vient du vrai serveur) |
testExplorerEndToEnd |
première synchronisation, création d'un dossier (vérifiée sur le serveur), ouverture dans QuickLook, renommage, favori, « garder hors ligne », grille, lien de partage réel, relance de l'app (l'état local et l'épinglage survivent), écrans Hors ligne, Favoris, Partagés, Transferts, Paramètres |
testTrashRestoreAndSearch |
corbeille (vérifiée sur le serveur), restauration, recherche insensible aux accents |
testFilesAppShowsSPDriveLocation |
app Fichiers : SP Drive figure dans les emplacements ; son contenu est listé par l'extension |
Captures : build/shots/<simulateur>/.
Scénario de validation du cahier des charges (15 étapes)
| # | Étape | État |
|---|---|---|
| 1 | Installer sur un iPhone | Non fait : aucun iPhone n'était branché. Build disponible sur TestFlight. |
| 2 | Se connecter | Passkey : non vérifié sur appareil. Code écrit, association de domaine en production, encodage testé. Liaison par code : vérifiée jusqu'à l'affichage du code réel. |
| 3 | SP Drive dans Fichiers | Vérifié sur simulateurs iPhone et iPad. |
| 4 | Ouvrir un dossier distant | Vérifié (app et Fichiers). |
| 5 | Télécharger un fichier | Vérifié (app ; à la demande dans Fichiers). |
| 6 | Marquer hors ligne | Vérifié. |
| 7 | Mode avion | Non vérifié sur appareil. Équivalent testé : réseau coupé au niveau des requêtes dans les tests du moteur. |
| 8–10 | Ouvrir, modifier, enregistrer hors ligne | Moteur : vérifié. Édition par QuickLook ou par une app tierce via Fichiers hors ligne : non vérifié sur appareil. |
| 11–12 | Redémarrer, modifications conservées | Moteur : vérifié par relance sur le même stockage. Redémarrage réel d'un iPhone : non fait. |
| 13–15 | Reconnexion, synchronisation, aucune perte | Moteur : vérifié. Appareil réel : non fait. |
📦 Publication
Distribution TestFlight (App Store Connect).
# incrémenter CURRENT_PROJECT_VERSION dans project.yml, puis :
Scripts/release.sh archive # archive Release, affiche les droits, contrôle « aucun commutateur de test, ATS strict »
Scripts/release.sh export # IPA (Scripts/ExportOptions.plist)
Scripts/release.sh validate # validation par Apple
Scripts/release.sh upload # envoi à TestFlight| Élément | Valeur |
|---|---|
| Équipe | 3YM54G49SN |
| Signature | automatique ; l'archive est signée avec le compte Apple ID configuré dans Xcode (les groupes d'apps ne se provisionnent pas avec une clé d'API App Store Connect) |
| Clé d'API App Store Connect | utilisée pour l'export, la validation et l'envoi ; le fichier reste hors dépôt |
| Fiche | 6836524538, SKU spdrive-ios-001 |
| État | 1.0.0 (1) VALID, test interne TestFlight (2026-11-18) |
🛰 Backend
L'app ne modifie rien sur le serveur. Elle utilise l'API « clients natifs » de
sp-drive (branche native-clients, en production depuis le 2026-11-18), écrite par
la session qui construit SP Drive macOS. Toute évolution du serveur passe par le dépôt sp-drive sur son nœud (m5ma,
port 8660, PM2 via l'orchestrateur mld, exposition par le MacLustr Tunnel), pas par ce projet.
Ce que l'audit du backend a établi (2026-11-18)
| Sujet | Constat vérifié |
|---|---|
| Pile | Fastify 5 + PostgreSQL 17 + worker (antivirus ClamAV, aperçus), SPA React servie par l'API, PM2 via mld. |
| Stockage | Objets chiffrés au repos (AES-256-GCM par blocs, clé par objet enveloppée par une clé maîtresse sur le nœud). TLS jusqu'à la passerelle, WireGuard ensuite. Pas de chiffrement de bout en bout. |
| Arborescence | folders / files par propriétaire, identifiants UUID stables, unicité des noms par dossier (NFC + minuscules), corbeille logique (trashed_at, trash_root), purge définitive séparée. |
| Versions | file_versions numérotées ; restaurer crée une nouvelle version ; la version courante ne se supprime pas. |
| Envoi | Protocole résumable : POST /uploads → PATCH /uploads/:id?offset= (blocs ≤ 16 Mio, X-Chunk-SHA256) → POST /uploads/:id/complete (SHA-256 du fichier vérifié par le serveur). Décalage refusé = le serveur renvoie le décalage réel. |
| Téléchargement | GET /files/:id/content avec Range, If-Range et ETag = SHA-256. |
| Authentification | Passkeys WebAuthn uniquement (RP drive.spboucher.ai), comptes sur invitation. Web : cookie de session + en-tête CSRF. |
| Partage | Liens de partage (fichier ou dossier, lecture seule ou téléchargement, mot de passe, expiration, plafonds, usage unique, rotation, révocation immédiate, journal d'accès). Jeton montré une seule fois. |
| Liens de dépôt | « Portails » : le déposant n'obtient qu'un jeton de soumission. Quarantaine → antivirus → placement dans le dossier cible. Limites réévaluées à chaque bloc. |
| Partage entre comptes | N'existe pas côté serveur. |
| Recherche | Par nom (insensible aux accents), type, favoris, dates, taille. Pas de plein texte. |
Ajouts faits pour les clients natifs (branche native-clients, migration 002_native_clients) :
| Besoin | Ajout |
|---|---|
| Passkeys natives | /.well-known/apple-app-site-association (webcredentials, App ID de l'app iOS inclus). |
| Session d'appareil | POST /auth/login/verify avec client: {kind: "native"} → jeton Bearer, jamais tourné, durée glissante (400 jours repoussés à chaque usage, fermé après 90 jours de silence), révocable dans la liste des sessions. |
| Connexion de secours | Liaison par code (/auth/device/start, /auth/device/poll, approbation dans un navigateur sur /appareil). |
| Synchronisation incrémentale | Colonne rev monotone par propriétaire + pierres tombales ; GET /sync/changes?since=, GET /sync/cursor, POST /sync/items. |
| Conflits | baseVersionId à la création d'un envoi → 409 version_conflict ; PATCH /uploads/:id/options {asNewFile} transforme l'envoi refusé en copie de conflit sans renvoyer les octets. |
SPDriveCore (app macOS) — état de la réutilisation, sans l'embellir. L'app iOS ne lie pas encore les paquets
SPDriveCore / SPDriveSync de sp-drive-macos. Les deux implémentations
parlent la même API mais ne partagent pas de code aujourd'hui. Le point de raccord prévu est un adaptateur
DriveRemote → APIClient de SPDriveCore ; il reste à écrire.
📊 Parité web, macOS, iPhone, iPad
✔ = présent et vérifié ; ◐ = présent, vérification partielle ; ✘ = absent ; — = sans objet ; ? = fonction de l'app
macOS non vérifiée par cette session. Source : docs/AUDIT.md.
Matrice complète
| Fonction | Web | macOS | iPhone | iPad |
|---|---|---|---|---|
| Parcourir dossiers et fichiers | ✔ | ✔ | ✔ | ✔ |
| Liste / grille, tri, filtres | ✔ | ✔ | ✔ | ✔ |
| Créer, renommer, déplacer, dupliquer | ✔ | ✔ | ✔ | ✔ |
| Envoi résumable par blocs + SHA-256 | ✔ | ✔ | ✔ | ✔ |
Téléchargement avec reprise (Range) + vérification |
✔ (navigateur) | ✔ | ✔ | ✔ |
| Transferts en arrière-plan (URLSession background) | — | — | ◐ (jamais observé sur appareil réel) | ◐ |
| Hors ligne : fichiers et dossiers gardés, modifications différées | ✘ | ✔ | ✔ | ✔ |
| Synchronisation incrémentale bidirectionnelle | — | ✔ | ✔ | ✔ |
| Conflits sans écrasement + interface de résolution | ✘ (versions seulement) | ✔ | ✔ | ✔ |
| Intégration au système de fichiers | — | ◐ Finder | ✔ app Fichiers (simulateur) | ✔ app Fichiers (simulateur) |
| Aperçus | ✔ pdf.js etc. | ✔ | ✔ QuickLook | ✔ |
| Modification depuis l'app | ✘ | ◐ | ✔ annotations QuickLook, éditeur de texte | ✔ |
| Liens de partage (création, réglages, rotation, révocation, journal) | ✔ | ✔ | ✔ | ✔ |
| Liens de dépôt (création, limites, soumissions) | ✔ | ✔ | ✔ | ✔ |
| Formulaire de dépôt personnalisé (champs, consentement, marque) | ✔ | ? | ✘ (réglages essentiels seulement) | ✘ |
| Versions : liste, téléchargement, restauration, suppression | ✔ | ✔ | ✔ | ✔ |
| Corbeille : restaurer, purger, vider | ✔ | ✔ | ✔ | ✔ |
| Recherche serveur | ✔ | ✔ | ✔ | ✔ |
| Recherche hors ligne (index local) | ✘ | ✔ | ✔ | ✔ |
| Favoris, récents | ✔ | ✔ | ✔ | ✔ |
| Tags | ✔ | ? | ✘ | ✘ |
| Doublons | ✔ | ? | ✘ | ✘ |
| Passkey | ✔ | ✔ | ◐ (code + AASA en production ; jamais exécuté sur un appareil réel) | ◐ |
| Verrou biométrique de l'app | — | ? | ◐ (jamais exécuté sur un appareil réel) | ◐ |
| Import Photos / appareil photo / numériseur / feuille de partage | ◐ (navigateur) | — | ◐ (sélecteurs système : non pilotables en test) | ◐ |
| Glisser-déposer, clavier matériel, multifenêtre | ✔ (bureau) | ✔ | — | ◐ (non testé automatiquement) |
| Administration (utilisateurs, quotas, invitations), TOTP, codes de récupération, création de compte | ✔ | ? | ✘ (reste sur le web) | ✘ |
| Notifications | dans l'app | ? | locales ; pas de push APNs | idem |
🩺 Pièges connus
- Première utilisation dans Fichiers : iOS demande une fois « Activer SP Drive ? » à l'ouverture de l'emplacement. Tant que ce n'est pas fait, l'extension répond « La synchronisation n'est pas activée » (erreur -2011) et rien n'est listé. Les tests appuient sur « Activer ».
- Groupes d'apps et signature : l'archive doit être signée avec le compte Apple ID de Xcode ; la clé d'API App Store Connect ne peut pas provisionner un groupe d'apps.
- Tests d'interface lents (10 min pour le parcours complet) : avec un menu contextuel ouvert, l'app n'est jamais « au repos » pour XCTest, qui attend 60 s à chaque fois. Cause non élucidée (probablement l'animation du menu système).
- Compte de test vidé par chaque test d'interface (corbeille puis purge) : ne jamais pointer ces tests vers la
production (
Scripts/build.shn'utilise que le backend jetable). - Backend de test injoignable :
Scripts/build.sh tests'arrête avec « test backend unreachable » →Scripts/test-server.sh up(outunnelsi seul le tunnel est tombé). - pnpm sur le nœud de test :
pnpm installpeut sortir en erreur sur le script de build ignoré d'esbuild ;test-server.shle tolère (tsx fonctionne sans). - Tunnel SSH : il utilise sa propre connexion (pas de
ControlMasterpartagé, qui fermerait la redirection à son expiration). Info-Debug.plist: générés, non versionnés ;release.shrefuse une archive Release où le réseau local serait autorisé.
🚧 Reste à faire et limites connues
Construit, non vérifié
- Tout ce qui demande un appareil réel : passkey + Face ID, verrou biométrique, mode avion, redémarrage, transferts pendant que l'app est suspendue ou tuée (URLSession background), comportement de Fichiers hors ligne (file d'attente du système), mémoire de l'extension sur de très gros fichiers.
- Sélecteurs système (non pilotables par les tests) : import Photos, appareil photo, numériseur, sélecteur Fichiers, extension de partage (compile et s'installe ; jamais exécutée de bout en bout).
- Écrans exercés seulement en partie par les tests : détails et versions d'un fichier, liens de dépôt (création, soumissions), conflits et problèmes, stockage, compte et appareils, éditeur de texte, sélection multiple, déplacement par sélecteur de dossier.
- iPad : glisser-déposer entre apps, clavier matériel, multifenêtre ; le test File Provider par le système de fichiers n'a été exécuté que sur le simulateur iPhone.
- Performance : aucun profilage Instruments ; jamais essayé avec des milliers de fichiers (les listes sont paginées côté base et paresseuses côté interface, sans mesure).
- Notifications : jamais observées (l'autorisation système n'est pas accordée dans les tests).
Non fait
- Liaison du paquet
SPDriveCorede l'app macOS. - Tags, doublons, administration, formulaire de dépôt personnalisé, création de compte par invitation, TOTP et codes de récupération : restent sur le web.
- Notifications push (APNs) ; l'app sonde le serveur quand iOS lui donne la main.
- Anglais (interface en français seulement).
- Glisser un dossier entier depuis une autre app fonctionne par code mais n'a pas été essayé.
👤 Auteur
Simon-Pierre Boucher — conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 Licence
Logiciel privé. Tous droits réservés © 2026 Simon-Pierre Boucher.