feat: add an ant-core-powered direct browser client

[mickvandijke]

Summary

Adds a direct Autonomi browser client powered by ant-core compiled to WebAssembly.

The browser connects to storage nodes over WebRTC Direct, authenticates their ANT identities, establishes a fresh post-quantum application session, performs iterative closest-node lookup, verifies quotes, pays once, uploads content-addressed records, resolves public DataMaps, downloads/reconstructs files, and serves seekable media ranges without an application gateway.

Compatibility-sensitive behavior stays in Rust. JavaScript is limited to browser-owned boundaries: DOM interaction, file/save handles, worker and IndexedDB integration, service-worker messaging, and submitting an ant-core-verified payment plan through the wallet provider.

Companion node implementation: ant-node#220

ant-core architecture

• Preserves the existing native ant-core and ant-cli API through the default native feature.
• Adds a browser-wasm build that excludes Tokio networking, filesystem, daemon management, and native EVM providers.
• Owns WebRTC peer connections and DataChannels in Rust through web-sys.
• Parses canonical WebRTC Direct multiaddresses and pins the expected DTLS certificate fingerprint and ANT peer ID.
• Uses Saorsa's shared transport-independent iterative lookup runner instead of a browser-specific Kademlia implementation.
• Uses portable ant-protocol types for quote encoding, payment hashing, pricing, commitment verification, ML-DSA validation, transfer deadlines, and the complete encrypted session/record layer.
• Shares native/browser transfer policy: adaptive scheduling, bounded in-flight bytes, four-of-seven quorum, fallback targets, whole-record retries, and payload-aware deadlines.
• Uses the native self-encryption/DataMap implementation for upload, reconstruction, nested DataMaps, range decryption, and BLAKE3 verification.

The native facade is unchanged. Existing Rust desktop applications and ant-cli continue to use the native QUIC client without source changes; only browser-wasm selects the WebRTC adapter.

Post-quantum WebRTC application session

Browser protocol v4 replaces the former plaintext v3 RPC channel and standalone ML-DSA HELLO challenge:

1. ant-core generates an ephemeral ML-KEM-768 encapsulation key after the ordered DataChannel opens.
2. The node returns an ML-KEM ciphertext, ANT peer ID, ML-DSA-65 public key, and a signature over the domain-separated KEM transcript.
3. ant-core verifies the expected peer ID, the BLAKE3 public-key binding, and the ML-DSA signature.
4. Both sides derive independent client-to-server and server-to-client keys from the fresh KEM secret and transcript hash.
5. Every later request and response, including HELLO metadata, is protected by ordered ChaCha20-Poly1305 records.

The handshake, key derivation, replay protection, sequence handling, outer framing, and bounds all come from the shared ant-protocol module. JavaScript contains no parallel cryptographic protocol.

WebRTC still supplies certificate-pinned DTLS, ICE, SCTP, and DataChannel transport. The application session protects RPC and chunk plaintext against later compromise of only the classical DTLS key exchange, but it does not hide transport metadata, lengths, timing, or make the WebRTC stack itself post-quantum secure.

Browser workflows

Paid uploads

• Self-encrypts incrementally in a dedicated WASM worker.
• Stages encrypted records in IndexedDB instead of retaining the plaintext and complete encrypted file in page memory.
• Has ant-core locate targets, collect and verify quotes, calculate one payment plan, and store records using the shared native scheduling policy.
• Uses one narrow wallet callback for approval and the batched payment transaction.
• Never sends or persists the wallet key outside the page.
• Cleans staged records after success or failure.

Public downloads

• Accepts any public DataMap address, including files uploaded by ant-cli or another browser.
• Fetches and authenticates the DataMap from closest nodes instead of requiring manifest metadata.
• Resolves nested DataMaps and derives chunk metadata and file size in ant-core.
• Downloads, decrypts, and BLAKE3-verifies the complete file in Rust.
• Treats manifest filename, MIME type, and whole-file hash as optional metadata, not download authorization.

Random-access streaming

• Exposes a bounded Rust BrowserFileReader.
• Fetches and decrypts only records overlapping requested byte ranges.
• Uses a thin same-origin service worker to translate media requests into standards-compliant 200/206 responses.
• Supports disjoint seeks and suffix ranges used to locate MP4 metadata.
• Keeps the page-owned authenticated WebRTC session; no service worker or manifest server contacts storage nodes.

Compatibility and rollout

• Wire: browser protocol v4 requires a matching ant-node v4 listener. Plaintext v3 and encrypted v4 deliberately fail closed, so the browser client and node fleet must be redeployed together.
• Native wire: unchanged. ant-cli and Rust desktop callers retain the existing QUIC transport and public ant-core API.
• Storage: unchanged. Browser and native clients share the existing self-encrypted chunks and MessagePack DataMap representation; cross-client public addresses work.
• Payment: unchanged. Quote, commitment, EVM hash, transaction, and payment-proof formats are shared with native clients.
• API: adds browser-wasm bindings and browser-specific facade types without changing default native callers.
• Dependency: pins ant-protocol commit 4dad14b6947b6264e0b5982c976a385f9fdac9e0.

Coordinated draft stack

• Node/browser RPC: ant-node#220
• Transport: saorsa-transport#160
• Addresses/shared lookup: saorsa-core#158
• Portable/PQ protocol: ant-protocol#29

Draft dependencies are pinned by immutable Git SHA so CI does not depend on sibling worktrees.

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Reason: the client implements a new public transport/RPC surface and performs quote, payment, and storage operations while deliberately preserving existing native and stored-data formats.

Test evidence

Current-head protocol-v4 validation:

• cargo check -p ant-core --target wasm32-unknown-unknown --no-default-features --features browser-wasm
• cargo clippy -p ant-core --target wasm32-unknown-unknown --no-default-features --features browser-wasm -- -D warnings
• cargo test -p ant-core --lib browser::protocol::tests
  • 4 endpoint, framing, HELLO metadata, and SDP tests passed.
• Generated browser SDK from this exact ant-core tree:
  • release wasm-pack build passed;
  • TypeScript build and typecheck passed;
  • 8 unit/generated-WASM tests passed.
• Coordinated five-node integration against the pushed protocol revision:
  • ML-KEM/ML-DSA session establishment;
  • encrypted HELLO and iterative lookup;
  • public download;
  • signed quote and payment-proof handling;
  • paid upload and record read-back.
• git diff --check

Earlier headless-Chromium and public-testnet results validated WebRTC connectivity, decentralized lookup, range streaming, and paid uploads under protocol v3. They are useful transport evidence but do not validate the new v4 record layer. A real browser run against a matching deployed v4 node fleet remains required.

New dependencies

Rust/WASM surface:

• wasm-bindgen, wasm-bindgen-futures, web-sys, js-sys, serde-wasm-bindgen, gloo-timers, console_error_panic_hook, and browser-enabled getrandom.
• saorsa-dht-lookup from saorsa-core#158.
• Portable ant-protocol and pinned foundation draft revisions.

ADR

The browser architecture is covered by ADR-0003. The node-side transport and v4 cryptographic design are covered by ant-node ADR-0009.

Mitigation / rollback

Do not build or ship browser-wasm, and keep using the default native feature. Native ant-core, ant-cli, QUIC networking, and existing stored data remain available independently.

Remaining draft work

• Attach the required Linear issue and confirm the proposed T3 tier.
• Rebase onto current main.
• Replace draft dependency pins with reviewed releases before merge.
• Run protocol v4 in real Chrome, Firefox, and Safari against a matching deployed node fleet.
• Add relayed WebRTC and independently cacheable signed bootstrap records for production reachability/hardening.
• Complete-file download remains memory-bound; range streaming is the bounded path for large media.