End-to-end encryption

e2e encrypts messages and records on people's devices with keys only they hold, so your server stores ciphertext it cannot read. Groups use MLS. Reach for it for a private chat or notes.

e2e:
  driver: mls
  suite: classic
  recovery: passkey
  fields:
    notes: [title, body]
  accept: []

import { configureE2e, e2e, toWire } from "mainsdk/experimental/e2e";
import { localE2eDriver, memoryE2eRelay } from "@mainsdk/testing";

const relay = memoryE2eRelay();                                    // the server side; development only, with the local driver (a fake)
await configureE2e({ self: "bob", driver: localE2eDriver, relay }).join();    // bob's device publishes its key package
configureE2e({ self: "alice", driver: localE2eDriver, relay });
const group = await e2e.group.create({ members: ["bob"] });        // keys stay on the devices
const sealed = await e2e.encrypt(group.id, "meet at six");         // the server stores ciphertext only
const note = toWire(sealed);                                       // a string that starts e2e1., safe in a column

e2e:
  driver: mls

Quick start

e2e:
  driver: mls          # @mainsdk/e2e-mls; local is the development fake
  suite: classic
  recovery: passkey
  fields:
    notes: [title, body]   # encrypted end to end: search, moderation and analytics skip these

import { configureE2e, e2e, toWire } from "mainsdk/experimental/e2e";
import { localE2eDriver, memoryE2eRelay } from "@mainsdk/testing";

const relay = memoryE2eRelay();   // the server side; in your app it is a few routes of your own server
await configureE2e({ self: "bob", driver: localE2eDriver, relay }).join();   // bob's device publishes its key package
configureE2e({ self: "alice", driver: localE2eDriver, relay });

const group = await e2e.group.create({ members: ["bob"] });   // keys stay on the devices
const sealed = await e2e.encrypt(group.id, "meet at six");     // the server stores ciphertext only
const note = toWire(sealed);                                   // a string that starts e2e1., safe in a column

Configuration

What you get

• Private keys never leave the device.
• The server stores and relays ciphertext only.
• Adding or removing a member changes the epoch, and a removed member can't read anything new.
• Group membership changes are signed and audited.
• Recovery uses the passkey PRF extension, with nothing the server can read.

Adding or removing a member moves the group to a new epoch with fresh keys, and a removed member can't read anything new. A person who loses every device gets their keys back with their passkey.

Calls

Examples

Remove a member

import { createE2e } from "mainsdk/experimental/e2e";
import { localE2eDriver, memoryE2eRelay } from "@mainsdk/testing";

const relay = memoryE2eRelay();
const alice = createE2e({ self: "alice", driver: localE2eDriver, relay });
const bob = createE2e({ self: "bob", driver: localE2eDriver, relay });
const carol = createE2e({ self: "carol", driver: localE2eDriver, relay });
await bob.join();
await carol.join();

const group = await alice.group.create({ members: ["bob", "carol"] });
await alice.group.remove(group.id, "carol");          // epoch 1: carol gets nothing new
const sealed = await alice.encrypt(group.id, "carol is out");
await bob.decrypt(group.id, sealed);                   // bob reads it
await carol.decrypt(group.id, sealed).catch((e) => e.code);   // MAIN-E2E-0004

Recover on a new phone

The app asks the passkey for its PRF output with WebAuthn and passes a function that returns it.

import { createE2e, type PrfSource } from "mainsdk/experimental/e2e";
import { localE2eDriver, memoryE2eRelay } from "@mainsdk/testing";

// In the browser: navigator.credentials.get({ publicKey: { ..., extensions: { prf: { eval: { first: salt } } } } })
declare const prf: PrfSource;

const relay = memoryE2eRelay();
const oldPhone = createE2e({ self: "bob", driver: localE2eDriver, relay });
await oldPhone.join();
await oldPhone.recovery.enrol(prf);                   // keys, encrypted under the passkey's PRF output

const newPhone = createE2e({ self: "bob", driver: localE2eDriver, relay });
await newPhone.recovery.restore(prf);                 // same passkey, same keys

What the server can't do

A field encrypted end to end is a string that starts e2e1.. The server holds no key, so:

• Search does not index it.
• Moderation does not send it to a classifier. A recipient who holds the key files a report instead.
• Analytics does not record it as a prop.

mainsdk check names this trade-off for each field in e2e.fields that a search index, moderate or an analytics event would read (MAIN-E2E-0008). Keep the field out of that feature, or add the feature to e2e.accept once you accept it.

Errors and checks

Swapping drivers

Testing

Use localE2eDriver and memoryE2eRelay from @mainsdk/testing. The relay records every byte it is given as relay.seen, so a test can prove no plaintext reached the server. No network is used.

Your relay

Your relay must keep one global order (a seq) across a group's handshake messages. Members apply the first valid commit for an epoch in that order; a member whose commit lost applies the winner's and retries, up to three times, then fails with MAIN-E2E-0012. A relay that reorders handshakes can fork a group.

Security and privacy

• The mls driver keeps each past epoch's secret so old messages decrypt (retain, default all). Inside a retained epoch there is no forward secrecy. Removed members are still locked out of later epochs.
• The mls driver keeps the plaintext of every record it sealed or opened in its state, so a record can be read again (MLS message keys work once). Set keepRecords: false to turn it off, and then a second decrypt of the same record fails. The cache sits in device state, protected only by the passkey recovery blob when exported, and it grows without bound. This is awaiting the owner's sign-off.
• After you restore state on a new device, the first seal, add or remove rotates the member's keys.
• The contract epoch is the MLS epoch minus one: a new group is epoch 0.
• The driver does not yet build external commits, PSK, ReInit, X.509 credentials, more than one device per member or key transparency; those refuse with MAIN-E2E-0010.
• The driver's state is exported and imported by the driver; your app provides the store.

• The local driver is not MLS: no TreeKEM, no credentials (key packages are trusted on first use) and no per-message forward secrecy inside an epoch. Never use it for real data.
• The server still sees who is in a group and when messages are sent.
• A removed member keeps what they already read; end-to-end encryption can't unsend it.
• Key handling for the rest of the app is described in Keys, and general cryptography in Crypto.

FAQ

Can I use it in production? Not yet. The MLS driver is built and tested against the official vectors, but it stays production: false until an external audit signs off, and check refuses both drivers in production. The gap is recorded as debt in spec e2e.

Is it post-quantum safe? No. A hybrid post-quantum suite comes only once the post-quantum spec is in place.

Next

• Encrypt end to end
• Keys
• Crypto