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:
@@ -0,0 +1,75 @@
|
||||
# Agents — CoHaiSe Cloud
|
||||
|
||||
Conventions pour reprendre ce dépôt seul. Démarrage rapide : `README.md`.
|
||||
Détails : `architecture.md`, `api.md`, `deployment.md`, `security.md`.
|
||||
|
||||
## Commandes
|
||||
|
||||
| Action | Commande |
|
||||
| --- | --- |
|
||||
| Lever l'ensemble | `make up` |
|
||||
| Dev front | `make dev` (Vite 5174 → proxy 3101) |
|
||||
| Vérifier | `make check` (typecheck + build) |
|
||||
| Republier le front | `make front` |
|
||||
| Migrations | `make migrate` / `--check` via `docker compose run --rm migrate …` |
|
||||
| Sauvegarder | `make backup` |
|
||||
| Comptes | `make admin ARGS="--email … --first … --last …"` |
|
||||
| Journal / état | `make logs`, `make ps` |
|
||||
| Santé | `curl -I http://localhost:8083/healthz` |
|
||||
|
||||
`make check` est le seul filet de sécurité automatique (ni linter, ni tests, ni
|
||||
CI). L'exécuter avant de déclarer un travail fini.
|
||||
|
||||
## Règles du dépôt
|
||||
|
||||
1. **Ne pas lire `.env`** : secrets de production. Écrire un `SESSION_SECRET`
|
||||
manquant est autorisé ; le diffuser, non.
|
||||
2. **Ne pas committer ni pousser** sans demande explicite.
|
||||
3. **Pas de `down -v`, pas de suppression de volume** : `db_data` porte les
|
||||
données, `media_data` les fichiers.
|
||||
4. **Ne jamais modifier une migration déjà appliquée** : nouveau fichier numéroté
|
||||
seulement. Le checksum bloquerait le démarrage.
|
||||
5. **API admin** : les routes `/api/cloud/admin/*` existent (UI Administration).
|
||||
La CLI (`make admin`) reste pour l'amorçage et les cas hors ligne.
|
||||
6. **Chemin disque** : toujours via `storage.ts` (`resolveInside`), jamais par
|
||||
concaténation depuis une entrée utilisateur.
|
||||
7. **404 plutôt que 403** sur une ressource non accessible : ne pas introduire
|
||||
d'énumération.
|
||||
8. **CSP stricte** : pas de script en ligne dans `index.html` (utiliser un
|
||||
fichier dans `public/`, comme `theme.js`).
|
||||
|
||||
## Conventions
|
||||
|
||||
- TypeScript strict, project references racine.
|
||||
- Hono + Zod : toute route avec corps passe par un schéma Zod dédié.
|
||||
- Erreurs : `AppError` + codes (`errors.ts`) — jamais `throw` brut, jamais de
|
||||
détail de schéma dans une 500.
|
||||
- SQL : requêtes préparées uniquement, pas de `raw()` hors DDL.
|
||||
- Front : un seul client HTTP (`frontend/cloud/src/lib/api.ts`),
|
||||
`credentials: "same-origin"`. React Router 7 (`App.tsx`) + `AppShell`, contexte
|
||||
de session dans `lib/session.tsx`.
|
||||
- `.editorconfig` : 2 espaces, LF, UTF-8.
|
||||
|
||||
## Design system
|
||||
|
||||
`frontend/shared` (`@cohaise/ui`) vit dans ce dépôt.
|
||||
|
||||
- `tokens.css` est la source unique des couleurs et typographies ; ne pas coder
|
||||
de couleur en dur ailleurs.
|
||||
- Un composant propre à une page se développe dans `frontend/cloud`, pas dans le
|
||||
design system.
|
||||
- Palette : accent carmin `#b71c1c`, destructif rouge `#d32f2f`/`#ef4444`,
|
||||
avertissement jaune. Aucune orange.
|
||||
|
||||
- **Aucun commit** : rien n'est encore historié, tout est untracked.
|
||||
|
||||
## Pièges
|
||||
|
||||
- **`.env` ≠ `.env.example`** : comparer avant de conclure à un bug de port.
|
||||
- **README de paquet périmés** — utiliser ce dossier `docs/`.
|
||||
- **Build Docker et DNS** : les `build:` passent par `network: host` ; si `npm ci`
|
||||
échoue par `EAI_AGAIN`, le résolveur du démon est en cause.
|
||||
- **Limitation de débit active** (applicatif + nginx) : un test en rafale peut
|
||||
recevoir `419`/`503` côté API ou `503` nginx — ce n'est pas un bug.
|
||||
- Après `make up`, vérifier l'ordre : `migrate` doit être `exited (0)` avant que
|
||||
`api` ne devienne `healthy`.
|
||||
+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": "…" } }
|
||||
```
|
||||
@@ -0,0 +1,96 @@
|
||||
# Architecture — CoHaiSe Cloud
|
||||
|
||||
Fichiers et médias : arborescence de dossiers, envoi, téléchargement, corbeille,
|
||||
recherche, galerie, partage nominatif, comptes et administration. Une API
|
||||
Node/TypeScript, une base MariaDB, un stockage de fichiers monté en volume.
|
||||
|
||||
## Pile
|
||||
|
||||
| Élément | Où |
|
||||
| --- | --- |
|
||||
| React 19 + Vite 8 + Tailwind 4 + react-router-dom 7 | `frontend/cloud` |
|
||||
| Hono | `backend/cloud/src/index.ts` (`@cohaise/server` pour le socle) |
|
||||
| MariaDB (`mysql2`) | `backend/shared/src/db.ts` |
|
||||
| Nodemailer | `backend/shared/src/mail.ts` |
|
||||
| sharp (vignettes) | `backend/cloud/src/media.ts` |
|
||||
| Validation Zod | `backend/shared/src/config.ts` et chaque route |
|
||||
|
||||
## Découpage
|
||||
|
||||
```
|
||||
backend/shared/ @cohaise/server : config, db, mail, ratelimit, http, service, auth, errors
|
||||
backend/cloud/ routes/, access.ts, storage.ts, media.ts, cli.ts
|
||||
backend/cloud/migrations/ 000 … 006
|
||||
frontend/shared/ @cohaise/ui : Design System (boutons, cartes, champs, spinner)
|
||||
frontend/cloud/ router + AppShell + pages/
|
||||
docker/ Dockerfile(.app/.api), nginx/, publish.sh
|
||||
```
|
||||
|
||||
`backend/shared` est générique (sessions, erreurs, migrations, courriel,
|
||||
limitation de débit) ; `backend/cloud` porte le métier : droits, quotas, chemins
|
||||
disque, traitement média.
|
||||
|
||||
## Chaîne de démarrage
|
||||
|
||||
`docker-compose.yml` — projet **`cohaise-cloud`**, 5 services :
|
||||
|
||||
```
|
||||
db ──healthy──▶ migrate (runMigrations + assertNoDrift, puis s'arrête)
|
||||
│
|
||||
└──service_completed_successfully──▶ api ──▶ nginx
|
||||
app-build (publish.sh, terminé avant nginx)
|
||||
```
|
||||
|
||||
- `migrate` monte `./backend/cloud/migrations:/migrations:ro`.
|
||||
- `api` refuse de démarrer si une migration appliquée a été modifiée (dérive de
|
||||
checksum). `onReady` purge les sessions et la corbeille expirées.
|
||||
- volumes : `app_data` (HTML), `db_data` (MariaDB), `media_data`.
|
||||
|
||||
## API et front
|
||||
|
||||
- API `/api/cloud` : voir [`api.md`](api.md).
|
||||
- Front : React Router (`frontend/cloud/src/App.tsx`) avec gardes
|
||||
`RequireAuth` / `RequireReady` / `RequireAdmin` et `AppShell`
|
||||
(`components/AppShell.tsx`) : navigation latérale, en-tête, contenu.
|
||||
- Pages : `Login`, `ForgotPassword`, `ResetPassword`, `ConfirmEmail`,
|
||||
`ChangePassword`, `Browser`, `Search`, `Gallery`, `Trash`, `Profile`,
|
||||
`Admin` (comptes / stockage / journal).
|
||||
- Client HTTP unique `lib/api.ts` (base `/api/cloud`, `same-origin`) ; contexte
|
||||
de session `lib/session.tsx` ; dialogues réutilisables dans
|
||||
`components/dialogs.tsx`.
|
||||
- En-têtes nginx : CSP stricte, HSTS, `nosniff`, `Referrer-Policy`,
|
||||
`Permissions-Policy` (`docker/nginx/snippets/`). `X-Frame-Options` est
|
||||
remplacé par `frame-ancestors 'none'` dans la CSP.
|
||||
- Dev : Vite **5174**, proxy `/api` → `http://127.0.0.1:3101`. Prod : nginx sert
|
||||
le SPA avec repli `try_files … @spa` (liens profonds pris en charge).
|
||||
|
||||
## Sessions
|
||||
|
||||
- Cookie `cohaise_session` : `httpOnly`, `SameSite=Lax`, `path=/`, `secure`
|
||||
déduit du schéma réel (et de `TRUST_PROXY`).
|
||||
- En base, uniquement le **SHA-256** du jeton. TTL `SESSION_TTL_HOURS`.
|
||||
- Changement de mot de passe ⇒ révocation des autres sessions ; gestion fine
|
||||
depuis la page compte.
|
||||
|
||||
## Stockage et médias
|
||||
|
||||
- `MEDIA_DIR=/data/media/originals`, `VARIANT_DIR=/data/media/variants`.
|
||||
- Chemin physique `${MEDIA_DIR}/<slug>/<uuid><ext>` (`storage.ts`), nom affiché
|
||||
jamais dans le chemin.
|
||||
- `media.ts` : classification (`image/video/audio/document/archive/other`),
|
||||
vignette (`sharp`, seuil 480 px) écrite dans `VARIANT_DIR`, métadonnées dans
|
||||
`media_metadata` / `file_variants`. Indexation **best-effort** après upload.
|
||||
- Avatars dans `user_avatars`.
|
||||
|
||||
## Corbeille
|
||||
|
||||
Suppression douce (`deleted_at`). `purgeExpiredTrash` (démarrage + accès) purge
|
||||
au-delà de `trash_retention_days`. Restauration et purge manuelles exposées via
|
||||
`/trash`.
|
||||
|
||||
## Limites connues
|
||||
|
||||
- Upload séquentiel par `<input type=file>` : pas de drag & drop, pas de
|
||||
reprise de transfert, pas de multipart.
|
||||
- `docker/README.md` (et tout README de paquet) peut décrire un état antérieur :
|
||||
se fier à `docs/`.
|
||||
@@ -0,0 +1,191 @@
|
||||
# Déploiement — CoHaiSe Cloud
|
||||
|
||||
## Démarrer
|
||||
|
||||
```sh
|
||||
cp .env.example .env # renseigner mots de passe + SESSION_SECRET (≥ 32 car.)
|
||||
make up # db → migrate → api → nginx, front compris
|
||||
make front # reconstruire et republier le front
|
||||
```
|
||||
|
||||
Réponse sur **`http://localhost:8083`**.
|
||||
|
||||
La configuration est validée **avant** l'ouverture d'aucun port : si une variable
|
||||
manque ou est mal formée, le process s'arrête en listant exactement ce qui
|
||||
pose problème (`backend/shared/src/config.ts`).
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Rôle | Défaut |
|
||||
| --- | --- | --- |
|
||||
| `COHAISE_HTTP_PORT` | port nginx | `8083` |
|
||||
| `COHAISE_API_PORT` | port API | `3101` |
|
||||
| `COHAISE_DB_PORT` | port MariaDB | `3407` |
|
||||
| `CLOUD_DATABASE` / `CLOUD_DB_USER` / `CLOUD_DB_PASSWORD` | base applicative | — |
|
||||
| `CLOUD_DB_ROOT_PASSWORD` | root, réservé aux sauvegardes | — |
|
||||
| `CLOUD_DB_CONNECTION_LIMIT` | taille du pool | `8` |
|
||||
| `SESSION_SECRET` | **obligatoire**, ≥ 32 car. | — |
|
||||
| `SESSION_TTL_HOURS` | durée de session | `336` |
|
||||
| `PUBLIC_ORIGIN` | **obligatoire**, URL absolue servant aux liens courriel | — |
|
||||
| `CLOUD_CORS_ORIGIN` | origines CORS (vide = CORS off) | vide |
|
||||
| `SMTP_HOST` | **obligatoire**, relais d'envoi | — |
|
||||
| `SMTP_PORT` | port SMTP | `587` |
|
||||
| `SMTP_USER` / `SMTP_PASSWORD` | authentification (vides = relais local) | vide |
|
||||
| `SMTP_FROM` | adresse d'expédition | — |
|
||||
| `SMTP_SECURE` | TLS implicite (port 465) | `false` |
|
||||
| `RATE_LIMIT_LOGIN_MAX` | tentatives par fenêtre | `10` |
|
||||
| `RATE_LIMIT_LOGIN_WINDOW_MS` | largeur de fenêtre | `60000` |
|
||||
| `LOG_LEVEL` | `silent…debug` | `info` |
|
||||
| `TRUST_PROXY` | croire `X-Forwarded-*` | `true` |
|
||||
|
||||
> `PUBLIC_ORIGIN`, `SMTP_HOST` et `SMTP_FROM` sont **obligatoires** : sans eux
|
||||
> l'API refuse de démarrer (courriel de réinitialisation / confirmation).
|
||||
|
||||
Variables fixes posées par compose : `PORT=8080`, `DB_HOST=db`,
|
||||
`MEDIA_DIR=/data/media/originals`, `VARIANT_DIR=/data/media/variants`,
|
||||
`NODE_ENV=production`, `TZ=Europe/Paris`.
|
||||
|
||||
> **Écueil** : si une clé attendue manque dans `.env`, compose utilise
|
||||
> silencieusement son **défaut**. En cas de doute, comparer avec `.env.example` :
|
||||
> c'est la référence, pas `.env`.
|
||||
|
||||
## Services
|
||||
|
||||
| Service | Port | Santé | Rôle |
|
||||
| --- | --- | --- | --- |
|
||||
| `db` | `3407` | `healthcheck.sh --connect --innodb_initialized` | MariaDB, volume `db_data` |
|
||||
| `migrate` | — | — | joue les migrations manquantes, puis s'arrête |
|
||||
| `api` | `3101` | `GET :8080/healthz` (start 20 s) | Hono, volume `media_data` |
|
||||
| `nginx` | `8083` | `GET /healthz` | sert le front, proxy `/api/` |
|
||||
| `app-build` | — | — | build + publication atomique, `restart: "no"` |
|
||||
|
||||
Ordre garanti par `depends_on` : `migrate` attend `db` healthy, `api` attend
|
||||
`db` healthy **et** `migrate` terminé avec succès.
|
||||
|
||||
> **Images** : la configuration nginx (CSP/HSTS, `limit_req`, snippets) est
|
||||
> **copiée dans l'image**. Toute modification de `docker/nginx/` exige de
|
||||
> reconstruire le service `nginx`. L'API embarque `sharp` (binaires précompilés
|
||||
> musl attendus sur Alpine) ; vérifier le démarrage après un changement de base.
|
||||
|
||||
## Commandes
|
||||
|
||||
```sh
|
||||
make help # liste complète
|
||||
make ps / make logs # état et journaux
|
||||
make front # reconstruire + republier le front
|
||||
make db # redémarrer la base
|
||||
make migrate # rejouer explicitement les migrations (hors démarrage)
|
||||
make backup # dump horodaté → ./backups/cloud-<stamp>.sql.gz
|
||||
make admin ARGS=... # créer / réinitialiser un compte
|
||||
make dev # Vite 5174, proxy /api → 3101
|
||||
make check # typecheck + build
|
||||
make down # arrêt, volumes conservés
|
||||
```
|
||||
|
||||
`make backup` lit le mot de passe **dans le conteneur** : il ne passe ni par la
|
||||
commande, ni par le dépôt.
|
||||
|
||||
## Migrations
|
||||
|
||||
- Fichiers `NNN_nom.sql`, tri lexical, appliqués une seule fois, checksum
|
||||
SHA-256 enregistré dans `schema_migrations`.
|
||||
- **Une migration appliquée ne se modifie jamais** : une correction passe par
|
||||
un nouveau numéro. Si le contenu d'un fichier déjà joué change,
|
||||
`assertNoDrift()` refuse le démarrage de l'API.
|
||||
- Application automatique au démarrage, ou manuelle :
|
||||
|
||||
```sh
|
||||
make migrate
|
||||
docker compose run --rm migrate node dist/cli.js --dir /migrations --dry-run
|
||||
docker compose run --rm migrate node dist/cli.js --dir /migrations --check # 1 s'il en reste
|
||||
```
|
||||
|
||||
Codes de sortie : `0` OK, `1` erreur ou dérive, `2` configuration.
|
||||
|
||||
## Comptes
|
||||
|
||||
```sh
|
||||
make admin ARGS="--email [email protected] --first Jean --last Dupont"
|
||||
make admin ARGS="--email [email protected] --reset"
|
||||
```
|
||||
|
||||
Options : `--email` (obligatoire), `--first`/`--last` (obligatoires à la
|
||||
création), `--role` (défaut `admin`), `--password`, `--reset`. Sans
|
||||
`--password`, le mot de passe est généré (18 caractères) et affiché **une
|
||||
seule fois**. Un compte créé a `must_change_password=1`.
|
||||
|
||||
Aucune route HTTP ne crée un compte.
|
||||
|
||||
## Sauvegarde et restauration
|
||||
|
||||
```sh
|
||||
make backup # dump compressé dans ./backups/
|
||||
```
|
||||
|
||||
Le dossier `backups/` est gitignoré. Pour restaurer : `gunzip -c <dump> | make
|
||||
… ` via un conteneur `db` en service — opération manuelle, à faire hors
|
||||
démarrage automatique.
|
||||
|
||||
## Exposition — Cloudflare Tunnel
|
||||
|
||||
L'application est prête à être publiée derrière un tunnel Cloudflare : aucune
|
||||
adresse ni aucun domaine n'est codé en dur.
|
||||
|
||||
- `nginx` écoute sur `COHAISE_HTTP_PORT` (8083 par défaut) avec `server_name _` :
|
||||
n'importe quel `Host` est accepté.
|
||||
- `cloudflared` publie le service local (`http://127.0.0.1:8083`).
|
||||
- Renseigner l'origine publique **exacte** vue par les navigateurs :
|
||||
`PUBLIC_ORIGIN=https://cloud.example.com`. Elle sert aux liens envoyés par
|
||||
courriel (réinitialisation, confirmation).
|
||||
- `CLOUD_CORS_ORIGIN` ne sert qu'à un front servi depuis une autre origine ;
|
||||
avec un tunnel unique, laisser vide.
|
||||
- Les cookies de session passent en `Secure` dès que le proxy annonce
|
||||
`X-Forwarded-Proto: https` (cloudflared le fait) : garder `TRUST_PROXY=true`.
|
||||
- Certificat et HSTS sont assurés en amont par Cloudflare — ne pas exposer
|
||||
directement le port 8083 sur Internet.
|
||||
|
||||
Exemple `~/.cloudflared/config.yml` :
|
||||
|
||||
```yaml
|
||||
tunnel: <id-tunnel>
|
||||
credentials-file: /home/<utilisateur>/.cloudflared/<id-tunnel>.json
|
||||
ingress:
|
||||
- hostname: cloud.example.com
|
||||
service: http://127.0.0.1:8083
|
||||
- service: http_status:404
|
||||
```
|
||||
|
||||
Les ports `8083`, `3101` et `3407` sont publiés sur **127.0.0.1 uniquement** :
|
||||
rien n'est joignable depuis l'extérieur en dehors du tunnel.
|
||||
|
||||
## Intégration continue (Gitea Actions)
|
||||
|
||||
Le dépôt vit sur Gitea. **Gitea Actions** reprend la syntaxe GitHub Actions,
|
||||
mais exige sur l'instance : un **runner self-hosted** enregistré
|
||||
(Administration → Actions → Runners) et les **Actions activées** sur le dépôt
|
||||
(Paramètres du dépôt → section Actions/Unités).
|
||||
|
||||
| Workflow | Déclencheur | Rôle |
|
||||
| --- | --- | --- |
|
||||
| `deploy.yml` | push `main` (backend/frontend/docker) ou manuel | `git pull`, `make check`, `make front`, rebuild `api`+`nginx` |
|
||||
| `pr.yml` | push hors `main` | ouvre une PR vers `main` via l'API REST Gitea (`curl` + `python3`) |
|
||||
| `renovate.yml` | hebdomadaire ou manuel | lance Renovate contre Gitea |
|
||||
|
||||
À adapter avant activation :
|
||||
|
||||
- **Chemin de déploiement** : `deploy.yml` lit le secret `DEPLOY_DIR` ; s'il
|
||||
n'est pas défini, la valeur par défaut `/srv/apps/cohaise-cloud/CoHaiSe-CLOUD`
|
||||
est utilisée. Créer le secret `DEPLOY_DIR` une fois le chemin réel connu.
|
||||
- **Label du runner** : `runs-on: self-hosted` ; si le runner porte des labels
|
||||
additionnels (ex. `gitea`, `docker`), les renseigner.
|
||||
- **Secrets** (Paramètres → Actions → Secrets) :
|
||||
- `pr.yml` utilise le `GITHUB_TOKEN` fourni par Gitea Actions. Si les PR sont
|
||||
refusées, créer un secret `PAT` (jeton personnel Gitea, portée `repo`) et
|
||||
remplacer `secrets.GITHUB_TOKEN`.
|
||||
- `renovate.yml` exige `RENOVATE_TOKEN` : jeton personnel Gitea avec la portée
|
||||
`repo`.
|
||||
- `python3` doit être présent sur le runner (Debian l'a par défaut).
|
||||
|
||||
**dependabot.yml n'est pas supporté par Gitea** : Renovate le remplace, avec
|
||||
`renovate.json` (groupes npm backend/frontend, images Docker) et le workflow
|
||||
`renovate.yml` (image `ghcr.io/renovatebot/renovate` en `RENOVATE_PLATFORM=gitea`).
|
||||
@@ -0,0 +1,78 @@
|
||||
# Sécurité — CoHaiSe Cloud
|
||||
|
||||
## En place
|
||||
|
||||
### Comptes et sessions
|
||||
|
||||
| Mesure | Détail |
|
||||
| --- | --- |
|
||||
| Mots de passe | `scrypt` natif `node:crypto` (`N=16384, r=8, p=1`, keylen 64, sel 16 o.), comparaison `timingSafeEqual` |
|
||||
| Stockage session | jeton aléatoire 32 o. côté client, **SHA-256** en base |
|
||||
| Cookie | `cohaise_session`, `httpOnly`, `SameSite=Lax`, `path=/`, `secure` selon le schéma réel |
|
||||
| Expiration | `SESSION_TTL_HOURS` (336 h) ; `revoked_at`, `is_active`, `deleted_at` vérifiés à chaque résolution |
|
||||
| Révocation | logout, purge au démarrage, **toutes les autres sessions** au changement de mot de passe, gestion des sessions ouvertes depuis le compte |
|
||||
| Anti-énumération | hash factice pour une adresse inconnue ; les flux « mot de passe oublié » répondent toujours `{ ok: true }` sans révéler l'existence du compte |
|
||||
| Jetons à usage unique | réinitialisation de mot de passe et changement d'adresse stockés **hachés**, avec expiration |
|
||||
| Changement d'adresse | mot de passe actuel exigé, confirmation **à la nouvelle adresse** avant application |
|
||||
|
||||
### Limitation de débit
|
||||
|
||||
- **Applicatif** : `createRateLimiter` (`backend/shared/src/ratelimit.ts`) par IP
|
||||
sur `auth/login`, `account/forgot-password`, `account/reset-password`,
|
||||
`account/email-change`. Réglages `RATE_LIMIT_LOGIN_MAX` (10) et
|
||||
`RATE_LIMIT_LOGIN_WINDOW_MS` (60 s).
|
||||
- **Edge nginx** : zones `limit_req` `login` (15 r/min, burst 5) et `api`
|
||||
(60 r/s, burst élevé) — voir `docker/nginx/cloud.conf`.
|
||||
|
||||
### 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`). Lecture : propriétaire, permission
|
||||
`folder_permissions` (`read`/`write`/`admin`), ou dossier `public`. Écriture :
|
||||
`write`/`admin`. **404 plutôt que 403** : jamais d'indice sur l'existence d'une
|
||||
ressource.
|
||||
|
||||
### Courriel
|
||||
|
||||
Nodemailer (`backend/shared/src/mail.ts`) avec `SMTP_HOST`. `PUBLIC_ORIGIN`
|
||||
(obligatoire) construit les liens de réinitialisation et de confirmation ;
|
||||
aucun HTML utilisateur n'est injecté dans les messages.
|
||||
|
||||
### Transport et enveloppe
|
||||
|
||||
- En-têtes API : `x-request-id`, `nosniff`, `referrer-policy: same-origin`.
|
||||
- En-têtes nginx (`docker/nginx/snippets/security-headers.conf`) :
|
||||
`Content-Security-Policy` (**`default-src 'self'`, `frame-ancestors 'none'`**,
|
||||
pas de `unsafe-inline`), `Strict-Transport-Security`,
|
||||
`X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`.
|
||||
- SQL : requêtes préparées uniquement, `multipleStatements: false`.
|
||||
- CORS désactivé par défaut (`CLOUD_CORS_ORIGIN` vide).
|
||||
|
||||
> Le script d'amorçage du thème est sorti de `index.html` vers
|
||||
> `public/theme.js` exprès : la CSP n'autorise pas `unsafe-inline`.
|
||||
|
||||
### Stockage des fichiers
|
||||
|
||||
- Chemin physique dérivé du slug + UUID, **jamais** du nom affiché ;
|
||||
`resolveInside()` rejette toute cible hors `MEDIA_DIR`.
|
||||
- Écriture temporaire `.upload-<uuid>` puis `rename()` atomique ; copie **en
|
||||
flux** (un fichier surdimensionné est coupé, pas bufferisé).
|
||||
- Téléchargement : `content-disposition: attachment`, `nosniff`,
|
||||
`cache-control: private, max-age=0, must-revalidate`.
|
||||
|
||||
## Hors périmètre (assumé)
|
||||
|
||||
| Sujet | État |
|
||||
| --- | --- |
|
||||
| CSRF | pas de jeton CSRF — reposé sur `SameSite=Lax` + `same-origin` ; acceptable tant que le front et l'API partagent l'origine |
|
||||
| HTTPS | nginx écoute le 80 ; le terminus TLS est le tunnel cloudflared, hors dépôt |
|
||||
| Chiffrement au repos | fichiers en clair ; seuls mots de passe, sessions et jetons sont dérivés |
|
||||
| Détection antivirus | aucune analyse des fichiers envoyés |
|
||||
|
||||
## À ne pas faire
|
||||
|
||||
- Ne jamais renvoyer de stack ou de détail de schéma au client.
|
||||
- Ne jamais ajouter de route qui prend un chemin disque en paramètre : passer
|
||||
par `storage.ts`.
|
||||
- Ne jamais persister le jeton de session en clair, ni logger un mot de passe.
|
||||
- Ne pas réintroduire de script inline dans `index.html` (casserait la CSP).
|
||||
@@ -0,0 +1,59 @@
|
||||
# Standards — CoHaiSe Cloud
|
||||
|
||||
Conventions appliquées dans ce dépôt.
|
||||
|
||||
## Formatage
|
||||
|
||||
`.editorconfig` : UTF-8, LF, indentation 2 espaces, `trim_trailing_whitespace`
|
||||
désactivé pour les `.md`. Aucun Prettier/ESLint installé.
|
||||
|
||||
## Palette
|
||||
|
||||
Source unique : `frontend/shared/src/styles/tokens.css`.
|
||||
|
||||
| Jeton | Rôle | Valeur |
|
||||
| --- | --- | --- |
|
||||
| `--cohaise-accent` | marque : liens, focus, primaire | carmin `#b71c1c` |
|
||||
| `--cohaise-destructive` | suppression, erreurs, champs invalides | `#d32f2f` clair / `#ef4444` sombre |
|
||||
| `--cohaise-destructive-foreground` | texte posé dessus | `#ffffff` clair / `#1a0505` sombre |
|
||||
| `--cohaise-warning` | avertissement, badges d'état | jaune `yellow-500` |
|
||||
|
||||
Règles :
|
||||
|
||||
- **Aucune orange** : `--cohaise-amber-*` a été retiré de la palette. Ne pas le
|
||||
réintroduire.
|
||||
- `tokens.css` est la source unique des couleurs : toute couleur ajoutée doit être
|
||||
déclarée là, puis exposée via `theme.css`.
|
||||
- Toute couleur ajoutée doit passer deux contrastes : comme **texte** sur le fond
|
||||
d'application, et comme **fond** avec un texte posé dessus (≥ 4.5:1).
|
||||
- Une règle sombre va dans le bloc `.dark`, jamais en
|
||||
`@media (prefers-color-scheme: dark)` : la préférence utilisateur prime.
|
||||
|
||||
## Typographies
|
||||
|
||||
Poppins (texte), Orbitron et Cinzel (display), JetBrains Mono (code) —
|
||||
woff2 hébergés dans `frontend/shared/fonts/`, jamais par CDN.
|
||||
|
||||
## Composants
|
||||
|
||||
`@cohaise/ui` : `Button`, `Card`, `Input`, `Skeleton`, `Spinner`, `cn`.
|
||||
|
||||
- Les composants du design system ne connaissent **jamais** le métier du Cloud.
|
||||
- Une variante propre à cette app se développe dans `frontend/cloud`, pas dans
|
||||
`frontend/shared`.
|
||||
|
||||
## Côté serveur
|
||||
|
||||
- Toute entrée validée par Zod, tout chemin disque via `storage.ts`.
|
||||
- `AppError` + code stable ; les erreurs 500 renvoient un message générique.
|
||||
- Journal JSON (`LOG_LEVEL`), audit en base pour les actions sensibles.
|
||||
- Cookies : `httpOnly`, `SameSite=Lax`, `secure` selon le schéma réel.
|
||||
|
||||
## Git et exploitation
|
||||
|
||||
| Élément | Attendu |
|
||||
| --- | --- |
|
||||
| `shared` | vit dans ce dépôt, cycle de vie commun |
|
||||
| Port HTTP | `8083` (`COHAISE_HTTP_PORT`) |
|
||||
| Dépôt | autonome, importance égale front et back |
|
||||
| `.env` | jamais versionné (`.env.example` seulement) |
|
||||
@@ -0,0 +1,93 @@
|
||||
# Workflow — CoHaiSe Cloud
|
||||
|
||||
## Boucle de développement
|
||||
|
||||
```sh
|
||||
make dev # Vite sur http://localhost:5174, proxy /api → 127.0.0.1:3101
|
||||
```
|
||||
|
||||
Le front tourne hors Docker ; l'API et la base doivent être levées :
|
||||
|
||||
```sh
|
||||
make up # db + migrate + api (+ nginx si besoin)
|
||||
```
|
||||
|
||||
Le proxy `vite.config.ts` envoie `/api` vers `3101`, donc les appels
|
||||
`fetch('/api/cloud/…')` du code source fonctionnent à l'identique en dev et en
|
||||
prod.
|
||||
|
||||
## Vérification
|
||||
|
||||
```sh
|
||||
make check # npm run typecheck puis npm run build
|
||||
curl -I http://localhost:8083/healthz
|
||||
curl -s http://localhost:3101/healthz
|
||||
```
|
||||
|
||||
Il n'y a **ni linter, ni framework de test, ni CI** : `typecheck` + `build`
|
||||
sont les seules garanties automatiques. `.editorconfig` porte les conventions.
|
||||
|
||||
Après un changement de `docker/nginx/cloud.conf` : l'image doit être
|
||||
reconstruite (`docker compose build nginx && docker compose up -d nginx`) — le
|
||||
fichier est copié dans l'image, pas monté.
|
||||
|
||||
## Modifier une route
|
||||
|
||||
1. Schéma d'entrée : Zod dans `backend/cloud/src/routes/<entity>.ts`.
|
||||
2. Droits : passer par `backend/cloud/src/access.ts` (jamais par un paramètre
|
||||
venu du client).
|
||||
3. Réponse : renvoyer **404** si la ressource n'est pas censée exister pour ce
|
||||
compte, 403 seulement pour une règle explicite.
|
||||
4. Erreur métier : `AppError` depuis `backend/shared/src/errors.ts`.
|
||||
5. Audit si l'action est sensible (`audit()` dans `access.ts`).
|
||||
6. `make check`, puis redémarrage de l'API (`docker compose up -d api`).
|
||||
|
||||
## Modifier le schéma
|
||||
|
||||
1. Écrire `backend/cloud/migrations/00N_….sql` (número suivant, jamais éditer
|
||||
un fichier déjà appliqué).
|
||||
2. Vérifier : `docker compose run --rm migrate node dist/cli.js --dir /migrations --check`
|
||||
3. Appliquer : `make migrate` ou redémarrage de l'API.
|
||||
4. Décrire la migration dans `docs/api.md` (tableau des migrations).
|
||||
|
||||
Le DDL MariaDB n'est pas transactionnel : une migration interrompue peut
|
||||
laisser la base à moitié migrée. Dans ce cas, corriger par une **nouvelle**
|
||||
migration, pas en éditant l'ancienne (le checksum bloquerait le démarrage).
|
||||
|
||||
## Modifier le design system
|
||||
|
||||
`frontend/shared` (`@cohaise/ui`) vit dans ce dépôt.
|
||||
|
||||
- `tokens.css` porte les couleurs et typographies ; ne pas en coder ailleurs.
|
||||
- Après modification : `npm run build --workspace=frontend/shared && make front`.
|
||||
|
||||
## Où changer quoi
|
||||
|
||||
| Besoin | Fichier |
|
||||
| --- | --- |
|
||||
| Droit d'accès à un dossier/fichier | `backend/cloud/src/access.ts` |
|
||||
| Taille/quota par défaut | migration `004`, table `users` / `settings` |
|
||||
| Chemin physique des fichiers | `backend/cloud/src/storage.ts` |
|
||||
| En-têtes, CORS, healthz | `backend/shared/src/http.ts` |
|
||||
| Durée de session | `SESSION_TTL_HOURS` |
|
||||
| Port | `COHAISE_HTTP_PORT` (nginx), `COHAISE_API_PORT` (API) |
|
||||
| Interface (parcours dossiers) | `frontend/cloud/src/pages/Browser.tsx` |
|
||||
| Routes et gardes du front | `frontend/cloud/src/App.tsx` |
|
||||
| Couleurs / composants | `frontend/shared/src/styles/tokens.css` |
|
||||
|
||||
## Git
|
||||
|
||||
- Branche `main`, remote `origin https://git.cohaise.dev/Esiah/CoHaiSe-CLOUD.git`.
|
||||
- **Aucun commit pour l'instant** : l'historique est vierge.
|
||||
- `.gitignore` exclut `.env`, `.env.*` (sauf `.env.example`), `backups/`,
|
||||
`node_modules/`, `dist/`, `*.tsbuildinfo`.
|
||||
|
||||
## Pièges connus
|
||||
|
||||
1. **`.env` local désynchronisé** de `.env.example` : les clés `COHAISE_*`
|
||||
manquantes basculent silencieusement sur les défauts compose.
|
||||
2. **README de paquet** (`docker/README.md`, `backend/cloud/README.md`) : états
|
||||
antérieurs du dépôt. Se fier à ce dossier `docs/`.
|
||||
3. **Limitation de débit active** (applicatif + nginx) : une rafale peut renvoyer
|
||||
`419`/`503`.
|
||||
4. **CSP stricte** : aucun script inline dans `index.html` (voir `public/theme.js`).
|
||||
Reference in New Issue
Block a user