| 1 | --- |
| 2 | title: Security Model |
| 3 | description: How Portal keeps tenant traffic opaque to relay operators. |
| 4 | --- |
| 5 | |
| 6 | # Security Model |
| 7 | |
| 8 | Portal is designed so relay operators do not receive tenant traffic plaintext. |
| 9 | |
| 10 | ## Tenant TLS |
| 11 | |
| 12 | For the default stream path, the relay only peeks at the TLS ClientHello long enough to read SNI and choose a lease. After that it bridges encrypted bytes over a reverse session. |
| 13 | |
| 14 | ```text |
| 15 | Client browser |
| 16 | -> Relay SNI router |
| 17 | -> Reverse session |
| 18 | -> SDK tenant TLS terminator |
| 19 | -> Local service |
| 20 | ``` |
| 21 | |
| 22 | Tenant TLS terminates on the SDK side. The local service receives the decrypted stream from the tunnel process, while the relay only handles routing metadata and ciphertext. |
| 23 | |
| 24 | ## Keyless Signing |
| 25 | |
| 26 | For relay-hosted names, the SDK builds a tenant-facing TLS server config backed by the relay's `/v1/sign` endpoint. The relay signs handshake digests with its certificate key, but it does not receive the negotiated tenant TLS session keys. |
| 27 | |
| 28 | Relay API TLS is separate from tenant TLS: |
| 29 | |
| 30 | - Relay API HTTPS protects `/sdk/*`, `/discovery`, `/api/admin`, installers, and `/v1/sign`. |
| 31 | - Tenant TLS protects end-user traffic for lease hostnames. |
| 32 | - The internal QUIC datagram backhaul uses `SNI_PORT/udp` with ALPN `portal-tunnel`. |
| 33 | |
| 34 | ## Tunnel ECH |
| 35 | |
| 36 | For default stream leases, the SDK derives an opaque route hostname from the tunnel identity private key. The relay still receives the lease identity name and can derive the public fallback hostname so it can validate plaintext-SNI fallback routing and manage DNS automation. The relay stores the route hostname for ECH routing and a validated hash of the public fallback hostname. When DNS automation is enabled, the relay also keeps the public hostname needed to publish and delete its HTTPS `ech` record. |
| 37 | |
| 38 | ECH-capable clients can use the opaque route hostname as the outer SNI while the real tenant SNI stays inside the ECH-protected ClientHello handled by the SDK. For multi-hop stream routes, the entry relay gets the opaque route hostname for ECH and the public hostname needed to validate the plaintext-SNI fallback hash and manage DNS automation. After the entry relay chooses the route, the remaining hops continue to use hop tokens and passthrough forwarding. |
| 39 | |
| 40 | When `ACME_DNS_PROVIDER` is configured, Portal publishes DNS HTTPS records with the `ech` parameter for the relay root and stream lease public hostnames. Without a DNS provider, operators must distribute the logged ECHConfigList through DNS HTTPS/SVCB or another ECH-capable bootstrap. Without that distribution, ordinary clients keep using the public hostname SNI and the relay routes them through the existing plaintext-SNI fallback. |
| 41 | |
| 42 | Legacy clients and raw TCP/UDP transports still use the legacy hostname registration path. On those paths the relay control plane receives the lease hostname and can expose it to admin views. |
| 43 | |
| 44 | ## MITM Self-Probe |
| 45 | |
| 46 | `portal expose` runs an asynchronous TLS passthrough self-probe after real tenant traffic starts. The SDK connects to its own public hostname, exports TLS keying material from the client side, recognizes the returning probe after SDK-side TLS termination, and compares exporter values. |
| 47 | |
| 48 | Matching exporter values mean the sampled connection preserved passthrough. A mismatch is treated as suspected relay-side TLS termination and logged by default; use `--ban-mitm` when suspected TLS termination should ban the relay. |
| 49 | |
| 50 | ## Relay Visibility |
| 51 | |
| 52 | | Relays can see | Relays cannot see | |
| 53 | |---|---| |
| 54 | | Source IP and timing metadata | HTTP headers or body | |
| 55 | | Lease identity/public hostname, including SNI on the plaintext-SNI fallback path | Tenant TLS session keys | |
| 56 | | Opaque route hostnames on the ECH path | ECH-protected inner SNI when clients use the distributed ECHConfigList | |
| 57 | | Traffic volume and connection duration | Application payload on the stream path | |
| 58 | | Requested TCP/UDP transport metadata | Local service plaintext on the tenant TLS stream path | |
| 59 | | Raw TCP/UDP payloads when the application protocol is unencrypted | Application-level encrypted raw TCP/UDP payloads | |
| 60 | |
| 61 | Raw TCP and UDP port transports do not add tenant TLS. Use application-level encryption for those modes when confidentiality matters. |
| 62 | |
| 63 | ## Identity |
| 64 | |
| 65 | Registration uses a SIWE challenge signed by the SDK's secp256k1 identity key. The key is loaded from `identity.json` either as a raw secp256k1 `private_key` or derived from a BIP-39 `mnemonic` and `derivation_path`. The relay then issues a lease-scoped ES256K access token used by renew, unregister, reverse connect, and QUIC datagram authentication. |
| 66 | |
| 67 | Relay admin token login and optional local agent wallet login are separate from |
| 68 | lease registration. They do not replace the local tunnel identity used for |
| 69 | registration. |
| 70 | |
| 71 | ## Next Steps |
| 72 | |
| 73 | - [Architecture](/architecture) - deep dive into Portal's internal design |
| 74 | - [Wallet and ENS](/wallet-and-ens) - admin tokens, wallet auth, and ENS gasless DNS import |
| 75 | - [Self-Hosting](/self-hosting) - run your own relay server |