Introducing Firefly: The Engine Behind Lupyd's Encryption

Imagine sending a message that not even the company delivering it can read. Imagine a group where every role, every permission, and every structural change is cryptographically enforced—not by a server's mercy, but by mathematical proof. Imagine a protocol so precise that a single tampered byte causes the entire message to be rejected before it ever reaches a screen.

This isn't a thought experiment. This is Firefly—Lupyd's encrypted messaging engine, built from the ground up in Rust, powered by the Messaging Layer Security (MLS) protocol, and designed to operate as a zero-knowledge blind relay that never sees, stores, or processes the content it carries.

What Is Firefly?

Firefly is the cryptographic backbone of every conversation on Lupyd. It handles direct messages, group communications, real-time WebSocket connections, key management, credential signing, and encrypted group state transitions—all through a high-performance server built on Hyper and communicating almost entirely via Protocol Buffers.

But calling Firefly a "messaging server" undersells it dramatically. Traditional servers read your messages to route them, index them, moderate them, and monetize them. Firefly does none of that. It is architecturally incapable of reading a single word you send. Every payload it handles is an opaque, encrypted blob—and it's designed to stay that way.

The MLS Protocol: Why It Matters

Most encrypted messengers use the Signal protocol for one-to-one chats, which works well for pairs. But groups are a different challenge entirely. When a group has 50 members, traditional E2EE requires managing pairwise keys between every participant—an approach that scales poorly and creates security gaps when members join or leave.

MLS solves this with a tree-based key agreement structure. Instead of pairwise keys, all group members share a cryptographic tree where each leaf represents a member. Key material derives from tree paths, meaning:

• Adding a member requires only a single "Welcome" message and a commit to the group state—not re-encrypting for every existing member.
• Removing a member instantly invalidates their position in the tree. They lose access to all future messages mathematically, not just by policy.
• Forward secrecy is automatic. Every commit rotates the group's cryptographic epoch. Even if a key is compromised in the future, past messages remain permanently sealed.

Firefly implements MLS through mls-rs with the RustCrypto provider, using production-grade ciphersuites that handle signature key generation, credential verification, and epoch-based key rotation without any plaintext ever touching the server.

Zero-Knowledge Architecture: The Server Sees Nothing

This is the part that changes everything about how you think about messaging infrastructure.

When you send a message through Firefly, your device encrypts the content using the group's current epoch key. What leaves your device is a GroupMessage containing an opaque binary blob—the MLS application message. The server receives this blob, checks the group ID and epoch number for routing purposes, and delivers it to other members via their WebSocket connections. At no point does the server decrypt, inspect, or even understand the content.

The server's role is that of a blind courier:

• It stores encrypted commits so devices that were offline can sync when they reconnect.
• It routes Welcome messages to invited members so they can join groups.
• It holds key packages—public cryptographic bundles that allow other users to initiate secure sessions—without ever possessing the private keys.
• It validates epoch sequences to prevent replay attacks, but only through numerical ordering—not by reading message contents.

The encryption keys are generated on your device, stored on your device, and never transmitted. Firefly's database contains nothing but ciphertext and routing metadata. A complete database breach would yield zero readable messages.

Credentials and Identity: Trust Without Exposure

Every user in Firefly operates through a FireflyIdentity—a structure containing a signature key pair and a signed credential. The credential is issued by calling the /sign endpoint, where your device generates a fresh signing key pair locally, sends only the public key to the server, and receives back a time-limited signed token (an AuthToken containing your username, device ID, address ID, and expiration).

This signed credential travels inside the MLS tree as part of your leaf node. When other group members process your messages, their devices verify your credential's signature against Firefly's public JWK set (available at /jwks.json). If the credential has expired or been tampered with, the message is rejected at the client level—the server never makes this decision.

Credentials are device-specific and time-bound. Each device gets its own identity, and the system enforces a maximum of five devices per user. When a credential expires, the user commits a leaf update with a refreshed credential—rotating their signing identity without disrupting the group.

Groups That Govern Themselves

Firefly groups are not just encrypted chat rooms. They are self-governing cryptographic structures with built-in roles, permissions, channels, and access control—all enforced at the protocol level through custom MLS proposals.

Every group carries a FireflyGroupExtension embedded in the MLS group context. This extension contains:

• Roles with granular permissions (manage members, manage channels, manage roles, and more).
• Members mapped to specific roles, with a default permission set for new joiners.
• Channels within the group, each with their own role-based permissions matrix.

When someone adds a member, changes a role, creates a channel, or modifies permissions, they submit a custom MLS proposal. Firefly's rule engine (FireflyMlsRules) validates every proposal against the committer's permissions before the commit is accepted. If a member without ManageMember permission tries to add someone, the commit is rejected by every client independently—not by the server. The governance is enforced by cryptographic consensus, not by a central authority.

This means even if someone compromises the server, they cannot alter group permissions, add unauthorized members, or escalate roles. The MLS tree state is verified independently by every member's device.

Real-Time Delivery: WebSockets That Never Sleep

Firefly maintains persistent WebSocket connections for real-time message delivery. When your device connects, it authenticates via JWT, specifies its device ID and address, and provides a last_synced_upto marker. The server streams any messages the device missed while offline—encrypted commits, welcome messages, group state updates—in the correct epoch order.

For devices that come online after extended periods, Firefly supports batch synchronization through the /group/sync and /group/commits endpoints, delivering paginated commit histories so the client can reconstruct the group's current state without missing a single cryptographic epoch transition.

The WebSocket layer also supports WebRTC signaling for encrypted voice and video calls, with TURN/STUN configuration served through the /webrtcConfig endpoint—keeping media streams peer-to-peer and out of the server's reach.

Built in Rust. Built to Last.

Firefly isn't written in a language chosen for developer convenience. It's written in Rust—a systems language that guarantees memory safety at compile time, eliminates entire categories of vulnerabilities (buffer overflows, use-after-free, data races), and delivers performance that matches C without the risk.

The server runs on Hyper with Tokio's async runtime, handling HTTP/1.1, HTTP/2, and WebSocket upgrades on a single listener. Protocol Buffers handle serialization—compact, strongly typed, and immune to the parsing ambiguities of JSON. The database uses connection pooling for concurrent access, and every endpoint enforces rate limiting and request timeouts to prevent abuse.

What This Means for You

• Your messages are yours. No one at Lupyd—not engineers, not executives, not anyone—can read them. The architecture makes it impossible, not just against policy.
• Your groups are self-sovereign. Permissions, roles, and channels are enforced by cryptographic rules that every member's device validates independently.
• Your identity is device-bound and time-limited. Credentials expire and rotate automatically. A compromised credential doesn't compromise your history.
• Multi-device works seamlessly. Up to five devices per account, each with its own cryptographic identity, all participating in the same encrypted group tree.
• Offline resilience is built in. Miss messages while your phone was off? Every encrypted commit is stored and replayed in order when you reconnect.

Firefly doesn't ask you to trust Lupyd with your data. It removes the need for trust entirely and replaces it with mathematics. That's the kind of infrastructure privacy deserves.