Sealed Storage Spec
This document specifies how Trioditis encrypts stored content so the server can encrypt incoming data to a member without ever being able to decrypt what it stored.
Both the TypeScript implementation (packages/crypto) and the Go implementation (apps/bridge-host/internal/seal) implement this contract and cross-verify against shared test vectors in packages/crypto/testdata/vectors.json and vectors-go.json.
Why per-object content keys?
Section titled “Why per-object content keys?”Instead of per-chat symmetric keys (which the bridge host would have to hold in plaintext to encrypt incoming messages—letting the server read the whole chat), every sealed object receives a fresh 32-byte random content key. Only that content key is sealed to each recipient’s X25519 public key, and the bridge host discards the content key immediately afterward.
| Key | Algorithm / Size | Held by |
|---|---|---|
| Identity key pair | X25519 | Each member; private key exists only on their devices (wrapped by password, recovery key, or passkey) |
| Agent-access key pair | X25519 | The server (allows the MCP server to decrypt chats explicitly granted to an agent) |
| Bridge key pair | X25519 | The bridge host (clients seal outbound sends and login credentials to its public key) |
| Content key | 32 random bytes | Discarded immediately after sealing |
A key ID (kid) is the first 16 bytes of BLAKE2b-256(publicKey), encoded as unpadded base64url.
Envelope v1
Section titled “Envelope v1”{ "v": 1, "nonce": "<24 bytes, base64url>", "ct": "<ciphertext + 16-byte tag, base64url>", "keys": [{ "kid": "<key ID>", "sk": "<sealed content key, base64url>" }]}- Cipher:
XChaCha20-Poly1305(IETF) using the 32-byte content key, a random 24-byte nonce, and the associated data below. Plaintext is UTF-8 JSON. - Key wrapping: Each recipient entry seals the content key using libsodium
crypto_box_seal(X25519 + XSalsa20-Poly1305, anonymous sender). Go uses the compatiblegolang.org/x/crypto/nacl/box.SealAnonymous. - Associated data (AAD):
trioditis/v1/<kind>/<ownerUserId>/<objectId>as UTF-8 bytes. This cryptographically binds each ciphertext to its exact row so ciphertexts cannot be transplanted between rows or accounts. - Encoding: Unpadded base64url for all binary fields.
Object kinds and IDs
Section titled “Object kinds and IDs”| Object | kind |
objectId |
|---|---|---|
| Incoming or echoed message | message |
eventId |
| Message edit | message |
The edit’s own eventId |
| Pending copy of a send | message |
clientMessageId |
| Chat metadata | chat |
portalId |
| Contact profile | contact |
ghostId |
Outbound send or edit command |
outbound |
clientMessageId |
| Login step input | outbound |
<loginSessionId>/<stepId> |
| Media attachment | media |
mediaId |
| Label (name & color) | label |
labelKey |
Recipient matrix
Section titled “Recipient matrix”| Object | Sealed to |
|---|---|
| Incoming message, chat metadata, contact profile | Owner’s identity key (+ agent-access key if chat is granted to an agent) |
| Member’s own stored copy of a sent message | Same as above |
Outbound send or login input (outbound) |
Bridge key only |
| Draft or label | Owner’s identity key only |
Granting an agent access to history: The member’s device unseals each message’s content key and re-seals it to the agent-access public key, appending an entry to keys without re-encrypting the message body. New messages include the agent-access key automatically. Revoking a grant strips those keys entries.
Media encryption
Section titled “Media encryption”Each attachment is encrypted as a single XChaCha20-Poly1305 blob (chunked streaming encryption is planned behind an envelope version bump) with its own random key, nonce, and AAD trioditis/v1/media/<ownerUserId>/<mediaId>. The file’s key and nonce travel exclusively inside the sealed message plaintext—never stored beside the encrypted blob.
Message plaintext schema (v1)
Section titled “Message plaintext schema (v1)”{ "type": "text | notice | emote | image | video | audio | file | sticker | location", "body": "plain text", "html": "optional formatted body, sanitized on render", "attachments": [ { "mediaId": "...", "mime": "image/jpeg", "size": 12345, "name": "photo.jpg", "key": "<base64url>", "nonce": "<base64url>", "width": 800, "height": 600, "durationMs": 0 } ], "mentions": ["<contact id>"], "truncated": true}truncatedis set only when the bridge host had to trim an oversized message to stay within the 256 KiB sealed envelope limit (htmldropped first, thenbodycut on a UTF-8 character boundary).- Chat and contact metadata carry their avatar in an
avatarattachment field. If an avatar hasn’t changed and its temporary upload expired, the metadata setsavatarUnchanged: trueso clients keep their cached copy. - A group’s collage (the members whose pictures make its picture when it has none) is sealed apart from its metadata in a
chatCollageevent: kindchat, object ID<portalId>/collage, plaintext{"ghosts": [...]}, to the person only. Apart, because bridgev2 changes a chat’s name, picture and members in one go and saves the chat after, so describing the chat again for its members could send a name or picture being replaced. It names up to four opaque ghost IDs, never the person’s, those with a picture first, in a fixed order. Clients draw each from that contact’s profile, so a member’s new picture needs no new collage. The bridge host chooses again on joins and leaves, when a member’s picture is set or removed, and at each start, and sends it only when the choice changed (the last one sent is kept as opaque IDs intrioditis_collage). - Readers preserve unknown fields so future writers can extend schemas cleanly.
Bridge key exposure & payload lifetimes
Section titled “Bridge key exposure & payload lifetimes”Payloads sealed to the bridge key (outboxPayloads) can be opened by anyone holding both the ciphertext and BRIDGE_PRIVATE_KEY. To minimize exposure:
- Separated from backups:
deploy/trioditis backupomitsBRIDGE_PRIVATE_KEYandAGENT_ACCESS_PRIVATE_KEYfromsecrets.env; keys are exported separately viadeploy/trioditis keys export. - Ephemeral retention: The backend deletes each
outboxPayloadsrow as soon as the bridge host accepts or rejects the command, or automatically via a scheduled deadline job atnotAfter(24 hours for sends, 10 minutes for login credentials). Once executed, the bridge host retains only IDs and status. - Scheduled sends (accepted exception): A scheduled message’s bridge-sealed copy (
scheduledPayloads, up to 365 days ahead) stays stored untilsendAt,scheduled.sendNow, cancellation, or chat deletion so scheduled messages dispatch on time even when all of your devices are offline.
Connector plaintext at rest
Section titled “Connector plaintext at rest”While the bridge host’s own tables and journal never store plaintext content, upstream bridgev2 connectors keep operational state in the shared PostgreSQL database:
portal,ghost, anduser_logintables (chat names, contact names, phone numbers)whatsapp_history_sync_message(raw WhatsApp history batches until imported and deleted)whatsmeow_event_buffer(decrypted incoming WhatsApp protobufs kept briefly so a crash mid-handler doesn’t lose a single-decryption Signal message; cleared once handled or swept after 14 days byinternal/wabuffer)
For this reason, Trioditis requires encrypted disk storage and encrypted backups for the server (see Encryption at rest). Server-key sealing of these connector columns is planned for Phase 1.