Building a Serverless, Post-Quantum Matrix Homeserver

Matrix serves as a leading platform for decentralized, end-to-end encrypted communication, utilized by government messaging systems, open-source communities, and privacy-focused organizations globally.

For individual developers, its appeal often lies in connecting disparate chat networks (such as Discord and Slack) into a unified inbox, or maintaining control over conversation history by hosting it on personal infrastructure. Matrix functions as a decentralized, eventually consistent state machine. Homeservers exchange signed JSON events via HTTP, employing a conflict resolution algorithm to combine these event streams into a coherent room history.

However, running a Matrix homeserver traditionally involves significant operational overhead. This includes provisioning virtual private servers (VPS), optimizing PostgreSQL for intensive write operations, managing Redis for caching, configuring reverse proxies, and handling TLS certificate rotations. It represents a stateful, resource-intensive system requiring ongoing time and financial investment, regardless of usage levels.

The goal was to explore whether this operational burden could be completely removed.

This proved achievable. This post details the process of porting a Matrix homeserver to Cloudflare Workers. The resulting proof of concept demonstrates a serverless architecture that eliminates operational tasks, reduces costs to near zero during idle periods, and secures every connection with post-quantum cryptography by default. The source code is available, allowing direct deployment of an instance from Github.

From Synapse to Workers

The project began with Synapse, the Python-based reference Matrix homeserver traditionally deployed with PostgreSQL for persistence, Redis for caching, and a filesystem for media.

Porting Synapse to Workers necessitated re-evaluating all conventional storage assumptions.

Storage presented a key challenge. Traditional homeservers rely on strong consistency provided by a central SQL database. Cloudflare Durable Objects provides a robust alternative, offering the strong consistency and atomicity essential for Matrix state resolution, while enabling the application to operate at the edge.

The core Matrix protocol logic, including event authorization, room state resolution, and cryptographic verification, was ported to TypeScript using the Hono framework. D1 now serves as the replacement for PostgreSQL, KV for Redis, R2 for the filesystem, and Durable Objects manage real-time coordination.

From monolith to serverless

Transitioning to Cloudflare Workers offers developers multiple benefits: simplified deployment, reduced costs, low latency, and integrated security.

Easy deployment: A conventional Matrix deployment necessitates server provisioning, PostgreSQL administration, Redis cluster management, TLS certificate renewal, load balancer configuration, monitoring infrastructure, and on-call rotations.

With Workers, deployment is streamlined to a single command: wrangler deploy. Workers automatically manages TLS, load balancing, DDoS protection, and global distribution.

Usage-based costs: Traditional homeservers incur expenses regardless of active use. Workers pricing is based on requests, meaning costs are incurred only during active usage and approach zero during idle periods.

Lower latency globally: A conventional Matrix homeserver located in us-east-1 can introduce over 200ms of latency for users in Asia or Europe. In contrast, Workers operate in over 300 locations globally. For instance, when a user in Tokyo sends a message, the Worker executes in Tokyo.

Built-in security: Matrix homeservers are often high-value targets due to their handling of encrypted communications, storage of message history, and user authentication. Traditional deployments demand meticulous hardening, including firewall configuration, rate limiting, DDoS mitigation, WAF rules, and IP reputation filtering.

Workers inherently provide these security features.

Post-quantum protection

Cloudflare implemented post-quantum hybrid key agreement for all TLS 1.3 connections in October 2022. Each connection to a Worker automatically negotiates X25519MLKEM768, a hybrid approach that combines classical X25519 with ML-KEM, the post-quantum algorithm standardized by NIST.

Classical cryptography depends on mathematical problems that are challenging for traditional computers but easily solvable by quantum computers utilizing Shor’s algorithm. ML-KEM, conversely, is founded on lattice problems that maintain their difficulty even for quantum computers. This hybrid strategy ensures that both algorithms must be compromised for a connection to be breached.

Following a message through the system

Understanding the points of encryption is crucial for security architecture. When a message is sent through this homeserver, the process unfolds as follows:

The sender’s client encrypts the plaintext message using Megolm, Matrix’s end-to-end encryption. This encrypted payload is then encapsulated within TLS for transport. On Cloudflare, the TLS connection employs X25519MLKEM768, providing quantum resistance.

The Worker terminates TLS, yet the data it receives remains encrypted as Megolm ciphertext. This ciphertext is stored in D1, indexed by room and timestamp, and then delivered to recipients. The plaintext message is never exposed to the homeserver. A message “Hello, world” exists solely on the sender’s and recipient’s devices.

Upon recipient synchronization, the process reverses. The recipient obtains the encrypted payload via another quantum-resistant TLS connection and then decrypts it locally using their Megolm session keys.

Two layers, independent protection

Protection is provided through two independent encryption layers:

The transport layer (TLS) secures data during transit. Encryption occurs at the client and decryption at the Cloudflare edge. With X25519MLKEM768, this layer achieves post-quantum security.

The application layer (Megolm E2EE) safeguards message content. Encryption happens on the sender’s device and decryption exclusively on recipient devices, utilizing classical Curve25519 cryptography.

Who sees what

Any Matrix homeserver operator, whether using Synapse on a VPS or this Workers implementation, has access to metadata such as existing rooms, participants, and message timestamps. However, no entity in the infrastructure chain can view message content, as the E2EE payload is encrypted on sender devices prior to network transmission. Cloudflare terminates TLS and forwards requests to the Worker, but both only encounter Megolm ciphertext. Media within encrypted rooms is client-side encrypted before upload, and private keys remain exclusively on user devices.

What traditional deployments would need

Implementing post-quantum TLS in a traditional Matrix deployment would involve upgrading OpenSSL or BoringSSL to a ML-KEM-compatible version, correctly configuring cipher suite preferences, testing client compatibility across all Matrix applications, monitoring for TLS negotiation failures, keeping up with evolving PQC standards, and gracefully managing clients that lack PQC support.

With Workers, this process is automatic. Chrome, Firefox, and Edge browsers all support X25519MLKEM768. Mobile applications leveraging platform TLS stacks inherently gain this support. The security posture automatically enhances as Cloudflare’s PQC deployment expands, requiring no manual intervention.

The storage architecture that made it work

A key insight from this porting effort was recognizing that various data types require distinct consistency guarantees. Each Cloudflare primitive is utilized for its optimal function.

D1 for the data model

D1 serves as the storage for all data requiring persistence across restarts and query support, including users, rooms, events, and device keys. This encompasses over 25 tables covering the complete Matrix data model.

CREATE TABLE events (
	event_id TEXT PRIMARY KEY,
	room_id TEXT NOT NULL,
	sender TEXT NOT NULL,
	event_type TEXT NOT NULL,
	state_key TEXT,
	content TEXT NOT NULL,
	origin_server_ts INTEGER NOT NULL,
	depth INTEGER NOT NULL
);

// Store OAuth code with 10-minute TTL
kv.put(&format!("oauth_code:{}", code), &token_data)?
	.expiration_ttl(600)
	.execute()
	.await?;

#[durable_object]
pub struct UserKeysObject {
	state: State,
	env: Env,
}

impl UserKeysObject {
	async fn claim_otk(&self, algorithm: &str) -> Result<Option<Key>> {
    	// Atomic within single DO - no race conditions possible
    	let mut keys: Vec<Key> = self.state.storage()
        	.get("one_time_keys")
        	.await
        	.ok()
        	.flatten()
        	.unwrap_or_default();

    	if let Some(idx) = keys.iter().position(|k| k.algorithm == algorithm) {
        	let key = keys.remove(idx);
        	self.state.storage().put("one_time_keys", &keys).await?;
        	return Ok(Some(key));
    	}
    	Ok(None)
	}
}

curl https://matrix.example.com/.well-known/openid-configuration
{
  "issuer": "https://matrix.example.com",
  "authorization_endpoint": "https://matrix.example.com/oauth/authorize",
  "token_endpoint": "https://matrix.example.com/oauth/token",
  "jwks_uri": "https://matrix.example.com/.well-known/jwks.json"
}