CD — Deployment / deploy (push) Successful in 43s
Root is a personal namespace per user, so duplicate checks must scope to the current owner when uploading at root level. Subfolders keep their existing uniqueness rules. Also fixed folder creation at root with the same owner scope. --------- Co-authored-by: xEsiah <[email protected]> Reviewed-on: #15 Reviewed-by: Esiah <[email protected]> Co-authored-by: Gitea Actions <-[email protected]>
215 lines
11 KiB
Markdown
215 lines
11 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` |
|
|
|
|
### Discussion (chat d'un dossier et membres)
|
|
|
|
Chaque dossier possède son propre salon. Le droit d'accès au dossier fait loi :
|
|
lecture comme écriture passent par `canRead` (`backend/src/access.ts`), donc le
|
|
salon d'un dossier `public` est ouvert à tout compte authentifié. La lecture est
|
|
en texte brut, React échappe le rendu. La synchronisation est incrémentale par
|
|
identifiant (`after`), sans WebSocket.
|
|
|
|
| Méthode | Chemin | Garde |
|
|
| --- | --- | --- |
|
|
| GET | `/api/cloud/folders/:folderId/chat/members` | `requireAuth` + `canRead` |
|
|
| GET | `/api/cloud/folders/:folderId/chat/messages?after=&limit=&editedAfter=` | `requireAuth` + `canRead` |
|
|
| POST | `/api/cloud/folders/:folderId/chat/messages` | `requireAuth` + `canRead` (limiteur 20 / 10 s par compte) |
|
|
| PATCH | `/api/cloud/folders/:folderId/chat/messages/:id` | `requireAuth` + `canRead` + **auteur du message** (limiteur 20 / 10 s par compte) |
|
|
| PUT | `/api/cloud/folders/:folderId/chat/messages/:id/pin` | `requireAuth` + `canRead` (limiteur 20 / 10 s par compte) |
|
|
| GET | `/api/cloud/folders/:folderId/chat/pins` | `requireAuth` + `canRead` |
|
|
| DELETE | `/api/cloud/folders/:folderId/chat/messages/:id` | `requireAuth` + `canRead` (auteur ou gestionnaire du dossier, soft-delete) |
|
|
|
|
`GET .../chat/members` renvoie les membres du salon, c'est-à-dire les comptes qui
|
|
ont accès au dossier : propriétaire, titulaires d'une permission nominative non
|
|
expirée, rôle global `admin`, et tous les comptes actifs si le dossier est
|
|
`public` (prénom, nom, rôle, présence d'avatar, `last_login_at`).
|
|
|
|
**Édition.** `PATCH .../chat/messages/:id` réécrit le corps du message et pose
|
|
`edited_at`. Seul l'auteur peut le faire, sans limite de temps : le filtre
|
|
`user_id` est porté par la requête SQL, donc un message d'autrui renvoie le
|
|
même `404` qu'un message inexistant. Le gestionnaire du dossier peut supprimer
|
|
un message, mais pas le réécrire à la place de son auteur.
|
|
|
|
**Épinglage.** `PUT .../chat/messages/:id/pin` bascule `is_pinned` en base
|
|
(bascule atomique, safe face à deux clics croisés). Plusieurs messages peuvent
|
|
être épinglés en même temps dans un même salon. Tout membre du salon peut
|
|
épingler et désépingler, y compris un message qu'il n'a pas écrit. La lecture
|
|
dédiée `GET .../chat/pins` est nécessaire parce que le curseur `after` ne
|
|
remonte que les messages plus récents : un épinglage posé sur un ancien
|
|
message resterait invisible sans elle.
|
|
|
|
**Synchronisation.** `GET .../chat/messages` accepte deux curseurs : `after`
|
|
(identifiant, messages plus récents) et `editedAfter` (horodatage, messages
|
|
réécrits depuis). Le second rattrape les réécritures d'anciens messages, que le
|
|
premier ne peut pas voir. `edited_at` est null pour un message jamais modifié.
|
|
|
|
Le curseur d'édition est un horodatage de la base au format
|
|
`AAAA-MM-JJTHH:MM:SS.ffffff`, et non un horodatage ISO : il est renvoyé tel quel
|
|
par la réponse (`cursor`) et doit être renvoyé tel quel par le client. Comparer
|
|
une chaîne ISO (UTC) à un `DATETIME` stocké en heure locale décalerait la
|
|
fenêtre de la différence de fuseau. Le serveur calcule son curseur **avant** la
|
|
requête de lecture : une réécriture survenue entre les deux porte un
|
|
horodatage postérieur au curseur, elle sera donc vue au tour suivant plutôt que
|
|
perdue. Une valeur qui ne respecte pas le format est ignorée, le serveur
|
|
utilise alors le sien.
|
|
|
|
### 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` |
|
|
| `007_chat.sql` | `chat_messages` (salon global, auteur `ON DELETE SET NULL`) |
|
|
| `008_user_preferences.sql` | préférences d'affichage, `user_file_stars`, `chat_reads` |
|
|
| `009_chat_edits_and_pins.sql` | `chat_messages.edited_at`, `chat_messages.is_pinned`, index `idx_chat_messages_pinned`, `idx_chat_messages_edited` |
|
|
|
|
Tables actives : `users, user_sessions, folders, folder_permissions, files,
|
|
media_metadata, file_variants, user_avatars, chat_messages, storage_locations,
|
|
settings, password_reset_tokens, email_change_requests, audit_logs,
|
|
user_file_stars, chat_reads`.
|
|
|
|
## 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": "…" } }
|
|
```
|