CD — Deployment / deploy (push) Successful in 34s
Split the monolithic backend (lib/, routes/, access.ts, storage.ts, media.ts) into a layered structure inspired by JeanXXIII-CRM: - config/: appConfig, db - middleware/: auth (session, roles, cookies) - models/: shared types - routes/: *Routes.ts (thin HTTP handlers) - services/: *Service.ts (business logic, one per domain) - utils/: errors, http, migrate, ratelimit, validators, service bootstrap Frontend likewise: services/*Service.ts + apiClient, contexts/, types/, utils/format. Route files now carry the "Routes" suffix; service files are named authService.ts, ratelimit.ts, etc. and live in their own files, frontend and backend separated. Updated docs and READMEs to reflect the new layout. Typecheck and builds pass. --------- Co-authored-by: xEsiah <[email protected]> Reviewed-on: #26 Reviewed-by: Esiah <[email protected]> Co-authored-by: Gitea Actions <-[email protected]>
239 lines
13 KiB
Markdown
239 lines
13 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) |
|
|
|
|
### Envoi resumable (gros fichiers)
|
|
|
|
Au-delà de la limite de corps de requête de Cloudflare (100 MB en Free/Pro), le
|
|
client découpe le fichier en morceaux de 50 MiB. Une session est créée en base,
|
|
le temporaire est préalloué sous `MEDIA_DIR/.uploads`, puis les morceaux sont
|
|
écrits à l'offset courant. La finalisation vérifie le nom et les droits une
|
|
dernière fois, calcule le SHA-256, publie le fichier et met à jour les quotas.
|
|
|
|
| Méthode | Chemin | Garde |
|
|
| --- | --- | --- |
|
|
| POST | `/api/cloud/uploads` | `requireAuth` (nom, `folderId`, `size`, `mimeType`) |
|
|
| GET | `/api/cloud/uploads/:id` | `requireAuth` (propriétaire de la session, donne l'offset de reprise) |
|
|
| PUT | `/api/cloud/uploads/:id/chunks` | `requireAuth` (corps brut, `Content-Length` obligatoire) |
|
|
| POST | `/api/cloud/uploads/:id/complete` | `requireAuth` (vérifie taille, nom, droits, quotas) |
|
|
| DELETE | `/api/cloud/uploads/:id` | `requireAuth` (annule et supprime le temporaire) |
|
|
|
|
Les sessions expirent après 24 h ; une purge au démarrage puis toutes les
|
|
heures supprime les temporaires orphelins. Un morceau interrompu ne fait pas
|
|
avancer le curseur : le client interroge `GET /uploads/:id` puis reprend à
|
|
l'offset exact.
|
|
|
|
### 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/services/auditService.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/services/auditService.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=` |
|
|
| Gros fichiers | au-delà de 90 MiB, le front bascule sur `/uploads` (morceaux de 50 MiB) pour rester sous la limite Cloudflare |
|
|
| Reprise | l'ID de session est conservé localement ; un envoi interrompu repart de `uploadedBytes` |
|
|
| 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/services/mailService.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` |
|
|
| `010_upload_sessions.sql` | `upload_sessions` (envoi resumable, temporaire préalloué, expiration) |
|
|
|
|
Tables actives : `users, user_sessions, folders, folder_permissions, files,
|
|
media_metadata, file_variants, user_avatars, chat_messages, upload_sessions,
|
|
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/utils/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": "…" } }
|
|
```
|