Architecture Overview

AgentVault is a secure enclave communications platform where AI agent owners communicate with their agents through end-to-end encrypted channels. The server acts solely as an encrypted relay — it never sees plaintext.

Core Security Properties

These four properties are enforced at every layer of the stack — cryptographic, application, and database.

Server never sees plaintext. All encryption and decryption happens client-side.
Closed, invite-only enrollment. No public discovery. Every device is explicitly approved by the owner.
Device-bound keys. Private keys are generated locally and never leave the device.
Strict tenant isolation via RLS. Row-Level Security policies on every database table prevent cross-tenant access.

System Architecture

OWNER (Browser / Mobile)
  Expo App + libsodium (MLS + Double Ratchet fallback)
  ├── Auth UI (Clerk)
  ├── Chat UI (E2E encrypted)
  └── Device Enrollment UI
        │
        ▼
AGENTVAULT BACKEND (FastAPI)
  Stores and relays ciphertext only
  ├── Enrollment Service
  ├── Message Store (BYTEA columns)
  └── WebSocket Relay (Redis pub/sub)
        │
        ▼
AGENT (OpenClaw / Third-Party)
  Node.js Plugin (@agentvault/agentvault)
  ├── libsodium (MLS + Double Ratchet fallback)
  └── OpenClaw Skill Interface

Components

Clients

AgentVault supports three client types, all sharing the same cryptographic library (@agentvault/crypto):

Owner App (Expo Universal)

The owner app runs on iOS, Android, and web from a single Expo codebase. It handles:

Authentication via Clerk (JWT issuance, session management)
Key generation (Ed25519 identity + X25519 ephemeral keypairs)
MLS/Double Ratchet encryption for every outbound message
Device management (invite, approve, revoke)
Key storage in platform-appropriate secure storage (SecureStore on native, IndexedDB on web)

Agent Plugin (@agentvault/agentvault)

The Node.js plugin integrates with OpenClaw and other agent frameworks:

3-line configuration in the agent’s config file
Automatic enrollment on first run (key generation, invite consumption, fingerprint display)
Persistent encrypted state on disk for subsequent runs
WebSocket connection for real-time bidirectional messaging
Message handler that decrypts inbound messages, passes them to agent logic, and encrypts responses

Client SDK (@agentvault/client)

A standalone TypeScript SDK for third-party integrations:

API key authentication (no Clerk dependency)
TOFU key exchange (Trust On First Use)
MLS/Double Ratchet E2E encryption via the shared crypto library
Programmatic access to all AgentVault APIs

Backend (FastAPI)

The backend is a Python FastAPI application that handles:

Responsibility	Details
Enrollment	Invite generation, token validation (BLAKE2b hashes only), device approval
Message relay	Stores ciphertext in PostgreSQL BYTEA columns, relays via WebSocket
WebSocket	Real-time bidirectional relay using Redis pub/sub for horizontal scaling
Tenant isolation	RLS policies on every tenant-scoped table, `tenant_id` scoping on every query
Rate limiting	Redis-backed limits (enrollment: 5/IP/10min, messaging: 60/min)

The backend has no access to private keys, no decryption capabilities, and no plaintext columns. Even a complete backend compromise exposes only ciphertext.

Database (PostgreSQL)

All data is stored in PostgreSQL 18 with Row-Level Security enabled on every tenant-scoped table:

tenants — Tenant identity and status
users — Clerk-authenticated users with RBAC roles
devices — Device identity keys (public only), fingerprints, status
invites — BLAKE2b hashed tokens (raw tokens never stored)
conversations — Owner-to-agent session metadata
messages — header_blob (BYTEA) + ciphertext (BYTEA). No plaintext columns exist.

Every query passes through RLS enforcement:

CREATE POLICY tenant_isolation ON messages
  USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid);

Cache and Pub/Sub (Redis)

Redis 7 serves two functions:

WebSocket relay — Redis pub/sub routes messages between connected clients, enabling horizontal scaling across multiple backend instances.
Rate limiting — Sliding window counters for enrollment, polling, and messaging endpoints.

Cryptographic Primitives

Function	Primitive	Why
Key exchange	X25519 (Diffie-Hellman)	Industry standard via libsodium `crypto_scalarmult`
Signing	Ed25519	Device identity keys, proof-of-possession during enrollment
Symmetric encryption	XChaCha20-Poly1305	192-bit nonce eliminates nonce reuse risk (unlike AES-GCM’s 96-bit nonce)
Group key agreement	MLS (RFC 9420)	Scalable group encryption with per-epoch forward secrecy
KDF	HKDF-SHA-512	Ratchet key derivation
Hashing	BLAKE2b	Invite token hashing, device fingerprints

XChaCha20-Poly1305 was chosen over AES-256-GCM specifically because its 192-bit nonce is safe to generate randomly with negligible collision probability. In a high-volume messaging system, AES-GCM’s 96-bit nonce creates a reuse risk that would result in full plaintext recovery. If FIPS compliance is later required, AES-256-GCM is a swap, not a rewrite.

Protocol Stack

Encryption: MLS Primary, Double Ratchet Fallback

AgentVault uses MLS (Messaging Layer Security, RFC 9420) as the primary encryption protocol for all conversation types — 1:1, rooms, and A2A channels. MLS provides scalable group key agreement with per-epoch forward secrecy via a ratchet tree structure. The Double Ratchet protocol (with X3DH key exchange) remains as a fallback for legacy 1:1 sessions and backward compatibility with older clients. Both protocols use XChaCha20-Poly1305 as the underlying AEAD cipher. MLS flow:

Key package upload during enrollment establishes the device’s MLS credentials
Group creation builds a ratchet tree for all conversation participants
Commit messages advance the group epoch on membership changes
Per-epoch forward secrecy — old epoch secrets are deleted after processing

Double Ratchet fallback (legacy 1:1):

X3DH key agreement during enrollment establishes a shared secret
Symmetric ratchet advances the chain key with every message
DH ratchet rotates the key agreement with every reply
Forward secrecy — old message keys are deleted after decryption

Message Flow

Owner types a message:
Advance sending chain key
Derive message key via KDF
Generate random 24-byte nonce
Encrypt with XChaCha20-Poly1305
Sign header with Ed25519 identity key
Send {header, signature, ciphertext} via WebSocket

Backend:
Store ciphertext in PostgreSQL (BYTEA)
Relay via Redis pub/sub to recipient

Agent receives:
Verify header signature
Advance receiving chain, derive message key
Decrypt ciphertext
Pass plaintext to agent logic

Infrastructure

Component	Service	Notes
App server	DigitalOcean Droplet	2 vCPU / 4GB, Docker deployment
Database	DO Managed PostgreSQL 18	Automated backups, SSL, connection pooling
Cache/PubSub	DO Managed Redis 7	TLS (`rediss://`), pub/sub for WebSocket relay
Auth	Clerk	JWT issuance, session management, custom domain
Frontend	Expo (EAS Build) + Vercel	Native apps via EAS, web SPA on Vercel
DNS/SSL	Cloudflare	Free tier, DDoS protection

Monorepo Structure

packages/
├── crypto/     # Shared TypeScript: MLS, Double Ratchet, X3DH, key generation
├── web/        # Expo universal app (iOS, Android, Web)
├── plugin/     # OpenClaw Node.js plugin
├── client/     # Third-party SDK
├── verify/     # Verification SDK (VCs, DID resolution)
├── site/       # Marketing site (Next.js)
└── backend/    # FastAPI Python backend (never decrypts)

The crypto library is the shared foundation — both the web app and the plugin import it for identical encryption behavior. The backend never imports or uses the crypto library because it never handles plaintext.

What’s Next

Zero-Knowledge Architecture

Deep dive into what the server can and cannot see.

Threat Model

Security goals, threat actors, and mitigations.

Protocol Flows

Visual sequence diagrams for enrollment, messaging, and device management.

Introduction & Core Concepts

Agent Identity & Cryptography

Secure Communications

Trust Scoring & Authorization

Agent Builder

Quality Control

Integrations

The AI Skill Marketplace

Observability & Audit Trails

Security & Compliance

API Reference

Architecture Overview

Core Security Properties

System Architecture

Components

Clients

Backend (FastAPI)

Database (PostgreSQL)

Cache and Pub/Sub (Redis)

Cryptographic Primitives

Protocol Stack

Encryption: MLS Primary, Double Ratchet Fallback

Message Flow

Infrastructure

Monorepo Structure

What’s Next

Zero-Knowledge Architecture

Threat Model

Protocol Flows

​Core Security Properties

​System Architecture

​Components

​Clients

​Backend (FastAPI)

​Database (PostgreSQL)

​Cache and Pub/Sub (Redis)

​Cryptographic Primitives

​Protocol Stack

​Encryption: MLS Primary, Double Ratchet Fallback

​Message Flow

​Infrastructure

​Monorepo Structure

​What’s Next

Zero-Knowledge Architecture

Threat Model

Protocol Flows

Core Security Properties

System Architecture

Components

Clients

Backend (FastAPI)

Database (PostgreSQL)

Cache and Pub/Sub (Redis)

Cryptographic Primitives

Protocol Stack

Encryption: MLS Primary, Double Ratchet Fallback

Message Flow

Infrastructure

Monorepo Structure

What’s Next