LumaWeb/docs/decisions/0003-crypto-library.md

ADR 0003: OMEMO session/ratchet engine and browser backend feasibility

• Status: proposed
• Task: S00-004, remediation S00-021.
• Date: 2026-10-15.
• Decision owner: auto-crypto-fcef9b6781bf (crypto).
• Reviewer: security (separate agent for S00-021 review).
• Requirements: ENC-003, ENC-009, ENC-011.

Context and required capabilities

Input: immutable ENC-003 (legacy OMEMO and OMEMO 2 wire formats with compatible device lists/bundles and identity/session lifecycle), ENC-009 (encryption runs in the client endpoint with proven implementations and compatible vectors; no homegrown algorithm, no server-side decryption, no treating shared storage as proven interoperability), and ENC-011 (OMEMO 2 wire format by an approved compatible revision with SCE and payload/key/MAC rules; not replaced by media AES-GCM). Also the accepted scope (ADR 0000), stack (ADR 0001) and reviewer decisions S00-001/S00-002, plus the S00-004 blocker report and handoff.

Output is one focused probe record and this ADR (proposed) establishing what is verifiably feasible today for a Web client: an audited session/ratchet engine with secure session-record persistence, and the honest boundary for the browser/worker/WASM endpoint and the OMEMO2 wire layer. Acceptance requires a real library/backend, verified vectors, no homegrown ratchet, and any unsupported format recorded as a blocker (not success).

Candidates and primary sources

Primary public sources and exact reachable-registry records retrieved 2026-10-15 via the configured npm proxy. These sources establish library and distribution boundaries; none of them is treated as a tested product integration.

Candidate	Reachable registry	License	Browser/WASM reality
@signalapp/libsignal-client@0.105.0	exists	AGPL-3.0-only	Node native addon (dist/Native.js uses node-gyp-build; prebuilds/*/*.node). No .wasm asset ships; cannot execute in a browser worker.
@signalapp/libsignal	404 Not Found	—	Signal's TypeScript/WASM web distribution is not published to the reachable npm registry; npm view @signalapp/libsignal version returns E404.
omemo-client	404 Not Found	—	not on reachable registry
omemo-top	404 Not Found	—	not on reachable registry
omemo-wasm	404 Not Found	—	not on reachable registry
@converse/omemo	404 Not Found	—	not on reachable registry

Sources:

• signalapp/libsignal repository package.json defines the Node distribution of the libsignal client (native bridge).
• Signal documentation on libsignal WASM/web: the library is compiled to WebAssembly for Signal's browser clients, but that artifact is produced from source into the Signal client builds; it is not shipped as a maintained standalone @signalapp/libsignal npm package on the reachable registry (E404, queried 2026-10-15).
• The exact registry records were queried with npm view <pkg> version; results (version or E404) are captured in evidence: state/evidence/S00-021-auto-crypto-fcef9b6781bf.md.

Focused experiment and actual result

The previously committed probes inside experiments/0003-crypto-library/session-probe/ were reproduced unchanged from the S00-004 handoff (this run re-ran both, actual exit codes recorded below):

1. node experiments/0003-crypto-library/session-probe/smoke.mjs — exit 0, SMOKE_PASS. A real A/B pair using @signalapp/libsignal-client sealed-sender APIs established a PreKey session, round-tripped the known plaintext known vector: OMEMO session smoke, stored a 631-byte session record and reloaded it byte-for-byte. This verifies an audited session/ratchet engine and session-record persistence without any homegrown ratchet; it mirrors Signal canonical in-memory store semantics.
2. node experiments/0003-crypto-library/session-probe/wasm-unsupported.mjs — exit 2. Inspects the installed package: wasmFiles: 0; prebuilds are darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64 native *.node files; dist/Native.js loads via node-gyp-build. This confirms that the shipped artifact cannot run in a browser worker/WASM endpoint, and the distribution ships no .wasm asset.

Result: the audited session/ratchet engine and persistence are verified; the browser/worker/WASM deployment and the OMEMO/OMEMO2 XMPP wire layer are not established by any maintained package on the reachable registry. Per focused check "unsupported format recorded blocker, not success", this is recorded as a blocker, not as an achieved capability.

Decision

Adopt @signalapp/libsignal-client only as the audited session/ratchet engine and session-record persistence primitive for the Node-side spike and downstream adapters that can run a native/external environment, and keep it as the verified evidence that an audited library (not a homegrown ratchet) supplies the whistler/session layer and durable session-records.

Record as a blocker on S00-004 that the browser/worker/WASM endpoint and the OMEMO2 wire-format layer are not available from any maintained package on the reachable registry, and that @signalapp/libsignal (the WASM distribution) is not published there. This remediation does not replace the missing browser backend with a homemade ratchet, does not reuse the shared Node session store as if it proved browser interoperability (ENC-009), and does not pretend the unsupported OMEMO2 wire layer is complete. The correct next step for S00-004's continued execution is: (a) obtain a verified browser/WASM-capable OMEMO2 backend (a distribution with a real .wasm/web build and an OMEMO2/S ce-format mapping) or (b) escalate with traceable upstream primary sources resolving ENC-009/ENC-011 client-endpoint encryption for the browser transport.

License / security / browser constraints

@signalapp/libsignal-client is AGPL-3.0-only. Its AGPL-3.0 obligations apply if the library (or modified copies) is distributed. Its official notices and license are bundled in node_modules/@signalapp/libsignal-client and its acknowledgments; the reader is referred to the package license text and the Signal acknowledgments file before any redistribution. AGPL compatibility with the eventual product distribution decision is a separate review item for the accepted stack/licensing tasks.

Browser constraints (from the accepted stack ADR 0001 and Web profile): the absent WASM distribution is a hard capability boundary here — no .wasm asset to instantiate in a worker. No plaintext fallback, no spy/decrypt bypass, and no server-side decryption path is introduced. Any real OMEMO2 wire mapping must be produced from approved primary sources and preserve ENC-009/ENC-011 client-endpoint encryption; media/transport AES-GCM alone does not satisfy ENC-011.

Consequences and downstream contract

• S00-004's acceptance requires legacy/OMEMO2 AND worker/wasm AND persistence. Two of the three (browser/WASM and the OMEMO2 wire layer) remain unresolved and are recorded here as a blocker; only persistence + audited ratchet/session are established. A new executor of S00-004 must not declare it done on this basis (it would bypass the requirements).
• Any crypto boundary contract (planned docs/contracts/crypto.md, S12 tasks) must key off a verified, maintained library and real vectors; it must not assume a browser/WASM OMEMO2 primitive that is still absent.
• No shared contract, plan definition, requirement snapshot or spec file is changed by this ADR.

Rejected alternatives and migration trigger

1. Hand-write the Double Ratchet or OMEMO2 wire format. Rejected: forbidden by ENC-009 (no homegrown algorithm/primitive replacement) and the crypto role constraints.
2. Reuse the Node session store as "interoperability". Rejected: ENC-009 forbids treating shared session storage as proof of interoperability; it is a persistence spike only.
3. Declare @signalapp/libsignal-client a full browser backend. Rejected: verified native-only, zero .wasm; would be a false success.

Migration/continuation trigger: a verified browser/WASM-capable OMEMO2 package or a resolved, traceable upstream path that satisfies ENC-009/ENC-011 becomes available; then S00-004 (or its assigned continuation) may be re-run and the browser-capable backend validated with known vectors in the web target before acceptance.