0.0.1-alpha.2

2026-09-27 22:02:32 +02:00
parent d632afe11e
commit 8cd187b700
21 changed files with 948 additions and 56 deletions
--- a/docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md
+++ b/docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md
@@ -0,0 +1,261 @@
+<!-- file: docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md -->
+<!-- version: 1 -->
+
+# Étude auth/admin — corpus historiques Actix
+
+## Objet
+
+Cette étude utilise deux projets historiques **inachevés** comme corpus d'inspiration pour SaseDev Knowledge. Ils ne sont ni des baselines autoritaires ni des dépendances à importer.
+
+```text
+actix-auth-app-master.zip
+SHA-256 bcdf4c568c827b77c70ee476218c2b07ea0fca408ab87d2f044333309d19ab71
+
+amahil-project-master.zip
+SHA-256 b6a3d83c3c2911a7ff36eeb20e353801fefddaf1e5eb7afec1ff12c67067a359
+```
+
+L'objectif est de distinguer :
+
+- les fonctionnalités réellement câblées ;
+- les structures préparatoires sans workflow complet ;
+- les intentions annoncées mais non implémentées ;
+- les concepts réutilisables pour Knowledge ;
+- les détails qui doivent rester différés.
+
+## `actix-auth-app` — fonctionnalités effectivement câblées
+
+Le projet expose réellement une base d'authentification Actix Web avec pages et API.
+
+### Routes front observées
+
+```text
+/
+/setlang
+/signup
+/confirm-signup
+/resend-confirmation-signup
+/lostpassword
+/login
+/newpassword
+/lostid
+/profile
+/logout
+```
+
+Les pages invitées sont protégées par un middleware `guest_only`; le profil et la déconnexion par `auth_only`.
+
+### API observée
+
+```text
+GET  /api/health
+GET  /api/captcha
+POST /api/auth/login
+POST /api/auth/logout
+POST /api/auth/signup
+POST /api/auth/confirm-signup
+POST /api/auth/resend-confirmation-signup
+POST /api/auth/lostpassword
+POST /api/auth/newpassword
+POST /api/auth/lostid
+POST /api/auth/refresh
+GET  /api/profile
+POST /api/profile/update
+POST /api/profile/change-password
+POST /api/profile/change-email
+POST /api/profile/change-avatar
+```
+
+Le code observé matérialise notamment :
+
+- hash/vérification de mot de passe avec Argon2 ;
+- access token et refresh token ;
+- sessions persistées avec informations de device/user-agent/IP ;
+- cookies `HttpOnly`, `SameSite=Lax` et `Secure` conditionnel au mode HTTPS pour les tokens ;
+- confirmation d'inscription ;
+- récupération d'identifiant et réinitialisation de mot de passe ;
+- CAPTCHA pour plusieurs parcours sensibles ;
+- rate limiting configurable sur certains parcours de récupération/confirmation ;
+- profil utilisateur, changement de mot de passe/email et avatar ;
+- statuts utilisateur et compteur d'échecs de connexion ;
+- middleware `admin_only`, `auth_only`, `guest_only` ;
+- stockage PostgreSQL et queries structurées ;
+- traduction Fluent, rendu Maud et frontend TypeScript/Vite/Sass.
+
+Ces éléments sont des **capacités observées**, pas des exigences Knowledge.
+
+## `actix-auth-app` — structures préparatoires ou incomplètes
+
+Le README annonce un kernel OAuth2/OIDC complet, et le schéma/les DTOs/queries couvrent notamment :
+
+```text
+OAuth clients
+OAuth authorization codes
+OAuth refresh/access tokens
+OAuth consents
+OAuth provider configs
+external user auth providers
+user 2FA recovery codes
+user events
+```
+
+Des types existent également pour OAuth/OIDC, MFA/TOTP et plusieurs niveaux d'authentification de session.
+
+Cependant, aucune route HTTP OAuth/OIDC n'est configurée dans les handlers observés et aucun flow MFA/TOTP complet n'est câblé. La dépendance OTP est même commentée dans le manifest. Ces capacités sont donc classées **préparatoires / annoncées**, pas implémentées de bout en bout.
+
+Le middleware `admin_only` existe, mais aucune surface d'administration n'est configurée dans les handlers du projet observé.
+
+Un autre détail interdit la copie mécanique : le modèle courant possède `User`, `Admin`, `Superadmin`, mais `admin_only` compare directement le rôle à `Admin`. Le comportement de `Superadmin` n'est donc pas une base suffisamment sûre pour définir le modèle Knowledge.
+
+## `amahil-project` — fonctionnalités effectivement câblées
+
+Amahil contient une base auth très proche sur les parcours classiques : login/logout, inscription, confirmation, récupération, refresh, profil, CAPTCHA, sessions et PostgreSQL.
+
+Il ajoute surtout un début d'administration applicative :
+
+```text
+scope /adminapi
+middleware admin_only
+GET /adminapi/user/list
+```
+
+La liste d'utilisateurs est donc une fonctionnalité admin backend réellement branchée derrière une vérification de rôle.
+
+Le schéma contient plusieurs niveaux de rôles :
+
+```text
+global
+company
+project
+task
+```
+
+Cette séparation montre qu'une identité partagée peut coexister avec des autorisations plus locales au domaine.
+
+## `amahil-project` — interface admin incomplète
+
+Le gabarit Maud d'administration référence notamment :
+
+```text
+/admin
+/admin/users
+/admin/users/add
+```
+
+avec sidebar et gestion des utilisateurs.
+
+Ces routes frontend ne sont toutefois pas configurées dans le handler `front.rs` observé. Le module admin API contient en outre des opérations add/edit/delete seulement commentées.
+
+Le corpus montre donc l'intention et une partie de l'UI, mais pas une console d'administration complète.
+
+## Enseignements retenus pour Knowledge
+
+### 1. Identité partagée, autorisation distribuée
+
+Le PostgreSQL partagé peut porter les identités, sessions et métadonnées d'autorisation communes aux trois applications.
+
+En revanche, chaque application Knowledge garde la responsabilité de vérifier côté serveur les opérations privilégiées de son propre domaine :
+
+```text
+knowledge-pgr-server
+knowledge-howtos-server
+knowledge-snippets-server
+```
+
+Une éventuelle application admin transversale est une façade supplémentaire, pas un bypass des autorisations locales.
+
+### 2. Les URL restent ouvertes
+
+Les chemins historiques :
+
+```text
+/login
+/admin
+/adminapi
+/profile
+```
+
+sont des exemples observés, pas un contrat Knowledge. Le routage exact sera décidé avec la première composition Web/auth réelle.
+
+### 3. Le modèle de rôles reste ouvert
+
+Les deux archives utilisent des modèles différents : rôle unique enum, tableaux de rôles, niveaux global/company/project/task.
+
+Knowledge ne copie donc aucun enum historique. Le futur modèle devra distinguer au minimum :
+
+```text
+identity
+session/authentication state
+platform-level capability when justified
+application/domain capability
+authorized action
+```
+
+La granularité concrète reste `DEFER`.
+
+### 4. Auth commune réutilisable, middleware Web séparé si nécessaire
+
+Les parcours compte/session sont naturellement candidats à une implémentation partagée entre les trois applications. Une future crate commune n'est créée que lorsqu'un ownership réel et un premier cas d'usage existent.
+
+Le code Actix spécifique peut rester distinct du domaine d'identité si cette séparation évite de coupler les contrats réutilisables au framework.
+
+Aucun nom de crate auth n'est figé par cette étude.
+
+### 5. OAuth/OIDC et MFA restent hors scope
+
+Les structures de `actix-auth-app` montrent qu'OAuth2/OIDC, fournisseurs externes, consentements, MFA et recovery codes pourront être étudiés plus tard.
+
+Ils ne deviennent pas des exigences de `0.0.1` parce que le corpus contient des tables ou des dépendances associées.
+
+### 6. La sécurité n'est pas héritée par copie
+
+Les archives apportent des idées utiles : Argon2, refresh token, sessions persistées, cookies protégés, rate limits, CAPTCHA et événements/audit.
+
+Elles ne prouvent pas pour autant un modèle de sécurité complet pour Knowledge. En particulier, cette étude n'a pas établi dans les corpus un contrat CSRF complet, un modèle de capabilities final, ni une administration bout en bout.
+
+Les propriétés de sécurité Knowledge devront être spécifiées puis testées dans leur propre scope.
+
+## Capacités candidates pour les futures surfaces admin
+
+Les éléments suivants combinent ce que les corpus montrent et les besoins déjà cadrés de Knowledge. Ils constituent un backlog conceptuel, pas le scope de `alpha.2`.
+
+### Commun/transversal
+
+- gestion des utilisateurs et de leur état ;
+- sessions actives et révocation ;
+- audit/événements utilisateurs ;
+- statut des sources Git et dernière synchronisation ;
+- jobs de synchronisation/indexation/publication ;
+- propositions, revues et conflits ;
+- configuration des sources publiques/privées ;
+- santé de PostgreSQL et projections reconstructibles.
+
+### PGR
+
+- état stable/dev et révision/tag source ;
+- propositions de changement normatif ;
+- validation/publication compatible avec la gouvernance PGR.
+
+### HOWTOs
+
+- création/révision/publication de procédures ;
+- classification, relations et validation du contenu procédural.
+
+### snippets
+
+- création/révision/publication de snippets ;
+- contexte, langage/technologie, classification et modération.
+
+Les trois groupes spécifiques ci-dessus sont des **déductions Knowledge**, pas des fonctionnalités directement présentes dans les deux archives historiques.
+
+## Décision de tranche
+
+`alpha.2` ne crée :
+
+- aucune route `/admin` ou `/login` ;
+- aucune crate auth/admin ;
+- aucun schéma PostgreSQL auth ;
+- aucun OAuth/OIDC/MFA ;
+- aucun rôle/capability définitif.
+
+La tranche conserve seulement les invariants architecturaux nécessaires avant matérialisation des serveurs et documente le corpus pour éviter de devoir le réinterpréter depuis la conversation.