Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-017 title: L’authentification entrante résout les principaux canoniques avant l’autorisation date: 2026-08-14 status: proposé relates-to:

  • ADR-010
  • https://github.com/zeroclaw-labs/zeroclaw/issues/7141
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8289
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8290
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8076
  • https://github.com/zeroclaw-labs/zeroclaw/issues/7142
  • https://github.com/zeroclaw-labs/zeroclaw/issues/6996
  • https://github.com/zeroclaw-labs/zeroclaw/pull/8063
  • https://github.com/zeroclaw-labs/zeroclaw/pull/8272
  • crates/zeroclaw-api/src/principal.rs
  • crates/zeroclaw-api/src/grants.rs
  • crates/zeroclaw-runtime/src/security/auth_provider.rs
  • crates/zeroclaw-runtime/src/security/principal_resolver.rs
  • crates/zeroclaw-runtime/src/rpc/dispatch.rs
  • crates/zeroclaw-runtime/src/rpc/wss.rs
  • crates/zeroclaw-memory/src/sqlite_permissions.rs

ADR-017 : L’authentification entrante résout les principals canoniques avant l’autorisation

Contexte

ZeroClaw dispose de plusieurs moyens pour que des acteurs externes atteignent le daemon : RPC local, WSS distant, la passerelle web, les clients CLI et Zerocode, les canaux, et les futurs chemins agent-à-agent. Avant la RFC #7141 acceptée, ces surfaces ne partageaient pas de réponse unique et appliquée à la question « qui agit ? » ni à la question « que peut faire cet acteur ? ».

Les jetons TLS et de reconnexion ne suffisent pas. TLS peut protéger une connexion sans prouver que le client connecté dispose de l’autorité ZeroClaw. Le mécanisme existant tui_id / tui_sig assure la continuité de reconnexion et ne constitue pas une preuve d’identité indépendante. Un client WSS distant, un utilisateur de navigateur, un processus local, un expéditeur de canal et un client de service doivent tous converger vers le même modèle d’autorisation avant que tout travail privilégié du runtime ne commence.

Le risque ne se limite pas à l’absence d’authentification sur une seule route. Le risque le plus important tient à la multiplication de systèmes de sécurité parallèles : jetons d’appairage natifs, identifiants de pair, clés SSH, mots de passe, sujets OIDC, expéditeurs de canaux et identifiants de service inventent chacun leur propre identité utilisateur, leur propre vocabulaire de rôles, leurs propres clés de propriété et leur propre comportement de repli. Si cela se produit, une revendication admin d’un fournisseur, un nom d’utilisateur local ou une chaîne de sujet réutilisée peut contourner par accident la politique dont dépend une autre surface.

La RFC #7141 acceptée tranche l’orientation architecturale. Elle exige que les fournisseurs vérifient les identifiants, qu’un résolveur partagé fasse correspondre les identités vérifiées à des principaux ZeroClaw canoniques et aux autorisations des profils de permissions, et que les surfaces d’exécution consomment ces principaux résolus au lieu de réinterpréter elles-mêmes les identifiants. Le séquençage de l’implémentation relève de #8289, et le travail détaillé sur les sessions, la mémoire et l’autorisation par expéditeur est suivi dans #8290. Cet ADR consigne la décision durable sans affirmer que le déploiement est terminé.

Décision

Séparer l’identité entrante en vérification, résolution et application

L’authentification entrante comporte trois étapes distinctes :

  1. Un AuthProvider vérifie un identifiant unique et renvoie une identité authentifiée avec la provenance du fournisseur, le sujet, le type d’acteur, les revendications ou la liaison avec le registre local, l’expiration et les métadonnées de revalidation.

  2. One shared ZeroClaw resolver maps that authenticated identity to a canonical PrincipalId and the current permission-profile grants.

    Wait, I need to be careful: the system asks me to translate to fr. Output translation only.

    Un résolveur ZeroClaw partagé fait correspondre cette identité authentifiée à un PrincipalId canonique et aux autorisations actuelles du profil de permissions.

  3. Les surfaces d’exécution privilégiées (dispatch, gestionnaires de passerelle, sessions, mémoire, outils, configuration et autres) appliquent le principal résolu et les autorisations accordées.

L’implémentation Rust peut combiner des types en interne, mais les frontières d’autorité restent distinctes. Les fournisseurs vérifient l’identité. Ils n’émettent pas d’autorisations d’exécution ZeroClaw, n’interprètent pas les rôles IdP comme des permissions et ne contournent pas le résolveur partagé.

Utilisez des principals canoniques qui ne peuvent pas entrer en collision par accident de chaîne de caractères

A principal is ZeroClaw’s durable identity for the actor after authentication succeeds. Principal identity is globally unambiguous within a deployment.

Wait — I should translate this, not return it unchanged. Here is the French translation:

Un principal est l’identité durable de l’acteur dans ZeroClaw, une fois l’authentification réussie. L’identité d’un principal est globalement univoque au sein d’un déploiement.

Les identités humaines OIDC sont identifiées par l’émetteur validé et sub, et non par sub seul. Un alias de fournisseur peut apparaître dans la sortie d’audit, mais il ne peut pas faire en sorte que des chaînes de sujet identiques provenant d’émetteurs différents représentent le même acteur.

Les identités locales sont mappées via une configuration explicite du roster. Des identifiants locaux différents ne peuvent résoudre vers le même principal que si la configuration les relie. Un renommage d’affichage dans le roster doit préserver un identifiant de principal stable ou migrer de manière atomique les enregistrements de session, de mémoire, d’approbation et d’audit qui lui appartiennent.

client_credentials se résout en un principal de service, et non en un utilisateur humain. Les principaux de service ne doivent pas hériter des sessions de navigateur, des hypothèses liées à un utilisateur interactif ni de la mémoire privée d’un humain, du simple fait que des revendications portent des noms similaires.

Le couplage natif reste un chemin de compatibilité. Sauf si un mappage explicite ultérieur entre jeton et principal est configuré, un jeton de couplage partagé correspond à l’opérateur partagé et non à un utilisateur nommé.

L’égalité des chaînes entre fournisseurs ne lie jamais les comptes. La liaison de comptes entre fournisseurs nécessite une configuration explicite et un chemin de migration auditable.

Faire des profils de permission le seul vocabulaire d’autorisation à l’exécution

Les profils de permissions constituent le seul vocabulaire d’autorisation à l’exécution. Les revendications brutes des fournisseurs, les groupes IdP, les noms d’utilisateur locaux, les expéditeurs des canaux ou les noms de clients de service n’accordent aucun droit tant que le résolveur partagé ne les a pas associés aux profils de permissions de ZeroClaw.

Lorsqu’une identité correspond à plusieurs profils d’autorisation, le résolveur initial combine les autorisations explicites par union déterministe. Les sélecteurs à granularité fine se composent par intersection avec l’autorisation de ressource correspondante. Les listes de sélecteurs vides n’accordent aucune instance, et un accès large nécessite une autorisation explicite de type joker (wildcard), sélecteur global (all-selector) ou administrateur.

Chaque opération privilégiée portant sur un RPC, une passerelle, un outil, une configuration, une session ou une mémoire est classifiée et refusée par défaut. Une route ou une méthode ajoutée sans classification n’est pas implicitement autorisée. L’accès administrateur n’efface pas la propriété ; l’accès inter-principaux requiert un octroi administratif explicite et produit un événement d’audit.

Les sémantiques de refus explicite, les langages de politique propres à chaque fournisseur, les API plus larges d’administration des politiques et les différentes règles de priorité constituent des décisions distinctes. Elles ne découlent pas automatiquement de cet ADR.

Gardez l’authentification et les autorisations actives suffisamment longtemps pour pouvoir les révoquer

initialize est la poignée de main d’authentification RPC. Seules les méthodes minimales nécessaires à la finalisation de l’authentification s’exécutent avant qu’un principal ne soit lié. Toute méthode privilégiée rejette les appelants non authentifiés.

Le routage des identifiants est explicite. Lorsqu’un format d’identifiant ne permet pas d’identifier de manière sécurisée son fournisseur, le handshake identifie l’alias du fournisseur visé. Un bearer opaque n’est pas diffusé vers chaque endpoint d’introspection, et un échec avec la méthode ou le fournisseur sélectionné ne peut pas basculer vers un accès opérateur partagé ni vers une autorité plus étendue.

Les connexions établies ne conservent pas d’instantanés d’autorisation indéfiniment. Avant la prochaine opération privilégiée qui suit un changement de génération de la politique d’autorisation, le runtime recalcule les droits effectifs à partir de la configuration actuelle de permission-profile et de claim-mapping. La suppression ou la restriction d’un profil, d’un mapping, d’une entrée de roster, d’un fournisseur ou d’un jeton d’appairage doit affecter l’autorisation établie à la frontière de génération ou de revalidation documentée, plutôt que d’attendre une reconnexion ou un redémarrage du daemon.

L’expiration des identifiants et la révocation par le fournisseur s’appliquent aux connexions établies dans les garanties réelles du fournisseur. Le Principal canonique, les registres de propriété, les journaux et les enregistrements d’audit restent non secrets. Si la revalidation en temps réel nécessite un matériau de type bearer ou un descripteur secret équivalent, le fournisseur ne conserve que ce matériau minimal dans un contexte de revalidation appartenant au fournisseur et limité à la connexion, via la frontière de stockage de secrets prise en charge. Les consommateurs ordinaires de l’exécution ne peuvent pas le lire, et il est détruit lors de la déconnexion, de l’expiration des identifiants, de la suppression du fournisseur ou de la révocation.

La finalité du jeton OIDC est explicite. Le flux Authorization Code avec PKCE dans le navigateur valide un ID token comme preuve de l’événement d’authentification et établit une session ZeroClaw. Les chemins bearer des API et RPC n’acceptent qu’un access token destiné à ZeroClaw. Le Device Authorization Grant couvre les clients humains sans navigateur, et client_credentials couvre les principals de service. La validation hors ligne des JWT est limitée par l’expiration du jeton et par une durée maximale d’authentification configurée ; les déploiements qui exigent une révocation plus rapide doivent utiliser l’introspection, la révocation back-channel ou une autre autorité en temps réel.

Appliquer la propriété du principal aux frontières de stockage des sessions et de la mémoire

Chaque session authentifiée appartient à un principal canonique. La recherche de session, l’approbation, le rattachement, la reprise, la modification et la suppression doivent concorder sur ce propriétaire avant que l’opération ne réussisse. Les enregistrements inconnus, en conflit ou hérités sans propriétaire échouent en mode fermé pour les principals à portée limitée, sauf si une migration documentée les associe au principal opérateur partagé.

La mémoire privée est indexée par principal et par agent et n’est visible que pour ce principal, sauf si une autorisation administrative explicite en permet l’accès. La mémoire partagée de l’agent constitue un périmètre distinct et n’est visible que lorsqu’elle est activée et accordée.

La propriété par principal constitue une dimension de stockage supplémentaire ; elle ne remplace pas les dimensions agent, session, espace de noms et locataire. Les lectures, écritures, upserts et suppressions de mémoire privée incluent la propriété par principal dans le prédicat de stockage atomique. Une vérification préalable suivie d’une mutation plus large, ou une lecture suivie d’un filtrage a posteriori, ne suffit pas.

Les travaux initiés en interne ne doivent pas choisir un propriétaire par accident. Les exécutions planifiées, initiées par une SOP ou autres exécutions non interactives qui écrivent un état de session ou de mémoire appartenant à un propriétaire ont besoin d’une règle de principal explicite avant que la première tranche d’implémentation ne dépende d’une valeur par défaut.

Gardez les implémentations de fournisseur et de transport séparées de l’autorité d’autorisation

Toutes les surfaces entrantes utilisent le même modèle de principal et de profil de permissions, mais elles n’ont pas besoin de la même implémentation de transport. Le RPC local peut utiliser les identifiants du pair, le WSS distant peut utiliser l’appairage natif ou OIDC, la passerelle web authentifie au niveau du routeur, et les clients CLI ou Zerocode exposent des flux de connexion adaptés au fournisseur.

Le couplage natif (appairage) et les identifiants de pair local sont des chemins de compatibilité requis pour le premier déploiement du contrôle d’application, afin que l’authentification WSS distante ne soit pas livrée dans un état appliqué mais inutilisable. OIDC est le premier fournisseur externe requis. La connexion par mot de passe local dans le navigateur, la challenge-response par clé SSH, l’identité mTLS, le provisionnement de type SCIM, l’identité de canal et l’identité agent-à-agent sont des extensions compatibles, et non des critères de clôture pour la première livraison OIDC, sauf si une décision ultérieure les promeut.

Critères d’acceptation

Cet ADR reste proposé jusqu’à ce que toutes ces conditions soient remplies :

  • le registre canonique des fournisseurs, le contrat d’identité authentifiée, le modèle d’identité des principaux, le vocabulaire des profils de permissions, le résolveur partagé, le routage explicite des identifiants et la ré-résolution des autorisations tenant compte de la génération, livrés ensemble avec des tests portant sur la gestion des espaces de noms, les identités non mappées, le comportement de refus par défaut des sélecteurs et le refus de repli vers un autre fournisseur;

  • l’appairage natif, les identifiants de pair locaux, la distribution RPC, la validation au démarrage de WSS et la continuité de reconnexion imposent l’authentification par construction, sans créer d’intervalle distant appliqué mais inutilisable ;

  • OIDC JWT/JWKS, introspection, Authorization Code avec PKCE dans le navigateur, Device Authorization Grant sans navigateur, client_credentials pour les services, séparation des usages des jetons, revalidation bornée et propagation du principal de la passerelle fonctionnent via le même resolver et échouent en mode fermé (fail closed) lorsque les identifiants, l’état du fournisseur ou le contexte de revalidation sont indisponibles ;

  • sessions, approvals, pièces jointes, reprises, suppressions, lectures de mémoire privée et modifications de mémoire privée appliquent la propriété du principal à la frontière du stockage, y compris un traitement documenté des enregistrements hérités et une règle explicite de propriétaire d’origine interne pour les travaux planifiés ou initiés par une SOP;

  • existing remote WSS and Nevis users have documented and tested migration paths, and local-only recovery can repair lockout without restoring unauthenticated remote access;

    Wait, I need to translate it, not repeat it. Here is the French translation:

    existing remote WSS et Nevis users ont des chemins de migration documentés et testés, et la récupération locale uniquement peut réparer un verrouillage sans rétablir un accès distant non authentifié;

  • La documentation explique les identités, les types d’acteurs, la correspondance des revendications (claims), les profils d’autorisation, les grants, la mémoire privée et partagée, les garanties des fournisseurs, la migration, la récupération et le vocabulaire de handshake aligné sur les standards, le cas échéant ; et

  • Le déploiement arrive sous forme de frontières de sécurité vérifiables et réversibles de manière indépendante, suivies par #8289 et #8290, plutôt que sous la forme d’une seule branche combinée couvrant le fournisseur, le dispatcher, la passerelle, le stockage, la migration et la documentation.

Le socle Principal / AuthProvider neutre en comportement et les tests de contrat préparatoires ont été intégrés via #8063 et #8272. Ces lots sont des travaux préparatoires, et non la preuve que les critères de validation complets de cet ADR sont atteints.

Conséquences

Conséquences positives :

  • Les nouveaux fournisseurs entrants peuvent être ajoutés sans que chaque fournisseur ait à créer son propre système d’autorisation.
  • Un relecteur futur peut poser une question à chaque frontière privilégiée : quels principaux résolus et quelles autorisations accordées sont appliqués ici ?
  • OIDC, les identifiants locaux, l’appairage natif et les identifiants de service ne peuvent pas entrer en collision simplement parce qu’ils partagent une même chaîne de caractères.
  • Les révocations et les modifications de profil d’autorisation ont des limites documentées en temps réel, au lieu d’attendre indéfiniment une reconnexion ou un redémarrage.
  • L’isolation des sessions et de la mémoire privée devient une propriété du stockage plutôt qu’un filtrage au mieux réalisé au-dessus du magasin.

Conséquences négatives :

  • Il s’agit d’un changement de sécurité incompatible pour le comportement WSS distant non authentifié ; la compatibilité native et la récupération doivent donc être livrées avec le mécanisme de mise en application.
  • Le résolveur partagé, le vocabulaire de profils et la revalidation tenant compte des générations ajoutent plus d’infrastructure qu’une vérification de rôle locale au fournisseur.
  • L’implémentation OIDC doit préserver la finalité des jetons, la découverte, le rafraîchissement du JWKS, l’introspection et les frontières des métadonnées conformes aux standards, plutôt que d’accepter tout jeton d’apparence valide.
  • La propriété principale touche le stockage des sessions et de la mémoire ; la migration et le retour arrière demandent donc plus de précautions qu’une simple vérification d’authentification en périphérie.
  • Quelques extensions utiles, notamment la connexion par mot de passe, l’authentification par clé SSH, le mTLS, SCIM, l’identité de canal et l’identité agent-à-agent, restent des travaux de suivi distincts.

Références