- storage: openForDownload accepte un intervalle d'octets - files: serveFile (200/206/416) + route GET /preview inline avec whitelist, sans increment du compteur - admin: creation et reinitialisation ne renvoient plus le mot de passe (envoi par e-mail uniquement) - docs: endpoint preview et whitelist/Range
7.6 KiB
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 :
{ "error": { "status": 404, "code": "NOT_FOUND", "message": "…", "requestId": "…" } }