Files
CoHaiSe-CLOUD/docs/api.md
T
Gitea ActionsandEsiah f689ab4d57
CD — Deployment / deploy (push) Successful in 34s
refactor: restructure frontend and backend by domain services (#26)
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]>
2026-11-13 09:13:27 +00:00

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/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 :

{ "error": { "status": 404, "code": "NOT_FOUND", "message": "…", "requestId": "…" } }