Files
kanbante/docs/correspondance-draco.md
Spark 7b0fee43d2
CI / test (pull_request) Failing after 1s
CI / test (push) Failing after 3m40s
fix(sso): aucune sortie nue au pont, « aucun » seulement si décidé, pont inerte signalé (0.46.11)
Ronde 2 du cas « bruno » : la 0.46.10 déployée, le bouton SSO
ramenait toujours au formulaire nu. Reproduction en pile de
chaque état candidat : la seule variante au symptôme identique
est DRACO_SESSION_SECRET absent du conteneur — draco inerte,
claims toujours None, sortie « jeton absent » vers /login nu,
bouton SSO rendu quand même.

- Pont : jeton absent → draco=absent ; cookie présent + service
  inerte → draco=inactif ; sub vide → draco=invalide. Le
  middleware signale de même une page demandée avec un cookie
  présent mais inutilisable. Relier sans session → draco=echec.
- Registre des rôles : hub_roles transporte le drapeau
  « explicite » (explicite_pour, cache partagé) ; le pont ne
  refuse un « aucun » que s'il est explicite ou d'origine
  inconnue — un défaut du registre ne verrouille plus l'entrée.
- Tests : contrats des sorties nues mis à jour (le cas réel du
  conteneur sans secret est test_pont_inerte_sans_secret),
  rôle aucun dans ses trois états, drapeau transporté.
  Suite complète : échecs identiques à l'arbre vierge (23).
2026-11-16 21:15:04 +00:00

260 lines
13 KiB
Markdown

# Correspondance draco par utilisateur (HUB-16, 0.46.0)
Kanbante participe au SSO de la suite dracodev : ObsiGate émet le
cookie `draco_session` (JWS HS256, claims `sub`, `name`, `iat`,
`exp`, `jti`), Kanbante le valide localement (`app/draco.py`) et le
pont `GET /auth/draco` le convertit en session Kanbante native.
Depuis la 0.46.0, un jeton draco valide désigne **le compte
Kanbante de cette identité** — et aucun autre. L'ancienne
hypothèse mono-utilisateur (« un jeton valide = l'opérateur ») a
disparu. C'est ce qui fait tenir le critère de la suite : « un
compte créé fonctionne dans toutes les applications ».
## Où vit la correspondance
Dans le modèle existant des comptes : la colonne
**`users.draco_sub`** (texte, `UNIQUE`, présente depuis la 0.24.0)
porte le `sub` draco lié à chaque compte Kanbante.
`models.get_user_by_draco(sub)` est la résolution canonique ; la
règle de décision complète vit dans
`app.accounts.resolve_draco_user()`, seul point d'entrée du pont
et du contrôle draco de `/api/search`. La correspondance est donc
biunivoque : un `sub` ↔ un compte, garanti par la contrainte
d'unicité.
## Résolution d'une connexion draco (`/auth/draco`)
Dans l'ordre :
1. **Session native déjà ouverte** : si le navigateur porte à la
fois une session Kanbante et un cookie draco dont le `sub`
n'est lié à aucun compte, le `sub` est lié au compte de la
session (première visite doublement connectée — mécanisme
historique, inchangé, aussi appliqué à la connexion native
dans `login_submit`).
2. **Correspondance existante** : la session du compte lié est
ouverte. Un compte **désactivé** n'ouvre aucune session et
n'est jamais contourné (voir § Désactivation).
3. **Compte d'amorçage — adoption conditionnée (fusion #145,
0.46.5)** : s'il n'existe qu'**un seul compte** et que c'est un
**admin actif sans liaison**, ce compte (celui créé à
l'installation depuis l'environnement `KANBANTE_AUTH_USER` /
`KANBANTE_AUTH_PASSWORD`, Bruno) n'est adopté que dans l'un
de ces deux cas :
- **(a)** le `sub` entrant est **« administrateur » pour
kanbante au registre des rôles du Hub** (le pont consulte le
registre avant la résolution et transmet le rôle à
`resolve_draco_user()` ; Hub muet ou rôle moindre = **pas
d'adoption**, dans le doute on ne lie pas) ;
- **(b)** l'adoption est initiée depuis une **session native
déjà authentifiée** (point 1 ci-dessus, ou connexion native
doublement connectée) : l'utilisateur connecté lie
explicitement son propre compte.
Tout autre `sub` inconnu reçoit le parcours ordinaire
(rattachement par homonymie, point 4, ou création JIT d'un
compte **membre** propre, point 5) — jamais l'amorçage.
Avant la 0.46.5, le premier `sub` valide de passage adoptait
l'amorçage quel qu'il soit : sur une instance fraîche, un
simple utilisateur de la suite devenait l'administrateur
local (audit « compte partout » du 2026-11-06). Les autres
accès de l'amorçage restent inchangés dans tous les cas :
connexion native avec le mot de passe du compte, et repli
d'urgence par les identifiants d'environnement (formulaire
et Basic), qui ne dépendent pas de draco.
4. **Rattachement par homonymie (0.46.10)** : si un compte local
porte **exactement le nom d'utilisateur** que l'identité
présentée porterait (nom des claims slugifié — `bruno` →
`bruno`) et qu'il n'a **aucun lien draco**, le `sub` y est
rattaché (journalisé `draco.link.nom`) et c'est la session de
**ce** compte qui est ouverte. Fondement : les noms centraux
font foi — les comptes de la suite sont créés par
l'administrateur au Hub et il n'existe aucune inscription
publique ; avant la 0.46.10, ce cas créait un clone JIT
suffixé (`bruno-2`) et le propriétaire légitime n'atteignait
jamais son compte. Si l'homonyme est déjà lié à un **autre**
`sub` : **conflit explicite** — le pont redirige vers
`/login?draco=conflit`, ne rattache rien et ne crée aucun
clone ; la sortie est la re-liaison par double preuve
(§ Re-liaison par double preuve). Un homonyme **désactivé**
résout à un échec ordinaire, jamais contourné.
5. **Création JIT** : sinon, un compte Kanbante est créé pour
cette identité (détail ci-dessous) et sa session est ouverte.
Un `sub` inconnu n'ouvre **jamais** la session de l'opérateur
d'environnement ni celle d'un compte existant d'un **autre nom**
que le sien : hors le rattachement par homonymie du point 4
(compte homonyme **sans lien**), le JIT crée toujours un compte
**nouveau** (nom suffixé `-2`, `-3`… en cas de collision),
jamais une adoption.
## Re-liaison par double preuve (0.46.10)
Quand le compte local du propriétaire est lié à un **ancien**
`sub` (ou quand le `sub` actuel est détenu par un autre
compte), aucun geste automatique ne réécrit le lien : le nom
prouve l'identité centrale, pas la propriété du compte local.
La **double preuve** la tranche : la connexion locale par mot
de passe réussie **pendant qu'un cookie draco valide de
l'identité désalignée est présent** (ou le passage du pont avec
une session native déjà ouverte) ouvre la page
`/auth/draco/relier`, qui nomme les deux identités et propose
le geste. La validation réécrit `users.draco_sub` (retrait à
l'ancien détenteur journalisé `draco.relink.retrait`, pose
journalisée `draco.relink`) ; le compte délié garde son mot de
passe local. Sans les deux preuves réunies, la page est
inatteignable et aucun lien ne bouge.
## Sorties d'échec du pont — toutes signalées (0.46.10, complété en 0.46.11)
Depuis la 0.46.11, **aucune** sortie d'échec de la chaîne
d'entrée draco (pont, entrée automatique du middleware,
re-liaison) ne ramène au formulaire sans message : chacune
porte un paramètre `draco=` que la page de connexion traduit
en explication.
- **Jeton présent mais illisible** (0.46.10) : signature —
secret partagé du conteneur divergent —, expiration ou
révocation → `/login?draco=invalide`, message explicite.
- **Jeton absent** (0.46.11) : le parcours SSO est arrivé au
pont sans aucun cookie `draco_session` (session de la suite
absente ou cookie non transmis) → `/login?draco=absent`.
Avant, c'était le formulaire nu historique.
- **Service draco inerte** (0.46.11) : le conteneur Kanbante
n'a **aucun** `DRACO_SESSION_SECRET` — le pont ne peut
valider aucune identité, alors que le bouton SSO est rendu
quand même. Un cookie présenté dans cet état →
`/login?draco=inactif`, qui nomme un défaut de configuration
du service. Cas réel (2026-11-16) : c'était l'état du
conteneur kanbante-dev — le propriétaire légitime, cookie
valide lu par ShaarIt et TikTak, revenait au formulaire nu
sans aucun moyen de savoir que la faute était dans le
conteneur. La même signalisation s'applique quand une page
protégée est demandée avec un cookie présent mais
inutilisable (entrée automatique du middleware).
- **Échec de résolution** (0.46.8) : compte désigné
désactivé, etc. → `/login?draco=echec`.
- **Conflit de nom** (0.46.10) : homonyme lié à un autre
`sub` → `/login?draco=conflit` (voir plus haut).
## Création JIT (juste-à-temps)
À la première connexion draco d'une identité sans correspondance :
- **nom d'utilisateur** : nom affiché des claims slugifié
(`Alice Exemple` → `alice-exemple`), libre ou suffixé ;
repli `draco-<sub>` si le nom est inexploitable ;
- **nom d'affichage** : le `name` des claims ;
- **rôle** : `member` (utilisateur standard) — jamais admin ;
- **mot de passe local** : secret aléatoire, haché (PBKDF2 comme
tous les comptes), **jamais divulgué** — l'accès normal passe
par draco. Un administrateur peut ensuite poser un mot de
passe local depuis `/admin` (bouton « Réinitialiser ») si un
accès local est voulu ;
- **espace** : le compte rejoint l'espace Principal comme membre,
comme tout utilisateur créé par l'administration ;
- le geste est journalisé (`draco.jit` dans le journal
d'administration).
## Liaison par l'administrateur (comptes préexistants)
Pour associer un compte Kanbante existant à une identité draco
sans attendre un premier passage :
1. Se connecter à Kanbante avec un compte **admin**.
2. Ouvrir **Administration** (`/admin`), section **Utilisateurs**.
3. Dans la colonne **Draco (sub)** du compte visé, saisir le
`sub` draco de l'identité (l'identifiant du compte de suite
chez l'émettrice, ObsiGate) et cliquer **Lier**.
4. La liaison est immédiate et journalisée (`draco.link.admin`).
Le bouton **Délier** de la même colonne la retire
(`draco.unlink.admin`).
Gardes : un `sub` déjà lié à un autre compte est refusé avec un
message d'erreur (délier l'autre compte d'abord). L'administrateur
peut lier **son propre** compte — c'est la voie manuelle pour le
compte d'amorçage si le premier passage ne l'a pas lié.
Chaque utilisateur peut aussi voir sa propre liaison dans
**Mon profil → Liaison draco (SSO)** et la délier lui-même.
> Le registre matriciel des rôles par application côté Hub
> (carte HUB-19) lit cette correspondance ; la 0.46.0 ne livrait
> que le côté Kanbante, qui reste la source de vérité locale.
> La consommation du registre par Kanbante est décrite à la
> section suivante (0.46.2).
## Rôles du Hub (HUB-19, 0.46.2)
Le registre des rôles du Hub (matrice par application, contrat
D3(a)) est consulté par `app/hub_roles.py` — portage du pilote
ShaarIt 0.7.0 : `GET {hub}/api/roles/kanbante`, en-tête Cookie
complet de la requête relayé, délai 2 s, cache mémoire par
`sub` de 60 s avec horodatage posé avant l'appel (un échec
conserve l'ancien cache et ne déclenche pas de rafale). L'URL
du Hub est celle de la barre commune (`resoudre_urls_draco`).
Toute erreur rend un rôle **inconnu**, qui vaut toujours
« comportement actuel » — jamais un verrouillage nouveau.
Effets, pour les seules sessions **établies par le pont
draco** :
1. **Pont `/auth/draco`** : la consultation précède la
liaison, la résolution de la correspondance et la création
JIT. Rôle connu `aucun` → refus explicite (403, en
français) : aucune session ouverte par draco pour ce
`sub`, aucun compte créé. **Précision 0.46.11** : la
consultation transporte le drapeau `explicite` de la
réponse (`app.hub_roles.explicite_pour`) et le refus
n'a lieu que si le niveau est une décision — explicite,
ou d'origine inconnue (réponse sans le drapeau :
comportement historique). Un `aucun` que le registre
présente comme son **défaut** (`explicite: false`) n'a
été décidé par personne : il ne verrouille pas l'entrée.
La session que le pont ouvre porte un marqueur « draco »
couvert par la signature du cookie
(`user.expiry.draco.hmac`).
2. **`/admin`** (et ses actions, même garde
`_require_admin`) : session établie par draco + rôle du
registre connu ⇒ il faut `administrateur` dans le
registre, **en plus** du rôle local. Rôle inconnu ou
session native ⇒ règles locales, inchangées.
Les autres accès ne sont pas draco et ne sont pas touchés :
session native préexistante, connexion native (mot de
passe), Basic d'environnement, jetons `kbt_`. Ni les droits
internes ni la réconciliation par étiquettes ne changent.
## Surfaces voisines
- **`GET /api/search`** (« Rechercher partout ») : le cookie draco
n'y est plus accepté « en tant qu'opérateur ». Il faut que le
`sub` désigne un compte (correspondance existante). Cette
surface ne consulte pas le registre et n'initie aucune liaison :
elle ne peut donc **jamais adopter le compte d'amorçage**
(fusion #145) — l'adoption a lieu au pont, ou pas. Aucune
création JIT sur cette surface : la création a lieu à la
première vraie connexion, par le pont. Les autres modes d'accès
à `/api/search` (session, Basic, jeton `kbt_`) sont inchangés.
- **Désactivation** : désactiver un compte dans `/admin` coupe
tous ses accès — session native, pont draco (la correspondance
résout à « refusé ») et jetons `kbt_`. Réactiver le compte
rétablit la correspondance telle quelle.
## Non-régressions garanties
- **Jetons personnels `kbt_`** : création, usage sur `/mcp` et
`/api/`, révocation — inchangés ; un jeton n'ouvre toujours pas
l'interface web.
- **Sessions propres Kanbante** et **connexion native**
(formulaire, mot de passe de la base) : inchangées, y compris
la liaison automatique à la première visite doublement
connectée.
- **Authentification Basic** (identifiants d'environnement, pour
les scripts) : inchangée.
- **Pont inerte sans `DRACO_SESSION_SECRET`** : sans secret
configuré, `/auth/draco` renvoie au login, comme avant.
- La réconciliation Kanbante/Gitea par étiquettes (adoption d'une
colonne seulement si exactement une étiquette `kanban:*` est
reconnue) n'est pas touchée par cette carte.