PORTAL v2

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_URL port with ALPN portal-tunnel; SNI_PORT controls 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 conditionCurrent behaviorRemaining boundary
Relay follows the forwarding protocolTenant TLS terminates at the SDK; the relay forwards ciphertextThe relay still controls routing and availability
Relay passively observes a forwarded sessionCertificate signatures do not disclose tenant traffic secretsIPs, SNI, timing, volume, and connection metadata remain visible
Tunnel client tries to reuse signing authority for another connectionThe signer requires a current lease and a matching, unexpired, single-use ClientHello bindingThis is policy enforced by the relay, not protection from a malicious relay operator
Relay splits a recognized probe into two TLS sessionsDifferent exporter values produce a suspected-termination verdictOnly that sampled connection is checked
Fully malicious relay controls the certificate keyIt can authenticate as a tenant endpoint; Portal does not cryptographically prevent impersonationIt may selectively forward, distinguish, or drop probes
Future Delegated Credentials supportCould avoid contacting the signer on each compatible handshakeNot 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 (or BAN_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 until AddRelay() 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 seeProtected on that forwarding path
Source IP and timing metadataHTTP headers or body
Lease identity/public hostname, including SNITenant TLS session keys
Traffic volume and connection durationApplication payload on the stream path
Requested TCP/UDP transport metadataLocal service plaintext on the tenant TLS stream path
Raw TCP/UDP payloads when the application protocol is unencryptedApplication-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