Files
CoHaiSe-CLOUD/docs/api.md
T
Esiah 332435187c feat(api): apercu en ligne (HTTP Range) et identifiants non renvoyes
- 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
2026-10-16 15:11:15 +02:00

159 lines
7.6 KiB
Markdown

# 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": "…" } }
```