SPB Git

Repository Public

ARCHITECTURE.md 8.7 KB 111 lines markdown

1<!--2SP Drive — macOS3File: docs/ARCHITECTURE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89## 1. Audit du système existant (2026-11-18)1011| Sujet | Constat |12|---|---|13| Dépôt | spbgit `sp-drive.git`, source de vérité = clone du nœud **m5ma** `~/apps/sp-drive`, PM2 `sp-drive` (API + web, :8660), `sp-drive-worker`, clamd, sauvegarde nocturne |14| Frontend | SPA Vite / React 19 / Tailwind servie par l'API |15| Backend | Fastify 5 + PostgreSQL 17, monorepo pnpm ; modules `auth`, `tree`, `files`, `uploads`, `content`, `shares`, `requests`, `worker` |16| Authentification | passkeys WebAuthn seules, session par cookie `__Host-spd` (rotation quotidienne), en-tête CSRF, codes de récupération, TOTP facultatif |17| Arbre | `folders` / `files` par propriétaire, un dossier racine, noms uniques par dossier (clé NFC minuscule), verrou consultatif par propriétaire |18| Stockage physique | objets chiffrés AES-256-GCM par blocs de 64 Kio sur le SSD du nœud, clé par objet enveloppée par une clé maîtresse ; dédupliqués par (propriétaire, SHA-256, taille) |19| Téléversement | sessions résumables : création avec taille finale, blocs ≤ 16 Mio ajoutés à l'offset annoncé (SHA-256 par bloc), finalisation avec SHA-256 du fichier |20| Téléchargement | flux déchiffré, `Range` / `If-Range`, `ETag` = SHA-256 du contenu |21| Fichiers volumineux | jusqu'à 50 Go par fichier (configuration) |22| Partage | liens à jeton haché : lecture seule ou téléchargement, mot de passe, expiration, plafonds, usage unique, révocation, journal d'accès |23| Liens de dépôt | portails `/request/<jeton>` : le déposant n'obtient qu'un jeton de soumission ; quarantaine → antivirus → placement |24| Permissions | tout est filtré par propriétaire ; un identifiant étranger répond 404 |25| Versions | `file_versions` numérotées ; restaurer crée une version ; suppression d'une version non courante |26| Corbeille | suppression logique (`trashed_at`, `trash_root`), restauration, purge explicite |27| Recherche | par nom (sans accents ni casse), type, étiquette, dates, tailles, favoris |28| Quota | par compte, somme des objets ; exposé par `/auth/state` |29| Utilisateurs | comptes sur invitation, rôles admin / user |30| Absent | partage entre comptes (« partagés avec moi »), flux de changements, jeton pour client natif, détection de conflit |3132## 2. Ajouts au backend (migration `002_native_clients`, tout additif)3334- **Session d'appareil** : `POST /auth/login/verify` avec `client: {kind:"native", name}` renvoie un jeton porté en35  `Authorization: Bearer`, jamais tourné (plusieurs processus le partagent), durée glissante (fermé après 90 jours de36  silence), listé et révocable. Un jeton porteur n'étant pas une accréditation ambiante, il est dispensé de l'en-tête CSRF.37- **Liaison par code** : `auth/device/start|poll|info|decide` + page `/appareil` ; l'approbation exige une passkey fraîche.38- **Flux de changements** : colonne `rev` sur `folders` et `files`, tirée d'une séquence *après* la prise du verrou du39  propriétaire dans un déclencheur — pour un propriétaire, les révisions sont validées dans l'ordre, donc `rev > curseur`40  ne manque rien. Pierres tombales pour les purges. `GET /sync/changes`, `/sync/cursor`, `POST /sync/items`.41- **Conflits** : `baseVersionId` sur un téléversement de nouvelle version → 409 `version_conflict` (à la création et à la42  finalisation) ; `PATCH /uploads/:id/options {asNewFile}` transforme le même téléversement en fichier distinct.43- **AASA** : `/.well-known/apple-app-site-association` (`SPD_APPLE_APP_IDS`).4445Vérifié : 75 tests d'intégration (63 existants + 12), 122 tests Playwright du site, aller-retour de migration.4647## 3. Client macOS4849```50┌──────────────── SP Drive.app (sandbox) ────────────────┐      ┌── SPDriveFileProvider.appex (sandbox) ──┐51│ SwiftUI ── AppModel ── SyncEngine                      │      │ NSFileProviderReplicatedExtension       │52│                        ├ OperationJournal (hors ligne) │      │  item / fetchContents / create / modify │53│                        ├ ChangeDetector (flux)         │      │  delete / enumerators / thumbnails      │54│                        ├ TransferQueue                 │      │  DriveServices                          │55│                        │   ├ UploadEngine              │      │   ├ UploadEngine  ├ DownloadEngine      │56│                        │   └ DownloadEngine            │      │   └ ChangeDetector └ ConflictResolver   │57│                        └ ConflictResolver              │      └─────────────────────────────────────────┘58└────────────┬───────────────────────────────────────────┘                        │59             │        conteneur du groupe 3YM54G49SN.ai.spboucher.spdrive         │60             ├── accounts/<serveur>-<compte>/metadata.sqlite  (miroir, journal, file, conflits) ──┤61             ├── trousseau, groupe …spdrive.shared  (jeton de session d'appareil) ────────────────┤62             └── notification Darwin « …changed »  ◀──────────────────────────────────────────────┘63                                   │ HTTPS (TLS système), Authorization: Bearer64                                   ▼65                        drive.spboucher.ai  (MacLustr, m5ma)66```6768### Deux chemins d'écriture, un seul contrat6970- **Dans le Finder** : le système tient la réplique locale et son propre journal ; il appelle l'extension pour pousser ce71  qui a été créé, modifié, renommé, déplacé, mis à la corbeille. Hors ligne, l'extension répond `serverUnreachable` et le72  système réessaie ; l'app signale la fin de la panne.73- **Dans l'application** : chaque action est écrite dans `ops` (journal SQLite) et appliquée au miroir au même instant,74  puis rejouée dans l'ordre contre le serveur. Les dossiers créés hors ligne portent un identifiant `local-…` échangé75  contre l'identifiant du serveur à la création. Les envois passent par `transfers` (copie mise en attente dans le conteneur).7677Dans les deux cas : un contenu envoyé comme nouvelle version nomme la version dont il dérive. Si le serveur en a une78autre, rien n'est écrasé : les octets deviennent une **copie de conflit** (`nom (conflit <Mac> <date>).ext`), le conflit est79enregistré, et la personne choisit (garder les deux, la sienne, celle du serveur) — la version écartée va à la corbeille.8081### Intégrité8283Envoi : SHA-256 par bloc et du fichier entier, confirmé par le serveur avant tout « terminé » ; un fichier modifié pendant84l'envoi est refusé. Téléchargement : écriture dans un fichier partiel étiqueté par le SHA-256 attendu, reprise par85`Range` + `If-Range`, hachage en flux, puis `F_FULLFSYNC` et `rename` atomique seulement si taille et empreinte concordent ;86un partiel d'une autre version ou abîmé n'est jamais livré.8788### Schéma du miroir (`metadata.sqlite`, version 1)8990| Table | Rôle |91|---|---|92| `items` | un fichier ou dossier tel que décrit par le serveur (`rev`), + `name_key` (recherche sans accents), `seq` (compteur local de changements) |93| `tombstones` | identifiants supprimés définitivement (`seq`) |94| `pins` | éléments gardés hors ligne (un dossier couvre ses descendants) |95| `local_state` | copies présentes sur ce Mac, rapportées par le File Provider |96| `ops` | journal des opérations décidées ici (`pending` / `done` / `failed`) |97| `transfers` | file persistante des envois et téléchargements |98| `upload_sessions` | sessions de téléversement reprenables (destination + SHA-256 + taille → identifiant serveur) |99| `conflicts` | conflits et leur résolution |100| `meta` | curseur du flux, racine, génération du miroir, `seq` |101102L'ancre de synchronisation donnée au File Provider est `génération:seq` : elle expire si le miroir est reconstruit.103104## 4. Sécurité105106HTTPS obligatoire (HTTP refusé hors boucle locale, et la version distribuée n'a aucune exception ATS) ; validation TLS du107système ; App Sandbox + runtime durci pour l'app et l'extension ; jeton dans le trousseau à protection des données108(`AfterFirstUnlockThisDeviceOnly`), jamais dans un fichier ni un journal ; noms assainis comme le serveur et chemins109contrôlés (`PathSafety`) avant toute écriture ; aucune adresse interne de stockage dans un lien.110Pas de chiffrement de bout en bout : le serveur détient les clés.111
Files main
Menu

Theme