feat: add IVNP relay overlay support

- Introduced RelayDescriptor field for IVNP destination in identity.go.
- Added new relay overlay paths in paths.go.
- Created documentation for IVNP Relay Overlay detailing configuration and usage.
- Implemented tests for overlay admission and refresh logic.
- Developed IVNP overlay handling for Unix systems, with fallback for unsupported platforms.
- Established HTTP server for handling relay connections and leases.
- Added relay binding management to ensure secure connections between local and remote leases.
- Implemented tests for relay binding and overlay connection handling.

Author: gosunuts

.env.example

@@ -28,7 +28,11 @@
 # ─────────────────────────────────────────────────────────────────────────────
 
 # Public HTTPS origin browsers and tunnel clients use. Must be publicly
-# resolvable when DISCOVERY=true; localhost and other local-only names are
+# resolvable when DISCOVERY=true
+
+# Optional IVNP router config (Linux/macOS). Empty keeps relay traffic direct.
+# The destination key is stored beside this config as <path>.destination.
+IVNP_CONFIG=; localhost and other local-only names are
 # rejected by public discovery.
 PORTAL_URL=https://localhost
 
@@ -63,6 +67,10 @@ MAX_PORT=0
 # reachable PORTAL_URL.
 DISCOVERY=true
 
+# Optional IVNP router config (Linux/macOS). Empty keeps relay traffic direct.
+# The destination key is stored beside this config as <path>.destination.
+IVNP_CONFIG=
+
 # Comma-separated relay API URLs to seed discovery from.
 BOOTSTRAPS=
 

README.md

@@ -37,10 +37,6 @@ keeps routing and x402 payment policy in the tunnel process, and avoids requirin
   after real traffic begins. It compares TLS keying material exported on both
   sides and treats a mismatch as suspected relay-side TLS termination.
 
-- **Multi-Hop Relay Routing** - Chain multiple relays together so no single
-  relay knows both the origin and the destination. Use `--multi-hop-depth 3` to
-  select a three-hop route automatically.
-
 - **No Accounts, No API Keys** - Authentication uses SIWE-compatible signing
   with a locally generated secp256k1 key pair. No email, no registration, no
   vendor lock-in.
@@ -62,7 +58,7 @@ keeps routing and x402 payment policy in the tunnel process, and avoids requirin
 | SNI hiding (ECH) | **Yes** | No | No | No |
 | MITM self-probe | **Built-in** | No | No | No |
 | Multi-relay failover | **Yes** | Managed | Built-in | No |
-| Multi-hop routing | **Yes** | No | No | No |
+| Optional relay overlay | **IVNP** | No | No | No |
 | Account required | **No** | Yes | Yes | No |
 | Native x402 payments | **Yes** | No | No | No |
 
@@ -127,8 +123,6 @@ portal expose --name paid-app \
 # Raw TCP port (Minecraft, databases, SSH)
 portal expose localhost:25565 --name minecraft --tcp
 
-# Three-hop route for maximum anonymity
-portal expose 3000 --multi-hop-depth 3
 ```
 
 See [CLI Reference](cmd/portal-tunnel/README.md) for the full route syntax and
@@ -139,7 +133,7 @@ helper endpoints.
 
 Use Portal Agent directly when tunnels should keep running outside your terminal.
 It runs as a local OS service, keeps every tunnel in one TOML config alive, and
-provides a dashboard for relay and multi-hop management.
+provides a dashboard for public relay management.
 
 ```bash
 portal agent run --config config.toml
@@ -190,20 +184,13 @@ When ECH is enabled, the relay also cannot see the actual tenant hostname. It
 routes by an opaque token derived from the tunnel identity, while the real SNI
 stays inside the ECH-protected ClientHello.
 
-## How Multi-Hop Routing Works
-
-```text
-Browser
-  -> Entry relay  (sees only the opaque route hostname)
-  -> Middle relay (sees only the next-hop token)
-  -> Exit relay   (sees only the reverse session token)
-  -> Portal tunnel
-  -> Local service
-```
+## Optional Relay Overlay
 
-Each relay in the chain knows only its immediate neighbors. No single relay
-holds the full path. Tenant TLS still terminates only on your side, so no relay
-in the chain receives tenant TLS plaintext.
+Relay operators can enable IVNP for authenticated relay exchanges. I2P owns
+internal routing; Portal owns relay admission and lease authorization. The
+standard tunnel client keeps its direct reverse backhaul. See the
+[overlay guide](docs/src/routes/ivnp-overlay/+page.md) for configuration and the
+lease binding API.
 
 ## Public Relay Registry
 

README.zh-CN.md

@@ -27,7 +27,6 @@ Portal 是一个本地隧道运行时和中继网络。它通过自托管或公
 
 - **内置 MITM 检测** - Portal 会在真实流量开始后主动自探测自己的连接。它会比较两端导出的 TLS 密钥材料，并把不匹配视为疑似中继侧 TLS 终止。
 
-- **多跳中继路由** - 将多个中继串联起来，使单个中继无法同时知道来源和目的地。使用 `--multi-hop-depth 3` 可以自动选择三跳路由。
 
 - **无账户，无 API Key** - 身份认证使用本地生成的 secp256k1 密钥对进行 SIWE 兼容签名。无需邮箱，无需注册，也没有厂商锁定。
 
@@ -88,8 +87,6 @@ portal expose --name paid-app \
 # 原始 TCP 端口（Minecraft、数据库、SSH）
 portal expose localhost:25565 --name minecraft --tcp
 
-# 三跳路由，获得更高匿名性
-portal expose 3000 --multi-hop-depth 3
 ```
 
 对于付费路由，支付策略运行在隧道进程内，而不是中继上。默认使用 Sui mainnet；加上 `--x402-testnet` 可切换到 Sui testnet，这个选择与中继自身的支付设置无关。隧道会在同一个公共 origin 上提供 `/x402/client.js` 和 `/x402/prepare`。浏览器前端可以导入 `/x402/client.js` 并调用 `x402Fetch()`；原生客户端可以直接调用 `/x402/prepare`，用自己的 Sui 运行时签名返回的交易，并发送签名后的 `X-PAYMENT`。
@@ -152,18 +149,9 @@ Browser
 
 启用 ECH 时，中继也看不到真实租户主机名。它会通过从隧道身份派生出的不透明 token 进行路由，而真实 SNI 保留在 ECH 保护的 ClientHello 中。
 
-## 多跳路由如何工作
+## 可选 IVNP 中继覆盖网络
 
-```text
-Browser
-  -> Entry relay  (只看到不透明 route hostname)
-  -> Middle relay (只看到 next-hop token)
-  -> Exit relay   (只看到 reverse session token)
-  -> Portal tunnel
-  -> Local service
-```
-
-链中的每个中继只知道自己的直接相邻节点。没有任何单个中继掌握完整路径。租户 TLS 仍然只在你这边终止，因此链中的任何中继都不会收到租户 TLS 明文。
+IVNP/I2P 负责中继之间的连接和内部多跳路由，Portal 负责公开中继选择与租约授权。默认隧道客户端仍使用直接反向连接。参见 [IVNP 指南](docs/src/routes/ivnp-overlay/+page.md)。
 
 ## 公共中继 Registry
 

cmd/portal-tunnel/README.md

@@ -149,9 +149,7 @@ Common `portal expose` flags:
 --name               Public hostname prefix; auto-generated when omitted
 --relays             Additional relay API URLs, comma-separated
 --discovery          Include registry relays and relay discovery expansion
---max-active-relays  Maximum auto-selected single-hop relays; multi-hop uses every eligible relay as an entry
---multi-hop          Ordered multi-hop relay API URLs, comma-separated
---multi-hop-depth    Automatically create this-depth multi-hop routes for every eligible entry relay
+--max-active-relays  Maximum auto-selected public relays
 --ban-mitm           Ban relay when the MITM self-probe detects termination
 --ech                Enable ECH hostname privacy for TLS stream tunnels (disabled by default)
 --identity-path      Identity JSON file path; created automatically when missing
@@ -186,7 +184,7 @@ portal agent stop
 portal agent restart
 ```
 
-The dashboard can edit basic tunnel settings, relays, and multi-hop routes. Add
+The dashboard can edit basic tunnel settings, relays, and public relay selection. Add
 Tunnel opens a small form for name, target or HTTP routes, x402 payment settings,
 relays, discovery, and max active relays. After creation, routed HTTP paths,
 route-level x402 amounts, payment network, and discovery mode are read-only in
@@ -206,8 +204,6 @@ restart the agent or tunnel to change them.
   `--x402-pay-to`. Sui is the default; Casper additionally requires
   `--x402-network casper:...` and the wCSPR contract in `--x402-asset`.
   The default CSPR.cloud facilitator also requires `CSPR_CLOUD_API_KEY`.
-- `--multi-hop` cannot be combined with `--multi-hop-depth`.
-- Multi-hop currently supports only the default SNI TLS stream transport.
 - `--tcp` and `--udp` require matching relay transport support.
 
 ## More Docs

cmd/relay-server/main.go

@@ -34,6 +34,7 @@ func main() {
 }
 
 type relayServerConfig struct {
+	IVNPConfig         string
 	PortalURL          string
 	FrontendDir        string
 	IdentityPath       string
@@ -99,6 +100,7 @@ func resolveRelayServerConfig(args []string) (relayServerConfig, error) {
 func registerRelayServerFlags(fs *flag.FlagSet, cfg *relayServerConfig) {
 	utils.StringFlagEnv(fs, &cfg.PortalURL, "portal-url", "https://localhost", "portal base URL", "PORTAL_URL")
 	utils.StringFlagEnv(fs, &cfg.FrontendDir, "frontend-dir", "", "custom SPA directory containing index.html; embedded frontend is used when empty", "PORTAL_FRONTEND_DIR")
+	utils.StringFlagEnv(fs, &cfg.IVNPConfig, "ivnp-config", "", "IVNP router config path; enables the optional relay overlay (Linux/macOS, requires DISCOVERY)", "IVNP_CONFIG")
 	utils.StringFlagEnv(fs, &cfg.IdentityPath, "identity-path", "./.portal-certs", "directory path for relay identity, policy state, and keyless materials", "IDENTITY_PATH")
 	utils.StringFlagEnv(fs, &cfg.Bootstraps, "bootstraps", "", "bootstrap relay API URLs; merged with bootstrap relays when discovery is enabled", "BOOTSTRAPS")
 	utils.BoolFlagEnv(fs, &cfg.DiscoveryEnabled, "discovery", false, "serve relay discovery endpoints and poll discovery peers", "DISCOVERY")
@@ -173,6 +175,7 @@ func runServeCommand(args []string) error {
 func runServer(ctx context.Context, cfg relayServerConfig) error {
 	server, err := portal.NewServer(portal.ServerConfig{
 		PortalURL:         cfg.PortalURL,
+		IVNPConfig:        cfg.IVNPConfig,
 		IdentityPath:      cfg.IdentityPath,
 		Bootstraps:        utils.SplitCSV(cfg.Bootstraps),
 		DiscoveryEnabled:  cfg.DiscoveryEnabled,

docker-compose.yml

@@ -25,6 +25,7 @@ services:
       PORTAL_FRONTEND_DIR: ${PORTAL_FRONTEND_DIR:-}
       BOOTSTRAPS: ${BOOTSTRAPS:-}
       DISCOVERY: ${DISCOVERY:-false}
+      IVNP_CONFIG: ${IVNP_CONFIG:-}
       IDENTITY_PATH: ${IDENTITY_PATH:-/portal-certs}
 
       API_PORT: 4017

docs/adr/0001-relay-overlay.md

@@ -22,3 +22,14 @@ No compatibility implementation of Portal hop routing is retained.
 Overlay reachability does not establish Portal admission or public ingress
 health. Overlay latency must not become the public relay performance score.
 NATed intermediate capacity belongs to IVNP, not a Portal worker catalog.
+
+The first overlay surface is the lease binding API, not a new SDK path planner.
+It links two already authorized leases and does not manage their renewal or TLS
+configuration. This is deliberately an API integration surface; ordinary CLI
+exposures keep their direct backhaul. Future convenience APIs must preserve the
+single destination boundary rather than recreate intermediate route state.
+
+I2P's authenticated stream endpoints plus Portal's signed destination binding
+establish relay identity. Catalog admission is separate from public health.
+Live NAT participation and the narrower Portal-only transit restrictions from
+#358 are deployment/upstream questions, not guarantees of this implementation.

docs/architecture.md

@@ -8,6 +8,18 @@ Relay selection returns public relay priorities. Portal does not construct an
 ordered list of intermediate relays. Explicit relay URLs, transport eligibility,
 admission, expiry, health, and load remain Portal responsibilities.
 
+The optional `portal/overlay` runtime embeds IVNP on Linux/macOS. It owns the
+destination, bounded authenticated exchanges, and stream shutdown. Catalog
+admission remains in `portal/discovery`; incoming I2P reachability cannot promote
+a public relay's health or affect its measured HTTPS latency.
+
+An existing SNI lease may hold one `relayBinding` to a remote lease with the same
+tenant identity. The remote token bounds the attachment's lifetime. Incoming
+overlay traffic always claims a local reverse session and cannot follow another
+attachment. TLS endpoint configuration remains the API caller's responsibility;
+the standard SDK/CLI does not orchestrate bindings. See the
+[IVNP overlay guide](src/routes/ivnp-overlay/+page.md) for the complete contract.
+
 See [ADR index](adr/README.md) for the relay overlay migration decision and
 [the site architecture documentation](src/routes/architecture/+page.md) for the
 rest of the system.

docs/src/lib/components/landing/CoreFeaturesGrid.svelte

@@ -26,9 +26,9 @@
 		},
 		{
 			eyebrow: 'Mesh',
-			title: 'Relay pools and multi-hop',
+			title: 'Relay pools and IVNP',
 			description:
-				'Use discovered relays for failover or chain relays to split path visibility.'
+				'Select public relays for failover and optionally connect relays through IVNP.'
 		},
 		{
 			eyebrow: 'Ops',

docs/src/lib/nav.ts

@@ -56,6 +56,7 @@ export const guidesNavigation: NavSection[] = [
 		title: 'Guides',
 		items: [
 			{ title: 'Self-Hosting', href: '/self-hosting' },
+			{ title: 'IVNP Relay Overlay', href: '/ivnp-overlay' },
 			{ title: 'Portal Agent', href: '/portal-agent' },
 			{ title: 'TCP/UDP Tunneling', href: '/tcp-udp-tunneling' },
 			{ title: 'Game Server Hosting', href: '/game-server-hosting' },