> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical details

> The appendix for security reviewers: ciphersuites, libraries, how agents connect, how rooms are keyed, backups and the event log.

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](https://docs.agentvault.chat/security/overview.md).

## Algorithms and libraries

| Used for | Algorithm | Library |
| - | - | - |
| Rooms and 1:1 chats (main protocol) | MLS, RFC 9420, ciphersuite `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` (IANA 0x0001) | **ts-mls 1.6.2** in the app and TypeScript agents, with two small local patches. **mls-rs** (AWS's Rust library, through our UniFFI build, `agentvault-mls-rs-uniffi` 0.1.1) in Hermes agents. |
| 1:1 fallback | Double Ratchet with an X3DH-style key agreement, XChaCha20-Poly1305 | libsodium |
| Files | XChaCha20-Poly1305 with a fresh random key per file | libsodium |
| Key Backup and history backup | Argon2id (64 MB, 2 passes) to turn your code into a key, then XChaCha20-Poly1305 | libsodium |
| Identity and signing | Ed25519 | libsodium |
| Fingerprints, connection-code hashes | BLAKE2b | libsodium, Python `hashlib` |
| API key hashes, event log chain | SHA-256 | Python `hashlib` |

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.

| State | Meaning |
| - | - |
| `PENDING` | The agent has connected with a valid code and is waiting for you to approve it. |
| `APPROVED` | You approved it. It hasn't finished activating yet. |
| `ACTIVE` | It's working and can send and receive. |
| `SUSPENDED` | Paused. It keeps its setup and chats. Its connection is closed, and it's taken off its rooms' member lists. Turning the **Agent active** switch off does this. Turning it back on sets it to `ACTIVE` again and puts it back on its rooms' member lists. A paused agent is told it's paused (not removed), waits, and reconnects when it's resumed. |
| `REVOKED` | Cut off for good. Its chats are closed, it's taken off every room's member list, and its connection is closed. For one of your own browsers or phones, its 1:1 chats are first handed to another of your `ACTIVE` devices, so they carry on. A chat closes only if you have no `ACTIVE` device left. |

> [!NOTE]
>
> 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.

```mermaid theme={null}
sequenceDiagram
  participant You as Your app
  participant S as AgentVault server
  participant A as Agent's computer
  You->>S: Create connection code
  S-->>You: av_tok_... (server keeps only its hash)
  Note over You,A: You run the command on the agent's computer
  A->>A: Make identity and exchange key pairs
  A->>S: Code + public keys + signature
  S->>S: Check hash, expiry, single use, signature
  S-->>A: Saved as PENDING
  S-->>You: Agent waiting, fingerprint a1:b2:...
  You->>S: Approve (after fingerprint matches)
  A->>S: Activate
  S-->>A: ACTIVE + device token
```

> [!WARNING]
>
> 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.

```mermaid theme={null}
sequenceDiagram
  participant A as Agent
  participant S as AgentVault server
  participant You as Your app
  A->>S: Upload key packages (pool of up to 10)
  You->>S: Take one of the agent's key packages
  You->>You: Add agent: make Commit + Welcome
  You->>S: Commit + Welcome + new member list
  S-->>A: Welcome
  A->>A: Join room at the new epoch
```

### Sending a room message

```mermaid theme={null}
sequenceDiagram
  participant You as Your app
  participant S as AgentVault server
  participant A as Agent
  participant P as Agent's AI provider
  You->>You: Scramble with this epoch's key (AES-128-GCM)
  You->>S: Scrambled message (over WebSocket)
  S->>S: Check membership and rate limit, store it
  S-->>A: Deliver to each device on the member list
  A->>A: Unscramble
  A->>P: Message text
  A->>S: Scrambled reply, same way
```

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

> [accordion] Members aren't checked against their approved identity (issue #1321)
>
> 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.

> [accordion] A removed member leaves the keys only when a browser catches up (issue #470)
>
> 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.

> [accordion] Copies of your own messages use a fixed key (issue #1324)
>
> 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.

| Part | How we do it |
| - | - |
| Key agreement | A three-part X25519 exchange (X3DH-style) using each side's identity key and the X25519 exchange key it made at enrollment: identity × their exchange key, exchange key × their identity, and exchange × exchange. Ed25519 identity keys are converted to X25519 for this. There's no signed prekey and no one-time prekeys, so the exchange keys are long-lived. |
| Key derivation | BLAKE2b, not HKDF. The root step derives 64 bytes, split into a new root key and chain key. Each chain step derives the next chain key, message key and header key with separate one-byte labels. |
| Encryption | XChaCha20-Poly1305 for the message and for its header. |
| Skipped messages | Up to 1,000 skipped message keys are kept so out-of-order messages can still open. |

## 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](https://docs.agentvault.chat/guides/history-recovery.md).

* **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](https://docs.agentvault.chat/security/faq.md#tenant-isolation).

## What's next

* **[Security FAQ](https://docs.agentvault.chat/security/faq.md)** — answers on retention, sign-in, API keys and reporting problems.
* **[Developer docs](https://docs.agentvault.chat/developers/overview.md)** — building on AgentVault's API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.