This System Security Plan (SSP) describes AgentVault’s security architecture, controls, and
risk management approach. It is intended for security auditors, enterprise customers, and
internal engineering teams.
This SSP covers the AgentVault Secure Enclave platform as deployed in production. It
is a living document updated as the platform evolves.
1. System Overview
AgentVault is a zero-knowledge, invite-only secure communications platform that enables
AI agent owners to communicate with their agents through end-to-end encrypted channels.
Core security property: The backend never possesses decryption keys. All encryption and
decryption happens client-side. The server stores and relays ciphertext only.
| Attribute | Value |
|---|
| System type | Secure communications enclave |
| Deployment model | Cloud-hosted (DigitalOcean, Cloudflare, Clerk) |
| Data classification | Confidential (message content), Internal (metadata) |
| User population | AI agent owners, agents, tenant administrators |
| Availability target | 99.9% uptime for API and WebSocket services |
2. Architecture Summary
AgentVault follows a monorepo architecture with clear separation between client-side
cryptography and server-side relay:
packages/
crypto/ -- Shared TypeScript cryptographic library (Double Ratchet, X3DH)
web/ -- Expo universal app (iOS, Android, Web)
plugin/ -- OpenClaw Node.js plugin for agent integration
client/ -- TypeScript SDK for third-party agent developers
verify/ -- Verification SDK for credential validation
backend/ -- FastAPI Python backend (ciphertext relay only)
Infrastructure Components
| Component | Technology | Security Role |
|---|
| Backend API | Python 3.11+ / FastAPI | Ciphertext relay, tenant management, RBAC enforcement |
| Database | PostgreSQL 16 (managed) | Encrypted data storage with RLS tenant isolation |
| Cache / Pub-Sub | Redis 7 (managed) | WebSocket message relay, rate limiting |
| Authentication | Clerk | JWT issuance, session management |
| DNS / TLS | Cloudflare | TLS termination, DDoS protection |
| Client crypto | libsodium (JS) | All encryption/decryption operations |
Data Flow
The backend is a ciphertext-only relay. It never decrypts, inspects, or transforms
message content. All cryptographic operations occur on client devices.
- Client generates Ed25519 identity keypair during enrollment.
- X3DH key exchange establishes a shared secret between owner and agent.
- Double Ratchet derives per-message encryption keys from the shared secret.
- Client encrypts message with XChaCha20-Poly1305 and sends ciphertext to backend.
- Backend stores ciphertext in PostgreSQL and relays via WebSocket/Redis pub-sub.
- Recipient client receives ciphertext, advances ratchet, and decrypts locally.
3. Roles & Responsibilities
| Role | Responsibility |
|---|
| Security Officer | Overall security posture, risk acceptance, incident escalation |
| Engineering Lead | Secure development practices, code review, architecture decisions |
| DevSecOps Lead | Infrastructure security, deployment pipeline, monitoring |
| Incident Response Lead | Incident detection, containment, recovery, post-mortem |
Application Roles (RBAC)
| Role | Scope | Key Permissions |
|---|
| Owner Admin | Tenant-wide | Full control: enrollment, revocation, billing, room management |
| Tenant Admin | Tenant-wide | Device management, enrollment approval, room management |
| Member | Assigned rooms | Send/receive messages, view conversations |
| Agent | Assigned conversations | Send/receive messages within assigned scope |
4. Access Control
Authentication
All API access requires a valid Clerk JWT in the Authorization: Bearer header. WebSocket
connections require the JWT as a query parameter (?token=<jwt>).
| Control | Implementation |
|---|
| Identity provider | Clerk (custom domain: clerk.agentvault.chat) |
| Token format | JWT with tenant and role claims |
| Session management | Clerk-managed with automatic rotation |
| Multi-factor auth | Supported via Clerk configuration |
Authorization
Authorization is enforced at two layers:
- API layer: FastAPI middleware checks role permissions on every endpoint.
- Database layer: PostgreSQL RLS policies enforce tenant scoping on every query.
-- RLS policy applied to all tables
CREATE POLICY tenant_isolation ON table_name
USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
Enrollment
| Step | Description |
|---|
| 1. Invite generation | Admin creates a time-limited invite token |
| 2. Token submission | New device submits the token with its Ed25519 public key |
| 3. Token verification | Backend verifies BLAKE2b hash of submitted token |
| 4. Admin approval | Administrator explicitly approves the enrollment |
| 5. Device activation | Device receives “active” status and can participate |
5. Cryptographic Controls
Algorithm Suite
| Function | Algorithm | Library | Key Size |
|---|
| Key exchange | X25519 (X3DH) | libsodium | 256-bit |
| Signing | Ed25519 | libsodium | 256-bit |
| Symmetric encryption | XChaCha20-Poly1305 | libsodium | 256-bit key, 192-bit nonce |
| Hashing | BLAKE2b | libsodium | 256-bit output |
| Key derivation | HKDF (via Double Ratchet) | libsodium | 256-bit |
Key Lifecycle
| Phase | Control |
|---|
| Generation | Ed25519 keypairs generated on-device during enrollment. Never transmitted in plaintext. |
| Storage | Private keys stored in platform secure storage (SecureStore on mobile, localStorage on web). |
| Usage | Keys used exclusively for X3DH session establishment and message signing. |
| Rotation | Double Ratchet automatically rotates symmetric keys per message. DH ratchet rotates on each reply. |
| Deletion | Message keys deleted after decryption (forward secrecy). Device keys deleted on revocation. |
Design Decisions
AgentVault uses XChaCha20-Poly1305 rather than AES-GCM. The 192-bit nonce space
of XChaCha20 eliminates the risk of nonce reuse, which is a practical concern with
AES-GCM’s 96-bit nonce in high-volume messaging systems.
6. Monitoring & Logging
Logging Policy
| Category | Logged | Content |
|---|
| API requests | Yes | Method, path, status code, latency, tenant ID |
| Authentication events | Yes | Login, logout, token refresh, failures |
| Administrative actions | Yes | Enrollment, revocation, role changes, room management |
| Message content | Never | Only message metadata (IDs, timestamps) is logged |
| Cryptographic keys | Never | No key material appears in any log output |
Observability
AgentVault implements an OTel-shaped telemetry pipeline for operational monitoring:
| Signal | Coverage |
|---|
| Traces | Request lifecycle, WebSocket message delivery, enrollment flows |
| Metrics | Connection health, message latency, error rates, active sessions |
| Logs | Structured JSON logs with correlation IDs (no plaintext content) |
Alerting
| Condition | Response |
|---|
| Failed authentication spike | Rate limiting escalation, admin notification |
| WebSocket disconnection anomaly | Connection health check, device status verification |
| Database connection failure | Automatic reconnection, infrastructure alert |
| Enrollment rate limit exceeded | IP-based throttling (5 attempts / 10 minutes) |
7. Risk Management
Methodology
AgentVault applies STRIDE threat modeling to identify threats and DREAD scoring to
prioritize risk treatment.
Threat Summary
| Threat | STRIDE Category | Mitigation | Residual Risk |
|---|
| Database breach | Information Disclosure | Ciphertext-only storage; no server-side keys | Low — attacker obtains only encrypted blobs |
| Compromised device | Elevation of Privilege | Device revocation + session re-establishment | Medium — attacker has access until revocation |
| RLS misconfiguration | Tampering | RLS on all tables, audit per release | Low — database-level enforcement |
| Enrollment social engineering | Spoofing | Fingerprint verification, short-lived invites, admin approval | Medium — relies on admin diligence |
| Network interception | Information Disclosure | TLS 1.3 + E2E encryption | Low — double-layer encryption |
| Rogue administrator | Elevation of Privilege | Audit logging, RBAC constraints | Medium — admin has inherent privileges |
Risk Acceptance
The following risks are accepted as outside the system’s assurance boundary:
- Fully compromised client operating system
- Nation-state traffic analysis and metadata correlation
- Screenshot or screen recording on client devices
- Physical device theft (mitigated by device revocation)
Review Cadence
| Activity | Frequency |
|---|
| Threat model review | Annual or after major architecture changes |
| RLS policy audit | Every release that modifies database schema |
| Penetration testing | Annual, by external assessor |
| Cryptographic review | Annual, by qualified cryptographer |
| Dependency vulnerability scan | Continuous (automated) |
| Security incident post-mortem | After every security incident |
8. Incident Response
Response Phases
| Phase | Actions |
|---|
| Detection | Monitoring alerts, user reports, automated anomaly detection |
| Containment | Device revocation, WebSocket disconnection, rate limit escalation |
| Eradication | Session re-establishment, credential rotation, patch deployment |
| Recovery | Service restoration, ratchet re-establishment, user notification |
| Post-mortem | Root cause analysis, control improvements, documentation update |
Device Compromise Procedure
- Admin revokes the compromised device via the management interface.
- Backend immediately closes the device’s WebSocket connection.
- Device status is set to “revoked” — all subsequent API calls are rejected.
- Remaining participants establish new encryption sessions, excluding the revoked device.
- Incident is logged in the audit trail.
9. Compliance Posture
| Framework | Status | Reference |
|---|
| SOC 2 Type I | Architecture aligned | Compliance Mapping |
| ISO 27001 | Architecture aligned | Compliance Mapping |
| NIST CSF | Partial alignment | Identify, Protect, Detect addressed |
| OWASP Top 10 | Mitigated | Input validation, auth enforcement, injection prevention |
Formal SOC 2 and ISO 27001 certification is on the roadmap. Current architectural
controls provide a strong foundation for certification when the organization is ready
to engage an auditor.
