Onion service (.onion) support

[igor53627]

Overview

Add support for accessing Tor hidden services (.onion domains) from the browser.

Background

Onion services (formerly hidden services) allow accessing servers that are only reachable through the Tor network. This is a key Tor feature that webtor-rs currently lacks.

Implementation Plan

Sub-Issues (in order)

1. Step 1: Onion address parsing and validation #37 - Onion address parsing and validation
2. Step 2: HSDir descriptor fetching #38 - HSDir descriptor fetching
3. Step 3: HS descriptor parsing #39 - HS descriptor parsing
4. Step 4: Introduction and rendezvous circuits #40 - Introduction and rendezvous circuits
5. Step 5: HS rendezvous protocol #41 - HS rendezvous protocol
6. Step 6: HTTP integration and .onion URL handling #42 - HTTP integration and .onion URL handling
7. Step 7: Onion service tests and documentation #43 - Tests and documentation

Architecture

+----------------+     +----------------+     +------------------+
|  TorHttpClient |---->|   HsClient     |---->| IntroCircuit     |
|  (.onion URLs) |     | (orchestrator) |     | RendCircuit      |
+----------------+     +----------------+     +------------------+
                              |
                              v
                       +----------------+
                       | tor-hscrypto   |  (address parsing, crypto)
                       | tor-netdoc     |  (descriptor parsing)
                       +----------------+

Technical Requirements

Key Arti Crates (already in vendor/)

• tor-hscrypto - Onion address parsing, blinded keys, subcredentials
• tor-netdoc - HS descriptor parsing
• tor-hsclient - Reference implementation (adapt, don't use directly)

Protocol Steps

1. Parse v3 .onion address -> extract ed25519 identity
2. Compute blinded key for current time period
3. Fetch HS descriptor from HSDir relays
4. Decrypt descriptor, extract intro points
5. Build intro circuit + rendezvous circuit
6. Send INTRODUCE1, receive RENDEZVOUS2
7. Open stream to hidden service

Challenges

• Complexity of the HS protocol (multiple cryptographic layers)
• Need to adapt Arti code while keeping WASM compatibility
• Increased connection establishment time (~10-20s)

References

• Tor Rendezvous Spec: https://spec.torproject.org/rend-spec-v3
• Arti HS implementation: https://gitlab.torproject.org/tpo/core/arti/-/tree/main/crates/tor-hsclient

Acceptance Criteria

• Can access .onion sites through webtor-rs
• Proper error handling for offline/invalid services
• Documentation for .onion usage
• Integration tests with test onion services