diff --git a/docs/features/liaison-appareil-draco.md b/docs/features/liaison-appareil-draco.md new file mode 100644 index 0000000..35e78f5 --- /dev/null +++ b/docs/features/liaison-appareil-draco.md @@ -0,0 +1,113 @@ +# #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`).