Security architecture
What is encrypted, where, and with which keys.
This is a readable technical overview of Polymorph’s current security
boundaries. It follows content from the device that creates it, through
Polymorph’s services, to the devices authorized to open it.
Implementation overview · Last reviewed
18 August 2026
The central boundary
Content keys stay with authorized devices.
Polymorph services authenticate devices, enforce membership and roles,
route messages, account for storage, and retain encrypted state. The
sensitive content itself is encrypted before those services receive it.
Sender Your device Creates content and encrypts it locally
Encrypted content →
Service boundary Polymorph Authorizes, routes, synchronizes, and stores ciphertext
Encrypted content →
Recipient Authorized device Authenticates and decrypts the content locally
Production API calls use HTTPS and realtime connections use WSS, both
protected by TLS. Encrypted WebRTC transport protects live media while
it is moving. These transport layers complement end-to-end and
client-side encryption; they do not replace it.
Content paths
Different content uses different key scopes.
The right encryption boundary depends on who needs access and how that
access changes. Conversation membership, personal account access, a
shared Space, and a live call are separate cryptographic contexts.
01 Conversations and collaborative tools
Messages, edits, reactions, polls, shared plans, call control, and profile projections
Protection
Direct and group conversations use the IETF Messaging Layer
Security protocol through OpenMLS. Application content is
encrypted for the devices in the current conversation epoch.
Membership changes advance that cryptographic state.
MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519 Service visibility
Polymorph routes ciphertext and enforces conversation and device
membership. Delivery destinations, group and device identifiers,
message size, timing, and protocol capability data remain visible;
the application body does not.
02 Attachments and Personal Files
Uploaded files, shared media, thumbnails, previews, and personal cloud content
Protection
New assets are encrypted on the client with AES-256-GCM using a
random 256-bit per-asset key and 96-bit nonce. Thumbnails use
their own keys. Decryption metadata is protected inside the
relevant account, Space, or MLS-encrypted scope.
AES-256-GCM · random key per asset · SHA-256 integrity Service visibility
Object identifiers, encrypted payload size, transfer timing,
format/version metadata, quota use, access grants, and reference
lifecycle remain visible. File and thumbnail plaintext does not.
03 Shared Spaces
Space names, folders, file metadata, shared files, and encrypted thumbnails
Protection
Each Space has versioned 256-bit key epochs. Space metadata and
per-asset decryption material are encrypted in that scope.
Authorized devices receive Space keys through device-specific
X25519 and AES-256-GCM grants. Access changes rotate the active
key epoch for future state.
AES-256-GCM · X25519 device grants · versioned key epochs Service visibility
The server remains authoritative for Space membership, roles,
ownership, quotas, object references, and deletion eligibility.
Those controls prevent a modified client from granting itself
access, but do not give the server the Space content keys.
04 Private account state
History, notes, lists, Clipboard data, settings, Circles, profile data, and backups
Protection
Account-scoped state is protected with AES-256-GCM. The account
data key is derived locally from the user key and secret passkey
using Argon2id, or transferred from a trusted device through an
encrypted device-link flow.
Argon2id → 256-bit account key → AES-256-GCM Service visibility
Synchronization cursors, encrypted record versions and sizes,
device state, and update timing remain operationally visible.
The account key and synchronized plaintext are not sent to the
server.
05 Voice, video, and screen sharing
Direct WebRTC calls and calls routed through Polymorph’s SFU infrastructure
Protection
Direct calls use WebRTC’s encrypted DTLS-SRTP media transport;
a TURN relay can forward those packets without reading the media.
SFU calls add LiveKit frame encryption initialized from a random
32-byte call key delivered inside MLS-encrypted signalling.
WebRTC DTLS-SRTP · LiveKit AES-GCM frame encryption Service visibility
Call and room membership, connection state, IP and relay data,
timing, traffic volume, and media-routing metadata remain visible.
Relays and the SFU do not receive the key needed to open media
frames.
06 Notifications
Message wakes, call alerts, and user-controlled lock-screen previews
Protection
Push notifications are not the source of message history. The app
retrieves durable encrypted state through its authenticated
mailbox. iOS preview delivery uses a separate per-device encrypted
preview channel, while lock-screen presentation follows the
user’s preview policy.
Service visibility
Apple, Google, and the operating system necessarily receive the
routing, device, timing, and presentation data required to deliver
a notification. Preview choices determine what may appear on a
locked screen.
07 API and realtime transport
Authenticated API requests, uploads, downloads, and realtime connections
Protection
Production clients connect through HTTPS and secure WebSockets
over TLS. TLS authenticates the service endpoint and protects
requests, responses, and ciphertext from network intermediaries
while they travel between a device and Polymorph.
HTTPS · WSS · TLS Service visibility
TLS terminates at the service endpoint, so it protects data in
transit but does not by itself hide content from Polymorph.
End-to-end and client-side encryption provide that separate
content boundary.
Keys and devices
Keys follow the boundary they protect.
Account access A passkey is transformed locally.
Polymorph uses separate Argon2id derivations for authentication and
the account data key. The raw passkey is not sent to the service.
Current parameters are 64 MiB of memory, three iterations,
parallelism of one, and a 32-byte result.
Device linking An existing device transfers authority securely.
The new and trusted devices establish an X25519 shared secret. An
HKDF-SHA-256-derived key protects the bootstrap payload with
AES-256-GCM. That payload carries the account data key and the new
device’s session directly to the intended device.
Conversation membership Every installation is its own MLS client.
Devices publish signed key packages and join conversation epochs as
distinct cryptographic participants. Adds, removals, updates, and
recovery advance or rebuild MLS state instead of sharing one static
conversation password forever.
Asset isolation A file key is not an account-wide file password.
Each new asset receives fresh key material. Moving a file between
Personal Files and a Space—or between Spaces—copies and re-encrypts
it for the destination scope rather than reusing the previous
encryption context.
Current algorithm inventory
The exact building blocks.
| Purpose | Current primitive | Where it is used |
| API and realtime transport | TLS | HTTPS API requests and WSS realtime connections |
| Conversation key agreement | X25519 | MLS key encapsulation and device-scoped key exchange |
| Conversation key schedule | HKDF-SHA-256 | MLS epochs and secret derivation |
| Conversation content | AES-128-GCM | MLS application messages |
| Device signatures | Ed25519 | MLS credentials and authenticated device context |
| Account and object encryption | AES-256-GCM | Account state, Files, attachments, thumbnails, Space state, and device links |
| Passkey derivation | Argon2id | Authentication verifier and account data key |
| Device linking | X25519 + HKDF-SHA-256 | Deriving the AES-256-GCM bootstrap key |
| File verification | SHA-256 | Detecting unexpected file-content changes after decryption |
| LiveKit media frames | AES-GCM | End-to-end frame encryption for SFU-routed calls |
SHA-256 hashes provide integrity checks and stable content identifiers;
they are not used as a substitute for encryption.
The service boundary
What the server knows—and what it does not.
Operationally visible
- Account handles, account identifiers, randomized device identifiers, and active sessions
- Conversation and Space membership, roles, and ownership
- Delivery destinations, synchronization state, size, and timing
- Storage quotas, object references, grants, and deletion eligibility
- Connection addresses, call-room state, traffic volume, and relay use
- Push tokens and the routing data required by notification providers
Not available as plaintext
- Messages and structured conversation content
- Attachment, Personal File, Space, and thumbnail contents
- Private notes, lists, Clipboard content, Circles, and account backups
- Full private profile data and recipient-scoped profile projections
- Account data keys, per-asset keys, Space keys, and call frame keys
- The raw account passkey
Visibility is not the same as retention. This list
describes information that necessarily reaches the service and could
technically be recorded. Polymorph does not treat that visibility as
permission to build a permanent activity history. Encrypted mailbox
entries are deleted when the receiving device acknowledges them, and
other temporary routing and operational records expire or are removed
after they are no longer needed. Account, membership, session, quota,
and storage records remain where they are required to keep the service
and its security controls working.
Limits
Encryption protects a boundary, not every possible risk.
An unlocked authorized device can read the content available to it.
Malware, a compromised operating system, or somebody with control of
that device may therefore reach decrypted information or keys.
A recipient can copy, photograph, record, or redistribute what they
receive. View-once and capture controls reduce common accidental
paths; they cannot make a malicious recipient trustworthy.
Encryption does not hide every connection. Services, networks, TURN
relays, SFUs, push providers, and operating systems can observe parts
of the routing, timing, address, size, and traffic pattern.
Removing a member or retiring a device blocks future authority and
advances relevant key state. It cannot erase plaintext or copies that
an authorized endpoint already obtained earlier.
End-to-end encryption protects confidentiality and integrity. It does
not by itself guarantee availability, prevent service disruption, or
replace server-side authorization and abuse controls.
Recovery material is equivalent to account authority. Users must keep
it private: anybody who obtains valid recovery material may be able to
restore access as an authorized endpoint.
Standards and implementations
Further technical reading.
