@chisquare-tech/yan-e2ee
v0.2.0
Published
Yan's end-to-end encryption: Olm and Megolm (vodozemac) compiled to WebAssembly
Readme
yan-e2ee
Yan's end-to-end encryption for direct messages (PLAN P1.7, TRD §5.8): thin bindings over vodozemac, Matrix's audited Rust implementation of Olm (1:1 device sessions) and Megolm (group sessions). No cryptography is implemented here; the crate only moves keys and ciphertext across the WebAssembly boundary. Android and iOS bindings (uniffi) come with A1/I1.
The server (yan-gox-apps/libs/messaging) only ever sees public keys and ciphertext.
Use (web)
import init, { Account, GroupSession, InboundGroupSession, verify_ed25519 } from '@chisquare-tech/yan-e2ee';
await init({ module_or_path: '/e2ee/yan_e2ee_bg.wasm' }); // serve the .wasm as an asset
const account = new Account();
const sig = account.sign(`yan.device.v1|${userId}|${deviceId}|${account.curve25519}|${account.ed25519}`);
account.generate_one_time_keys(20);
const otks = account.one_time_keys(); // { keyId: key }, sign each as yan.otk.v1|user|device|keyId|key
account.mark_keys_as_published();
const pickle = account.pickle(pickleKey); // 32-byte key that never leaves the deviceAccount: identity keys, signing, one-time and fallback keys, outbound and inbound Olm sessions.Session: an Olm session;encryptgives{ message_type, body }(0 = pre-key, 1 = normal).GroupSession/InboundGroupSession: Megolm, for every conversation (one sending session per device per epoch; itssession_keygoes to each member device over Olm).InboundGroupSession.export()/InboundGroupSession.import(): a session for another of your devices (history).sha256_base64,verification_code: the new-device check below.- Everything has
pickle(key)/from_pickle(pickle, key). Keys, signatures and ciphertext are unpadded base64.
Envelopes (v1)
What clients put around vodozemac's output. Every client (web: yan-ngx-apps-messages e2ee.ts; Android and iOS
later) must produce and check exactly this:
| Where | Shape |
|---|---|
| Signed device keys | yan.device.v1\|userId\|deviceId\|curve25519\|ed25519, signed with the device's Ed25519 key |
| Signed one-time / fallback key | yan.otk.v1\|userId\|deviceId\|keyId\|key / yan.fallback.v1\|… |
| To-device body (m.olm.v1.curve25519-aes-sha2) | {"v":1,"type":0\|1,"body":"<olm ciphertext>"} (0 = pre-key) |
| Its plaintext: a room key | {"t":"yan.room_key","conversationId","epoch","sessionId","sessionKey","sender":{"userId","deviceId","ed25519"},"recipient":{"userId","deviceId","ed25519"}} |
| Message ciphertext (m.megolm.v1.aes-sha2) | Megolm of {"v":1,"conversationId","kind","text"} |
Rules: verify a device's signature before trusting it, and pin its keys on first use; accept a room key only when
recipient is this device and sender is the device that sent it (as the server published it); show a message only
when its session's conversation and sender match the message, and treat a reused message index as a replay. One
Megolm session per conversation epoch (the server bumps it on membership changes), rotated after 100 messages; its
key goes to every member device, your own other devices included, before they should read.
Verifying a new device (history)
A new device can't read messages sent before it existed. Another of your devices can forward its Megolm sessions
(InboundGroupSession.export() → import()), but only after you allow it there, having checked both screens show
the same code: forwarding automatically would hand your history to any device the server adds to your account.
All four messages are Olm to-device payloads between devices of the same account:
- new → old
{"t":"yan.history_request","requestId","commitment":sha256_base64(n2),"requester":Party} - old → new
{"t":"yan.history_challenge","requestId","nonce":n1,"approver":Party,"recipient":Party} - new → old
{"t":"yan.history_reveal","requestId","nonce":n2,"requester":Party,"recipient":Party}; the old device checkssha256_base64(n2) == commitment - both show
verification_code("yan.verify.v1|userId|newDeviceId|newEd25519|oldDeviceId|oldEd25519|n1|n2"); once you allow it, old → new{"t":"yan.forwarded_room_keys","requestId","keys":[{"conversationId","sessionId", "senderUserId","senderDeviceId","exported"}],"sender":Party,"recipient":Party}(≤ 40 keys per message)
Party is {"userId","deviceId","ed25519"}; nonces are 16 random bytes, unpadded base64; requestId is h_ + 12
random bytes. The commitment means the new device fixes n2 before seeing n1, and the old device sends n1 before
seeing n2, so nobody (a server posing as either device included) can steer the 8-digit code. The new device accepts
forwarded keys only from a device it agreed a code with, for its own request, and keeps each session's original sender.
Build
cargo +stable test # native tests
cargo install wasm-bindgen-cli --version <locked> --locked
./build.sh [version] # → pkg/ (the npm package)
cd pkg && npm publish --access public