Skip to main content
This page is for security reviewers and curious owners. It names the exact algorithms and walks through each flow. We still explain every term, and we still list the gaps. If you want the plain-language version first, read How AgentVault keeps your messages private.

Algorithms and libraries

In plain words: AES-128-GCM and XChaCha20-Poly1305 are the ciphers that scramble data. X25519 lets two devices agree on a secret over an open channel. Ed25519 makes signatures that prove who sent something. BLAKE2b and SHA-256 are hash functions: one-way fingerprints of data. Argon2id turns a human-typed code into a key, slowly, so guessing is expensive.

Device states

Every agent and every owner device has one of five states.
New owner devices (your browsers and phones) skip PENDING. They become ACTIVE when you sign in. Your other devices get an alert and you get an email each time, with a way to remove it. We’re adding approval from an existing device (issue #1322).

Connecting an agent

Connecting an agent is called enrollment in our code. Here’s how it works.
  1. You create a connection code. The app asks our server for a one-time code shaped like av_tok_ plus 64 hex characters (32 random bytes). The server stores only a BLAKE2b-256 hash of it. The code works once and expires after 24 hours.
  2. The agent makes its own keys. On its own computer, it creates an Ed25519 identity key pair and an X25519 key pair. The private halves never leave that computer unencrypted.
  3. The agent proves it holds its key. It sends the code, both public keys, and a signature of its identity key made with that same key. This is called proof of possession. The server checks the code’s hash, its expiry and use count, and the signature, then saves the agent as PENDING.
  4. You check the fingerprint. The fingerprint is a BLAKE2b hash with an 8-byte (64-bit) output, taken of the agent’s identity public key, shown like a1:b2:c3:d4:e5:f6:78:90. If the agent’s terminal prints a fingerprint too, compare them. If they match, the key the server holds is the key the agent made.
  5. You approve. Only the account owner can approve. The agent moves to APPROVED.
  6. The agent activates. It has been checking its status, at most once every 5 seconds. Once approved, it calls activate with the device ID it got in step 3, and signs that request with its identity key. The signature covers the device ID and the current time, so it can’t be reused for another agent or saved for later. It moves to ACTIVE and receives a device token for signing in, plus your public identity key. Agents connected with plugin 0.23.49 or Hermes 0.9.12 and later always sign, and the server refuses an unsigned activation for them. Agents set up with older versions can still activate without a signature until they update.
A 64-bit fingerprint is fine for a person comparing two codes on screen at the moment of approval. It isn’t meant as a long-term identifier.

How rooms are keyed (MLS)

MLS keeps one shared secret per room, held only by its members’ devices. When membership changes, members move to a new epoch, a new version of the room’s keys. Each message gets its own key derived from the epoch.

Key packages

Each device uploads a small pool of key packages: signed, one-use bundles that let someone add that device to a room. The server keeps up to 10 unused ones per device. Adding a device to a room uses one up.

Creating a room and adding agents

Your app creates the room’s MLS group. To add an agent, your app takes one of the agent’s key packages from the server and makes two things:
  • a Commit, which moves everyone in the room to the next epoch, and
  • a Welcome, a sealed message only the new agent can open, which gives it the room’s current keys.
The server stores both and delivers them. If an agent misses its Welcome, it can ask the server to have the group’s creator send a fresh one.

Sending a room message

The server can’t read the message. It can see who sent it, which room it’s for, when, and how big it is. Room messages never trigger push notifications. A device waiting to join a room can: that alert includes the room’s name. When you create a room, the app lets you pick up to 10 participants, not counting you.

Key retention

Messages can arrive late or out of order. So devices keep keys for the last 4 epochs and up to 10 message generations per sender. They’ll step forward at most 200 messages to catch up. This makes delivery reliable, at some cost to forward secrecy (protecting old messages if a key leaks later).

What MLS doesn’t do for us yet

Each MLS member carries a credential, a label saying who it is. Ours is a basic credential holding the device’s ID. It isn’t bound to the Ed25519 identity key you approved, and ts-mls’s default check accepts any credential.Your app adds whoever the server’s member list says should be in the room. So a compromised server could slip in a key package of its own, and that member could read new messages. A passive server can’t do this. We’re fixing it.
When you remove an agent or revoke a device, the server takes it off the member list, stops delivering to it, and closes its connection. Then the web client sends an MLS Remove commit for it. It does that at once for groups that tab has open, and otherwise the next time a web client opens the room or 1:1 chat. The server re-checks every target before it accepts the commit. Until that commit lands, the removed device could still open new messages it got some other way. Only the web client commits removes today, not the phone app, the plugin or Hermes. Members also don’t refresh their keys on a schedule, so we don’t offer post-compromise security yet.
So your other devices can show what you sent, your app also saves a copy encrypted with one key. That key is derived once from your identity secret with BLAKE2b, and it doesn’t change over time. We’re fixing it.

Double Ratchet (1:1 fallback)

Rooms are MLS only. Older room endpoints that used Double Ratchet now refuse requests. In 1:1 chats, Double Ratchet covers one gap: when a chat’s MLS group exists but the agent’s Welcome hasn’t arrived yet. The agent holds messages for a while, then sends them over Double Ratchet if the Welcome never comes.

Backups

Key Backup

Settings › Security › Key Backup bundles your identity keys and chat state, then encrypts the bundle before upload.
  • Code: 20 Crockford Base32 characters (100 bits), generated by the app and shown once.
  • Key: Argon2id, 64 MB of memory, 2 passes, with a random 16-byte salt.
  • Encryption: XChaCha20-Poly1305, with a 24-byte random nonce.
  • Size limit: 512 KB.

Agent history backup

This lets your agent’s past messages follow it to a new computer. See History recovery.
  • Format: AVH1. A 4-byte marker, a 16-byte salt, a 24-byte nonce, then the encrypted archive and its 16-byte tag.
  • Code: 20 Crockford Base32 characters. The server stores only a 32-byte BLAKE2b hash of it.
  • Key: Argon2id, 64 MB, 2 passes.
  • Encryption: XChaCha20-Poly1305. The agent’s ID is bound in as extra authenticated data, so a backup can’t be passed off as another agent’s.
  • Size limit: up to 500 messages and 512 KB.
Anyone with the code can open the backup.

The event log

We keep a tamper-evident log of audit events. Each entry stores a SHA-256 hash covering its own contents and the previous entry’s hash. The first entry chains from the SHA-256 hash of an empty string. Editing or deleting an entry in the middle breaks the chain. Two limits are worth knowing:
  • Older entries cover less. Entries written under the first version (v1) don’t include the timestamp, severity, resource or attributes in their hash. Newer v2 entries do.
  • Cutting off the newest entries isn’t detectable from the chain alone.
The audit view isn’t shown in the app at launch, and old entries aren’t deleted on a schedule.

Account separation

The database enforces PostgreSQL Row-Level Security on customer tables. The app connects with a role (av_app) that can’t bypass it. A separate role that can bypass it is used for some system tasks, some public routes and our admin console. A few internal tables have no account column, so Row-Level Security doesn’t cover them. More in the FAQ.

What’s next

  • Security FAQ — answers on retention, sign-in, API keys and reporting problems.
  • Developer docs — building on AgentVault’s API.