* Validate Content-Length on single-part upload route against user limit * Check total expected size on chunked upload session creation * Re-evaluate user limit at finalization to reject dynamic quota reductions * Clean up temporary files on payload size rejection (413) * Add 60-second polling interval for periodic fetching of messages and images --------- Co-authored-by: xEsiah <[email protected]> Reviewed-on: #20 Reviewed-by: Esiah <[email protected]> Co-authored-by: Gitea Actions <-[email protected]>
13 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) |
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/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= |
| 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/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 |
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/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": "…" } }