T2 Authentification IoBase

Source de vérité

La doc officielle : Centre d'aide io-base · Procédure d'authentification via le DAP (extraits ci-dessous).

Endpoints DAP

Cycle de vie

Phase 1 — Enrôlement (1 seule fois)

Phase 2 — Refresh automatique (en continu)

Les 5 protections critiques

1 · Mutex single-use

Au début de build_dap_token et build_dap_refresh, on vérifie le flag global.dap_refreshing. Si déjà true, on log DAP_REFRESH_SKIP mutex et on retourne nil. Sinon on le set à true et on continue.

Dans handle_dap_resp, le flag est reset à false aussi bien sur succès que sur échec, garantissant qu'aucun deadlock n'est possible.

2 · Persistance flash

À chaque token update (register, token, refresh), handle_dap_resp propage msg.dap_persist contenant la nouvelle state. fn_persist_dap attache msg.filename = '/mnt/data/luvitred/dap_state.json', le node save dap state (file out, overwriteFile=true) écrit. Format :

{
  "device_code":   "DC...",
  "access_token":  "AT...",
  "refresh_token": "RT...",
  "saved_at":      1714056789
}

3 · Restore au boot

Au démarrage du flow (deploy ou reboot CG) :

1. inj_load_dap_state (once @startup, +3s)
2. file_load_dap_state lit le JSON depuis flash
3. fn_restore_dap_state parse via regex (sandbox Lua n'a pas json.decode garanti) et set les globals

Résultat : un reboot CG ne nécessite pas de re-enrôlement administrateur IoBase. Les tokens restent valides jusqu'à expiration naturelle.

4 · Retry sur 401

handle_iobase_resp et handle_health_resp émettent msg avec statusCode=401 vers fn_trigger_refresh_on_401 qui filtre, puis émet vers build_dap_refresh. Le mutex protège des refreshes en rafale (par ex. 10 trames qui prennent 401 d'affilée → 1 seul refresh est tiré).

La trame qui a essuyé le 401 est perdue : il n'existe pas de file de rejeu sur cette passerelle. Le renouvellement protège les trames suivantes, pas celle-là.

5 · Refresh préventif au retour de WAN

handle_cg_metrics (kind=internet) maintient global.wan_connected. Sur transition false → true, il émet un msg vers build_dap_refresh. Avantage : après une coupure longue on repart avec un jeton valide sans attendre la prochaine échéance du cron, qui n'a lieu que toutes les 12 heures → pas de boucle de 401.

Validation par tests

Deux environnements, cloisonnés

La passerelle peut s'authentifier auprès de deux environnements IoBase distincts. Rien n'est partagé entre eux — c'est la condition pour que le mécanisme à usage unique reste sûr :

Chaque déclencheur porte son environnement dans le message ; les fonctions le lisent et choisissent le jeu de clés correspondant. Un renouvellement bloqué sur un environnement ne bloque pas l'autre, et un ré-enrôlement en cours sur l'un n'entraîne pas l'autre sur la mauvaise route.

Restauration au démarrage

Chaque environnement recharge son propre fichier d'état au démarrage. Sans cela, le second environnement perdrait son jeton de renouvellement à chaque redémarrage du flux — un jeton à usage unique, obtenu par un enrôlement validé par un administrateur : le perdre coûte un aller-retour de plusieurs jours avec la plateforme.

Le journal le montre au démarrage, un message par environnement :

DAP_RESTORE_OK        env='a'  has_refresh=true
DAP_REFRESH_SKIP_FRESH env='a'  saved_age_s=2047
DAP_RESTORE_OK        env='b'  has_refresh=false

La garde DAP_REFRESH_SKIP_FRESH est essentielle : tout redéploiement redémarre les flux et rejoue cette restauration. Sans elle, chaque déploiement consommerait un jeton. Elle n'agit que si l'état a moins de six heures ; au-delà, un renouvellement part — c'est normal, mais c'est à savoir avant de déployer.

Variables utilisées

Voir la référence des variables globales pour la liste complète, qui indique aussi lesquelles se saisissent au cockpit. Les quatre valeurs de configuration (dap_host, dap_client_id, dap_api_key et leurs variantes _b) s'y modifient sans redéploiement du flux ; les jetons, eux, sont produits par l'enrôlement et ne se saisissent pas.

Premier enrôlement

1. Renseigner dap_host, dap_client_id et dap_api_key dans le cockpit (onglet Globals, rôle admin)
2. Déclencher l'injection DAP register depuis le canvas
3. Vérifier DAP_REGISTER_OK device_code=… dans le journal
4. Un administrateur de la plateforme valide l'équipement (« Services et équipements » → « Valider l'équipement »). Sans cette étape, l'appel suivant répond 425 Pending. C'est une dépendance externe : elle se demande tôt.
5. Une fois validé, déclencher l'injection DAP get token
6. Vérifier DAP_TOKEN_OK et l'écriture du fichier d'état

Le second environnement suit exactement la même procédure, avec ses propres identifiants et sa propre validation côté plateforme.