6.5 KiB
#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 dansdata/(draco_liaisons.json,draco_appareils.json— même patron quedraco_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ètresttl_secondsetextra_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 — commedka_). Il porte le claim"appareil": "<id>"; sonjtiest consigné dans le registre des émissions (draco_issued.json) et sa révocation rejointrevoked_list(doncGET /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_dracojoint_draco_appareilau 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_sessiond'agent-commun) — en cookie draco : 403 explicite ; enAuthorization: Bearer: 401 (ce n'est pas un jeton natif, rejet dèsget_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_utilisationreste à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
faireLoginde DracoSH : code, page/liaison, sondage 2 s, stockage chiffré) ; le backend TikTak accepte déjà le jeton (il reste à configurerDRACO_SESSION_SECRETdans 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).