# Cloud — modèle de données Stockage privé de fichiers. Le contenu ne vit jamais dans la base : MariaDB ne décrit que des métadonnées, les octets restent sur le disque sous `storage_locations.mount_path`. Le service **existe et sert ce modèle** : 10 routes sous `/api/cloud` (`src/routes/{auth,folders,files}.ts`). Le détail des endpoints, des droits et du déploiement est dans [`../../docs/api.md`](../../docs/api.md), [`../../docs/security.md`](../../docs/security.md) et [`../../docs/architecture.md`](../../docs/architecture.md). ## Modèle de données ```mermaid erDiagram roles ||--o{ users : "attribue" users ||--o{ user_sessions : "ouvre" users ||--o{ user_avatars : "a pour photo" users ||--o{ password_reset_tokens : "demande" users ||--o{ email_change_requests : "demande" users ||--o{ folders : "proprietaire" users ||--o{ files : "proprietaire" users ||--o{ folder_permissions : "beneficie" users ||--o{ chat_messages : "ecrit" users ||--o{ audit_logs : "trace" storage_locations ||--o{ folders : "contient" storage_locations ||--o{ files : "contient" storage_locations ||--o{ user_avatars : "contient" folders ||--o{ folders : "parent de" folders ||--o{ files : "contient" folders ||--o{ folder_permissions : "accede" files ||--o{ media_metadata : "decrit" files ||--o{ file_variants : "derive" ``` ## Tables 16 tables en base après `007` (`share_links` ayant été supprimée par `004`). Seules celles marquées « `/…` » sont atteignables depuis le front. | Table | Rôle | Exposée par l'API | |---|---|---| | `roles` | `admin` et `user` (le `readonly` de `002` a été retiré par `004`) | indirectement (`users.role_slug`) | | `users` | Comptes : prénom, nom, e-mail, mot de passe, quotas | `/auth/*` | | `user_sessions` | Appareils connectés, révocation, expiration | session interne | | `user_avatars` | Photo de profil, une ligne par compte | non | | `password_reset_tokens` | Réinitialisation de mot de passe, hachée | non (aucune route) | | `email_change_requests` | Validation du nouvel e-mail d'un compte | non (aucune route) | | `storage_locations` | Volumes de stockage et quotas globaux | non (interne à `storage.ts`) | | `folders` | Arborescence, avec `access_type` | `/folders` | | `folder_permissions` | Droits nominatifs sur un dossier `shared` | non (aucune route) | | `files` | Métadonnées de l'original, jamais ré-écrit | `/files` | | `media_metadata` | Dimensions, durée, codecs, EXIF, couleur dominante | non (galerie non exposée) | | `file_variants` | Miniatures et aperçus WebP dérivés | non | | `chat_messages` | Salon d'un dossier : dossier (`ON DELETE CASCADE`), auteur (`ON DELETE SET NULL`), soft-delete | `/folders/:id/chat` | | `settings` | Configuration clé-valeur | non | | `audit_logs` | Piste d'audit | non (écrit par `audit()`) | | `schema_migrations` | Versions appliquées | non | ## Trois notions à ne pas confondre | Notion | Où elle vit | Ce que c'est | |---|---|---| | Le fichier | le disque | les octets d'origine, jamais ré-encodés | | La ligne `files` | la base | le nom, la taille, la somme de contrôle, le chemin | | La ligne `media_metadata` | la base | ce qu'un lecteur sait du fichier : dimensions, durée, appareil | Un fichier dénué de `media_metadata` reste valide : un PDF ou un ZIP n'ont pas de dimensions. C'est le comportement voulu, une entrée de galerie non encore analysée doit rester listable. ## Originaux intacts, aperçus dérivés Aucun fichier téléversé n'est ré-encodé. Le contenu reçu est écrit tel quel et sa somme SHA-256 est mémorisée, ce qui sert à la fois de preuve d'intégrité et de détection de doublon. Les WebP d'aperçu sont des fichiers **supplémentaires** décrits par `file_variants`, avec un `purpose` valant `thumbnail` ou `preview` ; un `UNIQUE` sur `(file_id, purpose)` interdit d'en empiler deux du même type. La conséquence assumée : une photo contient ses coordonnées GPS, et puisqu'aucun fichier n'est modifié, ces coordonnées restent lisibles dans l'original. Les aperçus WebP sont ré-encodés et ne les portent pas. ## Trois types d'accès aux dossiers `folders.access_type` porte l'intention, et non une garde : | Valeur | Qui accède | Écriture | |---|---|---| | `private` | le propriétaire seul | le propriétaire | | `shared` | le propriétaire et les comptes listés dans `folder_permissions` | selon le niveau `read`, `write` ou `admin` | | `public` | tous les comptes de l'installation | tous peuvent ajouter, personne ne supprime les fichiers d'autrui | Un seul dossier de l'instance porte `is_system = 1`, et l'unicité est réelle en base : la colonne générée `system_marker` vaut `1` pour lui et `NULL` pour tous les autres, donc un second dossier système viole `uq_folders_system`. `chk_folders_system` impose en outre qu'un dossier système soit `public`. Les dossiers enfants d'un dossier `public` restent soumis à l'unicité de nom : deux enfants ne peuvent pas s'appeler pareil, puisque leur `parent_id` n'est pas `NULL`. La limite ne concerne que la racine, dont les éléments ont `parent_id IS NULL`. Le niveau d'accès est **vérifié à chaque requête** en base, depuis la session : voir [`../../docs/api.md`](../../docs/api.md). ## Budget et plafond par utilisateur Deux réglages distincts, tous deux portés par `users` : | Colonne | Effet | |---|---| | `quota_bytes` | volume total que le compte peut occuper, borné par `chk_users_quota` | | `max_file_bytes` | taille maximale d'un dépôt unique | `used_bytes` est maintenu par l'application et borné en base : impossible d'écrire `used_bytes > quota_bytes`, quelle que soit la requête. Le quota est en outre **re-vérifié en transaction** au moment de l'écriture. `max_file_bytes`, en revanche, ne peut pas être garanti par une contrainte, car il compare une ligne de `files` à une ligne d'`users` : c'est à l'application de le vérifier, sur la taille déclarée et sur la taille réellement reçue. `default_quota_bytes` et `max_upload_bytes` dans `settings` ne sont pas des plafonds globaux, seulement les valeurs proposées à la création d'un compte. ## Unicité après suppression logique Un nom ou une adresse peut être réutilisé après une suppression logique, grâce à des colonnes générées : ```sql active_email VARCHAR(255) GENERATED ALWAYS AS (IF(deleted_at IS NULL, email, NULL)) STORED, UNIQUE KEY uq_users_email (active_email) ``` La ligne supprimée produit `NULL`, et en SQL plusieurs `NULL` ne sont pas égaux : l'index ne la voit plus. C'est cette propriété qui sert deux fois, pour libérer une adresse de compte et pour autoriser la réimportation d'un fichier au même nom. ## Métadonnées : la part utile et le reste Ce que la galerie filtre ou affiche est mis en colonnes indexées : `taken_at`, `width`, `height`, `duration_ms`, `kind`, `video_codec`, `camera_make`, `camera_model`, `dominant_color`. Le reste des EXIF, qui peut représenter une trentaine de réglages d'objectif pour quelques kilo-octets et n'est jamais lu, est facultatif et compressé dans `extra_metadata`. Rien n'oblige à le remplir. ## Chemin physique Le nom affiché **n'entre jamais dans le chemin** : `${MEDIA_DIR}//`, avec `resolveInside()` qui refuse toute cible hors base. Le choix de l'emplacement se fait parmi les `storage_locations` actifs, en privilégiant la plus grande marge disponible. ## Migrations | Fichier | Contenu | |---|---| | `000_schema_migrations.sql` | table de suivi des versions | | `001_initial_schema.sql` | 11 tables, 17 clés étrangères, 14 `CHECK` | | `002_reference_data.sql` | rôles, emplacement principal, réglages | | `003_integrity_backstop.sql` | `CHECK` d'audit, interdiction du dossier parent de lui-même | | `004_cloud_requirements.sql` | identité complète, sessions, validation d'e-mail, avatar, `access_type`, médias, variantes, budget par compte, suppression des liens publics | | `005_storage_location_realign.sql` | `mount_path` réaligné sur `/data/media`, quota 400 Go, garde-fou sur les emplacements sans quota | | `006_public_folder.sql` | crée le dossier système « Public », retire les réglages devenus morts | | `007_chat.sql` | crée `chat_messages`, le salon d'un dossier (FK dossier `ON DELETE CASCADE`) | `004` porte le passage d'un modèle de partage public vers un stockage privé : elle supprime `share_links`, scinde `display_name` en `first_name` et `last_name`, et remplace le plafond global `max_upload_bytes` par les deux colonnes portées par `users`. Elle a aussi supprimé le rôle `readonly`, qui venait d'une supposition et non d'un besoin formulé. Une migration appliquée ne se modifie jamais : le checksum la fige. Voir [`../../docs/deployment.md`](../../docs/deployment.md). ## Sécurité (couche modèle) - Suppression d'un rôle encore attribué, ou d'un emplacement contenant des données : refusée par la base (`ON DELETE RESTRICT`). - Sessions et jetons stockés hachés en `CHAR(64)` ; `password_changed_at` permet de dater un changement. - Les identifiants de dossier et de fichier sont des UUID, non devinables. - `audit_logs` survit à la suppression d'un utilisateur (`ON DELETE SET NULL`) plus un instantané `user_email`, `ip_address`, `user_agent`. En-têtes (CSP/HSTS), CORS et limitation de débit sont décrits dans [`../../docs/security.md`](../../docs/security.md). Il n'y a **pas** de jeton CSRF : les écritures sont des `POST`/`PUT`/`DELETE` et le cookie de session est `SameSite=Lax`, ce qui bloque les écritures inter-origines. ## Limites actuelles - **La règle « ne pas supprimer les fichiers d'autrui » n'est pas en base.** Aucune contrainte SQL ne peut exprimer « le propriétaire ou un administrateur » : elle ne vit que dans l'API, et une personne ouvrant un client SQL la contourne. `audit_logs` est le seul rempart réel. - **`max_file_bytes` n'est pas appliqué en base** (voir plus haut). - **Les cycles profonds ne sont pas empêchés.** `chk_folders_not_self_parent` bloque le parent direct de lui-même, mais `A → B → A` reste possible et demande un parcours `WITH RECURSIVE` au moment d'un déplacement. - **Deux éléments racine peuvent porter le même nom**, dossier ou fichier, puisque leur clé étrangère de parent vaut `NULL`. - `extra_metadata` n'est pas contraint en taille. - **Partages publics par lien** : retirés par `004` ; le seul espace partagé est le dossier système « Public » (`006`), ouvert à tout compte authentifié. - Les réglages `allow_public_shares` et `default_share_expiry_days` ont été supprimés par `006` (données mortes).