Threat Model

The relay that connects your machines is treated as an attacker for everything it carries. This page states what that attacker cannot do, which model or test checks each statement, what is not protected, and what the relay still sees. Each measured number names its setup and its limits.


The attacker

For the data of a session, the attacker is the relay: its operator, every relay and replica a session crosses, the links between them, the network around them and anything they store. It can read, change, replay, reorder, drop and inject every message it carries, issue itself certificates for its own domain, and run machines of its own on the same relay. It does not hold the keys that stay on your machines: the organisation's root, the issuer's key and each machine's own key.

The relay is trusted for nothing about secrecy or authenticity. It is relied on for availability only: a hostile relay can always delay or refuse a session, and nothing on this page says otherwise.

The scope is the network layer: machine identity in an organisation, the end-to-end encrypted sessions between enrolled machines, direct paths, revocation, peer-to-peer transfers with a key file, and capability addresses.

Architecture

PartWhere it runsWhat it holds
Organisation rootThe owner's machine, offline from the relayThe root key. It certifies the issuer and signs root rotations, with a separate recovery key.
IssuerOne machine of the owner'sThe issuer key. It enrols machines from single-use tokens, renews their certificates and publishes the revocation list.
Enrolled machineEvery machine of the organisationIts own key and certificate, its groups, the root's fingerprint (delivered by your own provisioning, never by the relay) and the current revocation list.
Relaynfltr's hosted service, or a machine of yoursAccounts and routing. It passes sessions between machines that each keep one outgoing connection to it, and it carries the enrolment, renewal and revocation messages, which it cannot forge.

A session between two enrolled machines is a TLS 1.3 session from end to end, inside a stream the relay carries. Each end checks the other's certificate against the organisation's root, the name it asked for, the certificate's expiry and the revocation list, and the serving end admits only the groups the service names. When the two ends can reach each other and neither has turned direct paths off, the same session moves to a direct UDP connection between them under the same certificates, and returns to the relay when that path fails.

What is proven

Two kinds of model are checked on every change. A symbolic model of each end-to-end path, checked with ProVerif, gives the attacker above every relay and the keys of a rogue enrolled machine, a revoked one and an expired one. State-machine models, checked with TLA+, cover enrolment, revocation, moving the issuer and the direct path. Each model also contains planted mistakes (skip the certificate check, accept a key from the relay, fall back to plain on the relay's word), and each mistake must make a proof fail: 88 such mistakes in the symbolic models and 58 in the state-machine models of this scope.

PathProven against a hostile relay
Session between enrolled machines, through the relayThe bytes a client sends reach only the service of the machine it named, and both ends agree on the session. A rogue, revoked or expired machine is refused at the client and at the service. Only machines of the service's groups are admitted. An end the application sees as clean is the other end's clean close: a relay that cuts a session shows as a reset, never as a complete transfer. A group dial reaches only a service a machine of that group publishes. There is no downgrade to plain on the relay's word.
The same session on a direct pathWhat the client sends on a direct connection reaches only the agent of that session; the two ends agree on both the session key and the direct connection's key; the agent binds a direct connection only to the session's own client; no other machine's certificate is taken, wherever the relay pointed the client. A group dial cannot be moved to another instance.
Streams on a direct pathBytes arrive in order, none is lost, and a stream goes only to the peer that proved the session, never to an address the relay chose. When the direct path dies, the relayed path carries the session on.
EnrolmentOnly names the issuer issued are accepted; tokens are single use and bound to their name; a revoked machine is refused, also after it tries to renew; a root rotation needs the recovery key.
RevocationA bounded time after a revoke, no machine that verifies holds a session with the revoked machine, whatever revocation lists the relay delivered, an older list replayed included.
Moving the issuerThe issuer key reaches only the new machine; the root key never leaves the owner's machine, also after the new machine is compromised.
Peer-to-peer transfers with a key file on both endsSecrecy and authenticity of the data, media included.
Capability addressesSecrecy both ways; a session goes only to the key the address pins; admission needs the address's secret; a relay that sees an address's server key and its sessions cannot produce another address's pin; the direct path keeps the same pin.

TLS 1.3 and SSH are not proven again: each is taken as an authenticated channel to whoever holds the key the other end checked, as their published analyses show. What the models prove is how each end learns and checks the other's key.

From the models to the code

A model is only as good as its match with the code. Every field a model binds (a name, a certificate, a token, a key) has a binding test: it takes an honest message, changes that one field as a relay could, and requires the code to refuse it. There are 32 such rows in this scope. The enrolment and peer-to-peer models list no such fields yet, so their match with the code rests on ordinary tests. The state-machine models also check traces: the code's own tests record their steps, and every recorded step must be a step of the model.

What is not proven or not protected

What every relay sees

The relay seesThe relay does not see
The account, each machine's name and groups, which machine opens a session to which service, when, for how long, and how many bytes in each direction; each machine's address toward the relay, and its public UDP address when the machine asks the relay for it before a direct path; that a session asked for a direct path and when it fell back.The bytes of an end-to-end encrypted session, on either path; the addresses the two ends exchange for a direct path (they travel inside the session's TLS); keys that stay on your machines.
The plaintext of tunnels and sessions run with end-to-end encryption off, and of share links whose machine holds no certificate of its own for the link's host name.The content of peer-to-peer transfers with a key file.

On a direct path, each end learns the other's public address and port and its LAN addresses. Direct paths are on by default in organisation mode; off (direct: false, --direct=off, nfltr config set-direct off) is the opt-out, and hides the machine's addresses from its peers.

Revocation

Revoking a machine (nfltr org revoke <name> where the issuer runs) publishes a new revocation list. The relay carries it to every machine, each end checks its open sessions against it, and the session with the revoked machine ends, on the relay or on a direct path. Once the new list has reached an end, that end refuses every new session with the revoked machine.

Evidence: a revoked machine's live session

Setup
The NAT lab: Linux containers (Docker) on one 16-core Linux build machine, November 16, 2026, the released v2.1.67 code, the relay built from it. Two client networks behind NAT routers (cone and cone, so a direct path forms), a private relay, the issuer in a container of its own. Each run enrols a fresh machine and holds a session that sends a line every 100 ms and reads its echo, then runs nfltr org revoke where the issuer runs. The time is from just before the revoke to the session's end as the client reports it. Four variants, 20 runs each over two runs of the lab: the client revoked through the relay, the client revoked on a direct path, the serving machine revoked on a direct path, and a group-dialled direct session with its client revoked (p50 0.13 s, max 0.15 s).
Numbers
Through the relay: cut in 20 of 20 runs, p50 0.13 s, max 0.17 s. On a direct path, the client revoked: p50 0.12 s, max 0.17 s. On a direct path, the serving machine revoked: p50 0.13 s, max 0.17 s. Every new session after the revoke refused: 80 of 80 runs, the first new session already refused in each.
Reproduce
(a) With the released binaries: enrol two machines as the Organisations guide does, hold a nfltr cat pipe session open to a service of the other machine, run nfltr org revoke <name> where the issuer runs, and time the session's end. (b) Our check, in the closed nfltr repository, runs the lab and judges each run by its exit code: make conformance-direct-evidence.
Limits
One machine's containers: the relay and both ends are a network bridge apart, so the time is the issuer's publication, the relay's push and each end's check, with no network distance; a real network adds the round trips from the issuer to the relay and from the relay to the end. A relay that withholds the push delays the cut until the end's own fresh read (see above). The build machine ran other jobs at the same time (load average 7 to 9 on 16 cores). Twenty runs per variant show no tail.

Measured: direct and relayed sessions

Evidence: the same session, direct and through the relay

Setup
The same NAT lab and machine as the revocation runs (Linux containers on one 16-core build machine, November 16, 2026, v2.1.67), the routers cone and cone. One end runs a perf sink, the other nfltr cat perf against it, end-to-end encrypted, 10 s per run, one upload session, once on a direct path and once through the relay, with the client's router unshaped and shaped to 50 Mbit/s. Five runs of each; the numbers are their medians. The round trip is timed on a second channel of the same session, idle before the upload and every 100 ms during it.
Numbers
Round trip, idle, p50: direct 0.66 ms, relayed 0.94 ms. Round trip under load on a 50 Mbit/s link, p50: direct 72 ms, relayed 88 ms. Throughput: direct 47.5 Mbit/s, relayed 47.6 Mbit/s. Bytes through the relay for a direct session: 11 kB of the 60.6 MB sent. Client CPU per MB at 50 Mbit/s: direct 23 ms, relayed 1.6 ms.
Reproduce
(a) With the released binaries: with direct paths on (the default in organisation mode), serve a perf sink on one enrolled machine (nfltr cat serve <name> --perf) and run nfltr cat perf <machine>.<agent>/<name> --json from the other, once with --direct and once with --relayed. (b) Our check, in the closed nfltr repository, runs the lab's perf campaign in rounds: make conformance-direct-evidence-perf.
Limits
One machine's containers, so the unshaped round trip is a bridge's, with no network distance, and unshaped throughput is bound by the machine's CPU (a median of 1.6 Gbit/s on either path, varying from 1.4 to 2.6 Gbit/s with the other jobs it ran, load average 7 to 11 on 16 cores); on the shaped link both paths fill the link and the round trip under load is the router's queue. The CPU figures are at 50 Mbit/s: a direct path costs the client more CPU per byte: unshaped 5.0 against 1.9 ms per MB, and on macOS loopback 3.4 against 0.7 ms. A pair whose router maps each destination to a new port (symmetric) stays on the relay, as designed. Five runs are no distribution tail.

Measured: an appliance in a customer's network

A vendor's appliance runs Postgres at a customer's site, behind the customer's NAT router, listening on its own loopback only. The vendor's support laptop, behind another NAT router, reaches it through the relay or on a direct path. One scripted run checks each claim by an exit code or a JSON event the commands print.

Evidence: a support laptop, an appliance's Postgres and the relay

Setup
Linux containers (Docker) on one 16-core Linux build machine, November 16, 2026, three runs at one commit, the relay built from it. The appliance (Postgres 17.6, listening on 127.0.0.1 only, and nfltr up serving it as pg: {tcp: 5432, e2ee: true, allow_group: [support], direct: true}) behind one NAT router, the support laptop behind another (both cone), a private relay, the issuer in a container of its own, and a third machine of the vendor's in group ops. Every machine enrols with nfltr org join from a single-use token; the laptop runs psql through nfltr cat forward.
Numbers
In each of 3 runs: the appliance's only TCP listeners are on loopback; the machine outside group support is refused (exit 10); with --direct the session's path is direct 0.13 to 0.15 s after it began and the query answers; with --direct=off a 392 kB answer (a marker row 8000 times) comes through the relay, both sessions end-to-end encrypted by their open event; a capture on the relay's interface during that query holds about 406 kB from the appliance's router and 408 kB toward the laptop's, and the marker's bytes 0 times; nfltr org revoke of the laptop ends its held direct psql session 0.07 to 0.10 s later, the first new session is refused (exit 10) and a new psql connection fails; nfltr org audit --verify checks the issuer's log, which names the three enrolments and the revoke. A run takes about 70 s, 48 s of it building and starting the lab.
Reproduce
(a) With the released binaries: enrol the appliance and the laptop as the Organisations guide does, serve Postgres on the appliance with the pg line above in its nfltr up file, run nfltr cat forward <machine>.<agent>/pg --listen 127.0.0.1:15432 --direct --log-format json on the laptop and psql -h 127.0.0.1 -p 15432; capture on the relay with tcpdump while it runs; then nfltr org revoke <laptop> where the issuer runs and nfltr org audit --verify. (b) Our check, in the closed nfltr repository, runs all of it and judges each step by its exit code: make demo-appliance.
Limits
One machine's containers, so the times have no network distance (a real network adds the round trips between the issuer, the relay and each end). The capture is the relay's network interface: the connections to the relay are TLS themselves, so the capture shows what an observer of the relay's network sees; that the relay process cannot read the session rests on the session's end-to-end encryption (its open event) and the models above, not on the capture. Three runs show no distribution tail. The build machine ran other jobs at the same time (load average 9 to 13 on 16 cores).

Next