Files
ObsiGate/docs/features/liaison-appareil-draco.md
T

114 lines
6.5 KiB
Markdown

# #75 — Liaison d'appareil : flux « code d'appareil » émettant un jeton draco
**Carte :** issue Gitea #75 (demande de Bruno, 2026-11-16 : faire fonctionner
l'authentification TikTak Desktop avec le jeton central draco — option A
choisie après audit `~/workspace/audit-appareils-lies/RAPPORT.md`).
**Version :** 2.87.0. **Prérequis :** ACC-3.1 (#216) — ObsiGate émet
`draco_session` ; ACC-3.2 (ticktick-clone #213) — le backend TikTak
valide déjà draco (mapping `sub` → compte, provisionnement JIT HUB-15).
## Constat
Le backend TikTak accepte déjà draco, mais aucune application native ne
peut **obtenir** ce jeton : `draco_session` est un cookie HttpOnly sur
`.dracodev.net`, délivré par `Set-Cookie` au login navigateur, et
`GET /sso/authorize` refuse tout `return_to` hors `*.dracodev.net` (un
schéma `tiktak://` ou un loopback serait rejeté). Le flux équivalent
existe chez agent-commun (`app/appareils.py`, Fusion #45, 0.50.0) — même
UX (code `XXXX-XXXX`, page d'approbation, sondage) — mais il émet des
jetons `dka_` qui n'authentifient que contre agent-commun.
## Livraison (cette PR, côté émettrice)
| Méthode | Chemin | Effet |
|---|---|---|
| POST | `/api/v1/liaison` (201, sans auth) | Démarre une liaison `{nom, type}` → `{demande_id, code_utilisateur, code_appareil, expire_le, url_liaison}` |
| GET | `/liaison?code=XXXX-XXXX` | Page publique d'approbation (saisie manuelle possible) |
| GET | `/api/v1/liaison/en-attente` | Demandes en attente (session) |
| POST | `/api/v1/liaison/approuver` | Approuve (session) → `{appareil}` — **jamais le jeton** |
| POST | `/api/v1/liaison/refuser` | Refuse (session) → `{refusee}` |
| POST | `/api/v1/liaison/sonder` | `en_attente` / `approuvee` (+ `jeton`, livré UNE fois) / `refusee` / `expiree` / `livree` ; 404 si inconnue ou mauvais code |
| GET | `/api/v1/appareils` | Appareils liés de l'utilisateur (session) |
| POST | `/api/v1/appareils/{id}/revoquer` | Révoque (session) → `{revoque: true}` |
- **Module** `backend/draco_appareils.py` (logique pure, sans FastAPI) :
demandes et appareils en JSON dans `data/` (`draco_liaisons.json`,
`draco_appareils.json` — même patron que `draco_session.py` :
chargement paresseux, verrou, écriture atomique). Seule l'empreinte
SHA-256 du code d'appareil est stockée ; le jeton en clair ne vit
que dans la ligne de liaison, entre l'approbation et sa délivrance
unique (colonne vidée à la délivrance, lignes expirées purgées —
une demande approuvée mais jamais délivrée voit son appareil
révoqué à la purge).
- **Jeton** : un JWS draco standard, émis par
`draco_session.issue_token` (nouveaux paramètres `ttl_seconds` et
`extra_claims`) — **longue durée, 10 ans, révocable** (décision :
c'est le sens d'un appareil lié ; la révocation est le contrôle,
pas l'expiration — comme `dka_`). Il porte le claim
`"appareil": "<id>"` ; son `jti` est consigné dans le registre des
émissions (`draco_issued.json`) et sa révocation rejoint
`revoked_list` (donc `GET /api/sso/revocations`, HUB-13
« révoquer toutes les sessions », HUB-22).
- **Code** : 8 caractères, alphabet sans ambiguïté, affiché
`XXXX-XXXX` ; expiration 10 min
(`OBSIGATE_LIAISON_EXPIRATION_MIN`) ; plafond 20 demandes en
attente (429 au-delà).
- **Types** : `desktop` / `terminal` (agent-commun) + `tiktak`
(type dédié pour TikTak Desktop, sinon ambigu avec un desktop
générique) ; type inconnu → `desktop`, jamais d'erreur.
- **Dédoublonnage** : une liaison approuvée révoque les appareils
actifs de même nom+type du même utilisateur (vécu agent-commun
2026-11-13 : un poste = une ligne, un jeton vivant).
- **Rôles Hub (HUB-19)** : le jeton d'appareil est soumis aux mêmes
gardes que la session draco quand il est présenté chez ObsiGate —
changement de mot de passe (`iat`) et rôle Hub (« aucun » → refus
403 explicite). `user_for_draco` joint `_draco_appareil` au dict
utilisateur quand le claim est présent.
- **Garde 403** : un jeton d'appareil ne peut ni gérer les appareils
ni décider une liaison (patron `_exiger_session` d'agent-commun) —
en cookie draco : 403 explicite ; en `Authorization: Bearer` : 401
(ce n'est pas un jeton natif, rejet dès `get_current_user`).
- **Page** `GET /liaison` (`frontend/liaison.html` + `liaison.js` +
`liaison.css`, FR/EN, aucun script inline — CSP) : vérifie la
session (`/api/auth/me`), propose la connexion avec retour ici
(`/?return_to=…`), liste les demandes en attente ou recherche par
code, boutons Approuver / Refuser.
- **Écarts assumés vs agent-commun** : `derniere_utilisation` reste
à `null` (l'émettrice ne voit jamais l'usage du jeton — seul le
consommateur le voit) ; pas de journal d'audit ni d'événement
d'activité (ObsiGate n'a pas ces canaux) ; pas de vue « Appareils »
dans la console — la gestion se fait par l'API et la page
`/liaison` (une vue console est un travail séparé, si voulue).
## Conséquence à connaître (documentée, pas un bug)
Un jeton d'appareil est un **jeton draco à part entière** : présenté
comme cookie chez ObsiGate (ou chez tout consommateur draco), il
authentifie comme l'utilisateur, avec les mêmes gardes (mot de passe,
rôle Hub) — seule la gestion des appareils lui est interdite. Si un
appareil est perdu ou volé, il faut le révoquer (liste des appareils,
déconnexion globale, ou administration des comptes HUB-13) : la
révocation prend effet dès l'appel suivant.
## Côté clients (travaux séparés, après celui-ci)
- **TikTak Desktop** : écran « Lier cet appareil » (copie de
`faireLogin` de DracoSH : code, page `/liaison`, sondage 2 s,
stockage chiffré) ; le backend TikTak accepte déjà le jeton
(il reste à configurer `DRACO_SESSION_SECRET` dans son conteneur).
- **DracoSH / DracoTerm** : le même flux peut remplacer `dka_` si
voulu — les deux jetons coexistent, rien ne change côté
agent-commun.
## Tests
`tests/test_draco_liaison.py` (13 tests, TestClient sur la vraie
application) : flux complet (démarrer → approuver → sonder → jeton →
lister → révoquer → 401), page publique, types inconnus, dédoublonnage,
refus, sondage 404 indiscernable, expiration (410 / `expiree`),
double livraison, plafond (429), sans session (401), jeton d'appareil
refusé sur la gestion (403 cookie / 401 Bearer), rôle Hub « aucun »
(403 explicite), `issue_token` (ttl + claims, réservés non écrasés).
Vérification runtime en plus : flux complet contre un serveur réel
(uvicorn + curl, `~/workspace/obsigate-75/smoke.sh`).