IcyZip authenticated browser E2EE v3

This repository makes the browser cryptography and security-relevant receive logic of IcyZip protocol v3 inspectable and reproducible. src/e2ee.js is byte-identical to the module consumed by production IcyZip. src/snapshot.js contains exact integration and file-receive sections. The proprietary relay is outside this repository; every relay-visible message and trust boundary relevant to E2EE is documented here.

This is review release 0.4.0 for the protocol introduced in IcyZip production/staging commit edc7b8b80335bda8ff84589c7f4fac76c671f1f5. It includes a minimal standalone test, focused attack regressions and a reproducible container review lab. The repository contains no proprietary server code.

Read individual files or download the complete package at icyzip.com/open-source. The download includes SHA256SUMS for checking every published file. No hosting-platform account is required.

The read-only Git repository retains the full public history:

git clone https://icyzip.com/open-source/icyzip-e2ee.git
cd icyzip-e2ee

The source page also provides a complete .bundle for offline cloning with git clone icyzip-e2ee.bundle icyzip-e2ee. Submit non-sensitive bugs and questions through Issues, without an account or required email. New reports are reviewed before publication; security findings use the private route in SECURITY.md.

What v3 changes

• A new primary browser generates a random 32-byte pairing secret and places it only in the URL fragment: #k=<base64url>&v=3.
• The secondary stores that secret in tab-scoped sessionStorage and removes the fragment from its visible URL. URI fragments are not part of the HTTP request.
• The pairing secret authenticates each P-256 ECDH public key with HMAC-SHA-256 before the peer key is imported.
• The ECDH result and pairing secret jointly derive separate keys for text, file chunks, and file-offer authentication.
• Text envelope v2 encrypts the text, revision, and origin together.
• Every visible file-offer field is authenticated before the receiver accepts a transfer.
• Legacy key messages, text envelopes, file markers, malformed encodings, wrong roles, wrong pairs, altered offers, and unauthenticated ciphertext fail closed.

The complete pairing link is a secret capability. Anyone who obtains it can join that pair, so it must be kept private. The relay still sees the pair id, public keys and authentication tags, ciphertext sizes, timing, connection data, and file-offer metadata such as filename, MIME hint, sizes, and transfer identifiers. See PROTOCOL.md and THREAT-MODEL.md for the precise boundaries.

Verify it

Node.js 20 or newer is required. The tests use only built-in Node modules: no package installation, server, account, or network connection is needed.

npm run test:minimal
npm test

Start with the 21-line minimal test and 33-line endpoint adapter. TESTING.md explains how to add a small reproduction of a suspected weakness.

The full suite covers authenticated key exchange, an independent Node cryptography oracle, key separation, exact bidirectional text and file recovery, hidden and authenticated text metadata, public-key substitution and reflection rejection, ciphertext and context tampering, file-offer field authentication, downgrade rejection, cancellation and retry, storage failure, reload recovery, and deterministic source provenance.

For an immediate isolated run with the same tests plus deterministic mutation fuzzing and source/tool/SBOM inspection, use the public review image described in CONTAINER.md. Its default command runs without network access. A passing image is evidence for the published checks and inputs, not a claim that no weakness exists.

Optionally compare the same files with the JavaScript currently served by IcyZip:

npm run check:live

The live check permits only the two fixed https://icyzip.com browser assets, follows no redirects, marks its requests as test traffic, and writes no file. See PROVENANCE.md for its exact scope.

Source layout

• src/e2ee.js: complete byte-identical protocol module used by production IcyZip.
• src/snapshot.js: three exact integration and file-receive sections from the browser client.
• PROVENANCE.json: SHA-256 hashes, source anchors, original line locations, and byte counts.
• tools/snapshot.mjs: deterministic exporter and verifier.
• test/endpoint.mjs: test-only endpoint and storage adapter; it implements no cryptography.
• test/minimal.test.mjs: small standalone text-exchange and tampering example.
• test/crypto.test.mjs: protocol, tamper, recovery, and independent-oracle tests.
• test/file-receive.test.mjs: downgrade, offer authentication, cancellation, tamper, retry, and exact-byte tests using the real receive controller.
• test/security-regressions.test.mjs: expected rejection of the two active attacks disclosed by v0.2.
• test/container.test.mjs: public-only container recipe, deterministic fuzz controls and anti-false-green contracts.
• tools/fuzz.mjs: seeded synthetic mutations with legitimate forward progress after every rejection.
• Dockerfile, container-lock.json and CONTAINER.md: pinned review environment, inventory and reproducible use.

This code is review material for IcyZip's browser protocol, not a general-purpose cryptography library. Please report security findings privately as described in SECURITY.md.

Licensed under Apache License 2.0. Copyright 2026 Richard Andresik.