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/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/cloud/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 |
| 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 |
Modèle de données
backend/cloud/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/cloud/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 :