Encryption

What We Borrow From Each

Epicenter's Encryption Architecture

Environment Variables

# Required. Completely independent from BETTER_AUTH_SECRET.
# Always uses versioned format: "version:secret" pairs, comma-separated.
# Generate secret: openssl rand -base64 32

# Single key (initial setup):
ENCRYPTION_SECRETS="1:base64encodedSecret"

# After rotation (add new version, keep old for decryption):
ENCRYPTION_SECRETS="2:newBase64Secret,1:oldBase64Secret"

• ONE env var: ENCRYPTION_SECRETS (always plural, always versioned format)
• Format: version:secret pairs, comma-separated. Highest version = current key for new encryptions.
• Completely decoupled from BETTER_AUTH_SECRET--rotating one never affects the other
• Matches Better Auth's own BETTER_AUTH_SECRETS convention

Key Hierarchy

ENCRYPTION_SECRETS="1:base64Secret"
       |
       |  Parse -> keyring[{ version: 1, secret: "base64Secret" }]
       |  Current = highest version
       |
       |  SHA-256(currentSecret) -> root key material
       |  HKDF(root, info="user:{userId}") -> per-user key (32 bytes)
       |
       |  HKDF(userKey, info="workspace:{wsId}") -> per-workspace key (32 bytes)
       v
  XChaCha20-Poly1305 encrypt/decrypt with @noble/ciphers

Key Delivery Best Practices

Prefer inline key delivery over separate endpoints. If the session already authenticates the user, derive and embed key material in the session response. HKDF-SHA256 derivation adds <0.1ms—the optimization of splitting key delivery from session delivery costs more in complexity (version-tracking state, extra round-trips, duplicated callbacks) than it saves in compute.

Make unlock operations idempotent. Calling unlock() with the same key twice should be a no-op, and calling it with a different key should cleanly replace the active key. This eliminates client-side version tracking—the client receives the key, calls unlock, done. No mutable lastVersion state, no conditional fetches.

Embed key version in the ciphertext, not in application logic. The blob header (blob[1]) carries the version that encrypted it. Decryption reads the version from the blob and selects the matching key from the keyring. Clients never need to track which version they’re using—the data is self-describing.

Minimize client-side key state. Ideally zero mutable state. The session carries the key, the client passes it to unlock(), the workspace derives per-workspace keys internally. No caches to invalidate, no version comparisons, no separate fetch methods.

Why XChaCha20-Poly1305 Over AES-256-GCM

AES-256-GCM via WebCrypto uses hardware AES-NI and is faster, but it's async. We need synchronous encrypt/decrypt for the CRDT hot path.

Key Derivation

• Uses Web Crypto HKDF with SHA-256 hash
• Empty salt (acceptable for HKDF when input key material has high entropy)
• Info strings are domain-separation labels, NOT version identifiers
• user:{userId} for per-user keys, workspace:{wsId} for per-workspace keys
• Different secrets with the same info string produce cryptographically independent keys (RFC 5869)

EncryptedBlob Format

type EncryptedBlob = Uint8Array;

// Bare Uint8Array with self-describing binary header.
// v:1 binary layout:
//   blob[0]     = format version (0x01 = XChaCha20-Poly1305)
//   blob[1]     = key version (which secret from ENCRYPTION_SECRETS keyring)
//   blob[2..25] = random nonce (24 bytes, XChaCha20)
//   blob[26..]  = XChaCha20-Poly1305 ciphertext || authentication tag (16 bytes)

• blob[0] = format version. Currently always 1 (XChaCha20-Poly1305).
• blob[1] = key version, identifying which secret encrypted this blob
• Detection: value instanceof Uint8Array && value[0] === 1
• User values in the CRDT are always JS objects, never Uint8Arrays
• Use getKeyVersion(blob) to read blob[1] without decrypting
• Use getFormatVersion(blob) to read blob[0] without decrypting

Key Rotation

# Rotate by adding a new highest-version entry:
ENCRYPTION_SECRETS="2:newBase64Secret,1:oldBase64Secret"

• Parser splits by ,, then each entry by first : -> { version: number, secret: string }
• Sorted by version descending; first entry = current for new encryptions
• Encrypt: always uses current (highest version) key, embeds version as blob[1]
• Decrypt: read blob[1] to know which key version was used, select matching key from keyring
• Lazy re-encryption: on read with non-current key version, re-encrypt on next write
• Keep old secrets in keyring for at least 90 days to handle offline devices

Format Version Upgrade Path

• Format version 1 = XChaCha20-Poly1305 with key version byte at blob[1]

Format version bumps only needed for algorithm or binary layout changes (extremely rare):

isEncryptedBlob Detection

function isEncryptedBlob(value: unknown): value is EncryptedBlob {
  return value instanceof Uint8Array && value[0] === 1;
}

User values in the CRDT are always JS objects (from schema definitions), never Uint8Arrays. This makes instanceof Uint8Array a reliable discriminant. Truncated or corrupted blobs that pass this check will fail during decryptValue() and get quarantined by the encrypted wrapper's error containment.

AAD (Additional Authenticated Data)

When encrypting workspace values, the entry key is bound as AAD to prevent ciphertext transplant attacks (moving an encrypted value from one key to another).