feat: add direct WebRTC browser support

[mickvandijke]

Summary

Adds a direct, gateway-free browser endpoint to ant-node.

Browser clients can cold-bootstrap from one self-contained WebRTC Direct multiaddress, authenticate the node's persistent ML-DSA identity, establish a fresh ML-KEM-derived application session, walk the DHT themselves, read immutable chunks, obtain signed storage quotes, and submit paid immutable writes directly to closest storage nodes.

The HTTP manifest used by the local demo carries bootstrap metadata only. It never proxies file bytes, performs lookup for the browser, or receives wallet secrets.

Companion browser client: ant-client#186

Architecture

Direct browser transport

• Runs a separate ICE-lite + DTLS + SCTP WebRTC Direct listener alongside native QUIC.
• Persists the DTLS certificate so the certificate-pinned multiaddress remains stable across restarts.
• Publishes canonical /webrtc-direct/certhash/.../p2p/... endpoints through Saorsa's capability-negotiated V2 address plane.
• Preserves the existing V1 QUIC-only publication for older peers.
• Uses one persistent reliable ordered DataChannel per pooled browser/node association.
• Applies bounded frame/message sizes, connection/channel/request limits, 16-KiB DataChannel fragmentation, backpressure, cancellation, and payload-scaled deadlines.

Shared post-quantum application session

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

Before reading any RPC, the listener:

1. receives a versioned ephemeral ML-KEM-768 encapsulation key;
2. encapsulates a fresh shared secret;
3. signs a domain-separated transcript containing the client hello, KEM ciphertext, and ANT peer ID with the node's persistent ML-DSA-65 key; and
4. derives direction-separated application keys from the KEM secret and transcript hash.

Every later request and response, including HELLO, FIND_NODE, GET_CHUNK, QUOTE_CHUNK, PUT_CHUNK, errors, headers, and raw chunk bytes, is protected with ordered ChaCha20-Poly1305 records. Per-direction 64-bit sequences reject replay and reordering. Malformed handshakes, wrong identities, modified ciphertext, unexpected sequences, and authentication failures close the association.

The client and node use the same ant-protocol handshake, key derivation, encrypted-record, framing, and bounds implementation. ant-node owns only the RPC adapter and request admission logic.

Security boundary

The multiaddress certificate fingerprint still authenticates the WebRTC DTLS connection. The application session independently authenticates the ANT peer ID and protects RPC plaintext with post-quantum-derived keys.

This means compromise of only the classical DTLS key is insufficient to impersonate the ANT node or decrypt captured application records. It does not make ICE, DTLS, SCTP, certificate handling, packet lengths, timing, availability, or the WebRTC stack itself post-quantum secure.

The session authenticates the node to the browser, not the browser user to the node. Client authority remains method-specific; paid storage still requires the normal wallet transaction and verifiable payment proof.

Browser RPC surface

The versioned browser protocol remains deliberately narrow:

• HELLO returns protocol, peer, endpoint, capability, chunk-size, and payment metadata inside the already authenticated/encrypted session.
• FIND_NODE returns one bounded local closest-node view and never performs network lookup on the browser's behalf.
• GET_CHUNK returns only locally stored immutable data.
• QUOTE_CHUNK uses the ordinary signed quote and commitment path.
• PUT_CHUNK accepts content-addressed bytes only after the ordinary payment-proof and storage admission checks.

The node reuses native quote, commitment, pricing, payment-proof, content-address verification, and PUT admission behavior. Browser sessions are not inserted into routing tables and cannot invoke arbitrary DHT operations.

Endpoint discovery and deployment

• Standard builds enable WebRTC Direct; minimal/native-only builds may omit it with --no-default-features.
• Configuration can disable the listener with webrtc_direct.enabled = false.
• Public nodes map the browser UDP listener into the existing externally allowed UDP range and advertise the native transport's discovered external IP.
• ant-devnet can start a five-node browser-enabled network, publish a public file through normal storage admission, run local Anvil, and serve bootstrap metadata.
• Browser protocol v4 requires a coordinated browser-client and node deployment. Plaintext v3 and encrypted v4 fail closed rather than silently downgrading.
• Native QUIC, V1 address publication, storage formats, and existing node-to-node post-quantum networking are unchanged.
• This branch pins ant-protocol commit 4dad14b6947b6264e0b5982c976a385f9fdac9e0.

Coordinated draft stack

• Transport: saorsa-transport#160
• Addresses/shared lookup: saorsa-core#158
• Portable/PQ protocol: ant-protocol#29
• Companion browser client: ant-client#186

Draft dependencies are pinned by immutable Git SHA so this branch builds outside the sibling-worktree development setup.

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: this adds a public node transport/protocol and V2 DHT endpoint-discovery path. It intentionally reuses existing stored-data and payment formats.

Compatibility

• Browser wire: breaking relative to the experimental plaintext v3 protocol; v4 uses a mandatory PQ handshake and encrypted records.
• Native wire: unchanged QUIC and V1 address publication.
• Storage: unchanged content-addressed chunks and public DataMaps.
• Payments: unchanged quote, commitment, transaction, and proof formats.
• API/configuration: adds the webrtc-direct feature, listener settings, devnet support, endpoint artifact, and browser RPC module.

Test evidence

Current-head protocol-v4 validation:

• cargo clippy --lib --features webrtc-direct -- -D warnings
• cargo test --lib web_rtc --features webrtc-direct
  • 12 WebRTC listener, endpoint, request, discovery, payment-hash, and certificate tests passed.
• cargo test --test webrtc_direct_devnet --features webrtc-direct -- --ignored --nocapture
  • 1 five-node integration passed against the pushed ant-protocol revision.
  • Starts local Anvil and five nodes.
  • Completes ML-KEM/ML-DSA session establishment and encrypted HELLO.
  • Performs iterative lookup and public download.
  • Verifies a real signed quote and payment proof.
  • Accepts a paid PUT through the ordinary verifier and reads the record back.
• Shared ant-protocol cryptographic tests: 5 passed.
• ant-core WASM check and clippy pass.
• Browser SDK release build, typecheck, and 8 tests pass.
• ADR governance and git diff --check pass.

Earlier headless-Chromium and independently deployed public-testnet tests validated WebRTC connectivity, multi-node lookup, range streaming, and paid uploads under protocol v3. They remain useful transport evidence but do not validate v4. A matching v4 testnet must be deployed for the next real-browser run.

ADR

ADR-0009: Direct browser clients over WebRTC Direct now records:

• the exact ML-KEM-768, ML-DSA-65, ChaCha20-Poly1305 design;
• independent DTLS-certificate and ANT-identity bindings;
• shared ant-protocol ownership;
• framing, replay protection, security limits, and operational costs;
• coordinated v4 rollout requirements; and
• current local-v4 evidence separately from historical public-v3 evidence.

The ADR remains Proposed pending human review.

New dependencies

• saorsa-transport 0.35.3 with its optional webrtc-direct feature.
• self_encryption 0.36 for the devnet's published browser fixture.
• The coordinated ant-protocol Git revision above; replace draft pins with reviewed releases before merge.

Mitigation / rollback

Disable webrtc_direct.enabled or build without the default WebRTC feature. Native QUIC, existing ant-core/ant-cli clients, payment behavior, and stored data remain usable 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.
• Deploy a matching v4 testnet and run real Chrome, Firefox, and Safari interoperability tests.
• Review production rate limits and deployment defaults.
• Relayed WebRTC for NATed storage nodes remains follow-up work; this PR directly serves publicly reachable nodes.