Espaces et capacités
Quand plusieurs agents travaillent ensemble, chacun a besoin d’un endroit pour garder ses notes et ses résultats, d’un moyen de les partager avec les agents avec qui il travaille, et de la garantie qu’il ne peut pas lire le travail des autres. Donner à chaque agent le jeton global du serveur lui donne accès à tout. Les espaces donnent à chaque travail partagé sa propre base et ses propres clés.
Un espace est une base Barrel que
des agents partagent en détenant un jeton de
capacité pour elle : un
secret qui accorde des droits sur cet espace et sur rien d’autre. Une
session est le contexte de travail
d’un agent dans un espace, avec un TTL glissant : elle expire après une
période sans activité. Une
passation transmet une tâche, et
le jeton pour y travailler, d’un agent à un autre. Lisez cette page pour
comprendre le modèle avant d’utiliser le guide des
espaces, et pour savoir lesquelles de ces
vérifications vous protègent dans votre propre processus et lesquelles
seulement derrière
barrel_server.
Les exemples de cette page suivent un même scénario. Alice crée un espace pour un brouillon de recherche commun, donne à Carol un accès en lecture seule, travaille sur le brouillon dans une session, puis passe la tâche à Bob pour qu’il la termine.
Les éléments
| Élément | Ce que c’est | Où il vit |
|---|---|---|
| Espace | Une base nommée sp_ suivi de 16 caractères, avec une entrée dans le registre | Sa propre base ; l’entrée dans _barrel_spaces |
| Jeton de capacité | bsp_..., limité à un espace, avec des droits | Affiché une fois ; seul son hachage SHA-256 est stocké |
| Session | Un contexte de travail avec des messages, des données et des épingles | Des documents dans l’espace, qui expirent selon le TTL |
| Passation | Une tâche plus un jeton pour son espace | Le registre, pour qu’elle puisse être listée |
Comme seul le hachage d’un jeton est stocké, Barrel ne peut pas vous le montrer une seconde fois. Gardez-le quand vous l’émettez, et émettez-en un nouveau s’il est perdu.
Les droits
Chaque jeton porte des droits qui disent ce que son détenteur peut faire
dans l’espace. Les droits forment une échelle : read < write <
admin. Un droit supérieur inclut les droits inférieurs.
| Droit | Sur barrel_server, il permet |
|---|---|
read | Les GET, changes, query, search, et les lectures de réplication (pull) |
write | Les écritures de documents et de pièces jointes, et les écritures de réplication (push) |
admin | Émettre, lister et révoquer des jetons ; créer des passations pour l’espace |
Un jeton n’atteint jamais un autre espace, le cycle de vie des bases
(PUT et DELETE /db/:db), ni les routes _timeline : celles-ci
répondent 403.
Créer un espace et émettre un jeton
Alice crée l’espace et émet pour Carol un jeton read. Les deux
dernières lignes vérifient ce que permet le jeton de Carol : une
écriture dans l’espace, puis une lecture dans un autre espace.
{ok, _} = application:ensure_all_started(barrel_spaces),
{ok, #{id := SpaceId} = Space} =
barrel_spaces:create_space(#{label => <<"joint research">>,
owner => <<"alice">>,
vectordb => none}),
{ok, ReadTok, _} = barrel_caps:grant(SpaceId,
#{rights => [read], subject => <<"carol">>}),
barrel_caps:verify(ReadTok, SpaceId, write),
barrel_caps:verify(ReadTok, <<"sp_other">>, read). {error,forbidden}
{error,wrong_space} Les deux vérifications échouent, chacune pour sa raison. forbidden
signifie que le jeton est valide pour cet espace mais ne porte pas
write. wrong_space signifie que le jeton appartient à un autre
espace, quels que soient ses droits.
barrel_caps:revoke/1 met fin à un jeton ; barrel_spaces:drop_space/1
met fin à l’espace et révoque tous ses jetons.
Les sessions
Une session est l’endroit où un agent garde ce qu’il est en train de
faire : la conversation jusqu’ici, de petits éléments d’état, et des
épingles, les faits qu’il doit garder
sous les yeux. Une session appartient à un agent et expire après ttl
secondes sans touch (la valeur par défaut de l’espace est 3600). Elle
contient des messages, des données clé/valeur et du contexte épinglé, le
tout stocké comme documents dans l’espace : tout détenteur d’un jeton
pour l’espace peut donc les lire.
{ok, Sid} = barrel_session:create(Space,
#{agent => <<"alice">>, ttl => 1800}),
{ok, _} = barrel_session:add_message(Space, Sid,
#{role => <<"user">>, content => <<"draft is half done">>}). Ici, Alice ouvre une session qui expire après 30 minutes sans activité, et note où en est le brouillon.
Les passations
Une passation permet à Alice de confier la suite de la tâche à Bob sans
rien copier. Une passation émet un jeton pour l’espace (droits read et
write par défaut) et ne le renvoie qu’une fois. Celui qui le présente
accepte : la passation passe de en attente à acceptée, une deuxième
acceptation échoue, et celui qui accepte obtient une session dans le
même espace. Rien n’est copié ; le contexte est lu sur place.
{ok, #{token := HTok}} = barrel_handoff:create(Space,
#{task_name => <<"finish the draft">>,
from_agent => <<"alice">>, to_agent => <<"bob">>,
from_session => Sid}),
{ok, #{session := BobSid}} =
barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
barrel_handoff:accept(HTok, #{agent => <<"mallory">>}),
{ok, _} = barrel_handoff:complete(HTok,
#{result => <<"shipped">>}),
barrel_caps:verify(HTok, SpaceId, read). {error,already_accepted}
{error,revoked} Bob accepte le premier et obtient sa propre session. Mallory, qui
présente le même jeton, reçoit already_accepted. Une fois que Bob a
terminé la tâche, le jeton est révoqué : une vérification ultérieure
renvoie revoked.
Terminer une passation révoque son jeton par défaut. chain/2 le
transmet à la place ; utilisez l’un ou l’autre, pas les deux.
D’un nœud à l’autre
Les espaces et le registre se répliquent comme n’importe quelle base. Depuis barrel_spaces 2.0, chaque fait est un document à part entière, si bien que des nœuds qui écrivent en même temps ne perdent jamais les écritures les uns des autres : une révocation tient sur chaque nœud, les clés et les épingles d’une session écrites sur deux nœuds sont toutes conservées, une clé ou une épingle retirée le reste, et une passation ne revient jamais à un statut antérieur. Quand deux agents acceptent une passation sur des nœuds qui ne se voient pas, chaque nœud désigne le même titulaire : la première acceptation. Voir Espaces, sessions, passations pour les règles, et Passer à docdb 3 et spaces 2 pour migrer un maillage depuis la 1.x.
Dans le processus et derrière le serveur
L’endroit où le jeton est vérifié décide de ce qu’il vous protège. Dans
votre propre nœud Erlang, n’importe quel code peut atteindre n’importe
quelle base : un jeton n’y vaut que ce que vaut le code qui le vérifie.
Derrière barrel_server, le serveur le vérifie à chaque requête.
Dans votre propre nœud Erlang, les jetons sont indicatifs.
barrel_spaces:open_space/1 et chaque appel barrel_session ne prennent
aucun jeton : n’importe quel code du nœud peut donc ouvrir n’importe quel
espace. barrel_caps:grant/2, revoke/1 et barrel_handoff:create/2 ne
vérifient pas le droit admin. Le chiffrement par espace est la seule
isolation dans le processus.
| Vérification | Dans le processus (barrel_spaces) | REST et MCP de barrel_server |
|---|---|---|
| Un jeton est valide, non révoqué, non expiré | quand vous appelez barrel_caps:verify/3 | à chaque requête |
| L’espace du jeton correspond à la base | quand vous appelez verify/3 | oui, 403 sinon |
read / write par opération | quand vous appelez verify/3 | oui, par route ou par outil |
admin pour émettre, révoquer, créer une passation | non | oui |
| Accepter ou terminer une passation | demande seulement read sur le jeton | demande seulement read sur le jeton |
Donc : quand des agents ne doivent pas atteindre les données les uns des
autres, faites-les passer par barrel_server avec des jetons de
capacité, et gardez le jeton global hors de leur portée. Les mêmes
jetons valent en REST et en MCP. Voir
Authentification.
Notes
- Les droits émis et les passations vivent dans la base de registre
_barrel_spaces. La répliquer permet à un jeton émis sur un nœud d’être vérifié sur un autre ; la révocation voyage alors à la vitesse de la réplication. - Le stockage vectoriel d’un espace est propre à chaque nœud et n’est pas répliqué.
- Les espaces chiffrés ne sont disponibles que depuis Erlang : le serveur ne peut pas passer de spécification de clé quand il ouvre un espace.