Cipher suites

This document summarizes the cryptographic primitives used by Tearleads and where each is applied. It is a reference map, not a design spec — see keying-design.md and security-guarantees.md for how these fit together, and glossary.md for terminology.

Public-key operations in the application E2EE / keying protocol are post-quantum only (NIST FIPS 203 / 204): no X25519, Ed25519, RSA, ECDH, or NaCl. This scope is the client and API keying path — it does not cover deployment tooling, which uses conventional SSH host keys (Ed25519, and RSA/ECDSA in the Terraform stacks).

Primitives

Where each is used

ML-KEM-1024 (key encapsulation)

Container-KEK-to-principal wrap suite: tearleads.container-kek-wrap.ml-kem-1024-aes-256-gcm. Document and blob content keys are not ML-KEM-wrapped directly to recipients — they wrap to container KEKs with AES-GCM (see below), and only the KEK is ML-KEM-wrapped to users, principals, and parent containers. Parent key pairs are derived from their KEKs using a domain-separated HKDF-SHA-256 seed; their public keys are committed by signed container events and manifests.

ML-DSA-87 (signatures)

AES-256-GCM (symmetric)

Core helpers: packages/crypto/src/symmetric.ts (32-byte key, 12-byte IV, 16-byte tag).

Note: the principal policy payload carries a cipherSuite: "aes-256-gcm" label (PrincipalStatePayloadCipherSuite in packages/crypto/src/principalStateTypes.ts), but the payload itself is base64 JSON the server can read. The organization authority descriptor and the built-in Admins/Members role markers are plaintext; only a custom group’s name is AES-256-GCM-encrypted inside it, under an HKDF-SHA-256 key derived from the organization metadata container KEK (packages/crypto/src/groupMetadata.ts).

Key derivation

PIN-code wrap suite: pin-code-pbkdf2-sha256-aes-256-gcm.

Hashing / MAC

At-rest database

The SQLite cipher key is an HKDF-derived key from the local keyring (sqliteKey).

OPFS local storage

OPFS (the Origin Private File System) is a browser storage backend, not a cipher suite. Tearleads encrypts the data it writes there; OPFS itself does not provide an additional application-managed encryption layer.

Each encrypted blob has a fresh 96-bit base IV. Chunk IVs are derived from that base IV and the chunk index, and each ciphertext chunk includes the 16-byte GCM authentication tag. The persisted envelope records the format, version, chunk shape, base IV, and (when a string passphrase is used) a PBKDF2-SHA-256 salt and iteration count. Raw 32-byte/AES-GCM keys, including the production local-keyring-derived blob key, do not use this PBKDF2 envelope.

On supported platforms, SQLite uses the OPFS SyncAccessHandle Pool VFS and blob files are placed under an identity-namespaced tearleads OPFS directory. The app requests durable browser storage before the first persistent database write; this is best effort, so a browser can still deny it. Without OPFS the automatic storage policy selects in-memory SQLite; an explicitly requested persistent SQLite backend hard-fails instead. Encrypted OPFS blob-store factories likewise fail closed rather than silently writing unencrypted files elsewhere.

Libraries