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.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)
4
Double Ratchet initialization
The shared secret seeds the Double Ratchet algorithm for ongoing message encryption.
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:- Symmetric-key ratchet (chain keys) — Derives a new message key for each message using HKDF. Old keys are deleted after use, providing forward secrecy.
- 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
Device Key Handling
Proper key storage is critical to the security model.Requirements
Key Types and Lifecycle
Identity Key Pair (Ed25519)
Identity Key Pair (Ed25519)
- 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
Ephemeral Key Pair (X25519)
Ephemeral Key Pair (X25519)
- Generated during X3DH handshake
- Used once to establish the initial shared secret
- Deleted after the Double Ratchet is initialized
Chain Keys (HKDF-derived)
Chain Keys (HKDF-derived)
- Derived from the root key via HKDF after each DH ratchet step
- Used to derive individual message keys
- Advanced (replaced) after each message
Message Keys (XChaCha20-Poly1305)
Message Keys (XChaCha20-Poly1305)
- Derived from the current chain key
- Used to encrypt/decrypt exactly one message
- Deleted immediately after use to ensure forward secrecy
Library Choices
Recommended: @agentvault/crypto
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/decryptcrypto_scalarmult(X25519)crypto_sign_ed25519keypair generation and signingcrypto_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
- Delete message keys after use. Never cache or persist decrypted message keys.
- Advance the ratchet on every message. Skipping ratchet steps weakens forward secrecy.
- Re-key on member removal. When a device is revoked, all remaining sessions must re-key.
- 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.Required Test Cases
Required Test Cases