Partage par lien, comptes Authentik, soumission et moderation de packs, prerequis des sondes ; corrige le lien casse vers le script de l'editeur

docs/COMPTES-ET-MODERATION.md

@@ -0,0 +1,92 @@
+# Comptes, partage et modération
+
+Trois fonctionnalités s'activent indépendamment. Aucune n'est obligatoire : sans base de
+données, sans OIDC et sans jeton Gitea, Enclume reste l'éditeur qui génère du CLAPI. C'est
+ce qui permet à n'importe qui de l'auto-héberger sans rien configurer.
+
+| Fonction | Ce qu'il faut | Sans ça |
+|---|---|---|
+| Partage par lien | `ENCLUME_DATABASE_URL` | bouton absent |
+| Comptes et projets enregistrés | base + OIDC | site utilisable, sans connexion |
+| Soumission de packs | base + OIDC | contributions par pull request uniquement |
+| Publication des packs acceptés | jeton Gitea | modération possible, publication non |
+
+`/sante` annonce l'état réel de chacune.
+
+## Authentik
+
+Un seul fournisseur est déclaré côté Enclume. C'est Authentik qui fédère GitHub, Google ou
+tout autre fournisseur social : en ajouter un plus tard ne demande aucun redéploiement.
+
+**Créer le fournisseur** — Applications → Fournisseurs → Créer → OAuth2/OpenID.
+
+- Type de client : **Confidentiel**
+- URI de redirection, en correspondance stricte : `https://<domaine>/connexion/retour`
+- Portées : `openid`, `email`, `profile`
+- Noter l'identifiant client et le secret
+
+**Créer l'application** — Applications → Applications → Créer. Le **slug** compte : c'est lui
+qui apparaît dans l'URL de découverte.
+
+```
+ENCLUME_OIDC_METADATA=https://authentik.<domaine>/application/o/<slug>/.well-known/openid-configuration
+ENCLUME_OIDC_CLIENT_ID=...
+ENCLUME_OIDC_CLIENT_SECRET=...
+```
+
+**Le groupe de modération.** Enclume lit la revendication `groups` du jeton, qu'Authentik
+n'envoie pas par défaut. Créer une correspondance de portée (Personnalisation → Property
+Mappings → Scope Mapping), nom de portée `groups`, expression :
+
+```python
+return {"groups": [group.name for group in request.user.ak_groups.all()]}
+```
+
+Puis ajouter cette portée au fournisseur, et créer un groupe `enclume-admins` dont tu es
+membre.
+
+Le temps de mettre ça en place, `[email protected]` donne l'accès
+à la modération sur la seule foi de l'adresse. À vider ensuite.
+
+## Le jeton Gitea
+
+Un jeton d'accès personnel sur le compte qui ouvrira les demandes de fusion, avec la portée
+`write:repository` sur le dépôt du catalogue. Publier un pack accepté crée une branche, y
+dépose le fichier YAML et ouvre une pull request — **jamais un push sur la branche
+principale**. Tu relis dans Gitea avant de fusionner.
+
+## Ce qui n'est jamais stocké
+
+Les macros marquées « mot de passe » sont vidées avant toute écriture en base : partage,
+projet enregistré, soumission. Un site public n'a aucune raison de détenir le mot de passe
+MySQL de quelqu'un. L'avertissement affiché au partage le rappelle à l'utilisateur.
+
+## Migrations
+
+Le conteneur `web` exécute `alembic upgrade head` à son démarrage, puis lance gunicorn. Un
+échec de migration arrête le conteneur : une base à moitié migrée derrière une application
+qui répond serait pire qu'une indisponibilité visible.
+
+**Règle d'écriture des migrations** : on ajoute, on ne retire jamais dans la même version que
+le code qui cesse d'utiliser une colonne. La suppression arrive une version plus tard. Sans
+cette discipline, revenir à l'image précédente casse l'application — et tout l'intérêt des
+tags immuables disparaît.
+
+Sauvegarde avant une montée de version qui touche au schéma :
+
+```bash
+docker compose exec -T db pg_dump -U enclume enclume | zstd > enclume-$(date +%F).sql.zst
+```
+
+## Les limites en place
+
+| Réglage | Défaut | Rôle |
+|---|---|---|
+| `ENCLUME_PARTAGE_JOURS` | 90 | expiration des liens |
+| `ENCLUME_PROJETS_PAR_COMPTE` | 50 | projets enregistrés par compte |
+| `ENCLUME_SOUMISSIONS_PAR_JOUR` | 10 | soumissions par compte et par jour |
+| `ENCLUME_TAILLE_MAX_PACK` | 256 ko | taille d'un YAML soumis |
+| `ENCLUME_TAILLE_MAX_PROJET` | 2 Mo | taille d'un projet |
+
+Les identifiants de partage font 12 caractères tirés au hasard, soit 72 bits : ils ne
+s'énumèrent pas. Les liens expirés sont purgés à chaque nouveau partage.