Barrel
FR GitHub

One key per database. A credential on every request.

Barrel can encrypt a whole database at rest under its own key: documents, attachments, vectors and index files. In front of it, barrel_server checks a bearer, a capability token, a signed request or a client certificate before any route runs.

Both are off until you turn them on. This page says what each one covers, what it does not, and where tokens are enforced.

Encryption at restAuthentication

Encryption at rest

You pass an encryption spec when you open a database. A key provider turns the database keyspace into a 32-byte key; the stores encrypt every file they write with it. A branch shares its parent’s keyspace, so it opens with the same key.

  1. Master secret BARREL_ENCRYPTION_KEY
    Your key provider KMS, vault, per tenant

    HKDF-SHA256 with the database keyspace

  2. One key per database 32 bytes, never written to disk

    AES-256-CTR, per file and per sector

  3. Encrypted documents, WAL, blob attachments, vector store, disk BM25 and DiskANN files
    Not encrypted attachments on the S3 backend
What encryption at rest covers
DataAt rest
Document store (RocksDB files, WAL)Encrypted
Attachments in the default blob storeEncrypted
Attachments on the S3 backend (barrel_att_s3)Not encrypted: stored in clear in the bucket
Vector store, HNSW and FAISS stateEncrypted
Disk BM25 and DiskANN index filesEncrypted, per 4096-byte sector
Timeline branchesEncrypted under the parent’s key
Key-check file in the database directoryIn clear by design: it lets a wrong key fail at open

Who may call the server

Set an auth key and every route except /health needs a credential. A request is judged by the credential it presents: a signature first, else the token in Authorization, else the client certificate.

Auth models in barrel_server
ModelTurn it on withWhat it provesApplies to
Openno auth keyNothing. Every route answers.REST, sync, MCP
Bearer#{tokens => [...]}A shared secret, compared in constant time. A list lets you rotate.REST, sync, MCP
Capability tokenissued per space (bsp_...)One space, with read, write or admin. Lifecycle, timeline and unmapped routes refuse it.REST, sync, MCP
Signed request (v3)accept => [signed], signersAn Ed25519 key per client. Covers method, path, query, body hash and the headers that change a write; replays are refused.REST, sync
mTLSaccept => [mtls], verify_peerThat the client holds a certificate from your CA, not which client it is.REST, sync over HTTP/1.1 or HTTP/2 with TLS

In your node, and over the server

The agent layer is a library. Tokens mean something only where someone checks them.

Where tokens are enforced
ControlIn process (Erlang API)Over barrel_server (REST, sync, MCP)
Capability tokensAdvisory: checked only where your code calls barrel_caps:verify/3. open_space/1 and session calls take no token.Checked on every request and every MCP tool call.
Admin right (grant, revoke, handoffs)Not checked: the Erlang calls take no token.Required by the routes.
Per-database encryptionThe isolation boundary: no key, no data.Applied to every database through open_opts; keys never travel over HTTP.

What holds, and what tests it

Each property names the test or recorded run that checks it.

Nothing readable on disk

With encryption on, a search of every file for a marker written into a document, a vector text and an attachment finds nothing; the same write without encryption finds it.

Checked by a recorded end-to-end run (below), barrel_encryption_SUITE, barrel_encryption_facade_SUITE and barrel_vectordb_crypto_tests.

A wrong key fails at open

A wrong key answers wrong_encryption_key, a plaintext open of an encrypted database db_is_encrypted, never corrupted reads.

Checked by the recorded run and barrel_encryption_SUITE.

A failing signature is never rescued

A request that presents a signature is judged by it alone, even if a bearer or a client certificate would let it in.

Checked by t_bearer_with_bad_signature_rejected in barrel_server_signed_SUITE, t_bad_signature_rejected in barrel_server_mtls_SUITE.

Signed bodies and headers cannot be swapped

The body hash is checked before the handler runs, on every route; changing a signed header answers 401.

Checked by barrel_server_signed_SUITE: t_tampered_body_rejected, t_rest_doc_body_swap_rejected, t_att_put_digest_tamper_rejected, t_replay_rejected.

Capability tokens fail closed

A route not mapped to a right refuses a capability token with 403; a dead token gets 401.

Checked by t_capability_fail_closed and t_capability_dead_tokens in barrel_server_auth_SUITE.

mTLS refuses a client with no certificate

At the TLS handshake, before any route runs.

Checked by t_certless_refused in barrel_server_mtls_SUITE.

Use it

Encrypt a database

Encryption is runtime configuration: pass the same spec on every open.

%% export BARREL_ENCRYPTION_KEY="a long passphrase"
{ok, Db} = barrel:open(secret, #{encryption => default,
    vectordb => #{dimension => 3, bm25_backend => disk,
                  db_path => "data/secret_vec"}}),

%% or your own provider: key_for_db(Keyspace) -> {ok, <<_:256>>}
{ok, Db2} = barrel:open(tenant_a,
    #{encryption => #{provider => my_kms_provider}}).
Lines printed by a recorded run that wrote a marker into a document, a vector text and an attachment, closed the database and searched the files
read back: <<"TOPSECRETMARKER">>
bm25 hits: 1
files containing plaintext marker:        0
plaintext open: {error,db_is_encrypted}
wrong key open: {error,wrong_encryption_key}
reopened with right key: <<"TOPSECRETMARKER">>
encrypt existing plaintext db: {error,cannot_encrypt_existing_db}

Encrypt every database a server opens

sys.config
{barrel_server, [
    {open_opts, #{encryption => default}}
]}

Lock the server with bearer tokens

sys.config
{barrel_server, [
    {auth, #{tokens => [<<"new-token">>, <<"old-token">>]}}
]}

Sign requests between nodes

Generate the key pair with crypto:generate_key(eddsa, ed25519). Clients from barrel_docdb 2.1.0 send signature v3 only, so upgrade servers to barrel_server 1.13.0 first.

%% server: know each peer's public key
application:set_env(barrel_server, auth,
    #{accept  => [bearer, signed],
      signers => #{<<"node1">> => PubKey32},
      skew_ms => 300000}),

%% client: sign with the private key, kept out of task configs
application:set_env(barrel_docdb, sync_signing,
    #{<<"https://edge-1.example.com:8443">> =>
          #{key_id => <<"node1">>, priv_key => Priv32}}).

Gate the transport with mTLS

application:set_env(barrel_server, listeners,
    #{http => #{port => 8443, tls => true}}),
application:set_env(barrel_server, tls,
    #{certfile => "server.pem", keyfile => "server.key",
      cacertfile => "ca.pem", verify => verify_peer}),
application:set_env(barrel_server, auth,
    #{accept => [mtls, signed], signers => Signers}).

Limits

  • Attachments stored on the S3 backend are not encrypted, even when the database is.
  • There is no key rotation and no in-place encryption of an existing database. Replicate into a new database under the new key. A lost key means lost data.
  • The threat model is data at rest. CTR mode is not authenticated, so an attacker who can write the files is out of scope, and keys in memory are not zeroized.
  • A server with no auth key is open to anyone who can reach it. An empty accept list locks it completely.
  • Bearer tokens can be replayed without TLS. Signing authenticates the client and each request; it does not hide traffic or authenticate the server’s responses. Use verified HTTPS for that.
  • mTLS identifies your CA, not the peer: on its own every client with a certificate is one trusted peer. Add signed requests for identity. HTTP/3 listeners do not check client certificates yet.
  • /mcp and barrel-lite accept bearer tokens only (server or capability).

Up and down to moveEnter to open