chore: initial import of CoHaiSe Cloud
PR — Ouverture automatique / create-pr (push) Failing after 1s
PR — Ouverture automatique / create-pr (push) Failing after 1s
Standalone files & media application: React/Vite frontend with the @cohaise/ui design system, Hono + MariaDB backend, nginx reverse proxy, Docker Compose stack, migrations 000-006, and project docs. Adds Gitea Actions workflows for deployment, automatic pull requests, and Renovate dependency updates.
This commit is contained in:
+140
@@ -0,0 +1,140 @@
|
||||
# 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/cloud/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/cloud/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/shared/src/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": "…" } }
|
||||
```
|
||||
Reference in New Issue
Block a user