PolymorphSecurity architecture

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

Service boundary Polymorph Authorizes, routes, synchronizes, and stores ciphertext

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.

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.

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.

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.

Private account state

History, notes, lists, Clipboard data, settings, Personas, 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.

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.

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.

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, Personas, 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.

IETF RFC 8446 Transport Layer Security 1.3 IETF RFC 9420 Messaging Layer Security Implementation OpenMLS IETF RFC 9106 Argon2 NIST SP 800-38D GCM authenticated encryption Implementation LiveKit end-to-end encryption W3C Recommendation WebRTC