# #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": ""` ; 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`).