Authentification et principaux

Chaque connexion RPC au démon associe un principal lors de la négociation initialize, et chaque appel de méthode est vérifié par rapport aux droits que la configuration actuelle attribue à ce principal. Cette page décrit l’ensemble des fournisseurs, la liste des utilisateurs locaux, les profils de permissions et, surtout, ce qui change pour les connexions distantes existantes.

Le modèle en une seule passe

1. Fournisseur vérifie un seul identifiant : un auth_token explicite issu de la poignée de main sélectionne le fournisseur nommé par auth_provider (par défaut native, le jeton d’appairage de la passerelle), et sans jeton, un socket Unix local présente son uid de pair noyau au fournisseur peercred. Le rejet d’un fournisseur sélectionné est définitif : un identifiant n’est jamais réessayé auprès d’un autre fournisseur.

2. **Le résolveur partagé associe l’identité vérifiée à un identifiant de principal canonique et aux profils de permissions que la configuration lui attribue. Les identités OIDC sont indexées par le couple émetteur + sujet validés, tandis que les identités du registre local le sont par leur identifiant de principal durable [users.<name>].

3. Chaque méthode RPC, à l’exception des deux méthodes de poignée de main, est associée à une autorisation ressource-verbe requise et refusée sans celle-ci. initialize transporte lui-même l’identifiant d’authentification, et cert/renew est authentifié par le certificat client mutual-TLS qui le présente, et non par un principal. Les sélecteurs à granularité fine se composent par-dessus :

   • config writes check config_write_paths;
   • session/new et session/prompt vérifient le sélecteur d’agent et imposent que le répertoire de travail de la session soit un répertoire que la politique de cet agent autorise à la fois en lecture et en écriture, que ce répertoire ait été désigné par la requête, enregistré avec une session reprise ou restauré depuis une session durable. La session est liée au répertoire résolu et non à la graphie demandée ; ainsi, rediriger un cwd symbolique après admission ne le déplace pas, et une session active détenue sous un tel alias est refusée. Les autres méthodes de session ne vérifient pas encore l’agent, comme décrit dans Ce que cette couche ne fait pas (encore);
   • running ou approuver une SOP exige chacun des agents sous lesquels elle s’exécute, avec la même règle de sélection d’outils qu’une session, et créer, enregistrer ou supprimer une SOP exige les agents sous lesquels elle s’exécute. Une étape qui ne nomme aucun agent, ni sur l’étape ni sur la procédure, est considérée comme utilisant le premier alias d’agent configuré selon l’ordre de tri, c’est-à-dire l’agent vers lequel l’exécuteur headless se replie. Chaque étape est prise en compte, y compris les étapes d’une procédure déterministe ;
   • Les pièces jointes, les fichiers de personnalité, les requêtes de coûts qui désignent un agent et les tâches cron vérifient le sélecteur d’agent. Une pièce jointe envoyée par chemin local doit aussi indiquer un chemin absolu que la politique de l’agent destinataire autorise à lire. Un récapitulatif des coûts de la flotte ne liste que les agents du principal dans sa ventilation par agent, mais ses totaux et son utilisation par modèle couvrent toujours tous les agents;
   • fs/list_dir ne liste que les chemins absolus que la politique d’un agent activé, que le principal peut utiliser, autorise cet agent à lire. Il refuse les chemins relatifs, les composants .. et, sous Windows, les chemins réseau et de périphérique. Ces racines proviennent de la politique résolue de chaque agent : son profil de risque, les espaces de travail voisins auxquels workspace.access accorde un accès en lecture (en lecture et écriture, pour un espace de travail de session), ainsi que le répertoire partagé des skills, qui est en lecture seule. Un agent qui n’est pas limité à son espace de travail (autonomie full, un profil de risque avec workspace_only = false, le preset yolo, ou workspace.unrestricted_filesystem = true) peut lire tout chemin situé en dehors de ses chemins interdits ; un principal autorisé à utiliser un tel agent peut donc lister et ouvrir des sessions partout où cet agent le pourrait.

   session/new et session/prompt répètent ces vérifications après l’attente dans la file d’attente de la session, de sorte qu’une requête mise en file avant que son principal ne soit restreint ou que son justificatif n’expire soit refusée lorsque son tour arrive.

L’autorisation est active pour les modifications effectuées via les méthodes de configuration RPC du daemon, que l’éditeur de configuration de zerocode utilise : la modification de [permission_profiles], [users], [oidc] ou security.trust_daemon_uid de cette manière recompile la politique au moment de l’enregistrement. Les connexions établies par jeton natif et les connexions locales sont réévaluées lors de leur prochaine opération, sans reconnexion ni redémarrage, tandis qu’une connexion OIDC doit être réinitialisée. Les modifications effectuées en dehors du daemon, directement dans config.toml, via le tableau de bord web, ou avec zeroclaw config set, prennent effet au prochain rechargement ou redémarrage du daemon. La révocation d’un jeton d’appairage de la passerelle via les contrôles d’appairage de la passerelle invalide les connexions authentifiées avec ce jeton avant leur prochaine opération. Supprimer un jeton de gateway.paired_tokens en modifiant la configuration, via RPC ou sur le disque, n’a aucun effet sur le daemon en cours d’exécution, et les connexions utilisant ce jeton restent autorisées. La suppression prend effet au prochain rechargement ou redémarrage du daemon, sauf si une modification d’appairage effectuée via la passerelle d’ici là réécrit dans la configuration l’ensemble des jetons actifs, y compris ce jeton. Révoquez les jetons via les contrôles d’appairage.

Fournisseurs

Connexions locales

Sur un socket Unix, une connexion qui ne présente aucun jeton est identifiée par son uid de pair noyau. Tant que security.trust_daemon_uid vaut true (la valeur par défaut), le uid propre du démon se connecte en tant qu’opérateur partagé de confiance avec un accès complet, avec ou sans registre [users], de sorte qu’une installation sans registre se comporte comme auparavant pour le compte qui exécute le démon.

L’opérateur qui exécute le démon est propriétaire de son fichier de configuration, et la récupération locale en cas de verrouillage repose sur cette autorité. Sur une socket Unix, définissez security.trust_daemon_uid à false pour exiger que chaque pair local, y compris l’uid du démon lui-même, soit mis en correspondance avec le roster ou présente un jeton. Ce paramètre n’a aucun effet sur un tube nommé Windows, décrit ci-dessous.

Tout autre uid autre doit être associé par une entrée explicite [users.<name>].uid. Un uid non associé (y compris root) qui ne présente aucun jeton est refusé, qu’une liste d’utilisateurs existe ou non ; il n’existe aucun repli vers un accès opérateur partagé. L’écouteur crée le socket réservé au propriétaire ; aujourd’hui, seuls le compte du démon et root peuvent donc l’atteindre. Une entrée de la liste détermine ce que tout autre uid peut faire une fois qu’il y a accès.

Les named pipes Windows ne transportent aucun uid de pair. Sans roster, l’ACL du pipe sert d’identifiant et une connexion locale correspond à l’opérateur partagé. Dès qu’un roster [users] existe, un client local doit présenter un jeton, security.trust_daemon_uid n’a plus aucun effet, et le compte propre du daemon ne dispose d’aucune voie locale de confiance. Un jeton de passerelle appairé authentifie toujours en tant qu’opérateur partagé pendant la compilation de la politique ; un client qui en envoie un, via WSS ou via le pipe, peut donc réparer le roster à chaud. La connexion locale par pipe de zerocode n’envoie aucun jeton ; sans un tel client, un verrouillage se répare en éditant config.toml puis en redémarrant.

Un client peut transmettre son environnement shell dans initialize afin que les sous-processus du démon voient son PATH et ses sockets d’identifiants (voir Transmission des variables d’environnement). Ce snapshot n’est conservé que pour un principal de niveau opérateur (l’opérateur partagé, ou un principal du roster avec admin = true) sur une connexion locale. Tout autre principal, ainsi que toute connexion distante, reçoit à la place l’environnement propre du démon.

L’éligibilité est vérifiée à nouveau lors de la création ou de la restauration d’une session. Une session existante qui conserve un environnement transmis non vide ne peut être reprise ou recevoir de requête que par un opérateur local actuellement autorisé. Une reconnexion via WSS, ou la perte du rôle admin alors qu’une requête est en file d’attente, ne transmet pas cet environnement au tour suivant : la requête est refusée avant exécution. Créez une nouvelle session pour continuer sans l’environnement transmis. Les sessions sans valeurs transmises restent éligibles à une reprise normale, sous réserve des autres vérifications d’autorisation. L’environnement conservé est immuable pendant toute la durée de vie de sa session ; refuser une requête ultérieure ne le réécrit pas sous un tour déjà en cours d’exécution. Une reprise exige également que l’environnement autorisé de la connexion actuelle corresponde à l’environnement conservé de la session. S’il diffère, créez une nouvelle session ; une session sans environnement peut toujours être reprise après la suppression du rôle admin.

Récupération

Aucun contournement d’authentification à distance n’est proposé : une connexion distante doit toujours présenter un identifiant valide. Tant que la politique d’autorisation se compile encore, un client détenant un jeton de passerelle appairé ou un principal de niveau opérateur peut réparer un verrouillage depuis n’importe où. Sans un tel identifiant, et toujours dans l’état deny-all, la voie de retour s’exécute sur l’hôte qui exécute le démon. La voie locale à appliquer dépend du fait que la politique se compile encore ou non.

Accès bloqué à une politique qui compile. L’autorisation est active et le chemin local de confiance est intact sur un socket Unix ; sous Windows, voir la note sur le tube nommé ci-dessus. Connectez-vous localement avec l’uid propre au daemon : avec security.trust_daemon_uid = true (la valeur par défaut), ce compte est l’opérateur partagé de confiance, quelle que soit la liste des utilisateurs. Corrigez l’entrée fautive via cette connexion locale, par exemple dans l’éditeur de configuration de zerocode ou avec un RPC config/set sur users.alice.uid, et la modification est compilée et publiée au moment de l’enregistrement. La modification de config.toml ou l’exécution de zeroclaw config set corrige également le problème, mais seulement une fois que le daemon a rechargé sa configuration ou redémarré.

Verrouillé par un état accepté de refus total. La politique n’a pas pu être compilée, donc l’état accepté refuse chaque principal avant l’exécution de la résolution, y compris l’uid du démon lui-même et l’opérateur partagé. Aucun RPC ne permet de le réparer : config/set et config/reload sont refusés comme tout le reste. Modifiez config.toml directement en tant que propriétaire, puis redémarrez le démon afin que les sections réparées soient compilées et publiées. Le démon ignore SIGHUP, donc un redémarrage est l’étape qui le recharge.

Si security.trust_daemon_uid est défini à false, la route par UID de confiance disparaît. Une politique qui compile peut toujours être réparée à chaud par un client présentant un jeton de passerelle appairé, ou par un principal figurant dans le roster et disposant de droits d’administrateur ; sinon, les deux états se réparent de la même manière : modifier config.toml en tant que son propriétaire, puis redémarrer. Ne désactivez ce paramètre que là où c’est acceptable.

Liste des utilisateurs

zeroclaw config set users.<alias>.permission_profiles <value>

export ZEROCLAW_users__<alias>__permission_profiles=

zeroclaw config set users.<alias>.principal_id <value>

export ZEROCLAW_users__<alias>__principal_id=

zeroclaw config set users.<alias>.uid <value>

export ZEROCLAW_users__<alias>__uid=

Le nom de l’entrée sert d’identifiant de principal durable, sauf si principal_id en fixe un explicitement. Les enregistrements d’audit sont indexés sur cet identifiant aujourd’hui. Les sessions, la mémoire et les approbations ne sont pas encore indexées dessus (voir Ce que cette couche ne fait pas (encore)), mais elles le seront. Pour renommer une entrée sans rendre ses données orphelines plus tard, définissez donc principal_id sur l’identifiant d’origine dans la même modification.

OIDC

Chaque entrée [oidc.<alias>] correspond à une relation de confiance avec un émetteur ; la vérification des jetons (JWKS hors ligne ou introspection RFC 7662), le mappage des revendications et les bornes de durée de vie sont documentés dans la référence de la section :

zeroclaw config set oidc.<alias>.actor_claim <value>

export ZEROCLAW_oidc__<alias>__actor_claim=

zeroclaw config set oidc.<alias>.actor_claim_marks <value>

export ZEROCLAW_oidc__<alias>__actor_claim_marks=

zeroclaw config set oidc.<alias>.allowed_authorized_parties <value>

export ZEROCLAW_oidc__<alias>__allowed_authorized_parties=

zeroclaw config set oidc.<alias>.audience <value>

export ZEROCLAW_oidc__<alias>__audience=

zeroclaw config set oidc.<alias>.claim_path <value>

export ZEROCLAW_oidc__<alias>__claim_path=

zeroclaw config set oidc.<alias>.client_id <value>

export ZEROCLAW_oidc__<alias>__client_id=

zeroclaw config set oidc.<alias>.client_secret    # entrée masquée, stockée chiffrée

export ZEROCLAW_oidc__<alias>__client_secret=

zeroclaw config set oidc.<alias>.interactive_clients <value>

export ZEROCLAW_oidc__<alias>__interactive_clients=

zeroclaw config set oidc.<alias>.issuer <value>

export ZEROCLAW_oidc__<alias>__issuer=

zeroclaw config set oidc.<alias>.max_auth_lifetime_secs <value>

export ZEROCLAW_oidc__<alias>__max_auth_lifetime_secs=

zeroclaw config set oidc.<alias>.profile_map <value>

export ZEROCLAW_oidc__<alias>__profile_map=

zeroclaw config set oidc.<alias>.require_at_jwt <value>

export ZEROCLAW_oidc__<alias>__require_at_jwt=

zeroclaw config set oidc.<alias>.require_mfa <value>

export ZEROCLAW_oidc__<alias>__require_mfa=

zeroclaw config set oidc.<alias>.required_acr <value>

export ZEROCLAW_oidc__<alias>__required_acr=

zeroclaw config set oidc.<alias>.revalidation_secs <value>

export ZEROCLAW_oidc__<alias>__revalidation_secs=

zeroclaw config set oidc.<alias>.service_clients <value>

export ZEROCLAW_oidc__<alias>__service_clients=

zeroclaw config set oidc.<alias>.service_profile_map <value>

export ZEROCLAW_oidc__<alias>__service_profile_map=

zeroclaw config set oidc.<alias>.validation <value>

export ZEROCLAW_oidc__<alias>__validation=

Inscription (obtention d’un jeton à présenter)

Le démon ne fait que vérifier les jetons ; les clients les obtiennent auprès de l’IdP. Deux flux sans navigateur sont fournis avec la CLI :

# Connexion interactive via le flux d'autorisation par appareil (RFC 8628) :
# prints a verification code to enter in any browser, waits for
# approbation, puis écrit le jeton d'accès sur la sortie standard.
export ZEROCLAW_AUTH_TOKEN=$(zeroclaw oidc login corp)

# Identique, via le navigateur système : Authorization Code + PKCE (S256 uniquement)
# with an RFC 8252 one-shot loopback listener. The mechanisms never
# se replier l'un sur l'autre.
export ZEROCLAW_AUTH_TOKEN=$(zeroclaw oidc login corp --browser)

The user message is a truncated documentation heading: "# Headless service principals via client_credentials (requires the". Translate to French, preserving formatting and code literals.

# Principaux de service sans interface via client_credentials (nécessite le
# entrydu client_secret) :
export ZEROCLAW_AUTH_TOKEN="$(zeroclaw oidc token corp)"

Les messages de progression vont sur stderr ; stdout ne contient que le jeton, de sorte que les deux commandes se composent avec la substitution de commande (les commandes oidc s’exécutent avant tout préambule de démarrage susceptible d’afficher du texte, y compris la divulgation de la graine OTP). Rien n’est stocké : présentez le jeton sous la forme auth_token dans la poignée de main RPC (ou via la variable d’environnement) avant son expiration, puis réinscrivez-vous.

Le client ne fait confiance qu’à l’émetteur nommé dans l’entrée, et à aucun autre : le document de découverte doit affirmer exactement cet émetteur avant que tout point de terminaison qu’il annonce ne soit utilisé ; chaque point de terminaison qui reçoit un justificatif doit respecter la même politique d’URL que l’émetteur (https, ou http uniquement pour un hôte de bouclage exact) ; les redirections ne sont jamais suivies ; les corps de réponse ont une taille plafonnée ; et une réponse de jeton n’est acceptée que si elle contient un jeton d’accès Bearer non vide. Un client confidentiel (une entrée avec un client_secret) s’authentifie avec HTTP Basic à chaque requête ; un client public envoie son client_id dans le formulaire.

--browser ouvre le navigateur système pour vous sous macOS et Linux, et sur toutes les plateformes il affiche également l’URL de connexion afin que vous puissiez l’ouvrir manuellement dans un navigateur sur la même machine (le rappel arrive sur un port de bouclage local de l’hôte qui exécute la CLI). Le lanceur du navigateur s’exécute détaché des flux standard de la CLI, de sorte que tout ce qu’un lanceur écrit sur sa propre sortie standard ne peut pas contaminer le résultat : la sortie standard ne contient toujours que le jeton.

Les deux adaptateurs de rappel, l’écouteur loopback de la CLI et le rappel de la passerelle, appliquent la vérification de l’émetteur de la RFC 9207. Une réponse dont le paramètre iss ne correspond pas à l’émetteur qui a démarré le flux est refusée avant que son code ou son error ne soit pris en compte. Une réponse sans iss est acceptée, car ce paramètre est facultatif et tous les émetteurs ne l’envoient pas. Lorsque l’échange de code renvoie un id_token en plus du jeton d’accès, cet id_token est entièrement validé (émetteur, audience, expiration et nonce lié à ce flux), puis écarté. Seul le jeton d’accès est présenté au démon. Le client d’enrôlement applique la même méfiance à la découverte elle-même : il refuse un document .well-known/openid-configuration dont issuer ne correspond pas exactement à l’émetteur configuré, barre oblique finale comprise, avant d’utiliser tout point de terminaison qu’il désigne (la vérification de la RFC 8414). Il plafonne aussi la taille des documents lus, afin qu’un émetteur hostile ou défaillant ne puisse ni rediriger le flux vers des points de terminaison de son choix, ni répondre avec un corps de taille illimitée.

Les clients qui ne détiennent aucun identifiant IdP (le tableau de bord web, zerocode) s’enrôlent à la place via la gateway, qui relaie les mêmes flux avec les identifiants client de l’entrée configurée : GET /api/oidc/providers liste les alias, POST /api/oidc/{alias}/device/start et /device/poll pilotent le flux device grant, et GET /oidc/login/{alias} exécute le flux navigateur, dont la page de callback à usage unique transmet le jeton à la fenêtre ouvrante via postMessage (même origine uniquement), avec une copie manuelle en solution de repli. La gateway envoie également Cross-Origin-Opener-Policy: same-origin, ce qui rompt window.opener une fois que la popup a navigué vers le fournisseur d’identité. Dans les navigateurs actuels, la copie manuelle sur cette page est donc le transfert qui fonctionne aujourd’hui, et le contrat postMessage est en place pour le suivi côté tableau de bord. Ces routes ne nécessitent pas d’authentification par nécessité (l’enrôlement précède l’authentification), sont soumises à une limitation de débit et n’accordent aucun droit : elles se contentent de relayer ce que l’IdP accorde après l’approbation de l’utilisateur. Justification de la conception et tableau des modes de défaillance : docs/security/oidc-browser-pkce-design-8289.md dans le dépôt.

La limitation de débit fonctionne par couches. Les requêtes qui démarrent un flux (POST /api/oidc/{alias}/device/start, GET /oidc/login/{alias} et GET /oidc/callback) sont comptabilisées par une instance du limiteur de tentatives par force brute de la passerelle, dédiée à l’enrôlement : mêmes seuils et même verrouillage que ceux qui s’appliquent à un jeton d’appairage incorrect, mais tenue dans son propre registre. Ainsi, une adresse verrouillée pour l’enrôlement peut toujours s’appairer ou présenter une signature de webhook, et un verrouillage obtenu sur l’un de ces deux usages ne bloque jamais l’enrôlement. Un callback n’est comptabilisé comme tentative que s’il est infructueux : aucun état de flux actif pour le state qu’il transporte, un émetteur qui ne correspond pas, une erreur renvoyée par le fournisseur d’identité, aucun code d’autorisation, un alias supprimé pendant que le flux était en cours, ou un échec de l’échange de code. Un callback qui termine une connexion n’est pas compté, pas plus que celui que la passerelle refuse elle-même parce que sa capacité de relais est saturée ; ainsi, une foule de personnes qui se connectent simultanément ne peut pas verrouiller leur adresse partagée. Une connexion par navigateur refusée parce que le magasin de flux en attente est plein n’est pas non plus comptée pour l’appelant, pour la même raison. Les listages de fournisseurs, les interrogations de périphérique (device polls) et les démarrages de connexion sont soumis à un budget par client de 20 requêtes par minute, ce qui laisse une marge au-dessus de l’intervalle minimal d’interrogation de cinq secondes de la RFC 8628 (12 interrogations par minute) sans permettre à un client de tourner en boucle. Une interrogation est comptabilisée comme tentative lorsque le fournisseur d’identité répond slow_down ou rejette purement et simplement le code de périphérique ; ainsi, un client qui relaie des codes de périphérique invalides tombe dans le verrouillage existant au lieu d’interroger indéfiniment. En revanche, un échec de transport sur la liaison de la passerelle vers le fournisseur d’identité ne dit rien de l’appelant et ne lui est pas imputé. Un client qui dépasse son budget, ou qui est verrouillé, reçoit un HTTP 429 accompagné d’un Retry-After indiquant le délai en secondes ; zerocode attend au moins ce délai, et jamais moins que l’incrément de cinq secondes de la RFC, avant son interrogation suivante (dans la limite de la durée de vie restante du code de périphérique), et n’interroge en aucun cas plus d’une fois toutes les cinq secondes. Au plus 16 relais sortants vers le fournisseur d’identité sont en cours simultanément, tous clients confondus, ce qui borne ce que la passerelle peut faire auprès du fournisseur d’identité au nom de tous. Le magasin de flux en attente contient 32 connexions par navigateur simultanées, et un même client distant peut en détenir huit ; ainsi, un appelant qui démarre des connexions sans jamais les terminer ne peut pas monopoliser le magasin au détriment de tous les autres pendant les dix minutes de vie de ces flux. Les clients loopback sont exemptés des budgets par client, comme ils le sont de toute autre limite d’authentification de la passerelle ; un reverse proxy situé sur le même hôte doit donc activer trust_forwarded_headers pour que les limites par client s’appliquent aux appelants réels qui se trouvent derrière lui. Chaque réponse d’enrôlement porte Cache-Control: no-store et Pragma: no-cache en plus de la politique no-referrer de la passerelle, car les codes de périphérique et les jetons d’accès transitent dans ces corps de réponse.

zerocode s’inscrit via la même API depuis sa propre configuration. [connection.wss] enroll_url désigne l’origine HTTP de la passerelle, et un préfixe de chemin facultatif est autorisé. Elle doit être https://, sauf si elle pointe vers une adresse de bouclage (127.0.0.1, ::1 ou localhost), car le code d’appareil puis le jeton d’accès transitent par cette connexion, et les redirections ne sont pas suivies, de sorte qu’un saut en clair ne peut pas être introduit après coup. La connexion d’inscription utilise le même matériel de confiance [connection.wss.tls] que la branche WSS : l’autorité de certification configurée, skip_verify et le certificat client de TLS mutuel. Lorsque ce matériel laisse le certificat non vérifié, zerocode demande confirmation avant l’envoi du code d’appareil et non après l’arrivée du jeton, et cette demande porte sur l’origine d’inscription elle-même, qui peut ne pas être le démon auquel la session se connecte ensuite. Répondre always enregistre cette origine dans skip_verify_routes ; une exécution non interactive n’a personne à qui poser la question, l’inscription s’arrête donc à ce stade. zerocode borne chaque attente d’interrogation à la durée de vie restante du code d’appareil et n’interroge jamais après son expiration. Il refuse une durée de vie annoncée supérieure à une heure ou un intervalle d’interrogation supérieur à cinq minutes, plutôt que d’attendre sur une réponse hostile. Un intervalle annoncé de 0 ou 1 est ramené à la valeur par défaut de cinq secondes de la RFC 8628, afin qu’une réponse de la passerelle ne puisse pas placer zerocode sur une interrogation toutes les secondes, que le budget par client refuserait de toute façon. Le jeton reçu n’est conservé en mémoire que pour cette session.

Profils d’autorisation

zeroclaw config set permission_profiles.<alias>.admin <value>

export ZEROCLAW_permission_profiles__<alias>__admin=

zeroclaw config set permission_profiles.<alias>.allowed_agents <value>

export ZEROCLAW_permission_profiles__<alias>__allowed_agents=

zeroclaw config set permission_profiles.<alias>.allowed_tools <value>

export ZEROCLAW_permission_profiles__<alias>__allowed_tools=

zeroclaw config set permission_profiles.<alias>.config_write_paths <value>

export ZEROCLAW_permission_profiles__<alias>__config_write_paths=

zeroclaw config set permission_profiles.<alias>.grants <value>

export ZEROCLAW_permission_profiles__<alias>__grants=

Les profils refusent par défaut : une ressource non listée est refusée, une liste de sélecteurs vide n’accorde aucune instance, et un accès étendu exige le sélecteur explicite "*" ou admin = true. Plusieurs profils fusionnent par union. Pour les tâches cron, les pièces jointes, les fichiers de personnalité, les requêtes de coût par agent et la rédaction de SOP, allowed_agents = ["*"] ne couvre que les agents définis par la configuration, et non un alias qu’une requête nommerait.

Les sélecteurs d’outils se combinent par intersection lors de l’assemblage de l’agent, en complément de l’autorisation globale : l’exécution d’outils côté modèle correspond à tools = ["execute"], et un principal sans cette autorisation reçoit une session sans outil, quels que soient les outils nommés dans son allowed_tools, y compris "*". Lorsque cette autorisation est détenue, une session créée par un principal restreint ne reçoit que les outils nommés dans son allowed_tools (une liste vide donne une session sans outil), en plus de ce que le profil de risque propre à l’agent autorise. Après l’admission d’une invite en file d’attente, l’autorisation est revérifiée auprès du résolveur partagé, y compris l’expiration et la révocation des identifiants. Le sélecteur de principal actuel restreint les outils statiques, le registre de recherche différée, les outils déjà activés et le contenu de ressources MCP épinglé (chaque bloc épinglé est admis sous son nom <server>__<uri> et retiré des invites suivantes dès que le sélecteur ne le nomme plus) ; les outils supprimés ne peuvent pas être réactivés. Les sessions réutilisées sont restreintes avant leur prochain tour, et les sessions réhydratées sont reconstruites selon les autorisations actuelles. Les sélecteurs d’agent sont vérifiés avant chaque tour et avant la réhydratation.

Le rétrécissement ne rajoute jamais d’outils à un agent existant. Après l’élargissement des autorisations, créez une nouvelle session pour recevoir la surface élargie. Aucun nouvel instantané de configuration ni cache de politique de principal indépendant n’est stocké dans l’agent.

Les instructions MCP différées sont dérivées des outils restants pouvant être chargés et affichées uniquement lorsque tool_search est exposé. Un principal a besoin à la fois de tool_search et de l’outil MCP différé nommé pour l’activation à la demande ; l’assistant n’est jamais accordé implicitement. Les outils MCP autorisés avec mode = "always" sont préactivés et restent appelables sans l’assistant.

Si le sélecteur d’outils ou le sélecteur d’agents du principal est restreint, delegate (borné et indépendant), spawn_subagent et execute_pipeline sont indisponibles, y compris les alias de skills qui encapsulent ces outils. Ces chemins imbriqués ne disposent pas encore des deux plafonds actuels du principal ; le tour parent ordinaire reste utilisable. Les principaux administrateurs et les principaux dont les deux sélecteurs valent "*" conservent les capacités imbriquées configurées de leur agent.

Le constructeur Rust Agent::from_live_config_with_tui_env à huit arguments existant reste disponible. RPC utilise le constructeur additif from_live_config_with_tui_env_and_principal_tools et réapplique les autorisations accordées par le résolveur partagé lors de l’admission du prompt.

Cette composition ne couvre pas toutes les voies d’accès aux outils d’un agent. Les tâches cron et la création de SOP ne vérifient que le sélecteur d’agent. Un principal contraint détenant des autorisations cron peut créer une tâche shell pour son agent, ou attribuer un nouveau prompt à une tâche d’agent existante et la déclencher, et un principal détenant des autorisations de création ou de mise à jour de SOP peut enregistrer une procédure dont le déclencheur l’exécutera ultérieurement. Traitez les autorisations cron et de rédaction de SOP comme des autorisations sur les outils de l’agent.

Changement incompatible : le WSS distant nécessite une authentification

À partir de cette modification, une connexion WSS distante doit présenter auth_token dans initialize. Il n’existe aucun mode de repli distant non authentifié.

Un listener [wss] activé sans aucun chemin d’authentification possible (ni [oidc.<alias>], ni jetons appairés, et gateway.require_pairing = false) est rejeté par la validation de la configuration, de sorte qu’aucune interface prise en charge ne peut l’enregistrer. Une configuration déjà présente sur le disque sous cette forme démarre quand même : le daemon se lance et le listener refuse chaque poignée de main distante. Elle n’est pas refusée au chargement, car un opérateur doit pouvoir démarrer un daemon pour le réparer.

Les sections [oidc.<alias>], [users] ou [permission_profiles] invalides constituent le cas séparé. Dans ce cas, la politique d’autorisation elle-même ne se compile pas : le démon installe alors un état d’acceptation de refus total et journalise qu’il le fait, jusqu’à ce que les sections soient réparées et rechargées. Sous cet état, tous les principaux sont refusés, aussi bien pour les connexions distantes que locales, y compris l’uid du démon lui-même. La réparation consiste donc en la correction sur disque décrite sous Récupération ci-dessus.

Migration pour les utilisateurs existants de zerocode distants :

1. Associez-vous à la passerelle comme d’habitude pour obtenir un jeton d’accès (bearer token).

2. Donnez le jeton à zerocode, soit dans sa configuration :

   [connection.wss]
   uri = "wss://daemon.example.com:9443"
   auth_token = "zc_..."
   

   ou via la variable d’environnement ZEROCLAW_AUTH_TOKEN, qui remplace la valeur du fichier de configuration et permet de garder l’identifiant hors du fichier.

   Wait, I made an error in the first word. Corrected output:

   ou via la variable d’environnement ZEROCLAW_AUTH_TOKEN, qui remplace la valeur du fichier de configuration et permet de garder l’identifiant hors du fichier.

   ou en indiquant un fichier qui le contient :

   [connection.wss]
   uri = "wss://daemon.example.com:9443"
   auth_token_file = "/etc/zeroclaw/zerocode-bearer"
   

   L’ordre de priorité est ZEROCLAW_AUTH_TOKEN, puis auth_token_file, puis auth_token. Sur les plateformes disposant de bits de permissions Unix, un fichier référencé que tout autre compte peut lire est ignoré avec un avertissement au lieu d’être utilisé, et la source suivante dans cet ordre s’applique. Ailleurs, la liste de contrôle d’accès (ACL) du fichier est la seule protection.

   L’variable d’environnement est la méthode recommandée. Lorsque le jeton est conservé dans le fichier de configuration à la place, zerocode écrit ce fichier accessible uniquement à son propriétaire (0600, dans un répertoire de configuration 0700) et corrige les droits d’accès d’un fichier antérieur à cette fonctionnalité, sur les plateformes disposant des bits de permission Unix. Sur les plateformes qui n’en disposent pas, seule l’ACL du répertoire protège le fichier : il faut donc le traiter comme un secret.

Un jeton d’accès OIDC fonctionne de la même manière avec auth_provider = "oidc.<alias>".

La passerelle API HTTP

Les routes de configuration et de prise en main de la passerelle (/api/config*, /api/quickstart/*, /api/channels/bind) imposent l’authentification de manière structurelle : un unique middleware de couche de routage protège l’ensemble du groupe, de sorte qu’aucun gestionnaire individuel ne porte (ou ne peut oublier) une vérification. Ce middleware utilise le même modèle de principal que le chemin RPC, via le même registre des fournisseurs et le même résolveur :

• Un porteur apparié (Authorization: Bearer zc_...) correspond à l’opérateur partagé disposant d’un accès complet, exactement comme auparavant. Les refus conservent la forme historique de la réponse 401.
• Un bearer OIDC présenté avec l’en-tête X-ZeroClaw-Auth-Provider: oidc.<alias> est vérifié par ce fournisseur et résolu en un principal à portée limitée. La sélection est explicite, à l’image du champ auth_provider de la poignée de main RPC : le refus du fournisseur désigné fait autorité, et il n’existe jamais de repli entre fournisseurs.
• CORS preflight (OPTIONS) passe sans authentification, comme c’était déjà le cas. Toute autre méthode en dehors de GET, HEAD, POST, PUT, PATCH et DELETE est refusée.

Un principal à portée limitée voit ses autorisations Config appliquées en deux étapes. La couche de routage impose un plancher grossier par méthode HTTP : une lecture exige read, toute autre opération exige au moins l’un des droits create, update ou delete, de sorte qu’un principal en lecture seule n’atteint jamais un gestionnaire de mutation. Chaque gestionnaire de mutation autorise ensuite son ensemble complet d’écritures avant son premier effet de bord : chaque chemin de configuration que la mutation persistera, classé selon son effet sur la configuration (create pour un chemin qu’elle crée, delete pour un chemin qu’elle supprime, update sinon) et confronté aux sélecteurs config_write_paths du profil. La classification suit l’opération et non la méthode : créer une clé de dictionnaire via POST /api/config/map-key, ou implicitement via un PUT sous un nouvel alias, exige create ; un remove JSON Patch et DELETE /api/config/map-key exigent delete ; un renommage exige delete sur sa source et create sur sa destination ; les références que la cascade d’une suppression ou d’un renommage réécrit ailleurs font également partie de l’ensemble d’écritures. Un seul membre non autorisé refuse la mutation entière, lot ou cascade compris, et rien n’est écrit. Les opérations dont l’ensemble d’écritures ne peut pas être énuméré à l’avance (une migration de schéma du fichier, un apply Quickstart) exigent le sélecteur *. La frontière de persistance revérifie les chemins sur le point d’être écrits par rapport à ce que le gestionnaire a autorisé, de sorte qu’un gestionnaire ne peut pas persister plus qu’il n’a été autorisé à écrire.

La politique ne change qu’à la frontière de persistance : le gestionnaire qui écrit une configuration publie l’état d’autorisation compilé à partir de celle-ci comme prochaine révision acceptée, et chaque requête est vérifiée et résolue par rapport à l’instantané accepté tel qu’il est au moment de son traitement. Rien sur le chemin de traitement des requêtes ne recompile la politique. Ainsi, une requête qui a lu la configuration avant une persistance concurrente ne peut jamais réinstaller l’ancienne politique par-dessus la nouvelle. Une modification persistée des paramètres de vérification d’un fournisseur, d’une liste de membres (roster) ou d’un profil prend effet à la requête suivante. La surface RPC propre au démon possède une configuration active distincte et atteint le même état grâce au rechargement déclenché par les indicateurs d’écriture de la gateway. Les autres surfaces de la gateway conservent la vérification d’appairage par gestionnaire et adopteront la couche dans des suivis ultérieurs.

Cycle de vie des identifiants

• Expiration met fin à l’autorisation de la connexion à l’échéance ; le client se réinitialise avec un nouveau jeton.
• Revalidation par introspection : les identités d’introspection OIDC portent une échéance de revalidation ; une fois celle-ci dépassée, l’opération suivante est refusée tant que le client n’a pas été réinitialisé (ce qui réverifie l’identité auprès de l’IdP).
• Révocation de l’appairage s’applique avant la prochaine opération de la connexion.
• Abonnements aux journaux : un flux logs/subscribe ouvert est revérifié à chaque livraison et se termine dès la première livraison après l’expiration de son identifiant, la révocation de son appairage, ou la perte par son principal de Logs:Read.
• Modifications de politique : un enregistrement de configuration qui laisse [oidc], [users], [permission_profiles] et security.trust_daemon_uid inchangés conserve chaque liaison telle quelle. Toute modification de l’un d’eux publie une nouvelle politique. Les connexions par jeton natif et locales sont à nouveau résolues en place par rapport à celle-ci, mais le démon ne conserve pas de jeton porteur OIDC ; la prochaine opération sur une connexion OIDC est donc refusée tant que le client n’a pas été réinitialisé.
• Le mécanisme de reconnexion tui_id/tui_sig ne assure que la continuité : il préserve l’identité du TUI dans le registre et n’accorde aucune autorité. Chaque initialize présente à nouveau un identifiant d’authentification.

Isolation de session

Chaque session créée par un principal restreint est estampillée avec l’identifiant de ce principal, dans le store actif et sur disque (backend de chat et store ACP). Les principaux restreints ne voient et ne modifient que leurs propres sessions : les listes sont filtrées, les lectures et les modifications renvoient un refus uniforme « introuvable ou non possédée » (sans sondage d’existence), les suppressions destructives s’exécutent sous forme d’instructions de stockage conditionnées au propriétaire, et les approbations en cours ne sont résolues que par le propriétaire de la session pour laquelle elles ont été demandées. Les sessions créées avant cette modification (ou par des connexions non restreintes) n’ont pas de propriétaire : elles restent entièrement visibles pour les connexions non restreintes et invisibles pour les principaux restreints.

Chaque principal authentifié dispose d’une mémoire PRIVÉE : ses opérations de mémoire lisent et écrivent dans un plan propre à chaque principal, dont le propriétaire figure dans chaque instruction de stockage, combiné aux dimensions agent, espace de noms et tenant (la même clé sous deux agents correspond à deux lignes). Le plan suit l’identité du principal, et non le contournement administrateur : la mémoire d’un administrateur nommé est son propre plan privé, de sorte que promouvoir ou rétrograder un utilisateur ne masque jamais ses notes et ne redirige jamais ses écritures. Seul l’opérateur partagé non authentifié se trouve par défaut sur le plan partagé ; un appelant disposant du contournement administrateur peut désigner explicitement plane = "shared" dans une requête memory/*, ce qui fait l’objet d’un audit, alors qu’un principal à portée limitée ne le peut pas.

Les deux plans sont imperméables l’un à l’autre dans les deux sens : une écriture partagée ne peut ni désigner la clé de stockage d’une ligne privée, ni écraser une ligne privée ; une écriture privée ne convertit jamais une ligne partagée ; les exportations ordinaires et l’instantané markdown ne contiennent que des lignes partagées ; et les purges globales héritées ne touchent que les lignes partagées. Les lignes privées sont exportées et purgées par des opérations portant l’identifiant du propriétaire.

Une session créée par un principal voit son handle de mémoire épinglé au plan privé de ce principal pendant toute la durée de vie de la session, quel que soit l’utilisateur qui la sollicite ensuite (un administrateur qui restaure une session récupérée la restaure sur le plan du propriétaire durable). Les outils de mémoire et le rappel par tour dans une session restreinte n’accèdent donc jamais au plan partagé. Aucune autorisation n’ouvre le plan partagé à une session restreinte. Les écritures privées passent par les mêmes contrôles de contenu et les mêmes politiques que les écritures partagées, et les opérations privées sont journalisées avec le périmètre complet lorsque l’audit de la mémoire est activé. Sur les backends mémoire sans prise en charge des principaux (markdown, lucid, postgres, qdrant à ce jour), la mémoire privée échoue en mode sécurisé avec un refus explicite plutôt que de supprimer silencieusement le périmètre ; pour une session restreinte, cela signifie que ses outils de mémoire refusent d’opérer.

Migration depuis [security.nevis]

L’intégration IAM Nevis a été supprimée. Elle n’était branchée sur aucun chemin d’authentification : l’activer n’a donc jamais authentifié qui que ce soit, et sa suppression ne modifie aucun comportement en production. La table de configuration reste acceptée afin qu’un ancien config.toml continue de se charger. Au chargement, le démon ignore toutes les valeurs de cette table, émet un seul avertissement indiquant le remplacement, puis retire la table de config.toml lors de la prochaine sauvegarde, qu’il s’agisse d’une sauvegarde complète ou de la sauvegarde incrémentielle utilisée par la CLI, le tableau de bord et RPC pour une modification unique. La suppression ne touche que cette table ; les commentaires et les autres sections conservent leurs octets. Aucune conversion automatique n’est effectuée : la nouvelle pile de remplacement nécessite des valeurs (une audience, des autorisations de profil) que l’ancienne table ne contenait jamais.

Avant de mettre à niveau, copiez config.toml dans un emplacement protégé. Chaque enregistrement effectué après la mise à niveau écrit config.toml.bak à côté du fichier pendant la durée de l’écriture, puis le supprime une fois l’écriture durable. Un .bak n’est donc pas une sauvegarde permanente. Toute copie que vous conservez vous-même contient toujours la table retirée, y compris un client_secret en clair si un a été configuré. Traitez donc ces copies comme du matériel secret, et révoquez les identifiants client Nevis auprès de l’IdP dès que vous n’en avez plus besoin.

Field by field:

Validez avant de redémarrer, afin qu’une faute de frappe ne vous verrouille pas hors du système (voir Récupération sous Connexions locales pour la marche à suivre en cas de problème). Deux méthodes permettent de le faire :

• Écrivez les nouvelles entrées [oidc.<alias>] et [permission_profiles] via les méthodes RPC de configuration du daemon (l’éditeur de configuration de zerocode). Le daemon valide les sections d’autorisation avant toute sauvegarde ou mise en service : une cible profile_map orpheline ou un audience manquant est refusé avec la raison, et la politique précédente reste en vigueur.
• Si vous modifiez config.toml à la main, exécutez d’abord ZEROCLAW_AUTH_TOKEN="$(zeroclaw oidc login <alias>)" depuis la CLI. Cette commande charge le fichier modifié et refuse toute entrée [oidc.<alias>] qui ne valide pas (émetteur, audience, mode de validation, champs du client). Si la validation réussit, elle effectue une véritable connexion auprès de l’IdP avec le client configuré. L’émetteur, l’identifiant client et le secret sont ainsi vérifiés avant que le démon ne redémarre avec ces valeurs. Cette vérification porte sur l’entrée, pas sur les cibles de profile_map. Une valeur de profile_map qui ne désigne aucune entrée [permission_profiles] n’est détectée que par le démon. Celui-ci refuse alors de compiler la politique et démarre dans l’état de refus total décrit sous Recovery. Vérifiez donc ces noms à l’œil nu avant le redémarrage, ou utilisez la route RPC.

Les connexions distantes qui ne présentent aucun identifiant sont refusées dans tous les cas ; aucune des deux voies n’en ouvre une.

Revenir en arrière est une opération sur les données de configuration, et non une annulation du code : revenir à une version antérieure du binaire rétablit les anciens types, mais une table déjà supprimée de config.toml n’est restaurée par rien. Remettez en place la copie protégée réalisée avant la mise à niveau (ou rajoutez la table à la main). La version du schéma ne change pas pour cette suppression ; un binaire rétrogradé charge donc le fichier restauré sans étape de migration.

Ce que cette couche ne fait pas (encore)

La consolidation et la gouvernance dérivent les lignes du plan partagé et ne s’exécutent pas pour les sessions privées. L’accès administratif à la mémoire privée d’un autre principal n’a encore aucun chemin exposé (refus par défaut). sops/runs et sops/run-detail renvoient l’historique d’exécution de chaque procédure à un principal détenant Sops:Read, quels que soient les agents sous lesquels elle a été exécutée, contrairement à l’historique cron. Les routes HTTP de la passerelle conservent leurs vérifications d’appairage existantes, et les identités de canal ne se résolvent pas dans ce modèle de principal.

Tant que security.trust_daemon_uid = true (la valeur par défaut) et que la politique se compile, l’uid du démon sur un socket Unix conserve un accès complet, si bien qu’une installation à opérateur unique, sans liste [users] et avec des sections d’authentification valides, se comporte comme auparavant.

Les profils de permission limitent ce qu’un principal peut faire via RPC. Ils n’isolent pas le code qu’un principal amène un agent à exécuter. Les tours de session, les tâches cron et les étapes SOP s’exécutent sous le compte du démon. Sous Unix, ce code peut se connecter au socket local avec l’uid du démon, qui correspond à l’opérateur partagé tant que security.trust_daemon_uid = true (la valeur par défaut), et sinon obtient les droits de l’entrée du roster correspondant à cet uid. Sous Windows sans roster, le pipe donne l’opérateur partagé. Ce code peut aussi modifier config.toml, que le démon applique à son prochain rechargement ou redémarrage. Définir security.trust_daemon_uid = false ne change ni l’un ni l’autre. Accordez l’exécution ou la rédaction de sessions, de tâches cron ou de SOP uniquement aux principaux à qui vous feriez confiance avec un accès opérateur. Seul un confinement au niveau du système d’exploitation, qui tient les processus d’agent à l’écart du socket et de config.toml, isole ce code.

Certains chemins de configuration portent eux-mêmes une autorité, donc traitez un octroi large config_write_paths comme un accès opérateur, sauf s’il ne couvre que des paramètres feuilles validés. Par exemple :

• Un principal capable d’écrire permission_profiles, users, oidc, security ou gateway.paired_tokens peut s’accorder tous les droits ;
• celui qui peut écrire agents, risk_profiles, cron, channels ou les paramètres du fournisseur peut modifier les agents exécutés, les outils qu’ils utilisent et les emplacements où ils peuvent lire et écrire ;
• Quiconque peut écrire mcp, mcp_bundles ou tunnel.custom.start_command peut choisir les programmes que le compte du démon démarre.

Config:Update accorde également config/reload, qui applique le contenu actuel de config.toml sur le disque.

Le sélecteur de répertoire distant de zerocode s’ouvre à la racine du système de fichiers du démon. Un principal sans autorisations d’opérateur ne peut la lister que via un agent activé dont la politique lui permet de lire /, par exemple un agent qui n’est pas limité à l’espace de travail. Pour tout autre principal de ce type, le sélecteur signale un refus à cet emplacement jusqu’à ce qu’il s’ouvre plutôt dans une racine autorisée.