Sasedev/sasedev-knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.1-alpha.2

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 22:02:32 +02:00
parent d632afe11e
commit 8cd187b700
21 changed files with 948 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Documentation SaseDev Knowledge
@@ -12,6 +12,10 @@
- [`architecture/001-PROJECT_PROFILE.md`](architecture/001-PROJECT_PROFILE.md) — baseline PGR, owners/skeletons applicables, décisions `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` et nomenclature ;
- [`architecture/002-KNOWLEDGE_ARCHITECTURE.md`](architecture/002-KNOWLEDGE_ARCHITECTURE.md) — frontières application/domain, Git, forge, synchronisation, PostgreSQL, contenu et publication.
## Études
- [`studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](studies/001-AUTH_ADMIN_CORPUS_STUDY.md) — analyse des fonctionnalités auth/admin présentes ou seulement préparées dans deux archives historiques inachevées.
## Plans
- [`plans/001-V0_0_1_FOUNDATION_PLAN.md`](plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan vivant de la release de fondation `0.0.1`.

82
docs/architecture/001-PROJECT_PROFILE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Profil du projet Knowledge
@@ -54,37 +54,39 @@ Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont p
## Matrice des décisions importantes
| Décision | Classification | Contrat retenu / condition de reprise |
|--------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée pour l'état transversal et les projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; matérialisation `alpha.2` |
| `Cargo.lock` | `DEFER` | décider lors de la matérialisation selon le rôle application/workspace et `510` |
| Actix Web | `KEEP-LOCAL` | trois launchers serveur distincts ; PGR ne possède pas de profil Actix dédié |
| Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile |
| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web |
| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue |
| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle |
| Racine(s) frontend | `DEFER` | décider dans la tranche Web selon le partage réel entre les trois applications |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Topologie d'administration | `DEFER` | pas de quatrième application tant qu'un launcher d'administration séparé n'est pas justifié |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et les trois launchers sont cadrés ; créer une crate uniquement avec ownership réel |
| Décision | Classification | Contrat retenu / condition de reprise |
|----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée pour l'état transversal et les projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; matérialisation `alpha.2` |
| `Cargo.lock` | `KEEP-LOCAL` | versionné : workspace applicatif déployable, résolution reproductible entre opérateur et livraisons |
| Actix Web | `KEEP-LOCAL` | trois launchers serveur distincts ; PGR ne possède pas de profil Actix dédié |
| Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile |
| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web |
| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue |
| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle |
| Racine(s) frontend | `DEFER` | décider dans la tranche Web selon le partage réel entre les trois applications |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte encore différée |
| Quatrième application d'administration | `DEFER` | peut agréger du transverse plus tard mais ne remplace jamais les frontières admin locales |
| Modèle rôles/capabilities | `DEFER` | séparer identité partagée et autorisations métier avant de figer enums/scopes |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et les trois launchers sont cadrés ; créer une crate uniquement avec ownership réel |
Aucun `OVERRIDE` n'est requis à ce stade.
@@ -98,12 +100,12 @@ knowledge-howtos-server launcher Actix Web de la façade HOWTOs
knowledge-snippets-server launcher Actix Web de la façade snippets
```
Ils ne sont pas encore matérialisés en `alpha.1.fix.1`. Lorsqu'ils le seront, leurs `main.rs` resteront minces et composeront les bibliothèques réutilisables.
Ils ne sont pas encore matérialisés en `alpha.2`. Lorsqu'ils le seront, leurs `main.rs` resteront minces et composeront les bibliothèques réutilisables. Chacun doit pouvoir protéger sa propre surface d'administration métier.
Les responsabilités de bibliothèques suivantes restent candidates et ne deviennent des packages que lorsqu'elles possèdent un ownership réel :
```text
knowledge-domain-lib contrats et types métier stables
knowledge-domain-lib ownership des contrats et types métier stables ; crate matérialisée en alpha.2 sans contrats Git prématurés
knowledge-app-lib orchestration des use cases transversaux, si la séparation apporte une valeur réelle
knowledge-git-lib implémentation Git générique
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
@@ -121,6 +123,18 @@ Règles de création :
- ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
- ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.
## Corpus auth/admin étudié en alpha.2
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` sont des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
Elles justifient de conserver séparées :
- l'identité/authentification partagée de plateforme ;
- l'autorisation privilégiée propre aux cas d'usage de chaque application ;
- une éventuelle façade d'administration transversale ultérieure.
Elles ne justifient pas encore de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA comme scope `0.0.1`.
## Décisions à rouvrir
Les `DEFER` sont réexaminés dans la tranche qui consomme réellement la décision. Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé dans `alpha.1.fix.1`.

26
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Architecture de fondation Knowledge
@@ -13,6 +13,12 @@ Le principe directeur reste :
> Git est le backend du contenu ; une forge est une capacité optionnelle.
## Workspace Rust matérialisé
`alpha.2` instancie le skeleton PGR `002-RUST_CARGO_WORKSPACE` avec une première crate `knowledge-domain-lib`. Cette crate possède la frontière de domaine commune mais n'introduit pas encore les contrats Git/synchronisation réservés à `alpha.3`.
Le workspace est une application déployable à train de release unique ; `Cargo.lock` est donc versionné pour conserver la résolution effectivement vérifiée. Les artefacts Cargo sont dirigés hors du dépôt vers `../builds/sasedev-knowledge/target/`.
## Vue de responsabilités
```text
@@ -224,13 +230,25 @@ La stratégie exacte de partage des assets/frontend entre les trois applications
L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité.
Elle pourra gérer propositions, revues, synchronisation, validation et publication. Une UI complète est hors scope `0.0.1`.
Chaque application doit pouvoir protéger sa propre surface d'administration métier :
La décision entre routes d'administration réparties dans les trois applications et launcher d'administration dédié reste ouverte jusqu'à ce que les besoins d'auth, lifecycle et déploiement soient connus.
```text
knowledge-pgr-server -> administration PGR
knowledge-howtos-server -> administration HOWTOs
knowledge-snippets-server -> administration snippets
```
Les chemins HTTP exacts restent `DEFER`. Les exemples `/admin`, `/adminapi`, `/login` ou autres observés dans les corpus historiques ne sont pas adoptés comme convention Knowledge.
Une quatrième application d'administration MAY être créée ultérieurement si une vraie responsabilité transversale apparaît. Elle pourra agréger comptes, sources, jobs, propositions ou autres vues communes, mais MUST NOT remplacer les contrôles d'autorisation propres aux trois applications.
Une UI complète reste hors scope `0.0.1`.
## 11. Authentification et autorisation
Le domaine doit distinguer identité, rôle/capacité et action autorisée, mais le fournisseur d'identité et le mécanisme complet restent différés.
Le domaine doit distinguer identité, authentification, rôle/capacité et action autorisée. L'identité et les sessions peuvent être transversales via PostgreSQL partagé ; l'autorisation métier reste vérifiée côté serveur dans chaque application.
Le fournisseur d'identité, les URLs de login, le modèle détaillé de rôles/capabilities, OAuth2/OIDC et MFA restent différés.
Les permissions forge ne sont pas supposées équivalentes aux permissions applicatives.

9
docs/objectives/001-PROJECT_OBJECTIVES.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/objectives/001-PROJECT_OBJECTIVES.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Objectifs SaseDev Knowledge
@@ -27,6 +27,12 @@ knowledge-snippets-server
Cette séparation permet de faire évoluer, déployer et dimensionner chaque façade indépendamment tout en partageant les bibliothèques de domaine, Git, stockage, rendu et observabilité lorsque leur ownership est réellement commun.
## Administration par façade
Chaque application doit pouvoir proposer sa propre surface d'administration protégée pour les opérations qui appartiennent à son domaine. Les URL internes et le modèle détaillé d'autorisation ne sont pas définis par la fondation.
Une future quatrième application d'administration peut centraliser des vues et opérations transversales, mais elle ne remplace pas les contrôles locaux des trois serveurs.
## Sources Git de contenu
La fondation retient au minimum trois sources Git indépendantes :
@@ -53,6 +59,7 @@ Knowledge doit permettre à terme :
- de publier des HOWTOs procéduraux sans leur attribuer une force normative PGR ;
- de publier des snippets courts et contextualisés ;
- de déployer séparément les trois façades publiques sans dupliquer la logique partagée ;
- de protéger et administrer localement chaque façade, avec une éventuelle vue d'administration transverse en complément ;
- d'administrer des dépôts publics ou privés ;
- d'accepter des propositions externes sans écriture directe dans le contenu publié ;
- de conserver une révision Git de base pour détecter les conflits ;

20
docs/plans/001-V0_0_1_FOUNDATION_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/001-V0_0_1_FOUNDATION_PLAN.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Plan 0.0.1 — fondation SaseDev Knowledge
@@ -52,7 +52,7 @@ Acquis par le cadrage `alpha.1.fix.1` :
Restent volontairement ouverts jusqu'à la tranche qui les consomme :
- package manager et lockfile frontend ;
- `Cargo.lock` ;
- modèle détaillé des rôles/capabilities ;
- racine(s) et partage concret du frontend entre les trois applications ;
- driver/ORM et migrations PostgreSQL ;
- éventuel découpage en schémas PostgreSQL ;
@@ -60,7 +60,8 @@ Restent volontairement ouverts jusqu'à la tranche qui les consomme :
- fournisseur d'identité ;
- adapter forge réel ;
- formats finaux HOWTO/snippet ;
- topologie d'administration ;
- URL et routage exacts des surfaces d'administration/login ;
- décision d'une éventuelle quatrième application d'administration transverse ;
- liste définitive des crates de bibliothèque.
## Scope
@@ -113,17 +114,19 @@ Principes :
Matérialiser la fondation locale : version, règles, objectifs, profil PGR, architecture, plan, validation, roadmap/changelog et prompt de démarrage.
Le résultat opérateur initial est `FAIL`. Le fix `alpha.1.fix.1` corrige la politique Eclipse, la gate de fichiers et la topologie produit à trois applications sans ouvrir le scope `alpha.2`.
Le résultat opérateur initial est `FAIL`. Le fix `alpha.1.fix.1` corrige la politique Eclipse, la gate de fichiers et la topologie produit à trois applications. Sa gate opérateur est `PASS`.
Aucun code fonctionnel n'est ajouté.
Aucun code fonctionnel n'est ajouté dans `alpha.1` ou son fix.
### alpha.2 — workspace Rust/Cargo minimal
Instancier le skeleton `002-RUST_CARGO_WORKSPACE` sur la fondation : manifest workspace, toolchain/configuration durable réellement nécessaire et premier package de bibliothèque possédant une responsabilité claire.
Instancier le skeleton `002-RUST_CARGO_WORKSPACE` sur la fondation : manifest workspace, outillage durable, artefacts Cargo hors dépôt et première crate `knowledge-domain-lib` possédant la frontière de domaine commune.
Décider explicitement `Cargo.lock`, outputs de build et premier sous-ensemble de crates réellement matérialisé.
Décision `Cargo.lock` : le versionner, car Knowledge est un workspace applicatif déployable à train de release unique et doit conserver la résolution effectivement validée.
Les trois packages serveur sont connus architecturalement mais ne sont pas obligatoirement tous créés dans cette tranche si leur seule existence serait un placeholder.
Étudier les deux corpus historiques auth/admin fournis et formaliser uniquement les enseignements durables : identité partageable, autorisation serveur et surface admin propre à chaque application. Ne pas importer les URL, rôles, OAuth/OIDC, MFA ou écrans inachevés comme exigences.
Les trois packages serveur restent connus architecturalement mais ne sont pas créés dans cette tranche : sans routes/cas d'usage réels, ils seraient encore des placeholders.
### alpha.3 — contrats domaine/Git/synchronisation
@@ -172,6 +175,7 @@ REPLAN obligatoire si :
- une tranche nécessite plusieurs responsabilités non prévues qui ne peuvent plus être validées proprement ensemble ;
- un choix de crate impose un couplage du domaine à Actix/Gitea/PostgreSQL ;
- les trois launchers entraînent une duplication de logique qui devrait être possédée par une crate commune ;
- une future administration transverse tente de contourner ou remplacer les contrôles d'autorisation propres aux trois applications ;
- le frontend ne peut pas être validé indépendamment du host sans raison architecturale réelle ;
- le choix Git impose une API de forge pour une opération fondamentale ;
- la base PostgreSQL partagée impose un couplage de contenu qui contredit l'autorité Git ;

261
docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md Normal file
View File

@@ -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.

32
docs/validation/001-VALIDATION_MATRIX.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Matrice de validation Knowledge
@@ -65,6 +65,18 @@ AUDIT règles structurelles PGR seulement si la preuve n'est pas déjà posséd
Le profil strict et les éventuelles exceptions doivent être visibles dans les manifests/règles locales.
## Administration et authentification
Aucune route admin/login n'est validée tant qu'elle n'existe pas réellement. Lorsqu'elles seront matérialisées, les gates devront prouver séparément :
- refus d'accès non authentifié aux opérations privilégiées ;
- refus d'accès authentifié sans autorisation suffisante ;
- autorisation vérifiée côté serveur et pas seulement par la navigation frontend ;
- isolation correcte des opérations PGR, HOWTOs et snippets ;
- comportement d'une éventuelle façade admin transverse sans bypass des contrôles locaux.
Les corpus historiques ne constituent pas des preuves de sécurité pour Knowledge.
## Frontend Web
Dès que le frontend est matérialisé :
@@ -131,3 +143,21 @@ Le fix reste documentaire. Sa gate doit prouver :
- au moins trois sources Git initiales et une base PostgreSQL logique partagée ;
- l'absence d'override PGR non documenté ;
- la cohérence du plan et de la transition PASS/FAIL.
## Gate de `0.0.1-alpha.2`
La tranche doit prouver :
- `VERSION = 0.0.1-alpha.2` et `[workspace.package].version` identique ;
- `Cargo.lock` versionné et non ignoré ;
- `Cargo.toml`, `rustfmt.toml`, `clippy.toml` et `.cargo/config.toml` sans placeholder PGR ;
- `cargo metadata --format-version 1 --no-deps` ;
- `cargo fmt --all -- --check` ;
- `cargo check --workspace` ;
- `cargo clippy --workspace --all-targets --all-features -- -D warnings` ;
- `cargo test --workspace --all-targets --all-features` ;
- artefacts Cargo hors dépôt sous `../builds/sasedev-knowledge/target/` ;
- seule `knowledge-domain-lib` matérialisée comme première crate, sans création placeholder des trois serveurs ;
- étude auth/admin présente avec distinction entre fonctionnalités câblées, préparatoires et seulement annoncées ;
- surfaces admin locales documentées sans figer `/admin`, `/login` ou un modèle de rôles ;
- hygiène Git et headers documentaires applicables.