> ## 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.
# Threat Model
> Security goals, threat actors, and how AgentVault mitigates attacks.
This document defines AgentVault's security goals, enumerates threat actors, identifies high-value assets, and maps each threat scenario to specific mitigations. Honest limitations are documented alongside protections.
## Security Goals
| Goal | Enforcement |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **End-to-end encryption** | Server cannot decrypt messages. All crypto is client-side (MLS for groups, Double Ratchet fallback for legacy 1:1, XChaCha20-Poly1305 AEAD). |
| **Invite-only enrollment** | No public discovery. Every device requires an explicit owner-generated invite and manual approval. |
| **Device-bound identity** | Ed25519 keypairs generated locally. Private keys never leave the device. |
| **Tenant isolation** | Row-Level Security on every PostgreSQL table. Every query scoped to `tenant_id`. |
| **Forward secrecy** | MLS epoch secrets and Double Ratchet message keys deleted after use. Compromise of current keys does not expose past messages. |
| **Immediate revocation** | Device revocation closes WebSocket connections and blocks all further authentication. |
## High-Value Assets
These are the assets an attacker would target, ranked by impact:
| Asset | Storage Location | Protection |
| ----------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Message plaintext** | Client memory only (never stored server-side) | E2E encryption; server stores only BYTEA ciphertext |
| **Device private keys** | Client secure storage (SecureStore / IndexedDB / encrypted JSON) | Generated locally; never transmitted |
| **MLS/Ratchet state** | Client storage | MLS epoch secrets, chain keys, root keys, DH ratchet keys exist only on client devices |
| Asset | Storage Location | Protection |
| -------------------- | ------------------------------ | ------------------------------------------------------------- |
| **Membership graph** | PostgreSQL (tenant-scoped) | RLS policies prevent cross-tenant enumeration |
| **Invite tokens** | PostgreSQL (BLAKE2b hash only) | Raw tokens never stored; single-use, 10-minute expiry |
| **Session metadata** | PostgreSQL + Redis | Tenant-scoped; reveals communication patterns but not content |
| Asset | Storage Location | Protection |
| ----------------------- | ----------------------- | ------------------------------------------------------------ |
| **Public keys** | PostgreSQL | By definition, public. Cannot derive private keys. |
| **Device fingerprints** | PostgreSQL | BLAKE2b hash of public key; not sensitive |
| **Connection metadata** | Server logs, Cloudflare | IP addresses, timestamps; standard for any networked service |
## Threat Actors
### External Attacker
**Capability:** Network access, public endpoint probing, credential stuffing.
| Attack Vector | Mitigation |
| ---------------------- | ------------------------------------------------------------------------------- |
| Brute-force enrollment | Rate limiting: 5 attempts per IP per 10 minutes |
| API enumeration | Generic error messages on all auth/enrollment failures (no information leakage) |
| SQL injection | Parameterized queries via SQLAlchemy ORM; no raw string interpolation |
| WebSocket hijacking | JWT authentication on connection; TLS transport |
### Malicious Tenant Member
**Capability:** Valid authentication within their tenant.
| Attack Vector | Mitigation |
| ------------------------ | ------------------------------------------------------------------- |
| Cross-tenant data access | RLS policies enforce `tenant_id` scoping at the database level |
| Privilege escalation | RBAC with 4-tier role hierarchy (Owner Admin, Admin, Member, Agent) |
| Message forgery | Ed25519 header signatures verify sender identity |
| Device impersonation | Device fingerprint verification during enrollment |
### Compromised Device
**Capability:** Full access to one device's keys and state.
| Attack Vector | Mitigation |
| --------------------------- | ---------------------------------------------------------------- |
| Decrypt historical messages | Forward secrecy -- old message keys are deleted after decryption |
| Impersonate the device | Device revocation immediately terminates all sessions |
| Pivot to other tenants | Device keys are tenant-scoped; no cross-tenant key material |
| Continue after revocation | WebSocket closed on revocation; all API calls return 403 |
### Rogue Administrator
**Capability:** Tenant admin privileges (invite, approve, revoke devices).
| Attack Vector | Mitigation |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| Read existing messages | Cannot -- admin has no access to other devices' private keys |
| Enroll a surveillance device | Requires physical/logical access to place the device; all members see new devices in the dashboard |
| Revoke legitimate devices | Audit trail of admin actions; re-enrollment restores access |
| Modify server-side data | RLS prevents cross-tenant; ciphertext modification detected by AEAD integrity check |
### Backend Breach
**Capability:** Full database access and/or server code control.
This is the scenario AgentVault is specifically architected to survive. A full backend compromise exposes only ciphertext, public keys, and metadata. No message content can be recovered.
| Attack Vector | Mitigation |
| ------------------------- | ------------------------------------------------------------------------ |
| Read message content | Impossible -- only BYTEA ciphertext stored; no private keys on server |
| Derive encryption keys | Impossible -- keys exist only on client devices |
| Use stored invite tokens | Impossible -- only BLAKE2b hashes stored; raw tokens are one-time-use |
| Inject malicious messages | Detected -- Ed25519 signatures on message headers verify sender identity |
| Modify ciphertext | Detected -- Poly1305 authentication tag fails on tampered ciphertext |
### Network Attacker (MITM)
**Capability:** Intercept and modify network traffic.
| Attack Vector | Mitigation |
| -------------------------- | --------------------------------------------------------- |
| Eavesdrop on traffic | Two layers: TLS (Cloudflare) + E2E (XChaCha20-Poly1305) |
| Modify messages in transit | TLS integrity + Poly1305 AEAD + Ed25519 signatures |
| Replay messages | Message numbering in ratchet headers; duplicates detected |
| Downgrade attack | TLS 1.2+ enforced by Cloudflare; no fallback |
## Key Threat Scenarios
### 1. Backend Database Breach
```
Attacker gains full read access to PostgreSQL.
What they find:
- messages.ciphertext (BYTEA) -- random-looking bytes
- messages.header_blob (BYTEA) -- encrypted headers
- devices.identity_public_key (BYTEA) -- public keys only
- invites.token_hash (BYTEA) -- irreversible BLAKE2b hashes
What they can do with it:
Nothing. No private keys. No plaintext. No usable tokens.
```
**Mitigation:** Ciphertext-only storage. No server-side keys. BYTEA columns for all cryptographic material.
### 2. Compromised Agent Device
```
Attacker gains control of an agent's host machine.
Immediate impact:
- Can read current and future messages for that agent
- Can send messages as that agent
Cannot:
- Access other tenants' data
- Read messages sent before the compromise (forward secrecy)
- Survive device revocation
```
**Mitigation:** Owner revokes the device, which immediately closes WebSocket connections and returns 403 on all API calls. Owner re-enrolls with a new invite. New X3DH key agreement establishes fresh keys.
### 3. RLS Misconfiguration
```
A code change accidentally omits tenant_id from a query.
Impact:
- Could expose data across tenants
```
**Mitigation:** RLS is enforced at the database level, independent of application code. Even a query that omits `tenant_id` in its WHERE clause is filtered by the RLS policy. The `app.current_tenant_id` session variable is set by middleware on every request.
### 4. Enrollment Social Engineering
```
Attacker convinces an owner to approve a malicious device.
Impact:
- Attacker's device joins the tenant with valid keys
- Can send/receive messages in conversations it's added to
```
**Mitigation:** Device fingerprint verification during approval. Fingerprints are displayed as hex-encoded BLAKE2b hashes that the owner compares against the agent's console output. Short-lived invites (10-minute expiry) limit the attack window. Single-use tokens prevent reuse.
## Rate Limits
| Endpoint | Limit | Purpose |
| ---------------------------------- | ----------------------- | ------------------------------ |
| `POST /enroll` | 5 per IP per 10 minutes | Prevent enrollment brute-force |
| `GET /devices/:id/status` | 1 per 5 seconds | Prevent polling abuse |
| `POST /conversations/:id/messages` | 60 per minute | Prevent message flooding |
| WebSocket connections | 1 per device | Prevent connection flooding |
## Non-Goals
Being explicit about what AgentVault does **not** protect against is a deliberate security practice. Overstating security claims erodes trust; honest limitations build it.
| Non-Goal | Rationale |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Fully compromised host OS** | An attacker with root on the owner's device or agent host can extract keys from memory. This is true of all software-based encryption. Hardware security modules (HSMs) are a future enhancement. |
| **Screenshot / screen recording prevention** | Once plaintext is displayed on screen, it is outside the encryption boundary. DRM-style protections are unreliable and platform-specific. |
| **Nation-state traffic obfuscation** | Traffic analysis (who communicates with whom, when, and how much) is visible at the network level. Onion routing or mixnets would be required to mitigate this -- out of scope for the current architecture. |
| **Metadata minimization** | The server necessarily knows message timestamps, conversation participants, and message sizes. Sealed sender (a la Signal) is a potential future enhancement. |
| **Post-quantum cryptography** | X25519 and Ed25519 are not quantum-resistant. Migration to ML-KEM/ML-DSA is planned but not yet implemented. |
## Security Validation Checklist
These properties are verified continuously:
* [ ] Only ciphertext exists in the `messages` table (no TEXT columns)
* [ ] Only ciphertext traverses the wire (WebSocket payloads are BYTEA)
* [ ] RLS blocks cross-tenant access (verified via integration tests)
* [ ] Expired and reused invite tokens are rejected
* [ ] Revoked devices receive 403 on all endpoints
* [ ] No key material appears in server logs
* [ ] Rate limits enforce enrollment and messaging boundaries
* [ ] `npm audit` and `pip audit` show no critical vulnerabilities