Skip to main content

​
Overview

AgentVault defines formal state machines for three core protocol flows: enrollment (device onboarding), 1:1 messaging (E2E encrypted owner-agent communication), and room lifecycle (multi-participant task rooms). These state machines govern all valid transitions and enforce security invariants at every step.
The server never sees plaintext. All encryption and decryption happens client-side. Protocol messages are opaque blobs to the server.

​
Enrollment

​
Invite Token States

Invite tokens are the entry point for device enrollment. Tokens are single-use, short-lived, and stored as BLAKE2b hashes (never raw).

​
Device Lifecycle States

Devices progress through a lifecycle from pending enrollment to active participation, with administrative controls for suspension and revocation. State rules:
Revoking a device triggers an immediate rekey of all rooms the device belonged to. The revoked device cannot decrypt any messages sent after revocation (forward secrecy).

​
Enrollment Protocol Flow

The full enrollment sequence from invite creation through device activation: Failure cases return generic error messages to prevent information leakage:

​
1:1 Messaging

​
Session Establishment

Before two devices can exchange messages, they must establish a shared session using the X3DH (Extended Triple Diffie-Hellman) key agreement protocol.
The owner must send the first message. The agent must not send until it has received at least one message from the owner (the activated flag). This ensures the Double Ratchet is properly initialized from the X3DH shared secret.

​
Message Send/Receive

Each message advances the Double Ratchet, deriving a unique message key for every message. Old keys are deleted after decryption (forward secrecy). Message fields uploaded to server:

​
Replay Protection

  • Each message includes a unique message number from the ratchet chain.
  • The recipient rejects duplicate sequence numbers.
  • A sliding window handles out-of-order delivery (skipped message keys are cached temporarily for later decryption).

​
Encryption Details

​
Room Lifecycle

Each task room is a multi-participant group with its own encryption state. MLS (RFC 9420) is the primary encryption protocol for rooms, providing scalable group key agreement with per-epoch forward secrecy. Double Ratchet remains as a fallback for legacy 1:1 sessions.

​
Room State Machine

​
Create Room

1

Initialize Group State

Admin device generates the initial encryption group state for the room.
2

Upload Encrypted State

Admin uploads the encrypted group state blob to the server.
3

Add Initial Members

Admin adds initial members. Each member’s device receives the key material needed to participate.
4

Members Sync

Members fetch the room state and initialize their local encryption context.

​
Add Member

Rules:
  • Only ACTIVE devices may receive room membership.
  • Existing connected members are notified via WebSocket broadcast.
  • The new member’s device subscribes to the room’s Redis pub/sub channels.

​
Remove Member / Device Revocation

Guarantees:
  • Forward secrecy preserved — removed devices cannot decrypt messages from the new epoch.
  • WebSocket connections are closed immediately on revocation.
  • All room memberships are stripped atomically.

​
Concurrency Handling

​
Simultaneous Admin Changes

When multiple admins issue conflicting changes (e.g., two membership changes at once), the server enforces ordering:
  • The first commit to reach the server is applied.
  • Conflicting operations must rebase against the new state and retry.

​
Message During Rekey

If a device attempts to send during an epoch transition:
  1. The send fails with an epoch mismatch error.
  2. The client fetches the latest group state.
  3. The client updates local encryption state.
  4. The client retries the send under the new epoch.

​
Error Recovery

  1. Fetch latest room state from server.
  2. Verify the commit chain integrity.
  3. Resynchronize local encryption state.
  1. Trigger full state resync from server.
  2. If verification fails, admin can perform a room reset (re-establishes all encryption state from scratch).
When the Double Ratchet falls out of sync between owner and agent:
  1. Delete the broken session from local storage.
  2. Clear the relevant key material.
  3. Re-establish via fresh X3DH key exchange.
  4. The device_linked event triggers a new conversation.

​
Security Enforcement Rules

These invariants hold across all protocol state machines:

Zero-Knowledge Server

Server never decrypts content. All protocol messages are opaque BYTEA blobs.

RLS Enforcement

PostgreSQL Row-Level Security enforces membership before read/write on every tenant-scoped table.

Mandatory Rekey

Device revocation triggers mandatory rekey of all affected rooms.

No Content in Push

Push notifications contain zero message content. Content is fetched client-side after notification.

​
Non-Goals

The protocol explicitly does not protect against:
  • Fully compromised operating systems (device-level compromise).
  • Screenshot or screen recording prevention.
  • Global traffic analysis or metadata obfuscation beyond what TLS provides.

​
Validation Checklist

For implementers verifying protocol compliance:
Enrollment tokens are single-use and expire within 10 minutes
Device fingerprint is verified by admin before approval
All encryption state is validated client-side before use
No plaintext columns exist in the database
All tenant-scoped tables have RLS policies enabled
Revocation automatically triggers rekey of all affected rooms
Owner sends first message in every 1:1 conversation
Old ratchet keys are deleted after decryption