Phase 4: Verify Without Installing Anything

2026-02-15

Trust shouldn't require installing software. If someone sends you a tessera — a +bundle of preserved memories — you should be able to verify it's genuine and +unmodified without downloading an app, creating an account, or trusting a +server. That's what tesseras-wasm delivers: drag a tessera archive into a web +page, and cryptographic verification happens entirely in your browser.

What was built

tesseras-wasm — A Rust crate that compiles to WebAssembly via wasm-pack, +exposing four stateless functions to JavaScript. The crate depends on +tesseras-core for manifest parsing and calls cryptographic primitives directly +(blake3, ed25519-dalek) rather than depending on tesseras-crypto, which pulls +in C-based post-quantum libraries that don't compile to +wasm32-unknown-unknown.

parse_manifest takes raw MANIFEST bytes (UTF-8 plain text, not MessagePack), +delegates to tesseras_core::manifest::Manifest::parse(), and returns a JSON +string with the creator's Ed25519 public key, signature file paths, and a list +of files with their expected BLAKE3 hashes, sizes, and MIME types. Internal +structs (ManifestJson, CreatorPubkey, SignatureFiles, FileEntry) are +serialized with serde_json. The ML-DSA public key and signature file fields are +present in the JSON contract but set to null — ready for when post-quantum +signing is implemented on the native side.

hash_blake3 computes a BLAKE3 hash of arbitrary bytes and returns a +64-character hex string. It's called once per file in the tessera to verify +integrity against the MANIFEST.

verify_ed25519 takes a message, a 64-byte signature, and a 32-byte public key, +constructs an ed25519_dalek::VerifyingKey, and returns whether the signature +is valid. Length validation returns descriptive errors ("Ed25519 public key must +be 32 bytes") rather than panicking.

verify_ml_dsa is a stub that returns an error explaining ML-DSA verification +is not yet available. This is deliberate: the ml-dsa crate on crates.io is +v0.1.0-rc.7 (pre-release), and tesseras-crypto uses pqcrypto-dilithium +(C-based CRYSTALS-Dilithium) which is byte-incompatible with FIPS 204 ML-DSA. +Both sides need to use the same pure Rust implementation before +cross-verification works. Ed25519 verification is sufficient — every tessera is +Ed25519-signed.

All four functions use a two-layer pattern for testability: inner functions +return Result<T, String> and are tested natively, while thin #[wasm_bindgen] +wrappers convert errors to JsError. This avoids JsError::new() panicking on +non-WASM targets during testing.

The compiled WASM binary is 109 KB raw and 44 KB gzipped — well under the 200 KB +budget. wasm-opt applies -Oz optimization after wasm-pack builds with +opt-level = "z", LTO, and single codegen unit.

@tesseras/verify — A TypeScript npm package (crates/tesseras-wasm/js/) +that orchestrates browser-side verification. The public API is a single +function:

async function verifyTessera(
+  archive: Uint8Array,
+  onProgress?: (current: number, total: number, file: string) => void
+): Promise<VerificationResult>
+

The VerificationResult type provides everything a UI needs: overall validity, +tessera hash, creator public keys, signature status (valid/invalid/missing for +both Ed25519 and ML-DSA), per-file integrity results with expected and actual +hashes, a list of unexpected files not in the MANIFEST, and an errors array.

Archive unpacking (unpack.ts) handles three formats: gzip-compressed tar +(detected by \x1f\x8b magic bytes, decompressed with fflate then parsed as +tar), ZIP (PK\x03\x04 magic, unpacked with fflate's unzipSync), and raw tar +(ustar at offset 257). A normalizePath function strips the leading +tessera-<hash>/ prefix so internal paths match MANIFEST entries.

Verification runs in a Web Worker (worker.ts) to keep the UI thread +responsive. The worker initializes the WASM module, unpacks the archive, parses +the MANIFEST, verifies the Ed25519 signature against the creator's public key, +then hashes each file with BLAKE3 and compares against expected values. Progress +messages stream back to the main thread after each file. If any signature is +invalid, verification stops early without hashing files — failing fast on the +most critical check.

The archive is transferred to the worker with zero-copy +(worker.postMessage({ type: "verify", archive }, [archive.buffer])) to avoid +duplicating potentially large tessera files in memory.

Build pipeline — Three new justfile targets: wasm-build runs wasm-pack +with --target web --release and optimizes with wasm-opt; wasm-size reports +raw and gzipped binary size; test-wasm runs the native test suite.

Tests — 9 native unit tests cover BLAKE3 hashing (empty input, known value), +Ed25519 verification (valid signature, invalid signature, wrong key, bad key +length), and MANIFEST parsing (valid manifest, invalid UTF-8, garbage input). 3 +WASM integration tests run in headless Chrome via +wasm-pack test --headless --chrome, verifying that hash_blake3, +verify_ed25519, and parse_manifest work correctly when compiled to +wasm32-unknown-unknown.

Architecture decisions

No tesseras-crypto dependency: the WASM crate calls blake3 and +ed25519-dalek directly. tesseras-crypto depends on pqcrypto-kyber (C-based +ML-KEM via pqcrypto-traits) which requires a C compiler toolchain and doesn't +target wasm32. By depending only on pure Rust crates, the WASM build has zero +C dependencies and compiles cleanly to WebAssembly.
ML-DSA deferred, not faked: rather than silently skipping post-quantum +verification, the stub returns an explicit error. This ensures that if a +tessera contains an ML-DSA signature, the verification result will report +ml_dsa: "missing" rather than pretending it was checked. The JS orchestrator +handles this gracefully — a tessera is valid if Ed25519 passes and ML-DSA is +missing (not yet implemented on either side).
Inner function pattern: JsError cannot be constructed on non-WASM +targets (it panics). Splitting each function into +foo_inner() -> Result<T, String> and foo() -> Result<T, JsError> lets the +native test suite exercise all logic without touching JavaScript types. The +WASM integration tests in headless Chrome test the full #[wasm_bindgen] +surface.
Web Worker isolation: cryptographic operations (especially BLAKE3 over +large media files) can take hundreds of milliseconds. Running in a Worker +prevents UI jank. The streaming progress protocol +({ type: "progress", current, total, file }) lets the UI show a progress bar +during verification of tesseras with many files.
Zero-copy transfer: archive.buffer is transferred to the Worker, not +copied. For a 50 MB tessera archive, this avoids doubling memory usage during +verification.
Plain text MANIFEST, not MessagePack: the WASM crate parses the same +plain-text MANIFEST format as the CLI. This is by design — the MANIFEST is the +tessera's Rosetta Stone, readable by anyone with a text editor. The +rmp-serde dependency in the Cargo.toml is not used and will be removed.

What comes next

Phase 4: Resilience and Scale — OS packaging (Alpine, Arch, Debian, +FreeBSD, OpenBSD), CI on SourceHut and GitHub Actions, security audits, +browser-based tessera explorer at tesseras.net using @tesseras/verify
Phase 5: Exploration and Culture — Public tessera browser by +era/location/theme/language, institutional curation, genealogy integration, +physical media export (M-DISC, microfilm, acid-free paper with QR)

Verification no longer requires trust in software. A tessera archive dropped +into a browser is verified with the same cryptographic rigor as the CLI — same +BLAKE3 hashes, same Ed25519 signatures, same MANIFEST parser. The difference is +that now anyone can do it.

+ +