Secrets et handles

Touba ne met pas les valeurs sensibles dans le fichier .tb, l’AIR, le manifest ou les traces.

Un secret est référencé par un handle.

source.tb

tool SummarizeDatasets
    takes search as DatasetSearchResult
    gives DatasetBrief
    requires network, secret_read
    secrets OPENAI_API_KEY

Fichier secrets explicite

Il faut distinguer quatre choses :

Element	Role
Handle	nom logique utilise par Touba, par exemple OPENAI_API_KEY
Fichier de resolution	profil passe a --secrets, par exemple touba.secrets.dev.json ou touba.secrets.prod.json
Source	endroit ou chercher la valeur : touba_store, env ou dotenv
Valeur	secret reel, jamais stocke dans .tb, AIR, manifest ou trace

Un fichier de resolution peut contenir plusieurs handles, et chaque handle peut choisir sa propre source.

touba.secrets.dev.json

{
  "secrets_version": "touba-secrets-v1",
  "secrets": {
    "OPENAI_API_KEY": {
      "source": "env",
      "name": "OPENAI_API_KEY"
    }
  }
}

Le fichier indique comment résoudre le handle. Le même programme Touba peut utiliser plusieurs profils de résolution :

Structure

touba.secrets.dev.json
touba.secrets.prod.json

Touba ne devine pas automatiquement si l’exécution est en développement ou en production. Le profil est le fichier passé explicitement au runtime.

Exemple courant :

Sortie

touba.secrets.dev.json   -> cherche les valeurs dans touba_store
touba.secrets.prod.json  -> cherche les valeurs dans env

Ce n’est pas obligatoire : un profil peut melanger plusieurs sources si le projet en a besoin. Le point stable est que le fichier de resolution declare explicitement ou chercher chaque cle.

Dans un projet standard :

• touba init crée .touba/secrets.local.json et .env vides, puis les ignore via .gitignore ;
• touba prepare --mode write crée ou complète touba.secrets.dev.json et touba.secrets.prod.json quand des tool déclarent des secrets ;
• touba secret set <HANDLE> --value-stdin ajoute la valeur dans le store local touba_store.

Aucun de ces fichiers ne donne au runtime le droit de lire un secret par découverte automatique. Le runtime lit seulement le fichier passé à --secrets.

Sources supportées

touba_store

Recommandé pour le développement local.

touba.secrets.dev.json

{
  "source": "touba_store",
  "path": ".touba/secrets.local.json",
  "name": "OPENAI_API_KEY"
}

Le store local est géré par commandes Touba :

Terminal

touba secret set OPENAI_API_KEY --value-stdin
touba secret list
touba secret check OPENAI_API_KEY

La valeur est fournie par stdin, depuis le mécanisme local choisi par le développeur. Les commandes listent les handles, jamais les valeurs.

Un projet initialisé avec touba init ignore .touba/ par défaut. Le store local ne doit pas être commité.

env

Recommandé pour CI/CD, conteneurs et infrastructure.

touba.secrets.prod.json

{
  "source": "env",
  "name": "OPENAI_API_KEY"
}

dotenv

Supporté pour compatibilité locale explicite.

touba.secrets.dev.json

{
  "source": "dotenv",
  "path": ".env",
  "name": "OPENAI_API_KEY"
}

Le runtime ne lit pas automatiquement un fichier .env. Le chemin doit être déclaré explicitement.

Cycle de vie d'un handle

Un profil secrets peut aussi désactiver ou expirer un handle sans modifier le source Touba ni le manifest.

touba.secrets.dev.json

{
  "secrets_version": "touba-secrets-v1",
  "secrets": {
    "OPENAI_API_KEY": {
      "source": "touba_store",
      "path": ".touba/secrets.local.json",
      "name": "OPENAI_API_KEY",
      "status": "active",
      "expires_at": "2026-06-30T23:59:59.000Z"
    }
  }
}

Règles :

• status est optionnel et vaut active par défaut ;
• status: "revoked" refuse l'exécution avec SecretHandleRevoked ;
• expires_at est optionnel ; si la date est dépassée, le runtime refuse avec SecretHandleExpired ;
• les traces indiquent le handle refusé et une raison courte, jamais la valeur.

Ce cycle de vie rend une clé inutilisable avant handler. Les coffres externes, la rotation automatique et les politiques d’organisation restent des couches de gestion des secrets environnantes.

Manifest

Le manifest doit accorder le handle au binding du tool :

touba.manifest.json

"secrets": ["OPENAI_API_KEY"]

Si le tool déclare un secret et que le manifest ne l’accorde pas, le runtime refuse avant handler.

Scope agent

Quand un tool est appelé pendant l’exécution d’un agent, le manifest peut limiter les secrets par agent. touba prepare renseigne ce bloc pour les agents qui peuvent atteindre un tool déclarant un secret ; relisez-le comme une autorité explicite avant exécution.

touba.manifest.json

"agent_secret_scopes": {
  "agent:examples/Researcher": ["OPENAI_API_KEY"]
}

Cela signifie que le handle peut être utilisé dans ce périmètre agentique. Cela ne donne pas la valeur du secret à l’agent comme texte.

Injection handler

Le runtime lance le handler avec un environnement minimal contenant seulement les secrets requis et autorisés.

Le handler voit la valeur au moment de l’exécution. L’AIR et la trace ne voient que le handle.

Résultats et checkpoints

Un résultat de tool ou de décision contenant une valeur de secret déjà résolue est refusé avant propagation vers l'appelant, les observations du modèle ou la sortie CLI/SDK. Le contrôle parcourt les chaînes, sous-chaînes, champs et clés imbriqués ; il ne remplace pas silencieusement la valeur métier par du texte masqué. Les diagnostics restent expurgés.

Un refus de résultat intervient après l'éventuel effet externe. Le journal conserve le reçu d'un effet acquis, sans son résultat sensible, et une reprise ne réexécute pas cet effet pour tenter de récupérer la valeur.

Les checkpoints conservent les données métier nécessaires à la reprise : une trace minimisée ne signifie pas un checkpoint sans données personnelles. Les fichiers de checkpoint CLI et stores de reprise sont écrits avec des permissions privées (0600 sur POSIX). Ce n'est pas du chiffrement ; limitez les accès, sauvegardes et durées de conservation, puis supprimez les fichiers devenus inutiles. La détection vise les secrets connus du runtime, pas toute transformation ou toute donnée sensible inconnue.

Contrat De Secrets

Touba fournit des handles de secrets explicites, des profils de résolution, un store local de développement, la résolution par environnement, le statut de cycle de vie et le refus runtime avant dispatch handler.

Les backends de secret manager externes, les propriétés de coffre cryptographique, la découverte automatique .env, la classification automatique des données sensibles et le confinement complet de handlers autorisés se branchent autour de ce contrat explicite.