Barrel
EN GitHub

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émentCe que c’estOù il vit
EspaceUne base nommée sp_ suivi de 16 caractères, avec une entrée dans le registreSa propre base ; l’entrée dans _barrel_spaces
Jeton de capacitébsp_..., limité à un espace, avec des droitsAffiché une fois ; seul son hachage SHA-256 est stocké
SessionUn contexte de travail avec des messages, des données et des épinglesDes documents dans l’espace, qui expirent selon le TTL
PassationUne tâche plus un jeton pour son espaceLe 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.

DroitSur barrel_server, il permet
readLes GET, changes, query, search, et les lectures de réplication (pull)
writeLes é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.

Shell Erlang
{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).
Sortie d’une exécution sur barrel_spaces 1.3.1
{error,forbidden}
{error,wrong_space}
Ce qui vient de se passer

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.

Shell Erlang
{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.

Shell Erlang
{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).
Sortie d’une exécution sur barrel_spaces 1.3.1
{error,already_accepted}
{error,revoked}
Ce qui vient de se passer

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.

Limite

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érificationDans 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 basequand vous appelez verify/3oui, 403 sinon
read / write par opérationquand vous appelez verify/3oui, par route ou par outil
admin pour émettre, révoquer, créer une passationnonoui
Accepter ou terminer une passationdemande seulement read sur le jetondemande 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.

Traduit de la page anglaise: /docs/concepts/spaces/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir