vault

Messaging

End-to-end encrypted messaging

This document describes the multi-device E2EE model, delivery/read receipts, and retention behavior.

Back to docs

1. Key hierarchy

  • Identity keys: each user has a long-lived keypair.
  • Device keys: each device has its own keypair, registered with the server.
  • Message keys: per-message symmetric keys are wrapped for each recipient device.

2. Send flow

  1. Client generates a random message key.
  2. Message content is encrypted with the message key.
  3. The message key is sealed for each recipient and sender device.
  4. Server stores ciphertext + wrapped keys only.

3. Receipts

  • Delivered: device has received and decrypted the message.
  • Read: message is visible in the conversation view.

4. Retention

Messages and receipts are deleted after the retention window configured by MESSAGE_RETENTION_DAYS. Default is 90 days.

5. Polling to WS upgrade

Clients poll /api/messages/events for message and receipt events. This endpoint is designed to be upgraded to WebSocket or SSE without changing event payloads.

6. Admin user directory

Admins can query users via /api/users?query=. The API is rate-limited by default and returns only minimal identity fields needed for outreach.