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

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