Files
CoHaiSe-CLOUD/docs/api.md
T
Esiah f564908650 refactor: aplatir backend/cloud et frontend/cloud
Le niveau `cloud` etait redondant : il ne reste qu'une seule application.

- backend/cloud/* -> backend/*, frontend/cloud/* -> frontend/*
- workspaces npm : frontend et backend ; reference tsconfig ./backend
- extends tsconfig.base corrige (../ au lieu de ../../)
- docker-compose : APP_DIR backend/frontend, montage ./backend/migrations
- deploy.yml : reconstruit aussi l'image migrate
- chemins mis a jour dans les docs, le Makefile et docker/README.md
2026-10-16 11:50:55 +02:00

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

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 :

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