Merge pull request #153 from gosuda/feature/tls-termination-detection

Feature/tls termination detection

Author: gosunuts

README.md

@@ -18,11 +18,24 @@ Unlike other tunneling services, Portal is self-hosted and permissionless. You c
 
 - **NAT-friendly connectivity**: Works behind NAT or firewalls without opening inbound ports
 - **Automatic subdomain routing**: Gives each app its own subdomain (`your-app.<base-domain>`)
-- **End-to-end encryption**: Supports TLS passthrough with relay keyless certificates
+- **End-to-end tenant TLS**: Relay routes by SNI, while tenant TLS terminates on your side with relay-backed keyless signing
 - **Permissionless Hosting**: Anyone can run their own Portal — no approval needed
 - **One-Command Setup**: Expose any local app with a single command
 - **UDP Relay (Experimental)**: Supports raw UDP relay use cases, but the transport model and operational behavior may still change
 
+## How Portal Provides End-to-End Encryption
+
+Portal is designed so that tenant TLS terminates on your side rather than at the relay. In the normal data path, the relay forwards encrypted traffic without access to tenant TLS plaintext.
+
+1. The relay accepts the public connection and reads only the TLS ClientHello required for SNI-based routing.
+2. It forwards the tenant connection as raw encrypted bytes over the reverse session without terminating tenant TLS.
+3. The Portal client on your side acts as the TLS server and completes the tenant handshake locally.
+4. For relay-hosted domains, the Portal client obtains certificate signatures via `/v1/sign`, using the relay only as a keyless signing oracle.
+5. Session keys are derived entirely on your side. The relay provides certificate signatures only and does not receive tenant traffic secrets.
+6. After the handshake, the relay continues forwarding ciphertext without needing tenant TLS plaintext to keep routing traffic.
+
+Portal also checks that the relay is preserving TLS passthrough. The Portal client connects to its own public endpoint and compares TLS exporter values observed on both client-controlled ends. If they differ, Portal logs suspected TLS termination by default. You can switch to strict enforcement with `portal expose --ban-mitm`.
+
 ## Components
 
 - **Relay**: A server that routes public requests to the right connected app.

cmd/demo-app/main.go

@@ -33,6 +33,7 @@ func main() {
 type demoConfig struct {
 	relayURLs string
 	discovery bool
+	banMITM   bool
 	addr      string
 	name      string
 	desc      string
@@ -48,6 +49,7 @@ func runTCPCommand(args []string) error {
 	fs := utils.NewFlagSet("demo-app", printTCPUsage)
 	utils.StringFlagEnv(fs, &cfg.relayURLs, "relays", "https://gosunuts.xyz", "additional relay API URLs (comma-separated; scheme omitted defaults to https; merged with public registry relays when discovery is enabled)", "RELAYS")
 	utils.BoolFlagEnv(fs, &cfg.discovery, "discovery", true, "include public registry relays and enable discovery", "DISCOVERY")
+	utils.BoolFlagEnv(fs, &cfg.banMITM, "ban-mitm", false, "ban relay when the MITM self-probe detects TLS termination", "BAN_MITM")
 	utils.StringFlag(fs, &cfg.addr, "addr", "127.0.0.1:8092", "local demo HTTP listen address (host:port or URL; disable if empty)")
 	utils.StringFlag(fs, &cfg.name, "name", "demo-app", "public hostname prefix (single DNS label)")
 	utils.StringFlag(fs, &cfg.desc, "description", "Portal demo connectivity app", "lease description")
@@ -79,6 +81,7 @@ func runUDPCommand(args []string) error {
 
 	utils.StringFlagEnv(fs, &cfg.relayURLs, "relays", "https://localhost:4017", "additional relay API URLs (comma-separated; scheme omitted defaults to https; merged with public registry relays when discovery is enabled)", "RELAYS")
 	utils.BoolFlagEnv(fs, &cfg.discovery, "discovery", true, "include public registry relays and enable discovery", "DISCOVERY")
+	utils.BoolFlagEnv(fs, &cfg.banMITM, "ban-mitm", false, "ban relay when the MITM self-probe detects TLS termination", "BAN_MITM")
 	utils.StringFlag(fs, &cfg.name, "name", "demo-udp", "public hostname prefix (single DNS label)")
 	utils.StringFlag(fs, &cfg.desc, "description", "Portal demo UDP echo service", "lease description")
 	utils.StringFlag(fs, &cfg.tags, "tags", "demo,udp,echo", "comma-separated lease tags")
@@ -133,6 +136,7 @@ func runTCPDemo(ctx context.Context, cfg demoConfig) error {
 	exposure, err := sdk.Expose(ctx, sdk.ExposeConfig{
 		RelayURLs: utils.SplitCSV(cfg.relayURLs),
 		Name:      cfg.name,
+		BanMITM:   cfg.banMITM,
 		Discovery: cfg.discovery,
 		Metadata: types.LeaseMetadata{
 			Description: cfg.desc,
@@ -173,6 +177,7 @@ func runUDPDemo(ctx context.Context, cfg demoConfig) error {
 		RelayURLs:  utils.SplitCSV(cfg.relayURLs),
 		Name:       cfg.name,
 		UDPEnabled: true,
+		BanMITM:    cfg.banMITM,
 		Discovery:  cfg.discovery,
 		Metadata: types.LeaseMetadata{
 			Description: cfg.desc,

cmd/portal-tunnel/README.md

@@ -37,12 +37,14 @@ portal expose localhost:8080 \
 - `--name` is optional. When omitted, the CLI generates a name for that run.
 - `--relays` sets the relay API URLs for that run.
 - `--discovery=false` disables the public registry seed list and the discovery expansion loop for that run.
+- `--ban-mitm` enables strict rejection when the TLS self-probe detects termination in the path.
 
 Flags:
 
 ```text
 --relays          Portal relay API URLs (comma-separated, https only)
 --discovery       Include public registry relays and discover additional relay bootstraps
+--ban-mitm        Ban relay when the MITM self-probe detects TLS termination
 --name            Public hostname prefix (single DNS label); auto-generated when omitted
 --description     Service description metadata
 --tags            Service tags metadata (comma-separated)
@@ -80,4 +82,5 @@ Legacy execution compatibility has been removed:
 - With discovery enabled, the configured relay list starts with `public registry + --relays values` and can expand through relay discovery. With `--discovery=false`, only the explicit relay URLs are used. Published public URLs appear only for relays that have registered successfully.
 - SDK callers that do not set `ListenerConfig.RetryCount` use infinite retry semantics for each relay.
 - Tenant TLS is provisioned automatically through the relay keyless signer. The SDK fetches the relay certificate chain and uses `/v1/sign` for remote signing.
+- TLS self-probe mismatches log warnings by default. Use `--ban-mitm` to reject relays that terminate tenant TLS.
 - When the local service is unreachable, the tunnel returns an HTTP 503 page.

cmd/portal-tunnel/main.go

@@ -34,6 +34,7 @@ func main() {
 type exposeFlags struct {
 	relayCSV   string
 	discovery  bool
+	banMITM    bool
 	privateKey string
 	name       string
 	desc       string
@@ -52,6 +53,7 @@ func runExposeCommand(args []string) error {
 
 	utils.StringFlag(fs, &flags.relayCSV, "relays", "", "Additional Portal relay server API URLs (comma-separated; scheme omitted defaults to https)")
 	utils.BoolFlag(fs, &flags.discovery, "discovery", true, "Include public registry relays and discover additional relay bootstraps")
+	utils.BoolFlagEnv(fs, &flags.banMITM, "ban-mitm", true, "Ban relay when the MITM self-probe detects TLS termination", "BAN_MITM")
 	utils.StringFlag(fs, &flags.privateKey, "private-key", "", "Owner private key used to derive a discovery address")
 	utils.StringFlag(fs, &flags.name, "name", "", "Public hostname prefix (single DNS label); auto-generated when omitted")
 	utils.StringFlag(fs, &flags.desc, "description", "", "Service description metadata")
@@ -95,6 +97,7 @@ func runExposeCommand(args []string) error {
 		TargetAddr: flags.targetAddr,
 		UDPAddr:    flags.udpAddr,
 		UDPEnabled: flags.udp,
+		BanMITM:    flags.banMITM,
 		Discovery:  flags.discovery,
 		Metadata: types.LeaseMetadata{
 			Description: flags.desc,
@@ -252,6 +255,7 @@ func printExposeUsage(w io.Writer) {
 			"portal expose 3000",
 			"portal expose localhost:8080 --name my-app",
 			"portal expose 3000 --udp --udp-addr 127.0.0.1:5353",
+			"portal expose 3000 --ban-mitm",
 			"portal expose 3000 --relays https://portal.example.com --discovery=false",
 		},
 	)