ObsiGate 2.87.0 — Liaison d'appareil : flux code d'appareil émettant un jeton draco (#75) #76
@@ -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": "<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`).
|
||||||
Reference in New Issue
Block a user