Security Model
Portal minimizes relay trust; it does not yet eliminate it.
In the normal uncached HTTPS path, tenant TLS terminates in the local tunnel process. A relay that forwards this traffic cannot read application plaintext or derive the tenant session keys from its certificate signing key. A malicious relay holding that key can still authenticate as a tenant endpoint and actively terminate TLS. The self-probe adds detection on sampled connections, not a proof that all connections are safe.
This page defines the supported trust boundaries. For the design rationale, handshake flow, and browser-delegation context, read Building End-to-End TLS Tunnels Without Delegated Credentials. Raw port transports and opt-in static caching have different boundaries below.
Local TLS service namespace
<service>.<40-lowercase-hex-address>.<relay-root> is a tunnel-owned Local TLS
endpoint with an exact per-service leaf certificate. It is advertised only after
capability negotiation and certificate readiness. It never falls back to Keyless
or redirects automatically; unavailable certificates fail closed. Friendly aliases
and old one-label address-derived URLs retain their legacy Keyless behavior.
Moving to a new URL requires explicit application origin and cookie migration.
The relay’s existing wildcard cannot cover this two-label namespace. The relay still controls DNS/ACME validation and may obtain a new competing certificate; CT/CAA observations do not prevent that attack. Native channel binding signs the entire hostname, nonce, and current TLS Exporter. Sibling services cannot substitute bindings. Standard browser JavaScript cannot obtain the exporter and has no identical authentication proof. Legacy relay-cached sessions are outside this live tunnel-terminated channel-binding guarantee.
Local HTTP handlers support HTTP/2 with HTTP/1.1 backend translation, and retain HTTP/1.1. Raw decrypted stream consumers do not gain HTTP/2 merely from ALPN. Neither the friendly Keyless path nor relay-cache/control-plane ALPN changes.
Opt-in Static Cache
Cache publication is bound to the currently owned friendly alias. A new owner detaches the old snapshot and invalidates old upload admission during the serialized alias grant, before serving the new owner. Delayed uploads, renewals, deletes, and old-owner policy changes cannot restore or remove the new owner’s content. Retention does not reserve an alias. An empty new snapshot never falls back to a previous owner’s files.
Cached alias TLS terminates on the relay and exposes the files to it; it does not provide the live tunnel’s native channel-binding guarantees. Reassigning an alias keeps the same browser origin: relay invalidation does not clear cookies, storage, service workers, or browser caches.
portal expose --serve ./dist --cache explicitly permits selected relays to
store the site’s files and terminate browser TLS. Cached connections therefore
expose HTTP headers and content to the serving relay. If that connection falls
back to the live origin, it still trusts the relay; browser-to-origin end-to-end
TLS is not restored on an already terminated connection.
Only currently granted friendly aliases are cacheable. New canonical <service>.<address>.<relay-root> URLs never use relay static cache, retained
snapshots, or fallback: their TLS endpoint stays in the tunnel. Friendly hostnames
are reusable, first-come aliases, so they remain live-origin routes and do not
serve retained content after the origin disconnects.
Use explicit --relays with --discovery=false to choose exactly which relays
receive the files. Cache mode cannot be combined with --ban-mitm.
Ordinary uncached HTTPS tunnels retain the tenant TLS path described below.
See cache configuration for expiry and limits.
Application Access Authentication
portal expose 3000 --auth siwe places a SIWE login gate at the local tunnel
HTTP endpoint. --auth credential uses Portal-native credentials instead. Those
credentials are signed by a distinct
key derived from the tunnel identity and bind the subject, tunnel identity,
host, and expiry. Redeem URLs place the credential in the URL fragment, then
exchange it at the tunnel endpoint for the same tunnel-local session cookie.
The session cannot outlive the credential.
In normal passthrough operation, credential signing keys, SIWE challenges, session signing keys, cookies, subjects, and application plaintext remain outside the relay control plane. SIWE challenges expire after two minutes; signed sessions expire after at most 24 hours.
The auth gate wraps the complete HTTP router, including static files and x402
routes. Portal removes client-supplied X-Portal-User, X-Portal-Auth, and X-Portal-Proof headers before routing, whether or not the proof is
configured, and only restores verified values when --auth-identity-headers is enabled. It removes the same names spelled with
underscores too (X_Portal_User), which some CGI-style upstreams read as the
same header; nginx and Apache’s CGI handling drop such headers by default.
With --auth-identity-proof it also sends
an X-Portal-Proof secret that the upstream can verify to tell Portal from
another local process (details).
The gate also consumes the Portal session cookie, so upstream applications
receive their own cookies but never the __Host-portal_access credential.
Application auth cannot be combined with relay caching or raw TCP/UDP exposure.
API clients may submit the signed credential in X-Portal-Access-Credential. The tunnel validates it on every request and
removes the header before routing, so the upstream never receives the bearer
credential. When a request also carries a Portal session cookie, the explicit
credential header is authoritative; an invalid credential is rejected instead
of falling back to the session.
Tenant TLS
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.
Client browser
-> Relay SNI router
-> Reverse session
-> SDK tenant TLS terminator
-> Local service 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.
Browser/WASM transport
For an ordinary uncached exposure, running the SDK in WebAssembly changes the reverse carrier, not the tenant TLS boundary. The browser connector reaches the relay through WebSocket and carries reverse connections as yamux streams, but the encrypted tenant stream still terminates in the SDK runtime. The relay terminates the outer WebSocket TLS and observes multiplexing metadata, while tenant HTTP headers, bodies, and session keys remain protected by the normal tenant TLS path.
Each logical yamux stream is authorized with the current short-lived reverse capability before the relay can offer it to the lease. Keeping a WebSocket open does not extend an expired capability’s authority to open new streams.
Browser runtimes support HTTPS handler exposure only. Raw TCP, UDP, overlay, and the native MITM self-probe require socket capabilities that the browser runtime does not provide.
Keyless Signing
For friendly aliases and legacy canonical names, the SDK terminates tenant TLS
1.3 with a keyless_tls t13server backed by the relay’s /v1/sign endpoint. The SDK generates the
ephemeral key material and derives the session keys; the relay supplies
certificate signatures without receiving those traffic secrets.
The signing API requires an authenticated, current public lease. Each request
also carries a short-lived connection binding associated with that lease and
the ClientHello captured on the routed connection. Portal checks the binding’s
lease, expiry, and ClientHello hash and consumes it before signing. The signer
constructs a TLS 1.3 CertificateVerify signature from the submitted handshake
fields; it does not expose an arbitrary-digest signing endpoint. Portal’s
ingress comparison covers the ClientHello, not an independent observation of
every submitted server-side transcript field.
These checks constrain clients of an honest signer. The relay owns both the certificate private key and the binding registry, so they cannot prevent that relay from bypassing its own policy. See the binding implementation and signing endpoint.
Relay API TLS is separate from tenant TLS:
- Relay API HTTPS protects
/sdk/*,/discovery,/api/admin, installers, and/v1/sign. - Tenant TLS protects end-user traffic for lease hostnames.
- The QUIC datagram backhaul uses the public
PORTAL_URLport with ALPNportal-tunnel;SNI_PORTcontrols the relay’s corresponding local UDP listener.
Local development trust
Public relay endpoints use normal certificate-chain and hostname verification.
For loopback addresses, localhost, and .localhost names, the native SDK
instead bootstraps trust from the chain presented by the contacted endpoint.
That initial fetch skips certificate verification; subsequent connections use
the collected chain. This development convenience is not independent
verification of the relay operator.
The bootstrap is native-only. Browser/WASM clients fetch the chain through http.DefaultClient under ordinary browser certificate validation, so they
cannot bootstrap from an untrusted local TLS endpoint: a localhost setup that
relies on this path still fails in the browser. See the relay TLS bootstrap.
A local relay issues itself a self-signed certificate, fullchain.pem in its IDENTITY_PATH directory, valid for 825 days, the longest Apple platforms
accept. To open local tunnels in a browser, trust that certificate in the
system or browser certificate store, and remove it when you are done. The relay
issues a new one 30 days before expiry or when PORTAL_URL names a host the
stored one does not cover, and the new one must be trusted again. Apple
platforms also refuse a wildcard directly under localhost, so Safari and
other WebKit browsers there open no <name>.localhost tunnel. For them, set PORTAL_URL one label deeper, such as https://portal.localhost, so tunnels
are <name>.portal.localhost.
Relay Trust Reduction
The following guarantees apply to ordinary uncached tenant TLS with an uncompromised client and tunnel endpoint.
| Threat or operating condition | Current behavior | Remaining boundary |
|---|---|---|
| Relay follows the forwarding protocol | Tenant TLS terminates at the SDK; the relay forwards ciphertext | The relay still controls routing and availability |
| Relay passively observes a forwarded session | Certificate signatures do not disclose tenant traffic secrets | IPs, SNI, timing, volume, and connection metadata remain visible |
| Tunnel client tries to reuse signing authority for another connection | The signer requires a current lease and a matching, unexpired, single-use ClientHello binding | This is policy enforced by the relay, not protection from a malicious relay operator |
| Relay splits a recognized probe into two TLS sessions | Different exporter values produce a suspected-termination verdict | Only that sampled connection is checked |
| Fully malicious relay controls the certificate key | It can authenticate as a tenant endpoint; Portal does not cryptographically prevent impersonation | It may selectively forward, distinguish, or drop probes |
| Future Delegated Credentials support | Could avoid contacting the signer on each compatible handshake | Not implemented; retaining the parent certificate key still retains its authentication authority |
The relay’s certificate signing authority is distinct from the tenant TLS session secrets. Reducing online signing or distributing the signer does not by itself transfer hostname authentication to the tunnel. The article’s future directions distinguish those changes.
MITM Self-Probe
Once a reverse connection is ready, the native SDK asynchronously opens a separate TLS connection to its public tenant hostname, without waiting for visitor traffic. A random nonce identifies the returning probe after SDK-side TLS termination. Both TLS endpoints export keying material with the same label and context, and the SDK compares the values.
- Matching values support passthrough for that sampled connection.
- An exporter mismatch is logged as suspected relay-side TLS termination.
--ban-mitm(orBAN_MITM) closes and blocks the detected relay’s listener within the current exposure. When discovery is enabled, the SDK also reports an MITM failure to that exposure’s discovery controller, which bans the relay URL in its in-memory state. That ban has no automatic expiry and survives refresh and rediscovery untilAddRelay()clears it. Both bans end when the exposure is replaced; neither is durable across client restarts or network-wide. Closing the tunnel does not revoke the relay’s certificate or withdraw its hostname; a malicious operator can still serve forged pages at the public URL.- Timeouts, connection failures, and other probe errors are warnings, not exporter-mismatch verdicts; they do not trigger that block.
Serving traffic does not wait for the probe to pass. One background loop belongs to each active native lease. It checks once after reverse readiness, then samples an exponential delay with a 45-second mean parameter, capped at 120 seconds. Successful comparisons impose no fixed minimum delay. A token bucket allows a burst of three attempts and replenishes one token every 45 seconds; attempts wait for that budget when exhausted. Inconclusive attempts are logged and impose a separate retry minimum of 30 seconds, doubling to 120 seconds on consecutive failures and clearing after a completed comparison. Checks continue without visitor traffic and are skipped while no reverse connection is ready. Attempts run serially. Lease termination cancels and joins the loop before a replacement lease starts. Socket I/O shares the overall probe timeout and is closed on cancellation.
With Local TLS enabled, the probe targets the alias using its Keyless TLS configuration, including while the canonical certificate is unavailable. The legacy and alias endpoints use relay-owned certificate material; the canonical hostname uses the tunnel’s independent local certificate. This probe samples the legacy connection and does not verify every alias or canonical connection.
It cannot establish that other clients or connections were forwarded honestly. In particular, selective MITM and probe distinguishability remain limitations; random padding does not establish that probes are indistinguishable from normal application traffic.
The cap, budget, backoff, and probe runtime make this a bounded renewal schedule, not a pure Poisson process or an exact 45-second mean between actual attempts. Resource limits can introduce quiet intervals. Random timing does not hide the tunnel’s source IP or Go TLS fingerprint; a malicious relay can still selectively forward or suppress recognizable probes.
Both sides must support TLS keying material export. An explicit --ban-mitm request fails at startup when the selected tenant TLS stack lacks that
capability. Browser/WASM exposures cannot use the native socket-based
self-probe or request this option. Static cache mode explicitly allows relay TLS termination,
disables probing, and cannot be combined with --ban-mitm.
The probe implementation defines these verdicts and their lifecycle. A successful probe is evidence about one connection, not an authorization to trust every future connection.
Protection despite probe evasion requires independently authenticated endpoints. Both the trusted server identity and the verification code must come from a path outside the relay’s control. A tunnel-owned certificate key alone is insufficient if the relay can retain or obtain another certificate covering the hostname; see #541.
Certificate monitoring
Opt-in CAA and certificate transparency monitoring adds warning-only observations for canonical hostnames. It queries independent DNS and CertSpotter only when explicitly enabled; an absent operator-managed CAA baseline remains unconfigured. Observed DNS is never automatically accepted. Known local key history and explicitly approved SPKIs help identify competing certificate keys, but do not authenticate every visitor connection.
This is a best-effort evaluation pilot using CertSpotter’s unauthenticated API, not a production monitoring SLA, complete CT auditor, or pre-attack guarantee. Hourly polling, coalesced unexpired-only issuance results, merge/aggregation delays, source outages, and missing inclusion/consistency proofs limit coverage. Runtime findings never mutate DNS, replace certificates, block traffic, or switch relays. CAA does not revoke existing certificates or remove the DNS operator’s issuance authority. A missing or failed observation is unknown, not evidence of safety.
Relay Visibility
For a relay following the ordinary uncached forwarding path, visibility is as follows. The malicious certificate-owner case above is outside this passive confidentiality guarantee.
| Relays can see | Protected on that forwarding path |
|---|---|
| Source IP and timing metadata | HTTP headers or body |
| Lease identity/public hostname, including SNI | Tenant TLS session keys |
| Traffic volume and connection duration | Application payload on the stream path |
| Requested TCP/UDP transport metadata | Local service plaintext on the tenant TLS stream path |
| Raw TCP/UDP payloads when the application protocol is unencrypted | Application-level encrypted raw TCP/UDP payloads |
Raw TCP and UDP port transports do not add tenant TLS. Use application-level encryption for those modes when confidentiality matters.
Identity
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, keyless signing, and QUIC datagram authentication, plus a separate reverse-only capability for reverse streams.
Application access login, relay admin token login, and optional local agent wallet login are separate from lease registration. They do not replace the local tunnel identity used for registration.
Next Steps
- Keyless TLS Explained - handshake, signer policy, and self-probe rationale
- Architecture - Portal’s internal design and protocol flows
- Wallet and ENS - admin tokens, wallet auth, and ENS gasless DNS import
- Self-Hosting - run your own relay server