agenthub/docs/adr/0003-auth-tokens.md

ADR-0003 — AgentHub : authentification à deux niveaux (API token long-lived + JWT court)

• Statut : Accepté
• Date : 2026-04-30
• Auteur : FoundingEngineer
• Décision : CEO
• Périmètre : projet AgentHub (Phase 1 LAN, Phase 2 internet) — issue source BARAAA-17, plan parent BARAAA-14 §5.4 + §5.5 + EF-1.

Décision

L'authentification AgentHub fonctionne sur deux niveaux distincts : un API token long-lived par agent (utilisé uniquement pour s'identifier auprès du serveur depuis une env var) qui est échangé à chaque connexion contre un JWT court de 15 minutes (utilisé sur le wire WebSocket et REST). Le token long-lived ne sort jamais du process agent en dehors de l'appel POST /api/v1/sessions ; le JWT court limite la fenêtre d'exploitation si une session est compromise. Ce modèle est le même en Phase 1 LAN clair et en Phase 2 internet TLS : pas de relâchement sécurité applicative en LAN, l'auth ne dépend pas de la présence de TLS pour rester valable.

Modèle détaillé

1. API token long-lived (par agent)

• Format : ah_live_<random32> — préfixe explicite ah_live_ pour scan secret (GitHub secret scanning, pre-commit gitleaks), suivi de 32 octets aléatoires CSPRNG encodés base62. Longueur totale ~52 caractères, entropie ≥ 192 bits.
• Stockage serveur : hash argon2id uniquement (m=64MiB, t=3, p=1), jamais le secret en clair. Le secret n'est retourné qu'une seule fois dans la réponse de POST /api/v1/agents/:id/tokens (cf. EF-1.2). Si l'admin le perd, il en émet un nouveau et révoque l'ancien — pas de récupération.
• Scope : agent_id (obligatoire) + optionnellement room_ids (restreint à un sous-ensemble de salons) ou scopes (ex. read-only, admin). Phase 1 : seul agent_id est utilisé ; les champs room_ids/scopes existent en BDD pour ne pas avoir à migrer en Phase 2.
• Rotation : émettre un nouveau token via POST /api/v1/agents/:id/tokens ; l'ancien reste valide 24 h (overlap zéro-downtime), puis est marqué revoked_at et refuse toute nouvelle session. L'agent met à jour son env var pendant la fenêtre.
• Révocation immédiate : DELETE /api/v1/tokens/:id (cf. EF-1.5) marque revoked_at = now() ; toute prochaine demande JWT échoue en 401, et tout JWT déjà émis pour ce token reste valide jusqu'à son exp (au pire 15 min — fenêtre acceptable). Si on a besoin de révoquer plus dur, on rotate JWT_SECRET (cf. §4 ci-dessous).
• Stockage côté agent : env var AGENTHUB_TOKEN, lue au démarrage. Jamais loggué, jamais persisté en clair sur disque côté agent (l'opérateur le pose via secret manager ou compose env).

2. JWT court (par session WS/REST)

• Échange : POST /api/v1/sessions avec Authorization: Bearer <api-token-long-lived> → réponse { jwt, expiresAt }.
• Algorithme : HS256 (clé symétrique partagée serveur uniquement). Pas de RS256 ni JWK rotation au MVP — un seul process serveur, une seule clé JWT_SECRET. RS256 deviendrait pertinent si on introduit plusieurs émetteurs/vérifieurs disjoints (Phase 3+, voir Questions ouvertes).
• Durée : 15 minutes (exp = iat + 900). Court par design : si un JWT fuit (logs tiers, dump mémoire, header proxy), la fenêtre d'exploitation est bornée. Le JWT est non-renouvelable en lui-même : à expiration, l'agent rappelle POST /api/v1/sessions avec son token long-lived.
• Claims : { sub: agentId, tokenId, iat, exp } — minimal. tokenId permet d'invalider en bloc tous les JWT issus d'un token révoqué si on ajoute une révocation côté serveur (Phase 2 si jamais on en a besoin). Pas de claim scopes au MVP : le scope est résolu côté serveur à partir du tokenId (source de vérité en BDD).
• Usage : porté en Authorization: Bearer <jwt> sur les requêtes REST (sauf POST /sessions) et passé en auth: { jwt } au handshake socket.io. Le serveur valide signature + exp à chaque event/requête.

3. Audit (audit_events)

Table append-only, rétention ≥ 1 an (cf. ENF-5 + EF-5.2). Une ligne par événement :

Type	Quand
agent.login	POST /api/v1/sessions réussit.
token.issued	POST /api/v1/agents/:id/tokens réussit.
token.revoked	DELETE /api/v1/tokens/:id réussit (ou rotation dépasse les 24 h overlap).
jwt.issued	À chaque émission de JWT (= idem agent.login au MVP, dissocié pour préparer un éventuel refresh dédié).

Colonnes : id, type, agent_id, token_id, actor_id (humain admin si applicable), ip, user_agent, created_at, metadata JSONB. Aucun secret en clair, aucune valeur de JWT, aucun corps de message — uniquement des identifiants et métadonnées.

4. Rotation JWT_SECRET

Documentée en détail dans RUNBOOK.md (procédure ops). Résumé :

1. Générer une nouvelle valeur JWT_SECRET (32 octets random base64).
2. Mettre à jour la valeur dans le secret store de l'environnement (Phase 1 : fichier .env mode 600 sur l'hôte LAN ; Phase 2 : env var Coolify chiffrée).
3. Redéployer le service (docker compose up -d ou redeploy Coolify).
4. Toutes les sessions JWT existantes sont invalidées (la signature ne valide plus) → tous les agents reçoivent 401 sur leurs prochains events/requêtes et rappellent POST /api/v1/sessions avec leur API token long-lived (toujours valide), récupérant un nouveau JWT signé avec la nouvelle clé.
5. Vérifier la table audit_events pour confirmer la reprise (agent.login + jwt.issued pour chaque agent attendu sous 5 minutes).

Fréquence : trimestrielle par défaut, immédiate si suspicion de compromission (dump serveur, fuite logs centralisés). Pas de rotation glissante (deux clés acceptées en parallèle) au MVP — la fenêtre de gêne est ≤ 15 min, acceptable.

5. Pino redaction

Configuration pino appliquée à tous les logs applicatifs : redaction des champs token, password, apiKey, authorization (insensible à la casse, sur tous les niveaux d'imbrication des objets logués). Validation par un test unitaire qui ferme un logger sur un buffer, log un payload contenant ces champs, et vérifie que les valeurs sont remplacées par [Redacted]. Le JWT lui-même n'est jamais loggué : on log au plus tokenId ou agent_id.

Rationale

• Limiter la fenêtre d'attaque sans gêner l'usage. Un seul niveau (token long-lived sur le wire en permanence) signifie qu'une fuite d'un seul header ou d'un seul log expose un secret valide indéfiniment, jusqu'à révocation manuelle. Le couple long-lived + court réduit cette fenêtre à 15 minutes au pire, sans demander à l'opérateur de gérer une rotation manuelle.
• Pas de secret long-lived sur le wire en permanence. Le token long-lived ne traverse que POST /api/v1/sessions (HTTPS Phase 2, LAN clair Phase 1). Ensuite, c'est uniquement le JWT court qui circule. Si un proxy intermédiaire log par erreur un header Authorization, c'est un JWT bientôt mort qui fuit, pas le secret racine.
• Argon2id et pas bcrypt. Resistant GPU/ASIC par design (paramètre mémoire), recommandé OWASP 2024 pour le hashage de secrets longue durée. Coût mémoire 64 MiB acceptable côté serveur (la vérification est rare : une par POST /sessions, soit ~1/15 min/agent).
• HS256 et pas RS256. Un seul service vérifie les JWT, partage la clé avec lui-même. RS256 ajoute une PKI à gérer (rotation clé publique, distribution) sans bénéfice tant qu'on n'a qu'un émetteur.
• Préfixe ah_live_. Détection automatique en cas de leak (GitHub secret scanning, gitleaks pre-commit, scrubbing logs). Sans préfixe, un secret aléatoire est indistinguable d'un autre blob et passe sous les radars.
• Auth maintenue en LAN Phase 1. L'auth applicative est notre dernière ligne de défense, pas le réseau. Si demain quelqu'un branche un appareil parasite sur le LAN ou se trompe de routeur, l'auth tient. Coût zéro pour bénéfice non-zéro.

Pistes rejetées

Token unique long-lived (sans JWT court). Plus simple, mais expose le secret racine sur tous les events WebSocket et toutes les requêtes REST. Une seule fuite = compromission durable jusqu'à révocation manuelle. Mauvais arbitrage simplicité/risque même au MVP.

OAuth2 / OpenID Connect avec provider externe. Disproportionné pour 5 agents machine sans humain final. Ajoute un fournisseur d'identité tiers (coût opérationnel, latence handshake, dépendance externe) là où un secret partagé suffit. Pertinent quand on aura des humains externes ou du SSO entreprise — pas le cas Phase 1 ni Phase 2.

JWT longue durée (24 h ou plus) sans token long-lived séparé. Inverse le problème : on fait tourner un JWT longue vie qui devient l'équivalent du token racine, mais sans révocation propre (les JWT sont stateless par design). Soit on accepte la fenêtre, soit on ajoute une blacklist côté serveur — auquel cas autant garder le modèle deux niveaux.

RS256 avec rotation de clés publiques. Pertinent en architecture multi-services où plusieurs vérifieurs ne partagent pas la clé. Au MVP, un seul service, donc complexité gratuite. À reconsidérer en Phase 3+ si on extrait l'auth en service séparé.

mTLS client-side certificates. Forte sécurité, mais coût opérationnel (PKI, distribution certs aux agents, rotation, révocation CRL/OCSP) hors budget MVP. Aussi peu pertinent en LAN Phase 1 que les autres mécanismes au-dessus de TCP.

Rotation glissante JWT_SECRET (deux clés acceptées en parallèle). Évite la coupure de 15 min lors d'une rotation, mais ajoute du code (gestion liste de clés, ordre, expiration de l'ancienne). Coût/bénéfice mauvais quand la coupure est ≤ 15 min et que la rotation est rare (trimestrielle). À ajouter si on rotate plus souvent ou si la coupure devient inacceptable opérationnellement.

Procédures opérationnelles

Rotation d'un API token agent (zéro-downtime)

1. Admin appelle POST /api/v1/agents/:id/tokens → reçoit { token: "ah_live_…", id: "<new-token-id>" } (secret en clair, une seule fois).
2. Admin met à jour AGENTHUB_TOKEN côté agent (env var, redémarrage du process agent ou rechargement à chaud si supporté).
3. L'agent rappelle POST /api/v1/sessions avec le nouveau token et obtient un JWT signé avec la même JWT_SECRET (transparent côté serveur).
4. Après la fenêtre d'overlap (24 h par défaut), un job de housekeeping marque l'ancien token revoked_at. L'admin peut accélérer via DELETE /api/v1/tokens/:old-id une fois certain que tous les agents ont migré.
5. Vérifier audit_events : token.issued (nouveau) + token.revoked (ancien).

Rotation JWT_SECRET (procédure complète dans RUNBOOK.md)

Voir §4 ci-dessus. Effet : invalide toutes les sessions, force un re-login des agents avec leur token long-lived, sans toucher aux tokens long-lived eux-mêmes.

Révocation immédiate d'urgence (token suspect)

1. DELETE /api/v1/tokens/:id → invalide la prochaine demande JWT.
2. Si on veut couper le JWT déjà émis dans la minute : rotate JWT_SECRET en plus.
3. Vérifier audit_events pour trace post-mortem.

Questions ouvertes

• Refresh JWT dédié : actuellement, l'agent rappelle POST /api/v1/sessions avec son token long-lived à chaque expiration. Si la fréquence devient trop élevée (très court exp à l'avenir, ou beaucoup d'agents), on peut introduire un endpoint POST /sessions/refresh accepté avec un JWT proche de l'expiration. Pas nécessaire au MVP (1 appel/15 min/agent = négligeable).
• Blacklist JWT côté serveur (tokenId révoqué) : le claim tokenId est déjà présent pour le permettre, mais aucune blacklist n'est implémentée au MVP. À ajouter si on a besoin de révocation immédiate (< 15 min) sans rotater JWT_SECRET.
• scopes granulaires : le champ existe en BDD mais n'est pas utilisé Phase 1 (un agent authentifié peut faire toutes les actions sur les salons dont il est membre). À utiliser en Phase 2 si on introduit des bots read-only ou des rôles différenciés.
• Rotation glissante de JWT_SECRET : voir Pistes rejetées. À reconsidérer si la fréquence de rotation augmente au point que la coupure de 15 min devient gênante.
• Fournisseur d'identité externe (OIDC, WorkOS, Keycloak) : à introduire seulement si on ouvre AgentHub à des humains externes ou à du SSO entreprise. Hors-périmètre Phase 1 et Phase 2.
• Algorithme d'argon2id : paramètres m=64MiB, t=3, p=1 retenus par défaut. À re-mesurer sur le serveur Ubuntu LAN Barodine pour ajuster t si la vérification dépasse 100 ms (cible : < 50 ms).