# API et modèle de données — CoHaiSe Cloud Base : **`/api/cloud`**, plus `GET /healthz` (sonde base, `503` si indisponible). Middleware `attachUser` monté sur les préfixes ; `requireAuth` sur chaque route sauf la connexion et les flux publics (mot de passe oublié, confirmation d'adresse). ## Routes ### Session | Méthode | Chemin | Garde | | --- | --- | --- | | POST | `/api/cloud/auth/login` | publique, **limitée par IP** | | POST | `/api/cloud/auth/logout` | `requireAuth` | | GET | `/api/cloud/auth/me` | `requireAuth` | | POST | `/api/cloud/auth/change-password` | `requireAuth` + Zod | ### Compte | Méthode | Chemin | Garde | | --- | --- | --- | | PATCH | `/api/cloud/account/profile` | `requireAuth` | | GET | `/api/cloud/account/sessions` | `requireAuth` | | DELETE | `/api/cloud/account/sessions/:id` | `requireAuth` | | DELETE | `/api/cloud/account/sessions` | `requireAuth` (les autres) | | PUT | `/api/cloud/account/avatar` | `requireAuth` (corps brut image) | | GET | `/api/cloud/account/avatar/:userId` | `requireAuth` | | DELETE | `/api/cloud/account/avatar` | `requireAuth` | | POST | `/api/cloud/account/forgot-password` | publique, **limitée par IP** | | POST | `/api/cloud/account/reset-password` | publique, **limitée par IP** | | POST | `/api/cloud/account/email-change` | `requireAuth`, **limitée** | | POST | `/api/cloud/account/email-change/confirm` | publique (jeton) | ### Dossiers et fichiers | Méthode | Chemin | Garde | | --- | --- | --- | | GET | `/api/cloud/folders` | `requireAuth` (visibles seulement) | | POST | `/api/cloud/folders` | `requireAuth` | | PATCH | `/api/cloud/folders/:id` | `requireAuth` + gestion du dossier | | POST | `/api/cloud/folders/:id/move` | `requireAuth` + gestion | | DELETE | `/api/cloud/folders/:id` | `requireAuth` + gestion (corbeille) | | GET | `/api/cloud/folders/:id/permissions` | `requireAuth` + gestion | | POST | `/api/cloud/folders/:id/permissions` | `requireAuth` + gestion | | DELETE | `/api/cloud/folders/:id/permissions/:userId` | `requireAuth` + gestion | | GET | `/api/cloud/files` | `requireAuth` | | PUT | `/api/cloud/files` | `requireAuth` (corps brut, upload) | | GET | `/api/cloud/files/:id/download` | `requireAuth` | | GET | `/api/cloud/files/:id/preview` | `requireAuth` (aperçu en ligne) | | GET | `/api/cloud/files/:id/thumbnail` | `requireAuth` | | PATCH | `/api/cloud/files/:id` | `requireAuth` + écriture (renommer) | | POST | `/api/cloud/files/:id/move` | `requireAuth` + écriture | | PUT | `/api/cloud/files/:id/star` | `requireAuth` | | DELETE | `/api/cloud/files/:id` | `requireAuth` + écriture (corbeille) | ### Corbeille, recherche, galerie | Méthode | Chemin | Garde | | --- | --- | --- | | GET | `/api/cloud/trash` | `requireAuth` | | POST | `/api/cloud/trash/folders/:id/restore` | `requireAuth` | | POST | `/api/cloud/trash/files/:id/restore` | `requireAuth` | | DELETE | `/api/cloud/trash/folders/:id` | `requireAuth` (purge) | | DELETE | `/api/cloud/trash/files/:id` | `requireAuth` (purge) | | DELETE | `/api/cloud/trash` | `requireAuth` (vider) | | GET | `/api/cloud/search` | `requireAuth` | | GET | `/api/cloud/media` | `requireAuth` | ### Administration (`role_slug = admin`) | Méthode | Chemin | | --- | --- | | GET | `/api/cloud/admin/stats` | | GET | `/api/cloud/admin/users` | | POST | `/api/cloud/admin/users` | | PATCH | `/api/cloud/admin/users/:id` | | DELETE | `/api/cloud/admin/users/:id` | | POST | `/api/cloud/admin/users/:id/reset-password` | | GET | `/api/cloud/admin/storage-locations` | | POST | `/api/cloud/admin/storage-locations` | | PATCH | `/api/cloud/admin/storage-locations/:id` | | GET | `/api/cloud/admin/audit` | ## Droits d'accès Calculés **en base à chaque requête**, depuis la session — jamais depuis un en-tête (`backend/src/access.ts`). | Concept | Règle | | --- | --- | | Rôles (`users.role_slug`) | `admin` passe tout, `user` par défaut ; `readonly` seedé par `002` puis supprimé par `004` | | Lecture | propriétaire du dossier, **ou** ligne `folder_permissions` de niveau `read`/`write`/`admin`, **ou** dossier `access_type = 'public'` | | Écriture | propriétaire, **ou** `write`/`admin` dans `folder_permissions` | | Gestion (renommer/déplacer/partager/supprimer) | propriétaire, `admin` de partage, ou rôle global `admin` (`canManageFolder`) | | Expiration | `expires_at NULL` ou future ; une permission expirée disparaît de la lecture | | Listing | filtré en SQL — les entrées non visibles ne sont pas chargées puis masquées | | Réponse | **404 plutôt que 403** : jamais d'indice sur l'existence d'une ressource | Le dossier **Public** (`006_public_folder.sql`, `access_type='public'`) est lisible par tous les membres authentifiés, en écriture pour son propriétaire. ## Validation et limites d'upload | Contrôle | Détail | | --- | --- | | Corps | `PUT /files` en flux brut (pas de multipart), `?name=` et `?folderId=` | | Taille | plafond `users.max_file_bytes`, vérifié en flux (coupure si dépassement) | | Quota | `users.used_bytes` + quota `storage_locations`, revérifiés avant écriture | | Disque | `diskUsage()` (`statfs`) avant écriture ; `507` `INSUFFICIENT_STORAGE` si le support est plein | | Quota support | un quota d'emplacement ne peut dépasser la capacité réelle du disque (`assertQuotaFits`) | | Chemin disque | dérivé du slug + UUID, jamais du nom affiché (`storage.ts`) | | Renommage | `PATCH /files/:id { name }`, `PATCH /folders/:id { name, description }` | | Déplacement | `folderId`/`parentId` : refuse de placer un dossier dans son propre sous-arbre | ## Courriels Les messages sortants sont construits par `backend/src/lib/mail-template.ts` : gabarit HTML aux couleurs de l'app (`#b71c1c`), logo, bouton d'action et mention **ne pas répondre**. Un repli texte accompagne chaque envoi. Le logo `backend/src/assets/logo.png` est **embarqué** dans le message (pièce jointe `cid`), donc visible même quand le client bloque les images distantes. `MAIL_LOGO_URL` force une image distante à la place. Points d'envoi : réinitialisation du mot de passe, changement d'adresse, et **notification au nouvel utilisateur** à la création d'un compte admin (identifiants temporaires + lien de connexion). Un échec d'envoi n'annule jamais l'opération en base. ## Modèle de données `backend/migrations/` — application stricte dans l'ordre, checksum SHA-256 par fichier, dérive refusée au démarrage. | Fichier | Contenu | | --- | --- | | `000_schema_migrations.sql` | table de suivi (`version`, `applied_at`, `checksum`) | | `001_initial_schema.sql` | `roles, users, password_reset_tokens, storage_locations, folders, files, folder_permissions, share_links, settings, audit_logs` | | `002_reference_data.sql` | seeds : rôles, emplacement `principal`, réglages | | `003_integrity_backstop.sql` | `CHECK` d'intégrité (audit, auto-parenté) | | `004_cloud_requirements.sql` | `first_name`/`last_name`, `used_bytes`, `max_file_bytes`, `user_sessions`, `media_metadata`, `file_variants`, **suppression de `share_links`** | | `005_storage_location_realign.sql` | réalignement des emplacements | | `006_public_folder.sql` | `folders.access_type` / `is_system`, dossier `Public` | Tables actives : `users, user_sessions, folders, folder_permissions, files, media_metadata, file_variants, user_avatars, storage_locations, settings, password_reset_tokens, email_change_requests, audit_logs`. ## Erreurs métier `AppError` avec codes stables (`backend/src/lib/errors.ts`). Correspondances MariaDB : `1062` → 409, `1146` → 503 `NOT_MIGRATED`, `1406` → 422. Le corps d'une 500 ne contient jamais de détail de schéma. Réponse normalisée : ```json { "error": { "status": 404, "code": "NOT_FOUND", "message": "…", "requestId": "…" } } ```