Authentification
barrel_server est ouvert tant que vous ne configurez pas auth. Vous
pouvez alors accepter des jetons bearer globaux, des jetons de capacité
par espace, des requêtes signées Ed25519 et des certificats clients
(mTLS). Les clients de réplication trouvent leurs identifiants dans
l’app env de barrel_docdb. Lisez cette page avant d’exposer un
serveur, de donner accès à un navigateur ou à un agent, ou de répliquer
entre nœuds.
Quelle méthode
| Méthode | Qui l’utilise | Ce qu’elle prouve |
|---|---|---|
| Bearer global | Opérateurs, services de confiance | Le détenteur d’un secret partagé ; accès complet |
Jeton de capacité (bsp_...) | Agents, navigateurs | Le détenteur d’un jeton pour un espace, avec des droits |
| Requête signée (Ed25519, v3) | Nœuds qui répliquent | Le détenteur de la clé a envoyé exactement cette requête |
| mTLS | Nœuds sur un réseau privé | Un certificat de votre autorité de certification ; pas quel client |
Sans TLS, un jeton bearer peut être capturé et rejoué. Faites tourner le serveur en HTTPS quand vous utilisez des jetons sur un réseau non fiable.
Jetons bearer
{barrel_server, [{auth, #{tokens => [<<"s3cret">>]}}]}
Chaque route sauf /health exige alors Authorization: Bearer <token>.
Une liste vous permet la rotation : ajoutez le nouveau jeton, basculez
les clients, retirez l’ancien. / n’est plus public une fois l’auth
activée.
curl localhost:8080/db/demo/doc/a
curl -H 'authorization: Bearer s3cret' \
localhost:8080/db/demo/doc/a
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
{"error":"unauthorized"}
HTTP/1.1 200 OK
{"_rev":"000001a1b876972d00000000@w78160d59891ba7d7","id":"a",
"kind":"note","n":1,"title":"hello world"} Jetons de capacité
Un jeton de capacité est émis pour un espace avec les droits read,
write ou admin (voir Espaces et capacités) :
curl -X POST localhost:8080/spaces/sp_wh2tq2ocmemj52ln/grants \
-H 'authorization: Bearer s3cret' \
-H 'content-type: application/json' \
-d '{"rights":["read"],"subject":"agent-1"}'
Il est accepté sur /spaces, /handoffs, /mcp, et sur /db/:db/...
quand :db est l’espace concerné. Un jeton de lecture sur son propre
espace, puis une écriture, une autre base, et un appel sur le cycle de
vie d’une base :
GET /db/sp_wh2tq2ocmemj52ln 200 OK
PUT /db/sp_wh2tq2ocmemj52ln/doc/x 403 {"error":"forbidden"}
GET /db/demo/doc/a 403 {"error":"forbidden"}
PUT /db/sp_wh2tq2ocmemj52ln 403 {"error":"forbidden"} Un jeton mort ou inconnu répond 401 ; un jeton valide sur le mauvais
espace ou sans le droit voulu répond 403. Le cycle de vie des bases,
_timeline et toute route non associée à un droit répondent toujours
403 à un jeton de capacité.
Requêtes signées
Chaque requête est signée avec une clé Ed25519. Le serveur connaît la clé publique de chaque pair :
{barrel_server, [{auth, #{
accept => [bearer, signed],
signers => #{<<"node1">> => PubKey32},
skew_ms => 300000}}]}
Le client signe avec la clé privée, définie dans l’app env pour que les configurations de tâches restent sans secrets :
{barrel_docdb, [{sync_signing, #{
<<"https://edge-1.example.com:8443">> =>
#{key_id => <<"node1">>, priv_key => Priv32}}}]}
Générez une paire avec crypto:generate_key(eddsa, ed25519).
Ce que couvre une signature v3 :
- l’horodatage, l’id de clé, un nonce neuf, la méthode, le chemin avec sa query string brute, et le SHA-256 du corps ;
- les en-têtes qui changent l’effet d’une écriture :
content-type,if-match,if-none-match,x-barrel-actor,x-barrel-session,x-barrel-source,x-barrel-hlc,x-barrel-att-origin,x-barrel-digestetx-barrel-att-touch, chacun signé comme présent avec sa valeur ou comme absent.
Comment le serveur la vérifie :
- Sur chaque route, pour chaque requête signée avec un corps, le corps
est comparé au
x-barrel-content-sha256signé avant que le handler s’exécute. Un hachage absent ou faux répond 401content_hash_mismatch. - Un nonce rejoué ou un horodatage hors de
skew_msest refusé. - Une requête qui présente une signature est jugée sur elle seule. Une signature en échec répond 401, même si un jeton bearer ou un certificat client aurait laissé passer la requête.
- Les signatures v1 et v2 répliquent encore les documents, mais sont
refusées avec 401
signature_v3_requiredquand elles écrivent une pièce jointe ou portent l’un des en-têtes ci-dessus. Les clients barrel_docdb 2.1.0 n’envoient que du v3 : mettez donc d’abord à jour les serveurs. Fermez l’ancienne fenêtre avecaccept => [signed]etrequire_nonce => true.
Un proxy placé devant le serveur doit transmettre le chemin, la query string et les en-têtes signés sans les modifier.
La signature authentifie le client et protège chaque requête. Elle ne masque ni la requête ni la réponse, et elle n’authentifie pas le serveur. Utilisez pour cela du HTTPS vérifié.
mTLS
{barrel_server, [
{listeners, #{http => #{port => 8443, tls => true}}},
{tls, #{certfile => "server.pem", keyfile => "server.key",
cacertfile => "ca.pem", verify => verify_peer}},
{auth, #{accept => [mtls]}}]}
Le client présente son certificat via sync_ssl :
{barrel_docdb, [{sync_ssl, #{
<<"https://edge-1.example.com:8443">> =>
[{certfile, "client.pem"}, {keyfile, "client.key"},
{cacertfile, "ca.pem"}]}}]}
- Un certificat ne compte que pour une requête sans en-tête
Authorization. Si la requête porte un jeton ou une signature, c’est cet identifiant qui décide, et un identifiant en échec répond 401 même avec un bon certificat. - mTLS prouve que le certificat remonte à votre autorité de
certification, pas quel client l’a envoyé :
accept => [mtls]seul donne à chacun de ces clients l’accès à toutes les bases. Combinez-le, par exempleaccept => [mtls, signed]. mtlsest retiré deacceptquand la configuration TLS n’a pasverify => verify_peer.- HTTP/3 sert du TLS mais ne filtre pas encore par certificat client. Ne comptez pas sur lui pour mTLS.
Une liste accept échoue en position fermée : une liste vide verrouille
le serveur.
Identifiants pour la réplication
Le client de réplication lit trois clés de l’app env de barrel_docdb.
Chacune associe une URL de base, ou une origine (scheme://host:port),
à un identifiant ; l’URL complète est cherchée en premier.
| Clé | Valeur |
|---|---|
sync_auth | un jeton bearer |
sync_signing | #{key_id, priv_key} |
sync_ssl | une liste d’options ssl |
{barrel_docdb, [{sync_auth, #{
<<"http://edge-1.example.com:8080">> => <<"s3cret">>,
<<"http://edge-2.example.com:8080/db/orders">> =>
<<"other">>}}]}
Un barrel_rep:replicate/3 ponctuel peut aussi prendre auth,
signing ou ssl_options dans la map du point d’accès. Les tâches de
réplication les refusent : une configuration de tâche avec auth,
signing, ssl_options, headers, ou un utilisateur et un mot de passe
dans l’URL renvoie {error, {inline_credentials, Keys}}. Les tâches
lisent leurs identifiants dans l’app env à chaque démarrage, pause et
reprise. Quand les deux sont définis, la signature l’emporte sur un
jeton bearer.
MCP
/mcp n’accepte que des jetons bearer : un jeton global (accès complet)
ou un jeton de capacité (limité, outil par outil, à son espace et à ses
droits). Il n’accepte ni les requêtes signées ni mTLS. Un appel d’outil
refusé revient comme résultat d’outil avec isError: true. Voir Point
d’accès MCP.
Navigateurs
barrel-lite envoie un jeton bearer. Donnez-lui un jeton de capacité
pour son espace, jamais le jeton global, et activez CORS. Voir
Démarrage rapide : navigateur.