Merge pull request #224 from gosuda/copilot/replace-policy-engine-with-mols

feat: replace relay selection policy engine with MOLS over GF(64)

Author: gosunuts

AGENTS.md

@@ -9,7 +9,7 @@ Architecture, product behavior, and design rationale belong in `docs/architectur
 - Prefer a single stable contract with one real owner.
 - Prefer local simplicity over premature or speculative abstraction.
 - Add indirection only when it removes real coupling or protects a real boundary.
-- Tests should protect stable contracts and invariants, not drive the spec.
+- Tests should protect real stable contracts and invariants, not drive the spec or exist only for regression prevention.
 
 ## Project Principles
 
@@ -30,4 +30,4 @@ Architecture, product behavior, and design rationale belong in `docs/architectur
 - CI commands: `make vet`, `make lint`, `make test`, `make vuln`.
 - `make tidy` is local maintenance, not a CI requirement.
 - Run tests only when explicitly requested.
-- If verification seems necessary, ask before running it.
+- If verification seems necessary, ask before running it.

cmd/portal-tunnel/README.md

@@ -72,6 +72,8 @@ portal expose --name myapp \
 - Routed HTTP mode automatically forwards `X-Forwarded-*`, rewrites upstream `Location` redirects back to the public route path, and strips loopback cookie domains while remapping cookie paths to the mounted route prefix.
 - `--name` is optional. When omitted, the CLI generates a name for that run.
 - `--relays` adds explicit relay API URLs for that run. Explicit relays are always kept connected and are not counted against `--max-active-relays`.
+- `--multi-hop` sets one ordered multi-hop relay path for that run.
+- `--multi-hop-depth` automatically selects one multi-hop relay path with that hop count.
 - `--discovery=false` disables the public registry seed list and the runtime relay discovery expansion loop for that run. With `--discovery=false`, only the explicit `--relays` values are used.
 - `--ban-mitm` enables strict rejection when the TLS self-probe detects termination in the path.
 - `--tcp` requests a dedicated TCP port on the relay for raw TCP services that do not use TLS (e.g., Minecraft, game servers).
@@ -81,6 +83,8 @@ Flags:
 
 ```text
 --relays          Portal relay API URLs (comma-separated, https only)
+--multi-hop       Ordered multi-hop relay API URLs, comma-separated
+--multi-hop-depth Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop
 --discovery       Include public registry relays and discover additional relay bootstraps
 --max-active-relays  Maximum number of auto-selected relays; explicit --relays are always included
 --ban-mitm        Ban relay when the MITM self-probe detects TLS termination

cmd/portal-tunnel/main.go

@@ -60,6 +60,7 @@ type exposeFlags struct {
 	udpAddr         string
 	tcp             bool
 	maxActiveRelays int
+	multiHopDepth   int
 }
 
 func runExposeCommand(args []string) error {
@@ -85,6 +86,7 @@ func runExposeCommand(args []string) error {
 	utils.StringFlagEnv(fs, &flags.udpAddr, "udp-addr", "", "Local UDP target address for relayed datagrams (host:port or port only); defaults to the target when --udp is enabled", "UDP_ADDR")
 	utils.BoolFlagEnv(fs, &flags.tcp, "tcp", false, "Request a dedicated TCP port on the relay for raw TCP services (no TLS; e.g., Minecraft, game servers)", "TCP_ENABLED")
 	utils.IntFlagEnv(fs, &flags.maxActiveRelays, "max-active-relays", 3, nil, "Maximum number of auto-selected relays to keep connected; explicit --relays are always included", "MAX_ACTIVE_RELAYS")
+	utils.IntFlagEnv(fs, &flags.multiHopDepth, "multi-hop-depth", 0, nil, "Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop", "MULTI_HOP_DEPTH")
 
 	if err := utils.ParseFlagSet(fs, args, printExposeUsage); err != nil {
 		if errors.Is(err, flag.ErrHelp) {
@@ -124,6 +126,7 @@ func runExposeCommand(args []string) error {
 		UDPEnabled:      flags.udp,
 		TCPEnabled:      flags.tcp,
 		MultiHop:        utils.SplitCSV(flags.multiHopCSV),
+		MultiHopDepth:   flags.multiHopDepth,
 		BanMITM:         flags.banMITM,
 		MaxActiveRelays: flags.maxActiveRelays,
 		Metadata: types.LeaseMetadata{
@@ -308,6 +311,7 @@ func printExposeUsage(w io.Writer) {
 			"portal expose 3000 --ban-mitm",
 			"portal expose 3000 --relays https://portal.example.com --discovery=false",
 			"portal expose 3000 --multi-hop https://entry.example.com,https://transit.example.com,https://exit.example.com",
+			"portal expose 3000 --multi-hop-depth 3",
 		},
 	)
 }

docs/src/routes/cli-reference/+page.md

@@ -58,6 +58,8 @@ Instead of a positional target, you can use `--http-route` for multi-service rou
 |------|------|---------|-------------|
 | `--relays` | string | _(registry)_ | Portal relay API URLs (comma-separated, https only) |
 | `--discovery` | bool | `true` | Include public registry relays and discover additional bootstraps |
+| `--multi-hop` | string | | Ordered multi-hop relay API URLs, comma-separated |
+| `--multi-hop-depth` | int | `0` | Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop |
 | `--max-active-relays` | int | `3` | Maximum auto-selected relays to keep connected; explicit relays are always included |
 | `--ban-mitm` | bool | `true` | Ban relay when the MITM self-probe detects TLS termination |
 | `--identity-path` | string | `./identity.json` | Identity JSON file path; created automatically when missing |
@@ -113,6 +115,18 @@ Disable relay discovery:
 portal expose 3000 --relays https://portal.example.com --discovery=false
 ```
 
+Explicit multi-hop route:
+
+```bash
+portal expose 3000 --multi-hop https://entry.example.com,https://transit.example.com,https://exit.example.com
+```
+
+Automatic multi-hop route:
+
+```bash
+portal expose 3000 --multi-hop-depth 3
+```
+
 Warning-only MITM mode:
 
 ```bash

docs/src/routes/configuration/+page.md

@@ -95,6 +95,8 @@ The `portal expose` subcommand accepts the following flags. Flags that read from
 |------|---------|------|---------|-------------|
 | `--relays` | | string | _(registry)_ | Additional Portal relay server API URLs (comma-separated; scheme omitted defaults to https) |
 | `--discovery` | | bool | `true` | Include public registry relays and discover additional relay bootstraps |
+| `--multi-hop` | `MULTI_HOP` | string | | Ordered multi-hop relay API URLs, comma-separated |
+| `--multi-hop-depth` | `MULTI_HOP_DEPTH` | int | `0` | Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop |
 | `--max-active-relays` | `MAX_ACTIVE_RELAYS` | int | `3` | Maximum auto-selected relays to keep connected; explicit relays are always included |
 | `--ban-mitm` | `BAN_MITM` | bool | `true` | Ban relay when the MITM self-probe detects TLS termination |