SPB Git

Repository Public

README.md 39.3 KB 612 lines markdown

1<!--2SP Drive — macOS3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7<div align="center">89<img src="docs/brand/logo.svg" alt="Logo de SP Drive pour macOS" width="560">1011<br><br>1213<img src="docs/brand/icon.png" alt="Icône de SP Drive pour macOS" width="112" height="112">1415# SP Drive pour macOS1617**Le client macOS natif de drive.spboucher.ai, le stockage privé du cluster MacLustr : un emplacement dans le18Finder (File Provider répliqué), une application SwiftUI, un moteur de synchronisation et de transferts vérifiés19écrit en Swift. Aucun WebView, aucun moteur web, aucune dépendance tierce.**2021**Auteur : [Simon-Pierre Boucher](https://www.spboucher.ai)**2223[![serveur](https://img.shields.io/website?url=https%3A%2F%2Fdrive.spboucher.ai&label=serveur%20drive.spboucher.ai&style=for-the-badge&up_message=en%20ligne&down_message=hors%20ligne)](https://drive.spboucher.ai)24![version](https://img.shields.io/badge/version-2.0.0%20(3)%20·%20branche%20next-6a3df0?style=for-the-badge)25![plateforme](https://img.shields.io/badge/plateforme-macOS%2014%2B%20%C2%B7%20universelle-000000?style=for-the-badge&logo=apple&logoColor=white)26![licence](https://img.shields.io/badge/licence-tous%20droits%20r%C3%A9serv%C3%A9s-lightgrey?style=for-the-badge)27![author](https://img.shields.io/badge/author-Simon--Pierre%20Boucher-0A66C2?style=for-the-badge)2829![Swift](https://img.shields.io/badge/Swift-6.0%20%C2%B7%20concurrence%20stricte-F05138?style=flat-square&logo=swift&logoColor=white)30![SwiftUI](https://img.shields.io/badge/SwiftUI-%40Observable-0D96F6?style=flat-square&logo=swift&logoColor=white)31![AppKit](https://img.shields.io/badge/AppKit-l%C3%A0%20o%C3%B9%20il%20le%20faut-1575F9?style=flat-square&logo=apple&logoColor=white)32![File Provider](https://img.shields.io/badge/File%20Provider-extension%20r%C3%A9pliqu%C3%A9e-6f7dff?style=flat-square&logo=apple&logoColor=white)33![SQLite](https://img.shields.io/badge/SQLite-miroir%20%C2%B7%209%20tables-003B57?style=flat-square&logo=sqlite&logoColor=white)34![AuthenticationServices](https://img.shields.io/badge/AuthenticationServices-passkeys-3423A6?style=flat-square&logo=webauthn&logoColor=white)35![SHA-256](https://img.shields.io/badge/int%C3%A9grit%C3%A9-SHA--256%20par%20bloc%20et%20par%20fichier-2E7D32?style=flat-square)36![SwiftPM](https://img.shields.io/badge/SwiftPM-SPDriveCore%20%C2%B7%20SPDriveSync-F05138?style=flat-square&logo=swift&logoColor=white)37![XcodeGen](https://img.shields.io/badge/XcodeGen-project.yml-1575F9?style=flat-square&logo=xcode&logoColor=white)38![dépendances](https://img.shields.io/badge/d%C3%A9pendances%20tierces-0-brightgreen?style=flat-square)39![WebView](https://img.shields.io/badge/WebView-aucun-brightgreen?style=flat-square)4041[![commits](https://git.spboucher.ai/badge/sp-drive-macos/commits.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos/commits)42[![last commit](https://git.spboucher.ai/badge/sp-drive-macos/last-commit.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos/commits)43[![activity](https://git.spboucher.ai/badge/sp-drive-macos/activity.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos/insights)44[![language](https://git.spboucher.ai/badge/sp-drive-macos/language.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos)45[![languages](https://git.spboucher.ai/badge/sp-drive-macos/languages.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos/insights)46[![size](https://git.spboucher.ai/badge/sp-drive-macos/size.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos)47[![branches](https://git.spboucher.ai/badge/sp-drive-macos/branches.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos/branches)48[![tags](https://git.spboucher.ai/badge/sp-drive-macos/tags.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos/tags)49[![clones](https://git.spboucher.ai/badge/sp-drive-macos/clones.svg?style=flat-square)](https://git.spboucher.ai/sp-drive-macos)5051![fichiers Swift](https://img.shields.io/badge/fichiers%20Swift-55-informational?style=flat-square)52![lignes Swift](https://img.shields.io/badge/lignes%20Swift-6%20927-informational?style=flat-square)53![sections](https://img.shields.io/badge/sections%20de%20la%20barre%20lat%C3%A9rale-11-blue?style=flat-square)54![écrans](https://img.shields.io/badge/%C3%A9crans%20et%20feuilles-22-blue?style=flat-square)55![tests unitaires](https://img.shields.io/badge/tests%20unitaires-15-brightgreen?style=flat-square)56![tests d'intégration](https://img.shields.io/badge/tests%20d'int%C3%A9gration-27%20%C2%B7%20vrai%20backend-brightgreen?style=flat-square)57![auto-vérification](https://img.shields.io/badge/auto--v%C3%A9rification%20de%20l'app%20sign%C3%A9e-19-brightgreen?style=flat-square)58![scénario Finder](https://img.shields.io/badge/sc%C3%A9nario%20Finder-22%20%2F%2022-brightgreen?style=flat-square)59![contrôles](https://img.shields.io/badge/contr%C3%B4les%20de%20distribution-32-brightgreen?style=flat-square)6061![bundle](https://img.shields.io/badge/bundle-ai.spboucher.spdrive-555555?style=flat-square&logo=apple&logoColor=white)62![extension](https://img.shields.io/badge/extension-ai.spboucher.spdrive.fileprovider-555555?style=flat-square&logo=apple&logoColor=white)63![signature](https://img.shields.io/badge/signature-Developer%20ID%20Application-000000?style=flat-square&logo=apple&logoColor=white)64![notarisation](https://img.shields.io/badge/notarisation-accept%C3%A9e%20%C2%B7%20agraf%C3%A9e-brightgreen?style=flat-square)65![sandbox](https://img.shields.io/badge/App%20Sandbox-oui-brightgreen?style=flat-square)66![runtime durci](https://img.shields.io/badge/runtime%20durci-oui-brightgreen?style=flat-square)67![cible](https://img.shields.io/badge/cible%20de%20d%C3%A9ploiement-macOS%2014.0-informational?style=flat-square)6869</div>7071---7273## Sommaire7475- [Aperçu](#-aperçu)76- [Fonctions](#-fonctions)77- [Architecture](#-architecture)78- [Pile technique](#-pile-technique)79- [Organisation du dépôt](#-organisation-du-dépôt)80- [Construire et lancer](#-construire-et-lancer)81- [Configuration](#-configuration)82- [Écrans](#-écrans)83- [Modèle de données local](#-modèle-de-données-local)84- [Sécurité et confidentialité](#-sécurité-et-confidentialité)85- [Tests](#-tests)86- [Distribution](#-distribution)87- [À savoir et dépannage](#-à-savoir-et-dépannage)88- [Limites connues](#-limites-connues)89- [Documentation](#-documentation)90- [Auteur](#-auteur)91- [Licence](#-licence)9293---9495## 🚀 SP Drive 2.0 — état de la branche `next` (2026-11-19)9697> **Non livrée.** La version distribuée et notarisée reste la 1.0.0 (`main`, étiquette `v1.0.0`). La branche `next` porte la98> 2.0.0 (3) : construite en Release, signée Developer ID et vérifiée (`Scripts/verify-release.sh` : 32 contrôles, 0 échec),99> **ni notarisée, ni installée, ni étiquetée**. Le reste de ce README décrit la 1.0 et reste vrai pour ce qu'il couvre ;100> l'état exact de la 2.0, fonction par fonction, est dans [`docs/next/AUDIT-macOS.md`](docs/next/AUDIT-macOS.md).101102| | 2.0 |103|---|---|104| Serveur | SP Drive 2.0 (`sp-drive.git`, branche `next`) ; face à un serveur 1.0 l'app masque ce qu'il n'offre pas (`GET /meta`) |105| Nouveau paquet | **`SPDriveNext`** (`Next/`, Foundation seulement, macOS 14 + iOS 17) : tout ce que l'API 2.0 ajoute, partagé avec l'app iOS |106| Synchronisation | flux d'événements du serveur (SSE) branché sur le moteur, repli sur un sondage de 30 s, reprise après coupure ; concurrence adaptative 1–6, priorités, reprise après `SIGKILL`, économie d'énergie |107| Interface | système de design v2 (`docs/next/DESIGN-SYSTEM-V2.md`), grille à vraies vignettes, inspecteur, palette de commandes ⌘K, plusieurs fenêtres, Coup d'œil, glisser-déposer entrant et sortant, centre de transferts, Command Center de la barre de menus |108| Recherche | noms **et contenu** des documents (passages surlignés), recherche par le sens quand le serveur a son modèle |109| SP Drive AI | questions à un document, un dossier ou tout le Drive ; réponse en flux avec sources numérotées ; choix du modèle ; suggestions de rangement à confirmer ligne par ligne. **Aucun vrai modèle n'a été exercé** : les essais utilisent un faux fournisseur local |110| Organisation | collections intelligentes (règles), activité, versions en frise avec comparaison, centre de stockage (types, dossiers, croissance, doublons) |111| Partage | membres et rôles sur un dossier, espaces de travail, « Partagés avec moi », code QR des liens, portails de dépôt complets |112| Compte | appareils connectés (plateforme, version), consentement aux fournisseurs d'IA externes, vue d'administration pour les administrateurs |113| Finder | état « partagé », pastilles, actions du menu contextuel (déclarées et évaluées par le système ; **exécution non vérifiée**) |114| Langue | français seulement (pas de localisation anglaise, en 1.0 comme en 2.0) |115116Essais du 2026-11-19 sur le code final (variante de test, backend 2.0 local @ 0073557, celui de la production) : paquets117Swift **75 / 75** (61 + 14 pour `SPDriveNext`), auto-vérification de l'app **75 / 75** deux fois de suite depuis une118liaison d'appareil neuve (dont 11 contrôles « à l'écran » qui pressent les vrais boutons par l'API d'accessibilité),119scénario Finder **22 / 22**, tournée de 34 écrans sans plantage. Captures de la120fenêtre : [`docs/next/shots/`](docs/next/shots/).121122## 🎯 Aperçu123124Client macOS **natif** de [drive.spboucher.ai](https://drive.spboucher.ai) (stockage privé sur le cluster MacLustr) :125Swift 6, SwiftUI/AppKit, extension File Provider pour le Finder, moteur de synchronisation et de transferts en Swift.126Aucun WebView, aucun moteur web, aucune dépendance tierce.127128| | |129|---|---|130| Application | `ai.spboucher.spdrive` — macOS 14+, universelle (arm64 + x86_64), App Sandbox, runtime durci |131| Extension Finder | `ai.spboucher.spdrive.fileprovider` (File Provider répliqué) |132| Serveur | https://drive.spboucher.ai (dépôt `sp-drive.git`, nœud m5ma) — routes pour clients natifs ajoutées le 2026-11-18 |133| Paquets Swift | `SPDriveCore` (`Core/`) et `SPDriveSync` (`Sync/`), aussi liés par l'app iOS |134| Version | 1.0.0 (1), étiquette `v1.0.0`, signée Developer ID et notarisée |135136État réel, fonction par fonction : [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md). Preuves et limites :137[`docs/TEST_REPORT.md`](docs/TEST_REPORT.md). Conception : [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).138139### Famille140141| App | Plateforme | Dépôt | Rôle |142|---|---|---|---|143| **SP Drive** | Web + API — `drive.spboucher.ai` | [git.spboucher.ai/sp-drive](https://git.spboucher.ai/sp-drive) | Serveur (Fastify + PostgreSQL), site, stockage chiffré au repos, partage, portails de dépôt |144| **SP Drive pour macOS** (ce dépôt) | macOS 14+ natif | [git.spboucher.ai/sp-drive-macos](https://git.spboucher.ai/sp-drive-macos) | Application, extension Finder, paquets `SPDriveCore` et `SPDriveSync` |145| **SP Drive pour iOS / iPadOS** | iOS · iPadOS natif | [git.spboucher.ai/sp-drive-ios](https://git.spboucher.ai/sp-drive-ios) | Client natif iPhone et iPad (File Provider, hors ligne) |146147---148149## ✨ Fonctions150151Légende de la colonne « Vérifié » (celle de [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md)) : **T** = tests Swift152contre le vrai backend local, **A** = auto-vérification de l'app signée, **V** = écran vu dans la tournée,153**F** = scénario par le Finder. « Non vérifié » est écrit en toutes lettres.154155### Repris du site156157| Fonction | Client macOS | Vérifié |158|---|---|---|159| **Connexion par passkey** | Feuille système (`webcredentials`) | Serveur : T. Touch ID réel contre la production : constaté par le propriétaire |160| **Sessions, révocation d'appareil** | Paramètres › Compte | T |161| **Parcourir dossiers et fichiers** | Liste, grille, fil d'Ariane | T, A, V |162| **Créer un dossier, renommer, déplacer, dupliquer** | Oui, hors ligne aussi | T, A |163| **Favoris** | Oui | T, A |164| **Téléverser** (résumable, blocs + SHA-256) | File persistante, blocs adaptatifs | T (48 Mo, coupure, panne serveur), A |165| **Téléverser un dossier** | Glisser-déposer, sélecteur | Non vérifié de bout en bout |166| **Télécharger** (`Range`) | Reprise, vérification SHA-256, placement atomique | T, A |167| **Aperçu** | Coup d'œil natif sur copie vérifiée | Copie locale : A. Panneau Coup d'œil : non vérifié à l'écran |168| **Vignettes** | Dans le Finder (File Provider) | Non vérifié |169| **Corbeille, restauration, purge** | Purge après confirmation, en ligne seulement | T, A |170| **Versions** : liste, téléchargement, restauration, suppression | Oui | T, A, V |171| **Recherche** (nom, type, dates, tailles, favoris) | Locale, hors ligne (+ extension, dossier, partagés) | T, V |172| **Liens de partage** (mot de passe, expiration, plafonds, usage unique, révocation, journal) | Oui | T (accès public réel), A, V |173| **Liens de dépôt** (portails) | Création, pause, renouvellement, révocation, dépôts reçus | T (dépôt public réel), V |174| **Notification de dépôt** | Notification macOS | Serveur : T. Notification affichée : non vérifiée |175| **Quota** | Barre latérale, Stockage, barre de menus | A, V |176| Étiquettes, doublons, administration, récupération par code, TOTP, ajout de passkey | Non repris (restent sur le site) | — |177178### Propre au client macOS179180| Fonction | Détail | Vérifié |181|---|---|---|182| **Emplacement SP Drive dans le Finder** | File Provider répliqué | F : 22 / 22 sur la variante de test |183| **Liaison d'appareil par code** | Code approuvé dans un navigateur déjà connecté (`/appareil`) | T |184| **Journal d'opérations hors ligne** | Créer, renommer, déplacer, corbeille, favoris ; rejoué dans l'ordre à la reconnexion | T (serveur arrêté, « redémarrage », reprise) |185| **Ajout de fichiers hors ligne** | Copie mise en attente dans le conteneur | T |186| **Synchronisation incrémentale** | Flux de changements du serveur | T |187| **Conflits** | Détection, copie de conflit, résolution (garder les deux, la sienne, celle du serveur) | T, F ; écran de résolution : V |188| **Disponibilité hors ligne** | Épingler un fichier ou un dossier | Fichier : A. Dossier entier : non vérifié |189| **Libérer l'espace local, vider le cache** | Éviction d'un fichier désépinglé puis relecture intacte | Vérifié ; cache : A |190| **File de transferts** | Pause, reprise, annulation, réessai, priorités, parallélisme adaptatif, limites de débit | T |191| **Barre de menus** | Oui | Non vérifiée à l'écran |192| **Notifications** | Lot terminé, conflit, erreur persistante, espace, dépôt | Non vérifiées à l'écran |193| **Verrou Touch ID** | Oui | Non vérifié |194| **Ouverture à l'ouverture de session** | `SMAppService` | Non vérifié |195| **Tableau de bord du stockage** | Oui | V |196197### Absent du serveur, donc absent du client198199| Fonction | Raison |200|---|---|201| « Partagés avec moi », partage privé entre comptes, permission de modification | Le serveur n'a pas de partage entre comptes : rien n'est affiché plutôt qu'un écran vide |202| Recherche dans le contenu des documents | Pas d'index de contenu côté serveur |203| Auteur d'une version | Compte unique par arbre : non exposé |204| Chiffrement de bout en bout | Non construit ; l'app le dit dans ses réglages |205206---207208## 🏗 Architecture209210```mermaid211flowchart TB212    subgraph APP["SP Drive.app — sandbox"]213        UI["SwiftUI · AppModel"]214        SE["SyncEngine"]215        OJ["OperationJournal<br/>hors ligne"]216        CD["ChangeDetector<br/>flux de changements"]217        TQ["TransferQueue<br/>UploadManager · DownloadManager"]218        CR["ConflictResolver"]219        UI --> SE220        SE --> OJ221        SE --> CD222        SE --> TQ223        SE --> CR224    end225    subgraph EXT["SPDriveFileProvider.appex — sandbox"]226        FP["NSFileProviderReplicatedExtension<br/>item · fetchContents · create · modify · delete"]227        DS["DriveServices<br/>envoi · téléchargement · changements · conflits"]228        FP --> DS229    end230    F["Finder<br/>fileproviderd"]231    subgraph GRP["Conteneur du groupe d'applications"]232        DB[("metadata.sqlite<br/>miroir · journal · file · conflits")]233        KC[("Trousseau partagé<br/>jeton de session d'appareil")]234    end235    SRV["drive.spboucher.ai<br/>MacLustr · nœud m5ma"]236    F <--> FP237    SE <--> DB238    DS <--> DB239    APP -.-> KC240    EXT -.-> KC241    EXT -. "notification Darwin « changed »" .-> APP242    TQ -->|"HTTPS · Authorization: Bearer"| SRV243    DS -->|"HTTPS · Authorization: Bearer"| SRV244```245246### Modifier un fichier depuis le Finder, conflit compris247248```mermaid249sequenceDiagram250    participant U as Personne251    participant F as Finder252    participant X as Extension File Provider253    participant S as drive.spboucher.ai254    U->>F: enregistre un fichier255    F->>X: modifyItem (nouveau contenu)256    X->>S: téléversement résumable, baseVersionId = version de départ257    Note over X,S: SHA-256 par bloc, puis SHA-256 du fichier entier258    alt le serveur a toujours cette version259        S-->>X: nouvelle version confirmée260        X-->>F: élément à jour261    else une autre version existe déjà (409 version_conflict)262        X->>S: même téléversement transformé en fichier distinct (asNewFile)263        S-->>X: copie « nom (conflit Mac date).ext »264        X-->>F: les deux fichiers sont visibles265        Note over U,X: rien n'est écrasé, la personne choisit dans l'app266    end267```268269### Deux chemins d'écriture, un seul contrat270271- **Dans le Finder** : le système tient la réplique locale et son propre journal ; il appelle l'extension pour pousser272  ce qui a été créé, modifié, renommé, déplacé, mis à la corbeille. Hors ligne, l'extension répond273  `serverUnreachable` et le système réessaie ; l'app signale la fin de la panne.274- **Dans l'application** : chaque action est écrite dans `ops` (journal SQLite) et appliquée au miroir au même275  instant, puis rejouée dans l'ordre contre le serveur. Les dossiers créés hors ligne portent un identifiant276  `local-…` échangé contre l'identifiant du serveur à la création. Les envois passent par `transfers` (copie mise277  en attente dans le conteneur).278279Dans les deux cas : un contenu envoyé comme nouvelle version nomme la version dont il dérive. Si le serveur en a une280autre, rien n'est écrasé : les octets deviennent une **copie de conflit** (`nom (conflit <Mac> <date>).ext`), le281conflit est enregistré, et la personne choisit (garder les deux, la sienne, celle du serveur) — la version écartée282va à la corbeille.283284### Intégrité285286- **Envoi** : SHA-256 par bloc et du fichier entier, confirmé par le serveur avant tout « terminé » ; un fichier287  modifié pendant l'envoi est refusé.288- **Téléchargement** : écriture dans un fichier partiel étiqueté par le SHA-256 attendu, reprise par `Range` +289  `If-Range`, hachage en flux, puis `F_FULLFSYNC` et `rename` atomique seulement si taille et empreinte concordent ;290  un partiel d'une autre version ou abîmé n'est jamais livré.291292### Ce que le serveur a reçu pour les clients natifs (migration `002_native_clients`, additif)293294Session d'appareil (jeton porté en `Authorization: Bearer`, durée glissante, fermé après 90 jours de silence, listé295et révocable) · liaison par code (`auth/device/start|poll|info|decide` + page `/appareil`, approbation par passkey296fraîche) · flux de changements (`GET /sync/changes`, `/sync/cursor`, `POST /sync/items`, pierres tombales pour les297purges) · conflits (`baseVersionId` → 409 `version_conflict`, `PATCH /uploads/:id/options {asNewFile}`) · fichier298d'association Apple (`/.well-known/apple-app-site-association`).299300---301302## 🧱 Pile technique303304| Couche | Technologie | Version / réglage | Rôle |305|---|---|---|---|306| Langage | Swift | 6.0, `SWIFT_STRICT_CONCURRENCY: complete` | Tout |307| Interface | SwiftUI + AppKit | `@Observable` | Fenêtre principale, barre de menus, réglages |308| Finder | FileProvider | `NSFileProviderReplicatedExtension` | Emplacement SP Drive dans le Finder |309| Persistance | SQLite (`sqlite3` du système) | schéma du miroir version 1 | Miroir, journal, file de transferts, conflits |310| Authentification | AuthenticationServices | `webcredentials:drive.spboucher.ai` | Passkeys système |311| Secrets | Trousseau à protection des données | groupe partagé app + extension | Jeton de session d'appareil |312| Ouverture de session | ServiceManagement (`SMAppService`) | — | Lancement à l'ouverture de session |313| Paquets | SwiftPM : `SPDriveCore`, `SPDriveSync`, `spdrive-cli` | swift-tools 6.0 ; macOS 14, iOS 17 | Salle des machines sans interface, liée aussi par l'app iOS |314| Projet | XcodeGen (`project.yml`) | — | Génère `SPDrive.xcodeproj` |315| Système minimal | macOS | 14.0 | — |316| Dépendances tierces | aucune | 0 | Vérifié sur le produit signé par `Scripts/verify-release.sh` |317318---319320## 🗂 Organisation du dépôt321322```323sp-drive-macos/324├── Package.swift               # SPDriveCore (Core/), SPDriveSync (Sync/), spdrive-cli, tests325├── project.yml                 # XcodeGen : app SPDrive + extension SPDriveFileProvider326├── App/                        # 10 fichiers · 992 lignes — entrée, modèle (AppModel), environnement partagé327│   │                           #   app/extension, passkey, réglages, notifications, navigation328│   └── DevSelfTest.swift, DevTour.swift     # variante de test seulement329├── Core/                       # 12 fichiers · 1 408 lignes — SPDriveCore330│   ├── API/                    #   APIClient, Endpoints, DriveError331│   ├── Authentication/         #   AuthAPI332│   ├── Persistence/            #   MetadataStore, SQLite333│   ├── Security/               #   Hashing, KeychainTokenStore, NameRules334│   ├── Networking/             #   NetworkMonitor335│   ├── Metadata/               #   LocalSearch336│   └── Models/337├── Sync/                       # 8 fichiers · 1 155 lignes — SPDriveSync : SyncEngine, ChangeDetector,338│                               #   ConflictResolver, TransferQueue, UploadManager, DownloadManager,339│                               #   IntegrityVerifier, OperationJournal340├── FileProviderExtension/      # 5 fichiers · 558 lignes — extension Finder (FileProviderExtension, Enumerator,341│                               #   Item, DriveServices) + gestion du domaine côté app (FileProviderManager)342├── Features/                   # 12 fichiers · 1 687 lignes — écrans SwiftUI343│   ├── Home/                   #   MainView, MenuBarView, RootView344│   ├── MyDrive/                #   BrowserView, ItemActions, Sheets345│   ├── Shared/                 #   ShareSheet, PortalViews346│   ├── Transfers/, Offline/ (StorageView), Settings/, Account/ (LoginView)347├── Components/                 # vues et formats partagés348├── Resources/                  # Info.plist, droits, catalogue d'images (Release et variante Dev)349├── Tests/CoreTests/            # tests unitaires et d'intégration (vrai backend local)350├── Tools/spdrive-cli/          # petit client en ligne de commande : joue « un autre appareil » dans les scripts351├── Scripts/                    # construction, backend de test, tests, scénario Finder, distribution352└── docs/                       # ARCHITECTURE, FEATURE_MATRIX, TEST_REPORT, brand/353```354355---356357## 🛠 Construire et lancer358359```bash360Scripts/backend-dev.sh start        # vrai backend SP Drive local (clone ~/dev/sp-drive-testbed, base sp_drive_macdev, port 8665)361Scripts/t.sh [filtre] [secondes]    # swift test : 15 tests unitaires + 27 d'intégration contre ce backend362python3 Scripts/provision.py        # identifiants + profils Developer ID (clé App Store Connect existante), idempotent363Scripts/build.sh [Debug|Release]    # Debug = variante « SP Drive Dev » (identifiants .dev, backend local)364Scripts/run-dev.sh --link --keep    # lance la variante de test et la connecte par code d'appareil365Scripts/run-dev.sh --keep -- -spdSelfTest YES   # 19 vérifications faites par l'app signée elle-même366Scripts/run-dev.sh --keep -- -spdTour YES       # parcourt les 22 écrans et enregistre une image de chacun367Scripts/finder-scenario.sh          # scénario de validation par le Finder (exige l'emplacement activé dans Réglages Système)368Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh   # archive, 32 contrôles, notarisation + DMG369```370371Les produits de construction vont dans `~/Library/Developer/SPDrive/` (hors de `~/Desktop`, que les services système372qui chargent l'extension ne peuvent pas lire).373374| Script | Rôle |375|---|---|376| `Scripts/backend-dev.sh start\|stop\|env\|web-stop\|web-start` | Un vrai backend SP Drive sur ce Mac pour les tests : le code du cluster, sa propre base PostgreSQL, son propre dossier de données et sa clé maîtresse. `web-stop` / `web-start` arrêtent et relancent le serveur sur les mêmes données (tests « hors ligne »). Rien ne touche la production |377| `Scripts/backend-helper.mts` | Authentificateur WebAuthn logiciel réservé aux tests : crée le compte de test, ouvre des sessions d'appareil, approuve les codes de liaison par la vraie API |378| `Scripts/t.sh [filtre] [secondes]` | `swift test` avec filtre et limite de temps, n'affiche que les verdicts |379| `Scripts/build.sh [Debug\|Release]` | Génère le projet Xcode et construit l'app avec son extension |380| `Scripts/run-dev.sh [--shot f.png] [--wait s] [--keep] [--link] [-- arguments]` | Lance « SP Drive Dev » contre le backend de test ; peut capturer sa propre fenêtre (jamais l'écran) |381| `Scripts/seed-demo.sh` | Remplit le compte de test d'une petite bibliothèque de démonstration (contenu synthétique) |382| `Scripts/finder-scenario.sh` | Scénario de validation par le vrai emplacement Finder de la variante de test |383| `Scripts/provision.py`, `Scripts/asc.py` | Identifiants et 4 profils Developer ID (app, extension et leurs variantes `.dev`) par l'API App Store Connect |384| `Scripts/release.sh` · `verify-release.sh` · `notarize.sh` | Archive Release universelle, 32 contrôles, notarisation et DMG |385| `Scripts/make-icon.sh` · `window-shot.swift` | Rendu de l'icône · capture d'une fenêtre |386387`spdrive-cli` (même moteur que l'app) : `ls`, `changes`, `mkdir`, `put`, `putversion`, `get`, `cat`, `rename`,388`trash`, `restore`, `find`, `link`, avec `SPDRIVE_URL` et `SPDRIVE_TOKEN` dans l'environnement.389390---391392## ⚙️ Configuration393394| Réglage | Où | Sens |395|---|---|---|396| Identifiants | `project.yml` | Release : `ai.spboucher.spdrive` (« SP Drive ») + `.fileprovider` · Debug : `ai.spboucher.spdrive.dev` (« SP Drive Dev ») + `.dev.fileprovider` |397| `SPD_DEV` | condition de compilation, Debug seulement | Variante de test : ses propres identifiants, conteneur, élément de trousseau et emplacement Finder ; autorisée à parler à un backend local. Signée comme la version distribuée (Developer ID + profils) |398| `SPDRIVE_URL`, `SPDRIVE_TOKEN` | environnement | Serveur et jeton pour `spdrive-cli` |399| `NOTARY_PROFILE` | environnement | Profil `notarytool` existant utilisé par `Scripts/notarize.sh` |400| Arguments de la variante de test | `Scripts/run-dev.sh -- …` | `-spdSection <section>`, `-spdGrid YES`, `-spdFolder <nom>`, `-spdSearch <texte>`, `-spdSelect <nom>`, `-spdInspector YES`, `-spdSheet share\|versions\|portal\|rename\|move\|newFolder`, `-spdSelfTest YES`, `-spdTour YES` |401| Droits (Release) | `Resources/SPDrive.entitlements` | App Sandbox, réseau sortant, groupe d'applications, fichiers choisis par la personne, dossier Téléchargements, domaine associé `webcredentials:drive.spboucher.ai`, groupe de trousseau partagé |402403---404405## 🖥 Écrans40640711 sections de barre latérale (`App/Navigator.swift`) :408409| Section | Titre | Contenu |410|---|---|---|411| `drive` | Mon Drive | Navigateur de l'arbre (liste, grille, fil d'Ariane, inspecteur) |412| `recent` | Récents | Navigateur |413| `shared` | Partagés par moi | Liens de partage |414| `portals` | Liens de dépôt | Portails et dépôts reçus |415| `favorites` | Favoris | Navigateur |416| `offline` | Disponibles hors ligne | Éléments épinglés |417| `downloads` | Téléchargements | Téléchargements |418| `transfers` | Transferts | File d'envois et de téléchargements |419| `conflicts` | Conflits | Conflits et leur résolution |420| `trash` | Corbeille | Navigateur |421| `storage` | Stockage | Tableau de bord du stockage et du quota |422423Six feuilles : nouveau dossier, renommer, déplacer, partager, lien de dépôt, versions. S'y ajoutent l'écran de424connexion, les réglages et la barre de menus. La tournée `-spdTour` affiche 22 écrans et feuilles.425426---427428## 🗄 Modèle de données local429430Miroir `metadata.sqlite` (version 1), un par serveur et par compte, dans le conteneur du groupe partagé par l'app et431l'extension.432433| Table | Rôle |434|---|---|435| `items` | Un fichier ou dossier tel que décrit par le serveur (`rev`), + `name_key` (recherche sans accents), `seq` (compteur local de changements) |436| `tombstones` | Identifiants supprimés définitivement (`seq`) |437| `pins` | Éléments gardés hors ligne (un dossier couvre ses descendants) |438| `local_state` | Copies présentes sur ce Mac, rapportées par le File Provider |439| `ops` | Journal des opérations décidées ici (`pending` / `done` / `failed`) |440| `transfers` | File persistante des envois et téléchargements |441| `upload_sessions` | Sessions de téléversement reprenables (destination + SHA-256 + taille → identifiant serveur) |442| `conflicts` | Conflits et leur résolution |443| `meta` | Curseur du flux, racine, génération du miroir, `seq` |444445```mermaid446erDiagram447    items ||--o| pins : "id — gardé hors ligne"448    items ||--o| local_state : "id — copie sur ce Mac"449    items ||--o{ conflicts : "item_id"450    items ||--o{ transfers : "item_id"451```452453Les liens se font par identifiant d'élément ; le schéma ne déclare pas de clé étrangère. `ops`, `upload_sessions`,454`tombstones` et `meta` sont autonomes.455456L'ancre de synchronisation donnée au File Provider est `génération:seq` : elle expire si le miroir est reconstruit.457458---459460## 🔐 Sécurité et confidentialité461462- **Connexion** : passkey (Touch ID) via `webcredentials:drive.spboucher.ai`, ou liaison par code approuvé dans un463  navigateur déjà connecté (`/appareil`). Le jeton de session d'appareil est dans le trousseau, groupe partagé avec464  l'extension (`AfterFirstUnlockThisDeviceOnly`), jamais dans un fichier ni un journal.465- **Transport** : HTTPS obligatoire (HTTP refusé hors boucle locale ; la version distribuée n'a aucune exception466  ATS) ; validation TLS du système.467- **Chiffrement** : TLS en transit, chiffrement au repos côté serveur. Ce n'est **pas** du chiffrement de bout en468  bout : le serveur détient les clés.469- **Isolation** : App Sandbox + runtime durci pour l'app et l'extension.470- **Chemins** : noms assainis comme le serveur et chemins contrôlés avant toute écriture (refus de traversée de471  chemin et de lien symbolique sortant) ; aucune adresse interne de stockage dans un lien.472- **Suppression** : une suppression faite dans l'app ou dans le Finder met à la corbeille de SP Drive. Seule une473  action explicite sur un élément déjà dans la corbeille supprime définitivement.474- **Consentement Finder** : l'application ne contourne pas l'activation de l'emplacement par la personne.475476---477478## 🧪 Tests479480Aucun résultat n'est simulé : chaque test lit le serveur ou le disque.481482| Suite | Résultat | Commande |483|---|---|---|484| Paquets Swift — 15 unitaires + 27 d'intégration contre le backend réel local (1.0) | **42 / 42** | `Scripts/t.sh` |485| Paquets Swift de la branche `next` (2.0) — `CoreTests` 61 + `NextTests` 14, backend 2.0 local | **75 / 75** | `Scripts/t.sh` |486| Auto-vérification de l'app signée Developer ID, sandboxée | **19 / 19** | `Scripts/run-dev.sh --keep -- -spdSelfTest YES` |487| Tournée des écrans | 22 écrans et feuilles sans plantage | `Scripts/run-dev.sh --keep -- -spdTour YES` |488| Scénario par le Finder (variante de test) | **22 / 22** | `Scripts/finder-scenario.sh` |489| Contrôles du produit distribué | **32 contrôles, 0 échec** | `Scripts/verify-release.sh` |490491<details>492<summary><b>Détail des 42 tests Swift</b></summary>493494- **Unitaires (15)** : règles de nommage identiques au serveur ; refus de traversée de chemin et de lien symbolique495  sortant ; miroir (révisions qui n'avancent que vers l'avant, ancres paginées avec pierres tombales, épingles496  héritées et persistantes, recherche et filtres, 60 000 éléments en moins de 2 s, reconstruction) ; classement des497  changements ; conseiller de parallélisme ; limiteur de débit ; refus du HTTP en clair.498- **Sessions (2)** : jeton porteur, jeton refusé ; liaison par code approuvée, remise une seule fois,499  déconnexion = révocation.500- **Arbre (1)** : cycle complet dossier / fichier, purge seulement depuis la corbeille.501- **Transferts (8)** : 48 Mo aller-retour en flux et vérifié ; fichier vide ; envoi coupé puis repris à l'offset du502  serveur ; envoi qui traverse un arrêt du serveur ; échec propre si le serveur reste arrêté ; téléchargement coupé503  puis repris par `Range` ; partiel abîmé jamais livré ; reprise après changement de contenu qui repart de zéro.504- **Conflits (2)** : édition périmée → copie de conflit, original intact, contenu local préservé ; résolutions505  « la mienne » et « celle du serveur ».506- **Partage (3)** : lien protégé vu par un visiteur anonyme réel ; lien de dossier confiné ; portail de dépôt.507- **Versions (1)**, **flux de changements (3)**, **journal hors ligne (2)**, **file de transferts (3)**,508  **boucle de synchronisation (2)**.509510</details>511512<details>513<summary><b>Les six étapes du scénario Finder</b></summary>514515| Étape | Vérifié |516|---|---|517| 1. Parcourir, télécharger | Dossier créé par un autre appareil visible ; petit fichier lu = contenu du serveur ; fichier de 20 Mo lu avec le SHA-256 du serveur |518| 2. Modifier | Fichier modifié dans le Finder → version 2 sur le serveur, contenu identique |519| 3. Créer, renommer, déplacer | Confirmés par le serveur |520| 4. Conflit | Copie « (conflit …) » sur le serveur, version de l'autre appareil non écrasée, version de ce Mac préservée, le Finder montre les deux |521| 5. Hors ligne | Serveur arrêté : modifications, ajout, création ; application et extension tuées puis relancées ; serveur relancé → tout arrive intact (SHA-256) |522| 6. Supprimer | Suppression dans le Finder → corbeille du serveur ; restauration sur le serveur → retour dans le Finder |523524</details>525526Épinglage hors ligne (essai dédié) : fichier épinglé → téléchargé, SHA-256 identique ; éviction refusée par le système527tant qu'il est épinglé ; désépinglé → évincé ; relu → contenu identique.528529---530531## 📦 Distribution532533```bash534python3 Scripts/provision.py     # identifiants + 4 profils Developer ID, idempotent535Scripts/release.sh               # archive Release universelle signée Developer ID536Scripts/verify-release.sh        # 32 contrôles sur l'app et l'extension537Scripts/notarize.sh              # notarisation, agrafage, DMG538```539540| Élément | Valeur |541|---|---|542| Version | 1.0.0 (1) — étiquette `v1.0.0` |543| Signature | Developer ID Application, manuelle, `--timestamp`, runtime durci ; profils « SP Drive Developer ID » et « SP Drive File Provider Developer ID » |544| Contrôles | App et extension : signature, runtime durci, horodatage, sandbox, groupe, trousseau, profils ; domaine associé ; point d'extension ; aucun moteur web ; aucun reliquat de développement ; aucune exception ATS |545| Notarisation | App et DMG **Accepted**, tickets agrafés |546| Gatekeeper | `spctl` : app et DMG « accepted — Notarized Developer ID » |547| Produit | `dist/SPDrive-1.0.0.dmg` et son SHA-256 dans `dist/SPDrive-1.0.0.dmg.sha256` (hors git) |548549---550551## 🩺 À savoir et dépannage552553| Sujet | Explication |554|---|---|555| **Activation dans le Finder** | macOS garde un nouvel emplacement File Provider désactivé jusqu'à ce que la personne l'active dans Réglages Système › Général › Ouverture et extensions › Fournisseurs de fichiers. L'application le détecte, l'explique et ouvre le bon panneau ; elle ne contourne pas ce consentement |556| **Erreur passkey 1004** | Cause établie : le robot d'Apple avait demandé le fichier d'association avant la mise en production de la route ; le site avait répondu sa page HTML et le CDN d'Apple a gardé « Bad JSON content » une heure. Diagnostic : `nscurl -i https://app-site-association.cdn-apple.com/a/v1/drive.spboucher.ai` (pas `curl`, dont l'en-tête `Accept-Encoding` désigne une autre entrée du cache). Remède : attendre l'expiration du cache |557| **Épinglage différé** | `requestDownloadForItem` est accepté mais différé par macOS sur batterie ; l'app lit donc elle-même les fichiers épinglés (lecture coordonnée) pour un téléchargement immédiat |558| **Plantage sur macOS 27** | Cellules de tableau, menus et barre d'outils lisaient le modèle dans l'environnement SwiftUI, absent à ces endroits : le modèle leur est passé explicitement |559| **« The timestamp service is not available »** | Panne passagère du service d'horodatage d'Apple pendant `Scripts/release.sh` : relancer |560| **Construire hors de `~/Desktop`** | Les services système qui chargent l'extension ne peuvent pas y lire : produits dans `~/Library/Developer/SPDrive/` |561| **Tests d'intégration** | Ils exigent `Scripts/backend-dev.sh start` ; le scénario Finder exige en plus l'app de test connectée (`Scripts/run-dev.sh --link --keep`) et l'emplacement « SP Drive Dev » activé |562| **Purge** | Possible en ligne seulement, après confirmation, et seulement depuis la corbeille |563564---565566## 🧭 Limites connues567568Non vérifié ([`docs/TEST_REPORT.md`](docs/TEST_REPORT.md)) :5695701. **Le Finder sur la version distribuée** : le scénario a été exécuté sur la variante de test (même code, autres571   identifiants). L'emplacement « SP Drive » de production n'existe qu'après connexion du propriétaire, qui doit572   aussi l'activer dans Réglages Système. Vignettes dans le Finder, ouverture et enregistrement depuis une573   application graphique : non observés.5742. **Version distribuée contre la production** : elle n'a pas été lancée connectée par un test (aucun compte de575   test en production). La connexion par passkey réelle (Touch ID) fonctionne, constatée par le propriétaire.5763. Redémarrage réel du Mac ; reprise après veille.5774. Notifications, barre de menus, verrou Touch ID, ouverture de session, Coup d'œil : non observés à l'écran.5785. VoiceOver ; autre Mac, Intel, macOS 14–26.5796. Aucun test d'interface XCUITest (la tournée et l'auto-vérification en tiennent lieu).5807. Débit sur liaison lente ou coûteuse : le conseiller de parallélisme n'est testé que par ses règles.581582Non repris du site : étiquettes, doublons, administration (invitations, quotas), récupération par code, TOTP, ajout583de passkey. Pas de chiffrement de bout en bout.584585---586587## 📚 Documentation588589| Document | Contenu |590|---|---|591| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Audit du système existant, ajouts au backend, client macOS, intégrité, schéma du miroir, sécurité |592| [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md) | Matrice de parité site ↔ client macOS, avec la manière dont chaque fonction a été vérifiée |593| [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) | Rapport de tests : backend, paquets Swift, application signée, Finder, distribution, non vérifié |594595---596597## 👤 Auteur598599<div align="center">600<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>601602**Simon-Pierre Boucher** — conception, développement, exploitation<br>603[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai604605</div>606607---608609## 📄 Licence610611Tous droits réservés © 2026 Simon-Pierre Boucher.612
Files main
Menu

Theme