Merge pull request #288 from gosuda/feat/casper-x402-tunnel

Feat/casper x402 tunnel

Author: gosunuts

cmd/portal-tunnel/README.md

@@ -65,12 +65,14 @@ portal expose --name paid-app \
   --x402-pay-to 0x...
 ```
 
-Routed HTTP serves `/x402/client.js` and `/x402/prepare` on the tunnel origin so
-an upstream browser frontend can run the same in-page Sui wallet payment flow as
-the standalone payment app. Native clients should use `/x402/prepare` directly
-and send the signed payload as `X-PAYMENT`. The tunnel still verifies and
-settles payment before proxying the paid route. Paid routes use Sui mainnet by
-default; add `--x402-testnet` to use Sui testnet.
+Routed HTTP serves `/x402/client.js` and `/x402/prepare` on the tunnel origin
+for the Sui wallet flow. Casper clients instead consume the protected route's
+402 requirements, sign with an external Casper x402 SDK, and retry with
+`PAYMENT-SIGNATURE` or `X-PAYMENT`; Portal settles it through the configured
+Casper facilitator before proxying the request.
+The hosted CSPR.cloud facilitator requires `CSPR_CLOUD_API_KEY`, which Portal
+sends as its server-side authorization token. A custom unauthenticated
+facilitator does not require the token.
 
 Raw TCP and UDP:
 
@@ -83,7 +85,7 @@ portal expose localhost:8080 --udp --udp-addr localhost:19132 --name game
 
 ```text
 portal expose [flags] <target>
-portal expose [flags] --http-route "PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT]" [...]
+portal expose [flags] --http-route "PATH=UPSTREAM [METHOD[,METHOD...]:PAYMENT_AMOUNT]" [...]
 portal list [flags]
 portal agent run [flags]
 portal agent dashboard [flags]
@@ -111,9 +113,13 @@ Common `portal expose` flags:
 --owner              Service owner metadata
 --hide               Hide service from relay listing screens
 --serve              Serve a local static site: a directory (served with index.html) or an HTML file (folder served with that file as SPA/CSR entry)
---http-route         HTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT] form
---x402-pay-to        Sui USDC payment recipient address for this tunnel
---x402-testnet       Use Sui testnet for tunnel x402 payments
+--http-route         HTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:PAYMENT_AMOUNT] form
+--x402-pay-to        Payment recipient address for this tunnel
+--x402-testnet       Use Sui testnet when --x402-network is omitted
+--x402-network       Optional Sui or Casper CAIP-2 network
+--x402-asset         wCSPR CEP-18 contract hash required by Casper
+--x402-endpoint      Optional Sui RPC or Casper facilitator endpoint; repeatable
+--x402-facilitator-token  Casper facilitator authorization token; defaults to CSPR_CLOUD_API_KEY
 --tcp                Request a dedicated raw TCP port on the relay
 --udp                Enable public UDP relay
 --udp-addr           Local UDP target
@@ -132,11 +138,12 @@ portal agent restart
 ```
 
 The dashboard can edit basic tunnel settings, relays, and multi-hop routes. Add
-Tunnel opens a small form for name, target or HTTP routes, x402 pay-to/testnet,
+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
-the Settings pane. Edit `http_routes`, `x402_pay_to`, `x402_testnet`, or
-`discovery` in TOML, then restart the agent or tunnel to change them.
+the Settings pane. Edit `http_routes`, `x402_pay_to`, `x402_testnet`,
+`x402_network`, `x402_asset`, `x402_endpoints`, `x402_facilitator_token`, or `discovery` in TOML, then
+restart the agent or tunnel to change them.
 
 ## Constraints
 
@@ -146,9 +153,10 @@ the Settings pane. Edit `http_routes`, `x402_pay_to`, `x402_testnet`, or
   (`..`) is refused, but a symlink inside the folder that points outside it is
   still followed, so only serve folders you trust.
 - `--http-route` cannot be combined with `--udp`.
-- Route payment amounts are USDC values such as `0.01`, are part of
-  `--http-route`, and require `--x402-pay-to`; add `--x402-testnet` for Sui
-  testnet, otherwise payments use Sui mainnet.
+- Route payment amounts such as `0.01` are part of `--http-route` and require
+  `--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.

cmd/portal-tunnel/agent/config.go

@@ -39,28 +39,32 @@ type AgentConfig struct {
 }
 
 type TunnelConfig struct {
-	ID              string            `koanf:"id"`
-	Name            string            `koanf:"name"`
-	TargetAddr      string            `koanf:"target"`
-	HTTPRoutes      []HTTPRouteConfig `koanf:"http_routes"`
-	RelayURLs       []string          `koanf:"relays"`
-	Discovery       *bool             `koanf:"discovery"`
-	IdentityPath    string            `koanf:"identity_path"`
-	IdentityJSON    string            `koanf:"identity_json"`
-	UDPEnabled      bool              `koanf:"udp"`
-	UDPAddr         string            `koanf:"udp_addr"`
-	TCPEnabled      bool              `koanf:"tcp"`
-	MultiHop        []string          `koanf:"multi_hop"`
-	MultiHopDepth   int               `koanf:"multi_hop_depth"`
-	BanMITM         *bool             `koanf:"ban_mitm"`
-	MaxActiveRelays int               `koanf:"max_active_relays"`
-	Description     string            `koanf:"description"`
-	Tags            []string          `koanf:"tags"`
-	Owner           string            `koanf:"owner"`
-	Thumbnail       string            `koanf:"thumbnail"`
-	Hide            bool              `koanf:"hide"`
-	X402PayTo       string            `koanf:"x402_pay_to"`
-	X402Testnet     bool              `koanf:"x402_testnet"`
+	ID                   string            `koanf:"id"`
+	Name                 string            `koanf:"name"`
+	TargetAddr           string            `koanf:"target"`
+	HTTPRoutes           []HTTPRouteConfig `koanf:"http_routes"`
+	RelayURLs            []string          `koanf:"relays"`
+	Discovery            *bool             `koanf:"discovery"`
+	IdentityPath         string            `koanf:"identity_path"`
+	IdentityJSON         string            `koanf:"identity_json"`
+	UDPEnabled           bool              `koanf:"udp"`
+	UDPAddr              string            `koanf:"udp_addr"`
+	TCPEnabled           bool              `koanf:"tcp"`
+	MultiHop             []string          `koanf:"multi_hop"`
+	MultiHopDepth        int               `koanf:"multi_hop_depth"`
+	BanMITM              *bool             `koanf:"ban_mitm"`
+	MaxActiveRelays      int               `koanf:"max_active_relays"`
+	Description          string            `koanf:"description"`
+	Tags                 []string          `koanf:"tags"`
+	Owner                string            `koanf:"owner"`
+	Thumbnail            string            `koanf:"thumbnail"`
+	Hide                 bool              `koanf:"hide"`
+	X402PayTo            string            `koanf:"x402_pay_to"`
+	X402Testnet          bool              `koanf:"x402_testnet"`
+	X402Network          string            `koanf:"x402_network"`
+	X402Asset            string            `koanf:"x402_asset"`
+	X402Endpoints        []string          `koanf:"x402_endpoints"`
+	X402FacilitatorToken string            `koanf:"x402_facilitator_token"`
 }
 
 type HTTPRouteConfig struct {
@@ -221,6 +225,10 @@ func tunnelConfigDocumentMap(cfg TunnelConfig) map[string]any {
 	if cfg.X402Testnet {
 		out["x402_testnet"] = cfg.X402Testnet
 	}
+	addStringDocumentField(out, "x402_network", cfg.X402Network)
+	addStringDocumentField(out, "x402_asset", cfg.X402Asset)
+	addStringSliceDocumentField(out, "x402_endpoints", cfg.X402Endpoints)
+	addStringDocumentField(out, "x402_facilitator_token", cfg.X402FacilitatorToken)
 	return out
 }
 
@@ -268,6 +276,10 @@ func (cfg *Config) ApplyDefaults(configPath string) error {
 		t := &cfg.Tunnels[i]
 		t.ID = strings.TrimSpace(t.ID)
 		t.Name = strings.TrimSpace(t.Name)
+		t.X402Network = strings.ToLower(strings.TrimSpace(t.X402Network))
+		t.X402Asset = strings.TrimSpace(t.X402Asset)
+		t.X402Endpoints = compactStrings(t.X402Endpoints)
+		t.X402FacilitatorToken = strings.TrimSpace(t.X402FacilitatorToken)
 		if t.ID == "" {
 			t.ID = t.Name
 		}
@@ -372,9 +384,22 @@ func (cfg TunnelConfig) Validate() error {
 			return fmt.Errorf("tunnel %q http route %q methods require amount", cfg.ID, strings.TrimSpace(route.Prefix))
 		}
 	}
+	if strings.HasPrefix(strings.ToLower(strings.TrimSpace(cfg.X402Network)), "casper:") && strings.TrimSpace(cfg.X402Asset) == "" {
+		return fmt.Errorf("tunnel %q Casper payments require x402_asset", cfg.ID)
+	}
 	return nil
 }
 
+func compactStrings(values []string) []string {
+	out := values[:0]
+	for _, value := range values {
+		if value = strings.TrimSpace(value); value != "" {
+			out = append(out, value)
+		}
+	}
+	return out
+}
+
 func validateAgentPathComponent(name, value string) error {
 	value = strings.TrimSpace(value)
 	if value == "" {

cmd/portal-tunnel/agent/dashboard.go

@@ -62,6 +62,9 @@ const (
 	agentDashboardAddFieldHTTPRoutes
 	agentDashboardAddFieldX402PayTo
 	agentDashboardAddFieldX402Testnet
+	agentDashboardAddFieldX402Network
+	agentDashboardAddFieldX402Asset
+	agentDashboardAddFieldX402Endpoints
 	agentDashboardAddFieldRelays
 	agentDashboardAddFieldDiscovery
 	agentDashboardAddFieldMaxRelays
@@ -100,16 +103,19 @@ type agentDashboardModel struct {
 	routeDraft    []string
 	draftTunnelID string
 
-	addingTunnel   bool
-	addFocus       int
-	addName        textinput.Model
-	addTarget      textinput.Model
-	addHTTPRoutes  textinput.Model
-	addX402PayTo   textinput.Model
-	addX402Testnet textinput.Model
-	addRelays      textinput.Model
-	addDiscovery   textinput.Model
-	addMaxRelays   textinput.Model
+	addingTunnel     bool
+	addFocus         int
+	addName          textinput.Model
+	addTarget        textinput.Model
+	addHTTPRoutes    textinput.Model
+	addX402PayTo     textinput.Model
+	addX402Testnet   textinput.Model
+	addX402Network   textinput.Model
+	addX402Asset     textinput.Model
+	addX402Endpoints textinput.Model
+	addRelays        textinput.Model
+	addDiscovery     textinput.Model
+	addMaxRelays     textinput.Model
 
 	settingsEditTunnelID string
 	settingsFocus        int
@@ -179,6 +185,9 @@ func RunDashboard(configPath, stateDir string) error {
 		addHTTPRoutes:       newAgentDashboardInlineInput("/paid=3001 GET:0.01; /=5173"),
 		addX402PayTo:        newAgentDashboardInlineInput("0x..."),
 		addX402Testnet:      newAgentDashboardInlineInput("false"),
+		addX402Network:      newAgentDashboardInlineInput("casper:casper-test"),
+		addX402Asset:        newAgentDashboardInlineInput("hash-..."),
+		addX402Endpoints:    newAgentDashboardInlineInput("https://x402-facilitator.cspr.cloud"),
 		addRelays:           newAgentDashboardInlineInput("https://portal.example.com"),
 		addDiscovery:        newAgentDashboardInlineInput("true"),
 		addMaxRelays:        newAgentDashboardInlineInput("3"),
@@ -748,6 +757,12 @@ func (m *agentDashboardModel) focusedAddTunnelInput() *textinput.Model {
 		return &m.addX402PayTo
 	case agentDashboardAddFieldX402Testnet:
 		return &m.addX402Testnet
+	case agentDashboardAddFieldX402Network:
+		return &m.addX402Network
+	case agentDashboardAddFieldX402Asset:
+		return &m.addX402Asset
+	case agentDashboardAddFieldX402Endpoints:
+		return &m.addX402Endpoints
 	case agentDashboardAddFieldRelays:
 		return &m.addRelays
 	case agentDashboardAddFieldDiscovery:
@@ -766,6 +781,9 @@ func (m *agentDashboardModel) blurAddTunnelInputs() {
 		&m.addHTTPRoutes,
 		&m.addX402PayTo,
 		&m.addX402Testnet,
+		&m.addX402Network,
+		&m.addX402Asset,
+		&m.addX402Endpoints,
 		&m.addRelays,
 		&m.addDiscovery,
 		&m.addMaxRelays,
@@ -781,6 +799,9 @@ func (m *agentDashboardModel) resetAddTunnelForm() {
 		&m.addHTTPRoutes,
 		&m.addX402PayTo,
 		&m.addX402Testnet,
+		&m.addX402Network,
+		&m.addX402Asset,
+		&m.addX402Endpoints,
 		&m.addRelays,
 	} {
 		input.Reset()
@@ -903,6 +924,9 @@ func (m *agentDashboardModel) resizeInputs(width int) {
 		&m.addHTTPRoutes,
 		&m.addX402PayTo,
 		&m.addX402Testnet,
+		&m.addX402Network,
+		&m.addX402Asset,
+		&m.addX402Endpoints,
 		&m.addRelays,
 		&m.addDiscovery,
 		&m.addMaxRelays,
@@ -1017,6 +1041,15 @@ func (m agentDashboardModel) addTunnelRequest() (types.AgentTunnelRequest, error
 	if x402Testnet && !hasPaidRoute {
 		return types.AgentTunnelRequest{}, fmt.Errorf("X402 Testnet requires paid routes")
 	}
+	x402Network := strings.ToLower(strings.TrimSpace(m.addX402Network.Value()))
+	x402Asset := strings.TrimSpace(m.addX402Asset.Value())
+	x402Endpoints := utils.SplitCSV(m.addX402Endpoints.Value())
+	if x402Network != "" && !hasPaidRoute {
+		return types.AgentTunnelRequest{}, fmt.Errorf("X402 Network requires paid routes")
+	}
+	if strings.HasPrefix(x402Network, "casper:") && x402Asset == "" {
+		return types.AgentTunnelRequest{}, fmt.Errorf("casper payments require X402 Asset")
+	}
 
 	discoveryRaw := strings.TrimSpace(m.addDiscovery.Value())
 	if discoveryRaw == "" {
@@ -1045,6 +1078,9 @@ func (m agentDashboardModel) addTunnelRequest() (types.AgentTunnelRequest, error
 		MaxActiveRelays: maxRelays,
 		X402PayTo:       payTo,
 		X402Testnet:     x402Testnet,
+		X402Network:     x402Network,
+		X402Asset:       x402Asset,
+		X402Endpoints:   x402Endpoints,
 	}, nil
 }
 
@@ -1492,6 +1528,9 @@ func (m agentDashboardModel) renderAddTunnelForm(pane *agentDashboardView, width
 		{label: "Routes", input: m.addHTTPRoutes, field: agentDashboardAddFieldHTTPRoutes},
 		{label: "X402 Pay To", input: m.addX402PayTo, field: agentDashboardAddFieldX402PayTo},
 		{label: "X402 Testnet", input: m.addX402Testnet, field: agentDashboardAddFieldX402Testnet},
+		{label: "X402 Network", input: m.addX402Network, field: agentDashboardAddFieldX402Network},
+		{label: "X402 Asset", input: m.addX402Asset, field: agentDashboardAddFieldX402Asset},
+		{label: "X402 Endpoints", input: m.addX402Endpoints, field: agentDashboardAddFieldX402Endpoints},
 		{label: "Relays", input: m.addRelays, field: agentDashboardAddFieldRelays},
 		{label: "Discovery", input: m.addDiscovery, field: agentDashboardAddFieldDiscovery},
 		{label: "Max Relays", input: m.addMaxRelays, field: agentDashboardAddFieldMaxRelays},
@@ -1643,7 +1682,10 @@ func (m agentDashboardModel) renderSettingsInputRows(pane *agentDashboardView, w
 		if len(pane.lines)-startLine >= height {
 			return
 		}
-		pane.addMeta(width, 0, "Network", agentDashboardX402Network(tunnel.X402Testnet))
+		pane.addMeta(width, 0, "Network", agentDashboardX402Network(tunnel.X402Network, tunnel.X402Testnet))
+	}
+	if strings.TrimSpace(tunnel.X402Asset) != "" && len(pane.lines)-startLine < height {
+		pane.addMeta(width, 0, "Asset", tunnel.X402Asset)
 	}
 	if len(tunnel.HTTPRoutes) == 0 {
 		if len(pane.lines)-startLine >= height {
@@ -2054,7 +2096,10 @@ func agentDashboardHTTPRouteSummary(route types.AgentHTTPRoute) string {
 	return prefix + " -> " + upstream
 }
 
-func agentDashboardX402Network(testnet bool) string {
+func agentDashboardX402Network(network string, testnet bool) string {
+	if network = strings.TrimSpace(network); network != "" {
+		return network
+	}
 	if testnet {
 		return "sui:testnet"
 	}

cmd/portal-tunnel/agent/manager.go

@@ -259,6 +259,9 @@ func (m *manager) AddTunnel(req types.AgentTunnelRequest) error {
 		MaxActiveRelays: req.MaxActiveRelays,
 		X402PayTo:       strings.TrimSpace(req.X402PayTo),
 		X402Testnet:     req.X402Testnet,
+		X402Network:     strings.ToLower(strings.TrimSpace(req.X402Network)),
+		X402Asset:       strings.TrimSpace(req.X402Asset),
+		X402Endpoints:   compactStrings(append([]string(nil), req.X402Endpoints...)),
 	}
 	if slices.ContainsFunc(cfg.Tunnels, func(tunnel TunnelConfig) bool { return tunnel.ID == tunnelCfg.ID }) {
 		return fmt.Errorf("tunnel %q already exists", tunnelCfg.ID)
@@ -615,6 +618,9 @@ func (t *managedTunnel) Snapshot() types.AgentTunnelStatus {
 		MultiHop:        append([]string(nil), cfg.MultiHop...),
 		X402PayTo:       strings.TrimSpace(cfg.X402PayTo),
 		X402Testnet:     cfg.X402Testnet,
+		X402Network:     cfg.X402Network,
+		X402Asset:       cfg.X402Asset,
+		X402Endpoints:   append([]string(nil), cfg.X402Endpoints...),
 	}
 	if len(cfg.HTTPRoutes) > 0 {
 		status.HTTPRoutes = make([]types.AgentHTTPRoute, 0, len(cfg.HTTPRoutes))
@@ -697,23 +703,31 @@ func (t *managedTunnel) runOnce(ctx context.Context) error {
 	if cfg.BanMITM != nil {
 		banMITM = *cfg.BanMITM
 	}
+	x402FacilitatorToken := strings.TrimSpace(cfg.X402FacilitatorToken)
+	if x402FacilitatorToken == "" {
+		x402FacilitatorToken = strings.TrimSpace(os.Getenv("CSPR_CLOUD_API_KEY"))
+	}
 	exposure, err := sdk.Expose(ctx, sdk.ExposeConfig{
-		RelayURLs:       append([]string(nil), cfg.RelayURLs...),
-		Discovery:       discovery,
-		Identity:        types.Identity{Name: cfg.Name},
-		IdentityPath:    cfg.IdentityPath,
-		IdentityJSON:    cfg.IdentityJSON,
-		TargetAddr:      cfg.TargetAddr,
-		UDPAddr:         cfg.UDPAddr,
-		UDPEnabled:      cfg.UDPEnabled,
-		TCPEnabled:      cfg.TCPEnabled,
-		MultiHop:        append([]string(nil), cfg.MultiHop...),
-		MultiHopDepth:   cfg.MultiHopDepth,
-		BanMITM:         banMITM,
-		MaxActiveRelays: cfg.MaxActiveRelays,
-		Metadata:        metadataFromTunnelConfig(cfg),
-		X402PayTo:       cfg.X402PayTo,
-		X402Testnet:     cfg.X402Testnet,
+		RelayURLs:            append([]string(nil), cfg.RelayURLs...),
+		Discovery:            discovery,
+		Identity:             types.Identity{Name: cfg.Name},
+		IdentityPath:         cfg.IdentityPath,
+		IdentityJSON:         cfg.IdentityJSON,
+		TargetAddr:           cfg.TargetAddr,
+		UDPAddr:              cfg.UDPAddr,
+		UDPEnabled:           cfg.UDPEnabled,
+		TCPEnabled:           cfg.TCPEnabled,
+		MultiHop:             append([]string(nil), cfg.MultiHop...),
+		MultiHopDepth:        cfg.MultiHopDepth,
+		BanMITM:              banMITM,
+		MaxActiveRelays:      cfg.MaxActiveRelays,
+		Metadata:             metadataFromTunnelConfig(cfg),
+		X402PayTo:            cfg.X402PayTo,
+		X402Testnet:          cfg.X402Testnet,
+		X402Network:          cfg.X402Network,
+		X402Asset:            cfg.X402Asset,
+		X402Endpoints:        append([]string(nil), cfg.X402Endpoints...),
+		X402FacilitatorToken: x402FacilitatorToken,
 	})
 	if err != nil {
 		return err