Skip to main content

​
Key Architecture

AgentVault’s cryptographic identity system is built on Ed25519 signing keys and X25519 key exchange, organized in a dual-key architecture that separates long-term identity from operational use.

​
Dual-Key Model

Every agent operates with two distinct keypairs:
Why two keys?
  • Least privilege — Operational key compromise doesn’t expose ownership authority
  • Key rotation — Operational keys rotate without changing the agent’s identity
  • Offline signing — Owner key can remain air-gapped for high-security deployments
  • Non-repudiation — Owner key actions are attributable to the human operator

​
Key Generation

Keys are generated client-side using libsodium. The server never sees private key material.

​
Key Derivation

​
X3DH Key Agreement

The Extended Triple Diffie-Hellman (X3DH) protocol establishes a shared secret between parties who have never communicated:
1

Key bundle upload

Each device uploads a signed prekey bundle: identity key (IK), signed prekey (SPK), and one-time prekeys (OPK).
2

Initial message

The initiator computes a shared secret from four DH operations: DH(IK_A, SPK_B) || DH(EK_A, IK_B) || DH(EK_A, SPK_B) || DH(EK_A, OPK_B)
3

KDF

Concatenated DH outputs pass through HKDF-SHA-512 to derive the root key for the Double Ratchet.
4

Ratchet initialization

Both parties initialize a Double Ratchet session from the shared secret.
Security properties: Forward secrecy, deniability, asynchronous setup.

​
Double Ratchet (Fallback for Legacy 1:1 Sessions)

For legacy 1:1 sessions that predate the MLS migration, the Double Ratchet provides per-message forward secrecy after X3DH. New sessions use MLS as the primary protocol.

​
Auto-Resync

If ratchet state desynchronizes (e.g., after a crash):
  1. Receiver detects decryption failure
  2. Sends resync_request to the peer
  3. Both parties perform a fresh X3DH key exchange
  4. New ratchet sessions are established
  5. av.resync telemetry span is emitted

​
Key Storage

​
Agent-Side

State file: {dataDir}/agentvault.json (Plugin) or {dataDir}/client-state.json (Client SDK) Contains: device ID, identity keypair, ephemeral keypair, per-conversation ratchet state, message history.
State files contain private key material. Ensure dataDir has restrictive file permissions (chmod 700). A backup is automatically maintained at agentvault.json.bak.

​
Owner-Side

  • iOS/Android: SecureStore (Keychain/Keystore)
  • Web: IndexedDB with encryption at rest
  • Keys scoped per device — multi-device fan-out encrypts independently per ratchet

​
Server-Side

The server stores only public keys and encrypted prekey bundles. No private keys, no message plaintexts, no ratchet state.

​
Key Rotation

Operational key rotation:
  1. Owner initiates rotation from the dashboard
  2. Agent generates a new Ed25519 keypair
  3. New public key uploaded, signed by the owner key
  4. Old sessions maintained until they naturally expire
Emergency revocation:
  1. Owner revokes the key from the dashboard
  2. All active sessions for that key are terminated
  3. Agent must re-enroll with a new keypair
  4. security_violation audit event is recorded

​
Fingerprint Verification

Key fingerprints are BLAKE2b hashes displayed as colon-separated hex:
Owners verify their agent’s fingerprint by comparing values shown in the app, the agent’s CLI output during enrollment, and the DID document. This out-of-band verification prevents man-in-the-middle attacks.