How Glyph keeps your chats private.

Imagine passing a note across a noisy classroom. Many hands touch it on the way. You want two things: nobody reading it en route can understand it, and the person who gets it knows it truly came from you. Those goals — secrecy and authenticity — are the heart of cryptography.

Keys and locks

A key is just a very large secret number. A lock (an algorithm) uses that key to encrypt or decrypt a message. There are two families of locks:

        PUBLIC  /  PRIVATE  KEY  PAIR

  ┌──────────────┐                ┌──────────────┐
  │  PUBLIC KEY  │  ── give to ──▶ │  Anyone can  │
  │   (open)     │    everyone     │  LOCK to you │
  └──────────────┘                └──────────────┘
         │  (mathematically linked, one pair)
         ▼
  ┌──────────────┐
  │ PRIVATE KEY  │  ── keep secret, never share ──
  │   (yours)    │     only this UNLOCKS the box
  └──────────────┘

Three jobs cryptography does for Glyph

It all starts from a seed

When you sign up, your device generates a random 12-word seed phrase (the BIP-39 standard). Those words are your account. From that single seed, Glyph deterministically derives both key pairs — so the same words always rebuild the same keys on any device.

// A device identity: an Ed25519 signing key and an X25519 key-exchange key.export type Identity = {  signing: KeyPair // Ed25519 — proves authorship  dh: KeyPair      // X25519 — agrees on message keys} // Deterministically derive both keypairs from a BIP-39 seed.export function deriveIdentity(seed: Uint8Array): Identity {  const edSk = hkdf(sha256, seed, SALT, encodeUtf8("ed25519"), 32)  const dhSk = hkdf(sha256, seed, SALT, encodeUtf8("x25519"), 32)  return {    signing: { privateKey: edSk, publicKey: ed25519.getPublicKey(edSk) },    dh: { privateKey: dhSk, publicKey: x25519.getPublicKey(dhSk) },  }}

hkdf(...)is the "make many keys from one" tool, turning your seed into two distinct private keys. Public keys are safe to share; private keys never leave your device.

Logging in without a password

So how does the server know it's you, with no password? Your device signs a small challenge (your public key plus the time) with your private Ed25519 key. The server checks the signature with your public key, then hands back a short-lived ticket (a JWT) valid for one hour.

// Key-based auth. No email/phone: a client proves ownership of its// Ed25519 identity by signing a fresh challenge...ok = await verifyEd25519(sign_pub, signature, `${sign_pub}.${ts}`)if (!ok) return json({ error: "Bad signature" }, 401)// ...verified, so mint a short-lived (1 hour) ticket whose sub = users.idconst token = await mintJwt(user.id, sign_pub)

What "anonymous identity" really means

The two locked copies

Alice also needs to read her own sent message later (e.g. on another device). So Glyph makes two locked copies — one Bob can open, and one Alicecan open (a "self-copy"). Only ciphertext is stored.

const plaintext = encodeUtf8(params.text) // Encrypt-to-self so the sender can read their own message back.const senderCopy = sealMessage(plaintext, params.identity.dh.publicKey, params.identity) // The copy for the peer uses the Double Ratchet (a fresh key per message).const state = await initiatorRatchet(params.peer, params.identity)const msg = ratchetEncrypt(state, plaintext)envelope = { v: 2, x3dh: state.pendingX3dh, msg } await getSupabase().from("messages").insert({  sender_id: params.meId,  recipient_id: params.peer.id,  envelope,                // ciphertext for the peer  sender_copy: senderCopy, // ciphertext for me})

Inside the lockbox: sealMessage

A brand-new throwaway ephemeral key is made for this message, both sides derive the same secret with X25519, the text is encrypted with XChaCha20-Poly1305, and the whole thing is signedwith Alice's Ed25519 key so Bob can prove it's from her.

const ephSk = x25519.utils.randomSecretKey()         // fresh per messageconst ephPub = x25519.getPublicKey(ephSk)const shared = x25519.getSharedSecret(ephSk, recipientDhPublicKey)const key = deriveKey(shared, ephPub, recipientDhPublicKey) const nonce = randomBytes(24)const ct = xchacha20poly1305(key, nonce, sender.signing.publicKey).encrypt(plaintext)const sig = ed25519.sign(concatBytes(ephPub, nonce, ct), sender.signing.privateKey)

On the other end, Bob's device does the reverse — but checks the signature firstand refuses anything that doesn't verify:

if (!ed25519.verify(sig, concatBytes(ephPub, nonce, ct), from)) {  throw new Error("Bad signature: message is not from the claimed sender")}const shared = x25519.getSharedSecret(recipient.dh.privateKey, ephPub)const key = deriveKey(shared, ephPub, recipient.dh.publicKey)return xchacha20poly1305(key, nonce, from).decrypt(ct)

How it travels

The locked message sits in a database table. Bob's device keeps an open live connection (Supabase Realtime) that instantly notifies him when a new row is addressed to him — no refreshing needed.

Two ratchets working together

• The symmetric ratchet derives a fresh single-use key for each message, clicking forward each time.
• The Diffie-Hellman ratchet mixes in a brand-new X25519 key whenever the conversation changes direction. This gives post-compromise recovery: even after a brief key theft, the conversation "heals" once you exchange a couple of messages.

   THE  CHAIN  OF  ONE-TIME  KEYS  (cannot run backwards)

 root ─▶ Key#1 ─▶ Key#2 ─▶ Key#3 ─▶ Key#4 ─▶ ...
          │        │        │        │
          ▼        ▼        ▼        ▼
       "hi"     "how"    "are"    "you"
        🔒        🔒        🔒        🔒
                          ▲
            steal Key#3 ──┘  → CANNOT derive Key#1 or Key#2
                             → past messages stay locked

The first hello: X3DH

To start a ratchet, both devices need a shared starting secret — even if one person is offline. X3DH solves this: at sign-up your device uploads a bundle of public prekeys. Anyone who wants to message you grabs that bundle and sets up a session immediately, without you being online.

The file is encrypted in your browser's memory with a fresh random key, and only the ciphertext is uploaded. The key and nonce are returned to the caller — never saved to the server in plaintext.

export function sealBytes(data: Uint8Array): EncryptedBlob {  const key = randomBytes(32)  const nonce = randomBytes(24)  const ciphertext = xchacha20poly1305(key, nonce).encrypt(data)  return { ciphertext, key: toBase64(key), nonce: toBase64(nonce) }}

The upload stores only the ciphertext, then returns a descriptor — the storage path plus the key and nonce. That descriptor is what gets sealed inside the normal E2E message.

const sealed = sealBytes(bytes)              // encrypt the whole fileconst path = `media/${meId}/${crypto.randomUUID()}`await getStorage().upload(path, sealed.ciphertext) // only ciphertext leaves return {  kind: "media", path,  key: sealed.key, nonce: sealed.nonce, // the secret to open it — goes in the sealed message  name: file.name, mime: file.type, size: file.size,}

Each copy is a normal sealed message tagged with a shared group_id and a shared client_id. The client_idis the "same announcement" reference number, used later to collapse the many copies into one bubble.

const clientId = crypto.randomUUID()      // shared across all copiesconst others = params.members.filter((m) => m.id !== params.meId) for (const member of targets) {  await sendText({            // ← the very same 1:1 send from Section 4    meId: params.meId,    identity: params.identity,    peer: { id: member.id, dhPub: member.dhPub },    text: params.body,    groupId: params.groupId,    clientId,                 // so copies dedupe to one bubble  })}

What the server learns about a group

// Short human-comparable fingerprint of a signing key — the "safety number".export function fingerprint(signingPublicKey: Uint8Array): string {  const digest = sha256(signingPublicKey)  return bytesToHex(digest.slice(0, 6)).match(/.{4}/g)!.join(" · ")  // e.g.  "a1b2 · c3d4 · e5f6"}

If Alice and Bob see the samesafety number (in person or over a trusted channel), no man-in-the-middle swapped the keys. Glyph also warns on a sneakier sign: if a contact's signing key stays the same but their encryption key suddenly changes.

Disappearing messages

Set a timer and the message row carries an expires_at timestamp. After that moment it's removed and stops showing up. Same locked message as always — it just has an expiry attached.

View-once media

A photo can be marked view_once. The recipient opens it once; after that, the encrypted blob is deleted and a placeholder marker (media_removed_at) is left behind. Because the file used a one-off key that lived only inside the message, once the blob is gone it's gone — there's no copy the server can resurrect.

Recall that deriveIdentity(seed) is deterministic: the same seed always yields the same keys. So to add a device — or recover after losing one — you simply enter your 12 words and the device rebuilds the exact same identity.

     12  WORDS   →   SAME  IDENTITY  EVERYWHERE

  "ocean velvet ... maple"
           │
           ├──▶ Laptop   ──▶ deriveIdentity() ──▶ same keys
           ├──▶ Phone    ──▶ deriveIdentity() ──▶ same keys
           └──▶ New PC   ──▶ deriveIdentity() ──▶ same keys

On your device, the seed is kept encrypted behind your PIN, so a thief who grabs your unlocked-but-not-signed-in device still can't read it.

• What's stored: only ciphertext blobs, at a path like media/<your-id>/<random>. The decryption key is never there.
• Per-file cap:25 MB, checked in the browser before uploading.
• Per-user quota:a default of 1 GiB, enforced by a database trigger that runs before each upload is accepted.

Can they read your messages?

What Glyph honestly does NOT protect against

• Metadata: the server still learns who messages whom, when, and group membership. Contents stay secret; the social graph is partly visible.
• A compromised device:malware or a thief on your unlocked phone sees what you see. Cryptography can't help after the endpoint is owned.
• The recipient leaking: anyone you message can screenshot or repeat it. E2E protects against outsiders, not the people you talk to.
• Losing your 12 words:there's no recovery. That's the cost of having no central authority that could also be forced to unlock your account.