tnl.dev :: docs
security.
Understand encryption, visitor access, and trust boundaries.
where encryption starts and ends
The visitor connects to a public URL or managed service using its required TLS protocol. For public endpoint visitors, visitor TLS passes through ingress and relay as encrypted bytes and terminates in the selected publisher's tnl process. Connectors bypass ingress: two relay packet paths carry one encrypted QUIC connection to that publisher. Neither forwarding path lets relays read HTTP content or database credentials. The publisher then uses the declared backend transport. Optional target.tls verifies the separate publisher-to-target TLS hop; omitting it permits a plaintext backend. Control HTTPS is different: Fly's edge or a self-hosted proxy terminates it and sends HTTP to a private, explicitly trusted control listener.
Encryption does not hide connection metadata. On the public visitor path, ingress sees the source IP, requested TLS hostname, timing, and volume; the relay receives source and destination metadata. On connector paths, each relay observes the connector's source address and supplies evidence bound to the prepared pair. Source evidence is not visitor permission: the publisher checks current access and IP policy before target work. Neither path exposes encrypted HTTP content to the relay.
The tnl server controls public URL DNS and certificate issuance. An active operator controlling both could send visitors to another endpoint and obtain a valid certificate to impersonate your URL. Passive forwarding cannot read the HTTP, but visitor TLS does not remove trust in the operator or the certificate authority.
post-quantum encryption
Native tunnel connections require TLS 1.3 with hybrid X25519 + ML-KEM-768 key agreement. This covers publisher-to-relay, connector-to-relay, ingress-to-relay, and the inner connector-to-publisher connection. TCP fallback keeps the same requirement; it does not downgrade to classical-only key agreement.
Hybrid key agreement combines conventional and post-quantum algorithms to protect recorded traffic against future quantum decryption. Certificate and identity signatures remain separate; this is not a claim of fully post-quantum authentication.
Public URLs require TLS 1.3 and negotiate hybrid post-quantum key agreement when the visitor supports it. To reject visitors without that support:
tnl publish 3000 --require-post-quantumOr declare it on a configured service:
services: {
app: { publicURL: { requirePostQuantum: true } },
}Static files use require_post_quantum. The setting is saved with the public URL
and enforced at the publisher's TLS handshake, before HTTP reaches the app.
Omitting it preserves the saved value; set it to false explicitly to remove the
requirement. Stop the URL's active publish runs before changing it. Paths on that
hostname share its requirement; separate alias, OAuth, and webhook hostnames do
not inherit it.
Ad-hoc SDK publication accepts requirePostQuantum: true in TypeScript,
require_post_quantum=True in Python, and RequirePostQuantum: true in Go.
Control API HTTPS depends on the deployed edge or proxy. Publisher-to-target TLS
depends on the backend; the native tunnel requirement does not upgrade those
separate connections. Successful publisher TLS metrics and native transport traces
include the negotiated tls.key_exchange.
control who can visit
Local public URLs default to restricted access: visitors need a current sign-in, share link, or URL-scoped token. A service can declare access: { team: true } for team access. A local HTTP service can declare publicURL: { access: "anonymous" }; named-group managed HTTP cannot override its visitor policy to anonymous. An optional IP policy adds a source filter; an IP match does not replace a credential. No denied request reaches the target. Keep the app's own authentication where needed. See who can visit.
Authorization applies for the duration of HTTP bodies and WebSockets, as it does for managed database/TCP streams. tnl rechecks the admitted subject within 30 seconds while control is available, closes the affected stream on denial, and cannot continue past its last accepted deadline during a control outage. A new login or workload session authorizes later work; it cannot replace an existing stream's original subject or move its fixed session deadline. Failed application requests, SQL, and upgrades are not replayed or migrated.
For a webhook integration URL, ingress admits the union of provider ranges from the selected server and replacement source_ips ranges because it cannot see the encrypted HTTP path. Local tnl then checks each endpoint's exact path, method, and original source before reading its body. Ordinary app hostnames do not gain provider IP access. Verify sender signatures in the app. With oauth: true, the project OAuth URL forwards only callbacks with an unexpired locally recorded state to the originating worktree; the app still validates state and exchanges the code.
accounts, teams, and credentials
Your sign-in creates a control session used to manage public URLs. Teams and memberships decide who can use a team's domains and public URLs; they do not log visitors in to your app. Local tnl holds the access and refresh tokens for its session, a publish run token to update one run, and a credential for each assigned publisher connection. It also holds the visitor TLS private key. Keep client state private: someone with those credentials could act as you or publish under your run.
trust boundaries on your machine and server
tnl auth login [--team NAME] uses one control-owned device approval flow with
browser-bound authorization code, PKCE, and nonce verification. Hosted accounts
use shared GitHub/Google/Microsoft sign-in apps; matching email addresses never
merge identities. Explicit linking requires fresh proof and does not change the
session's source authentication. A company directory decides eligibility, not
how the person signed in. Only a verified source event can produce the canonical
company context. Self-hosted direct Google/Entra admission uses explicit operator
rules over verified subjects or claims, never an untrusted email suffix.
Only control connects to PostgreSQL and holds the server's DNS and ACME credentials. Split ingress and relays authenticate to control with a cluster secret; leases and connection assignment checks reject stale processes, while ingress uses short-lived routing information. Local tnl checks the visitor hostname and replaces untrusted forwarding headers before sending HTTP to your app. Treat the local service as reachable by anyone your visitor policy admits, unless the app enforces its own access rules.
X-Forwarded-For can help with request logs, but do not use it to authorize visitors in the app. Someone who can reach the app's listener directly can set that header without going through tnl. Use the public URL's IP policy for visitor source rules, and keep the app's own authentication where needed. Bind development listeners to loopback so they are not exposed to other machines.
self-hosted responsibilities
If you run your own server, you operate DNS, certificate issuance, PostgreSQL, and process credentials. Keep control's DNS and ACME credentials and storage key private, and retain the storage key with database backups: without it, encrypted recoverable secrets cannot be restored. In split deployments, protect the cluster secret on all processes that use it. Relay transport certificates secure publisher connections to relays; they do not terminate visitor TLS.
private target and publisher trust
Managed services have a control-assigned hostname, certificate, and port. Private endpoint DNS resolves to loopback; public endpoint DNS resolves to ingress. For either exposure, a signed-in visitor uses tnl connect to open an authenticated local listener with current service authorization. Native HTTP and database clients still verify the managed publisher hostname and certificate, using the printed loopback override or hostname mapping. No application client certificate is needed on this connector path. Opaque TCP helpers verify the outer managed TLS before carrying application bytes. Direct public HTTP access checks each request using the admitted identity, a supported token, or a host-bound browser session. Exposing an endpoint does not make it anonymous.
target.tls: { caFile?, serverName? } configures publisher-side backend verification for HTTP, TCP, PostgreSQL, and MySQL. Static files use ca_file and server_name. Approved revisions capture CA material; failed verification never falls back to plaintext. An opaque TCP helper can carry an application's own end-to-end TLS inside managed TLS. See target TLS.
Keep the original cluster CA and hostname for native Kubernetes HTTPS. OpenSSH still verifies sshd's host key and authenticates its user. tnl supplies neither Kubernetes privileges nor SSH accounts.
Each publisher replica needs its own retained signing identity and durable TLS keys. Its short-lived leases do not replace those keys. Preserve the replica-private identity directory across replacement; keep runtime SQLite separate. Inject the same signing credential on every launch, retain the full /identity directory, and never overlap processes for one identity. Unsetting the environment variable prevents child inheritance but does not securely erase memory. See publisher groups.
Company suspension and directory loss stop member-owned access and runs without changing roles. Eligible members can recover from reversible suspension, but sync cannot restore a manually removed membership. Explicit contractor exceptions remain owner-controlled. Team-owned unattended publishers continue independently of their creator's membership.
Team audit history stores transactional management facts and unsampled asynchronous connection observations. Bounded reporting can lose observations during crashes or outages; it is not complete durable request history and contains no HTTP paths, SQL, commands, payloads, or secrets.