Skip to main content
AgentVault provides end-to-end encryption for all agent-owner communications. The server never sees plaintext — all encryption and decryption happens client-side. MLS (RFC 9420) is the primary encryption protocol for all conversation types, with Double Ratchet + X3DH retained as a fallback for legacy 1:1 sessions. This guide covers the cryptographic primitives, key handling requirements, and forward secrecy guarantees that every integration must follow.
AgentVault’s crypto library (@agentvault/crypto) implements all of these requirements. If you are building a custom integration, follow this guide to ensure compatibility.

Cryptographic Primitives

AgentVault uses a carefully chosen set of modern primitives via libsodium.
AgentVault does not use AES-GCM. The 192-bit nonce in XChaCha20-Poly1305 eliminates nonce reuse risk that plagues AES-GCM’s 96-bit nonce, which is critical for high-throughput messaging where random nonce collisions become statistically significant.

Key Exchange: X3DH (Double Ratchet Fallback)

For legacy 1:1 sessions that have not migrated to MLS, AgentVault uses the Extended Triple Diffie-Hellman (X3DH) protocol to establish shared secrets between an owner and an agent device. New sessions use MLS group creation instead.
1

Identity key generation

Each device generates a long-term Ed25519 identity key pair stored in OS secure storage (Keychain on iOS, Keystore on Android, expo-secure-store cross-platform).
2

Ephemeral key generation

The initiating device generates a one-time X25519 ephemeral key pair for the handshake.
3

Triple DH computation

Three DH computations produce the shared secret:
  • DH(identity_A, ephemeral_B)
  • DH(ephemeral_A, identity_B)
  • DH(ephemeral_A, ephemeral_B)
The results are concatenated and passed through HKDF to derive the initial root key.
4

Double Ratchet initialization

The shared secret seeds the Double Ratchet algorithm for ongoing message encryption.
AgentVault’s X3DH implementation uses synchronous enrollment (both parties are online), so signed prekeys and one-time prekeys are not required. This is acceptable for the agent use case where devices enroll in real-time.

Double Ratchet Protocol (Fallback)

For legacy 1:1 sessions, the Double Ratchet algorithm provides forward secrecy and break-in recovery after the X3DH handshake. New conversations use MLS as the primary protocol.

How It Works

The Double Ratchet combines two ratcheting mechanisms:
  1. Symmetric-key ratchet (chain keys) — Derives a new message key for each message using HKDF. Old keys are deleted after use, providing forward secrecy.
  2. Diffie-Hellman ratchet — Periodically performs a new DH key exchange to provide break-in recovery. If a key is compromised, future messages remain secure after the next DH ratchet step.

Ratchet Advancement

The ratchet must advance on every message. Reusing a message key breaks forward secrecy and exposes all messages encrypted under that key.

Device Key Handling

Proper key storage is critical to the security model.

Requirements

Key Types and Lifecycle

  • Generated once per device during enrollment
  • Stored permanently in OS secure storage
  • Used to sign messages and derive DH shared secrets
  • Survives app updates; lost only on device wipe or explicit revocation
  • Generated during X3DH handshake
  • Used once to establish the initial shared secret
  • Deleted after the Double Ratchet is initialized
  • Derived from the root key via HKDF after each DH ratchet step
  • Used to derive individual message keys
  • Advanced (replaced) after each message
  • Derived from the current chain key
  • Used to encrypt/decrypt exactly one message
  • Deleted immediately after use to ensure forward secrecy

Library Choices

The @agentvault/crypto npm package provides a complete implementation of AgentVault’s cryptographic protocols (MLS and Double Ratchet fallback).
The examples below show the Double Ratchet fallback API. For new integrations, the MLS group API is used automatically by the SecureChannel and AgentVaultClient classes. These lower-level APIs are relevant for custom implementations or legacy session support.

Custom Implementations

If you are building a custom integration in a language other than TypeScript, use any libsodium binding that provides:
  • crypto_aead_xchacha20poly1305_ietf_encrypt / decrypt
  • crypto_scalarmult (X25519)
  • crypto_sign_ed25519 keypair generation and signing
  • crypto_generichash (BLAKE2b)
  • crypto_kdf_hkdf_sha256_extract / expand (or equivalent HKDF)

Forward Secrecy Guarantees

AgentVault’s protocols provide multiple levels of forward secrecy:

Ensuring Forward Secrecy in Your Integration

  1. Delete message keys after use. Never cache or persist decrypted message keys.
  2. Advance the ratchet on every message. Skipping ratchet steps weakens forward secrecy.
  3. Re-key on member removal. When a device is revoked, all remaining sessions must re-key.
  4. Verify epoch consistency. Ensure both parties agree on the current ratchet state.

Validation Tests

Any custom cryptographic integration should pass these test categories before deployment.

Operational Safeguards

These safeguards are mandatory for production deployments.