Cryptographic Specification

1. Client calls opaque.client.startRegistration(password), producing a registrationRequest and a local clientRegistrationState.
2. Client sends registrationRequest to the server.
3. Server calls opaque.server.createRegistrationResponse using the OPAQUE_SERVER_SETUP secret and the user identifier. Returns a registrationResponse. Stores nothing yet.
4. Client calls opaque.client.finishRegistration(clientRegistrationState, registrationResponse, password, keyStretching: 'memory-constrained'). Produces a registrationRecord and an exportKey.
5. Client sends registrationRecord to the server. The server stores it. The exportKey never leaves the client.

1. Client calls opaque.client.startLogin(password).
2. Server calls opaque.server.startLogin using the stored registrationRecord. Produces a loginResponse and a short-lived serverLoginState stored in Redis (5-minute TTL).
3. Client calls opaque.client.finishLogin(clientLoginState, loginResponse, password). Produces a finishLoginRequest and an exportKey.
4. Server calls opaque.server.finishLogin(serverLoginState, finishLoginRequest). A sessionKey is derived (used only for mutual authentication proof). The server issues a session cookie. The exportKey on the server side is discarded. Only the client holds it.

A 32-byte (256-bit) random master key is generated with crypto.getRandomValues at vault creation. It is never stored in plaintext. It is wrapped (AES-256-GCM encrypted) before upload and unwrapped on each login.

The KEK for wrapping the master key under the password path is derived from the OPAQUE exportKey:

HKDF-SHA-256(
  ikm  = exportKey          (32 bytes, from OPAQUE login)
  salt = kdfSalt            (16 random bytes, stored on server)
  info = 'whenary.e2ee.kek.password.v1'
  len  = 32 bytes
)

The exportKey is zeroed after derivation. The kdfSalt is stored in the vault record on the server in plaintext. It is a public nonce, not a secret.

A second KEK is derived from a BIP39 recovery phrase generated at vault creation:

HKDF-SHA-256(
  ikm  = recoveryPhraseSeed  (bytes derived from mnemonic)
  salt = kdfSalt             (same salt as above)
  info = 'whenary.e2ee.kek.recovery.v1'
  len  = 32 bytes
)

The master key is wrapped independently under both KEKs and stored on the server. Either path can unlock the vault. Losing both means the vault cannot be opened unless a WebAuthn PRF wrap was also stored for a remaining passkey.

Passkey registration and authentication request the WebAuthn PRF extension. When the authenticator returns a PRF secret, the client derives a third KEK and stores a wrap on that passkey row. The server cannot compute the PRF output.

HKDF-SHA-256(
  ikm  = WebAuthn PRF first output
  salt = kdfSalt
  info = 'whenary.e2ee.kek.prf.v1'
  len  = 32 bytes
)
eval salt = 'whenary.e2ee.kek.prf.v1:{userId}'

After that wrap exists, a locked vault can be opened with the same passkey without re-entering the password. Tab persist still uses the device wrapping key so a reload does not prompt for the authenticator.

Master key wrapping uses AES-256-GCM with a 12-byte random IV and domain-separated additional authenticated data (AAD):

wrappedMasterKeyPassword = AES-256-GCM(
  key   = passwordKEK
  data  = masterKey (32 bytes)
  iv    = 12 random bytes
  aad   = 'whenary:vault:master:password:{userId}'
)
format: 'e1.{base64_iv}.{base64_ciphertext+tag}'

wrappedMasterKeyRecovery = AES-256-GCM(
  key   = recoveryKEK
  data  = masterKey (32 bytes)
  iv    = 12 random bytes
  aad   = 'whenary:vault:master:recovery:{userId}'
)
format: 'e1.{base64_iv}.{base64_ciphertext+tag}'

wrappedMasterKeyPrf = AES-256-GCM(
  key   = prfKEK
  data  = masterKey (32 bytes)
  iv    = 12 random bytes
  aad   = 'whenary:vault:master:prf:{userId}:{credentialId}'
)
format: 'e1.{base64_iv}.{base64_ciphertext+tag}'

The GCM authentication tag (16 bytes) is appended to the ciphertext by the WebCrypto API before base64 encoding. Decryption fails if the ciphertext, IV, or AAD is tampered with.

An X25519 keypair is generated on the client at vault creation. The private key is wrapped under the master key:

wrappedPrivateKey = AES-256-GCM(
  key   = masterKey
  data  = x25519PrivateKey (32 bytes)
  iv    = 12 random bytes
  aad   = 'whenary:vault:identity:{userId}'
)
format: 'e1.{base64_iv}.{base64_ciphertext+tag}'

The X25519 public key is stored in plaintext on the server and used by other users to seal calendar or space keys for sharing. The private key is unwrapped in client memory during vault unlock and used for decrypting incoming grants.

After unlocking, the master key is held in memory as a hex string in the Zustand vault store. On web, the key is not written to sessionStorage in the clear. Instead, a 256-bit AES-GCM wrapping key is generated per device and stored in IndexedDB with extractable: false. The master key is encrypted under that device key and the resulting ciphertext is written to sessionStorage under whenary:e2ee:master. On reload, the device key is retrieved from IndexedDB and used to unwrap the master key from sessionStorage, avoiding a re-prompt. If IndexedDB is unavailable the raw bytes fall back to sessionStorage directly. On Android (Capacitor), the key is stored in Capacitor Preferences under whenary.e2ee.master. In all cases the key is cleared on logout or vault lock.

When E2EE is enabled on a calendar or space chat, the owner generates a 32-byte random key and wraps it under their master key:

calendarKey = randomBytes(32)

ownerGrant = AES-256-GCM(
  key   = masterKey
  data  = calendarKey
  iv    = 12 random bytes
  aad   = 'whenary:calendar:key:{calendarId}'           (version 1)
       or 'whenary:calendar:key:{calendarId}:v{n}'     (version n > 1)
)
stored as GrantRecord { wrapMethod: 'master', wrappedKey, keyVersion: 1 }

Space chat keys use the same structure with AAD whenary:space:key:{spaceId}.

When the calendar owner shares with another user, the calendar key is sealed for their identity public key using an ephemeral X25519 ECDH exchange:

ephemeralPrivateKey = randomBytes(32)
ephemeralPublicKey  = x25519.getPublicKey(ephemeralPrivateKey)

sharedSecret = x25519(ephemeralPrivateKey, recipientPublicKey)

sealKey = HKDF-SHA-256(
  ikm  = sharedSecret
  salt = randomBytes(32)    (stored alongside as 'salt')
  info = 'whenary.e2ee.kek.ecdh.v1'
  len  = 32 bytes
)

sealedCalendarKey = AES-256-GCM(
  key   = sealKey
  data  = calendarKey (raw bytes)
  iv    = 12 random bytes
  aad   = 'whenary:calendar:grant:{calendarId}:{recipientUserId}'
       or 'whenary:calendar:grant:{calendarId}:{recipientUserId}:v{n}'
)

stored as GrantRecord {
  wrapMethod: 'ecdh',
  wrappedKey: sealedCalendarKey,
  ephemeralPublicKey,
  salt,
  keyVersion
}

Recipients decrypt by computing the same ECDH shared secret using their private key and the stored ephemeral public key, re-deriving the seal key via HKDF, and decrypting with the matching AAD. Because the ephemeral key is fresh for each grant, each sealed copy is independent. The grant request must include the recipient's current public key and identityEpoch. The server rejects the write if either no longer matches the stored vault, so a substituted public key cannot silently receive a newly shared calendar key.

Space grants use the same pattern with AAD whenary:space:grant:{spaceId}:{userId}.

The owner can rotate a calendar key to revoke access from removed members. Rotation:

1. Generates a new 32-byte key (version = oldVersion + 1).
2. Wraps the new key under owner's master key.
3. Seals the new key for each kept member via ECDH.
4. Re-encrypts all existing events under the new key.
5. Re-wraps all media file keys under the new key.
6. Atomically submits new grants, re-encrypted events, and re-wrapped media keys to the server in a single request.

Rotation prevents future decryption by removed members. It does not retract content already decrypted and copied before removal.

ciphertext = AES-256-GCM(
  key   = calendarKey[version]
  data  = UTF-8(plaintext)
  iv    = 12 random bytes (fresh per field per save)
  aad   = length-prefixed context:
          purpose | protocol | resource | scopeId | recordId | field | keyVersion

stored as: 'e2ee2.' + keyVersion + '.' + base64(iv) + '.' + base64(ciphertext+tag)
legacy:    'e2ee1.' + 'e1.' + base64(iv) + '.' + base64(ciphertext+tag)

New writes use the e2ee2. envelope, which binds ciphertext to a specific record so values cannot be swapped between events, messages, or files. Legacy e2ee1. values remain readable and are upgraded on edit or rotation. Timing metadata is authenticated with a separate integrity tag. Push workers store a derived notification key and decrypt e2ee2n. titles only. Guest RSVP, availability-poll, and public calendar links for encrypted calendars carry a fragment key in the URL hash. The server stores ciphertext and never sees that key.

The AAD binds each ciphertext to its calendar, field type, and key version. A ciphertext cannot be moved to a different calendar or field without causing decryption to fail.

The following event fields are stored in plaintext even on E2EE calendars, because the server must read them to operate correctly:

• Start time, end time, all-day flag
• Timezone
• Recurrence rule (RRULE), excluded dates (EXDATE)
• Color
• Attendee user IDs and RSVP status
• External attendee email addresses
• e2eeKeyVersion (which version of the calendar key encrypted this event)

ENC_KEY         = scrypt(ENCRYPTION_KEY,    'whenary.aes256gcm',       len=32)
MAC_KEY         = scrypt(SESSION_SECRET,    'whenary.hmac.sha256',     len=32)
BLIND_INDEX_KEY = scrypt(BLIND_INDEX_SECRET,'whenary.blind-index.sha256', len=32)

Optional DEK (key rotation):
DATA_KEY = AES-256-GCM-decrypt(WRAPPED_DATA_KEY, ENC_KEY)
           (unwrapped once at startup, held in process memory)

ENCRYPTION_KEY, SESSION_SECRET, and BLIND_INDEX_SECRET are environment variables set by the operator. Key derivation uses Node.js crypto.scryptSync with the domain string as the salt.

v1 format (direct ENC_KEY):
  'v1.{base64url_iv}.{base64url_tag}.{base64url_ciphertext}'

v2 format (wrapped DEK, if WRAPPED_DATA_KEY is configured):
  'v2.{base64url_iv}.{base64url_tag}.{base64url_ciphertext}'

ale2 format (context-bound keyring writes):
  'ale2.{keyId}.{base64url_iv}.{base64url_tag}.{base64url_ciphertext}'

algorithm: AES-256-GCM, 12-byte IV, 16-byte auth tag (explicit, separate from ciphertext)
v1/v2 have no AAD. ale2 AAD binds purpose, model, field, and row id.

Dual-read still accepts v1, v2, and ale2. New application-layer writes use ale2 with AAD bound to the model, field, and row so those values cannot be copied onto a different record. Legacy unbound ale1 and unbound ale2 rows still decrypt.

All of the following are encrypted before database write and decrypted in server memory when needed. The server can always read these:

• Username, email address
• Space names, display names, passkey labels
• Calendar names and descriptions (non-E2EE calendars)
• Event titles, descriptions, locations, URLs, tags, and conference links (non-E2EE calendars)
• Event message bodies (non-E2EE calendars)
• List and checklist labels, poll text (non-E2EE calendars and spaces)
• Guest RSVP names, aliases, notes, and guest poll names (non-E2EE calendars)
• Photo captions on non-E2EE calendars, subscription labels, public link labels and tokens
• TOTP secrets
• BYOS credentials (access key, secret key, bucket, endpoint)
• OAuth access and refresh tokens (Google Calendar, Microsoft Outlook)
• Push subscription endpoint and key material, in-app notification title and body
• Guest event token labels
• OIDC identity linkage
• Contact form messages and reply addresses

Searchable encrypted fields also have a blind index stored alongside them. A blind index is an HMAC-SHA256 of the normalized plaintext, keyed separately from the encryption key. It allows exact-match lookups without decrypting all rows:

blindIndex(scope, value) = HMAC-SHA256(BLIND_INDEX_KEY, '{scope}\0{value}').base64url

Indexes in use:
  user.email         -> emailBlindIndex  (normalized lowercase)
  user.username      -> usernameBlindIndex  (normalized lowercase)
  push.endpoint      -> pushEndpointBlindIndex
  oidc.issuer-subject -> oidcIssuerSubjectBlindIndex  ('issuer\0subject')
  attendee.email     -> externalAttendeeEmailBlindIndex  ('eventId\0email')

pairDigest = SHA-256(
  'whenary.safety.v1'  (UTF-8)
  || sort(publicKeyA, publicKeyB)[0]  (32 bytes, lower of the two)
  || sort(publicKeyA, publicKeyB)[1]  (32 bytes, higher of the two)
)

Safety words (8):
  for i in 0..7:
    index = ((pairDigest[i*2] << 8) | pairDigest[i*2+1]) % 2048
    word  = BIP39_wordlist[index]

Safety number (60 digits):
  for each byte in pairDigest:
    append (byte % 10) as a decimal digit
  format as groups of 5 separated by spaces

Key fingerprint (single key):
  SHA-256(publicKey)[0:16] as uppercase hex groups of 4

The keys are lexicographically sorted before hashing so both parties compute the same digest regardless of who initiates the comparison. The BIP39 wordlist has 2048 entries. 8 words provides approximately 88 bits of comparison space.

The browser stores seen public keys for each user ID in localStorage under the key whenary:e2ee:pinned-keys. Each entry records the public key, when it was first seen, and optionally when it was verified by the user. If a contact's key changes, the UI shows a warning. This is a trust-on-first-use (TOFU) model. Users who verify out-of-band can mark a key as confirmed.

curl https://whenary.com/integrity.json.asc | gpg --verify

Import the Releases key first if needed:

curl https://whenary.com/security-pgp.asc | gpg --import