> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Claims & Assurance

> Formal security claims and the evidence that backs them.

AgentVault is designed as a **zero-knowledge secure communications enclave** for AI agent owners.
The core security property is simple: the server never sees plaintext. All encryption and
decryption happens client-side, and the backend only stores and relays ciphertext.

<Note>
  This document describes the security claims AgentVault makes and the architectural
  evidence supporting each claim. It is intended for security reviewers, auditors, and
  enterprise customers performing due diligence.
</Note>

## Security Model Overview

AgentVault's security model rests on four pillars:

| Pillar                       | Description                                                                                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Zero-knowledge backend**   | The server never possesses decryption keys. All message content is encrypted client-side before transmission.                                                               |
| **Client-side cryptography** | MLS (RFC 9420) as primary protocol for all conversation types. Double Ratchet (with X3DH) as fallback for legacy 1:1 sessions. XChaCha20-Poly1305 for symmetric encryption. |
| **Tenant isolation**         | Row-Level Security (RLS) policies on every database table enforce strict tenant boundaries at the PostgreSQL layer.                                                         |
| **Device-bound identity**    | Ed25519 identity keys are generated and stored on-device. Enrollment requires explicit admin approval.                                                                      |

***

## Confidentiality Claims

### Claim C1: End-to-End Encryption for All Message Content

All messages between owners and agents are encrypted using **MLS (RFC 9420)** as the primary
protocol, with **Double Ratchet** (X3DH key exchange) as a fallback for legacy 1:1 sessions.
Symmetric encryption uses **XChaCha20-Poly1305**, which provides authenticated encryption
with a 192-bit nonce, eliminating nonce reuse risk.

**Evidence:**

* Encryption and decryption occur exclusively in the client (`packages/crypto/` library shared between web and plugin).
* The backend `messages` table stores only `BYTEA` columns for ciphertext -- no plaintext columns exist.
* The crypto library is open source and independently auditable.

### Claim C2: No Plaintext Storage on Backend Systems

The backend database contains no plaintext message content. Invite tokens are stored as
BLAKE2b hashes only -- never in raw form.

**Evidence:**

* Database schema enforces `BYTEA` type for all cryptographic material columns.
* No plaintext columns exist in the `messages` table.
* Invite tokens are hashed with BLAKE2b before storage.

### Claim C3: No Plaintext in Push Notifications

Push notifications never contain message content. Notifications are delivery signals only,
triggering the client to fetch and decrypt messages locally.

**Evidence:**

* Push notification payloads contain only metadata (conversation ID, sender name).
* Message content is fetched and decrypted client-side after the notification is received.

### Claim C4: Forward Secrecy

MLS provides per-epoch forward secrecy: each Commit advances the group to a new epoch and
old epoch secrets are deleted. For legacy Double Ratchet sessions, forward secrecy is
per-message, with old message keys deleted after decryption. In both cases, compromise
of current keys does not expose past messages.

**Evidence:**

* MLS epoch secrets are deleted after epoch advancement.
* Double Ratchet state advances after each message exchange (fallback sessions).
* Key deletion is enforced in the crypto library after successful decryption.

***

## Integrity Claims

### Claim I1: Cryptographic Message Authentication

All messages are cryptographically authenticated using **XChaCha20-Poly1305**, which is an
AEAD (Authenticated Encryption with Associated Data) construction. Any tampering with
ciphertext is detected and rejected.

**Evidence:**

* Poly1305 MAC verification occurs on every decrypt operation.
* Corrupted or tampered messages fail authentication and are discarded.

### Claim I2: Device Proof-of-Possession

Device enrollment requires proof-of-possession of the Ed25519 identity key. Devices must
complete the enrollment flow and receive explicit admin approval before participating in
any communication.

**Evidence:**

* Enrollment generates an Ed25519 keypair on the device.
* The public key is submitted during enrollment; the private key never leaves the device.
* Admin approval is required before the device is activated.

### Claim I3: Tenant Data Integrity

Row-Level Security policies ensure that tenants can only read and write their own data.
Every query is scoped to `tenant_id`, enforced at both the application layer and the
database layer.

**Evidence:**

* RLS policy: `USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid)` on every tenant-scoped table.
* Middleware sets `app.current_tenant_id` on every database session.
* Every table (except `tenants`) includes a `tenant_id` column.

***

## Availability Claims

### Claim A1: Real-Time Encrypted Message Delivery

Messages are delivered in real-time via WebSocket connections, with Redis pub/sub providing
the relay layer for horizontal scalability.

**Evidence:**

* WebSocket connections are authenticated via JWT.
* Redis pub/sub enables message fan-out across multiple backend instances.
* HTTP polling fallback ensures delivery when WebSocket connections are interrupted.

### Claim A2: Stateless Backend Relay Architecture

The backend acts as a stateless relay for encrypted messages. It does not maintain
decryption state, making it horizontally scalable and resilient to instance failures.

**Evidence:**

* No cryptographic state is stored server-side.
* Any backend instance can relay any message.
* Database and Redis are managed services with built-in redundancy.

### Claim A3: Connection Resilience

The platform includes automatic reconnection with wake detection, ensuring message delivery
survives network interruptions, device sleep, and tab backgrounding.

**Evidence:**

* Wake detector identifies connection gaps exceeding 120 seconds and triggers reconnection.
* HTTP pending-message poll (15-second interval) provides fallback delivery.
* Browser `visibilitychange` listener detects tab foregrounding on web.

***

## Assurance Boundaries

<Warning>
  AgentVault's security claims are bounded. The following scenarios are explicitly
  **outside** the assurance boundary and are not protected against.
</Warning>

| Exclusion                           | Rationale                                                                                                                                                |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fully compromised client OS**     | If the operating system is compromised, an attacker has access to keys in memory. This is a fundamental limitation of any client-side encryption system. |
| **Malicious tenant administrators** | A tenant admin can approve or revoke devices within their tenant. Admin compromise is mitigated by audit logging but not prevented.                      |
| **Nation-state traffic analysis**   | AgentVault does not provide traffic obfuscation or metadata hiding. Message timing and size patterns are visible to network observers.                   |
| **Screenshot prevention**           | The platform does not prevent screenshots or screen recording on client devices.                                                                         |

***

## Validation Controls

The following validation activities are recommended to maintain assurance:

| Control                   | Frequency   | Description                                                                                       |
| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| **Cryptographic review**  | Annual      | Independent review of the `packages/crypto/` library by a qualified cryptographer.                |
| **RLS policy audit**      | Per release | Verify that all new tables have RLS policies and that existing policies are not weakened.         |
| **Penetration testing**   | Annual      | External penetration test covering API endpoints, WebSocket connections, and enrollment flows.    |
| **Dependency audit**      | Continuous  | Automated scanning of npm and Python dependencies for known vulnerabilities.                      |
| **Key management review** | Semi-annual | Review of key generation, storage, rotation, and deletion procedures across all client platforms. |

***

## Cryptographic Primitives Summary

| Function                  | Algorithm          | Notes                                                          |
| ------------------------- | ------------------ | -------------------------------------------------------------- |
| Key exchange              | X25519 (X3DH)      | Extended Triple Diffie-Hellman for session establishment       |
| Signing                   | Ed25519            | Device identity and DID document signatures                    |
| Symmetric encryption      | XChaCha20-Poly1305 | AEAD with 192-bit nonce (no nonce reuse risk)                  |
| Group key agreement       | MLS (RFC 9420)     | Primary protocol -- per-epoch forward secrecy via ratchet tree |
| Key derivation (fallback) | Double Ratchet     | Per-message forward secrecy for legacy 1:1 sessions            |
| Hashing                   | BLAKE2b            | Invite token hashing, key fingerprints                         |
| Library                   | libsodium          | Battle-tested implementation used on all platforms             |