SPB Git

Repository Public

README.md 51.4 KB

SP Drive logo



SP Drive icon

# 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

drive.spboucher.ai version plateforme langue licence author

Swift SwiftUI File Provider Share Extension SQLite URLSession Passkeys QuickLook PDFKit Swift Package XcodeGen dépendances

commits last commit activity language languages size branches tags clones

fichiers Swift lignes Swift cibles opérations API tables locales sections tests moteur tests hébergés tests d'interface blocs

bundle groupe d'apps signature TestFlight App Store Connect backend


# Sommaire


# 🚀 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 avec SPDriveCore de 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

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

bash
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 generate crée aussi les Info-Debug.plist (réseau local autorisé pour joindre le backend de test par tunnel — jamais en Release, release.sh le vérifie). SPDrive.xcodeproj et les Info-Debug.plist ne sont pas versionnés.
  • Simulateurs dédiés : « SPDrive iPhone » (défaut) et « SPDrive iPad » ; SPDRIVE_SIM choisit.
  • 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_VERSION avant 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 Bearer rangé 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 archive refuse 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
  1. Session d'appareil et dossier racine.
  2. 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.
  3. Noms : doublon refusé, nom invalide refusé (../…), nom libre choisi à la création.
  4. Envoi puis téléchargement sur un autre appareil, empreinte SHA-256 identique, copie réutilisée sans nouveau transfert.
  5. 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.
  6. Intégrité : un fichier partiel de bonne taille mais au contenu faux n'est jamais installé ; le vrai contenu est récupéré.
  7. 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.
  8. 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 ».
  9. Modifié ici, supprimé définitivement ailleurs : la modification est conservée, puis renvoyée comme nouveau fichier.
  10. 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.
  11. Annulation d'un envoi jamais parti, cache vidé sans toucher au Drive, pause et reprise d'un téléchargement.
  12. 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).

bash
# 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.sh n'utilise que le backend jetable).
  • Backend de test injoignable : Scripts/build.sh test s'arrête avec « test backend unreachable » → Scripts/test-server.sh up (ou tunnel si seul le tunnel est tombé).
  • pnpm sur le nœud de test : pnpm install peut sortir en erreur sur le script de build ignoré d'esbuild ; test-server.sh le tolère (tsx fonctionne sans).
  • Tunnel SSH : il utilise sa propre connexion (pas de ControlMaster partagé, qui fermerait la redirection à son expiration).
  • Info-Debug.plist : générés, non versionnés ; release.sh refuse 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 SPDriveCore de 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.

Files main
Menu

Theme