chore: initial import of CoHaiSe Cloud
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:
2026-10-14 15:24:06 +02:00
commit cc397e96d8
113 changed files with 12678 additions and 0 deletions
+75
View File
@@ -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
View File
@@ -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": "…" } }
```
+96
View File
@@ -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/`.
+191
View File
@@ -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`).
+78
View File
@@ -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).
+59
View File
@@ -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) |
+93
View File
@@ -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`).