System Security Plan

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 (MLS, Double Ratchet fallback, 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 18 (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.
MLS group creation (primary) or Double Ratchet (fallback) derives 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 every tenant-scoped table
CREATE POLICY tenant_isolation ON table_name
  USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::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
Group key agreement	MLS (RFC 9420)	libsodium	Per-epoch secrets
Key derivation	HKDF (via MLS/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	MLS Commits advance the epoch key. Double Ratchet (fallback) rotates symmetric keys per message.
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 every tenant-scoped table, 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.

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

System Security Plan

1. System Overview

2. Architecture Summary

Infrastructure Components

Data Flow

3. Roles & Responsibilities

Application Roles (RBAC)

4. Access Control

Authentication

Authorization

Enrollment

5. Cryptographic Controls

Algorithm Suite

Key Lifecycle

Design Decisions

6. Monitoring & Logging

Logging Policy

Observability

Alerting

7. Risk Management

Methodology

Threat Summary

Risk Acceptance

Review Cadence

8. Incident Response

Response Phases

Device Compromise Procedure

9. Compliance Posture

​1. System Overview

​2. Architecture Summary

​Infrastructure Components

​Data Flow

​3. Roles & Responsibilities

​Application Roles (RBAC)

​4. Access Control

​Authentication

​Authorization

​Enrollment

​5. Cryptographic Controls

​Algorithm Suite

​Key Lifecycle

​Design Decisions

​6. Monitoring & Logging

​Logging Policy

​Observability

​Alerting

​7. Risk Management

​Methodology

​Threat Summary

​Risk Acceptance

​Review Cadence

​8. Incident Response

​Response Phases

​Device Compromise Procedure

​9. Compliance Posture

1. System Overview

2. Architecture Summary

Infrastructure Components

Data Flow

3. Roles & Responsibilities

Application Roles (RBAC)

4. Access Control

Authentication

Authorization

Enrollment

5. Cryptographic Controls

Algorithm Suite

Key Lifecycle

Design Decisions

6. Monitoring & Logging

Logging Policy

Observability

Alerting

7. Risk Management

Methodology

Threat Summary

Risk Acceptance

Review Cadence

8. Incident Response

Response Phases

Device Compromise Procedure

9. Compliance Posture