Organisations: Machines by Name

An organisation lets your machines trust each other by name. You hold one root key; an issuer on a machine of yours gives each machine a short-lived certificate for its name and groups. Clients dial web-1.db/pg, services admit the group db, and a revocation or a lost root reaches every machine. The relay carries all of it and can forge none of it.

Why organisations

End-to-end encryption needs each end to know the other's key. Doing that by hand means a pin on every client for every service, and a list of client keys on every service: for N machines and M services, about N × M values to copy and keep current. That stops scaling at a handful of machines, and a stale pin fails exactly when you need it.

With an organisation, each machine has one first step: your provisioning hands it the root's fingerprint, the recovery key's fingerprint and a single-use token. After that:

• Names, not keys. A client names the machine it wants; its certificate proves the name.
• Groups. A service admits groups (db), not lists of keys. A machine's groups are in its certificate.
• One root you control. It stays on your machine, and you approve each of its signatures (Touch ID, or a passphrase).
• Revocation and rotation reach every machine. A revoked machine's sessions end within seconds. A lost root is replaced with the recovery key, and every machine follows.

The relay is not trusted with any of this. It carries enrolments, certificates and revocation lists, but it holds no key of your organisation, so it cannot issue a certificate, hide a revocation for longer than an hour, or put itself in the middle of a session.

Organisation mode covers end-to-end encrypted TCP (nfltr tcp, dial, tcp-connect, connect: mappings), nfltr shell over SSH, and machines' agent-to-agent keys. It is the only end-to-end encrypted mode for those: pins and client key lists are gone.

Concepts

Who runs what, where

The issuer runs on a machine of yours, never on nfltr.xyz. The relay is the party this design does not trust: an issuer there could mint certificates for any name. Today the issuer lives where nfltr org init ran, beside the root, so pick a machine that stays on and awake (a home server or a small VM rather than a laptop that sleeps); see Keep the issuer up for why. Every machine uses the same relay account: enrolment, renewal and revocation travel through that account.

Set up the organisation

Choose the root

The root is one of two kinds, chosen at nfltr org init and kept for the organisation's life. Each signature asks you first.

A file root can be copied, and a copy plus the passphrase signs anywhere, with no trace on your machine. So use a long passphrase (at least 12 characters; several random words), keep the file on a machine only you use, and keep the recovery key offline: it alone replaces a stolen root. The passphrase is read from the terminal only, never from standard input, an argument or the environment, so these commands need one (ssh -t works).

Make it

On the issuer's machine, with your relay account configured (nfltr config login, or nfltr config set-relay for a relay you run):

$ nfltr org init --groups web,db,ci --recovery-out /Volumes/USB/recovery.key
New passphrase of the organisation root (~/.config/nfltr/org/root-org.key, at least 12 characters):
The passphrase again:
Passphrase of the organisation root, to make the organisation's root and its issuer (30 days):
Passphrase of the organisation root, to make the organisation's root and its issuer (30 days):
organisation o-dg4lusupegx2eytlh7m6xcccmi
root      sha256:19b8ba4a8f21afa2626b3fd9eb884262dfda28701a2da2488867c970d0e34960 (file)
recovery  sha256:b343a8935d14b3b1e34b588cb9aa06cb714fda51ddf5c11fc5ead82e601eaee4
issuer    groups web,db,ci, until 2026-12-11T17:15:54Z
The recovery key is in /Volumes/USB/recovery.key: move it offline now. It alone rotates the root (nfltr org rotate).

The root line says which kind of root it made. With --root secure-enclave and the helper installed, the four passphrase prompts become two Touch IDs. Keep both fingerprints: every machine needs them. Move the recovery key file offline now. --groups is the issuer's policy: it can give out only these groups.

Keep the issuer up

The issuer answers enrolments and renewals, signs the CRL every hour and at once after a revoke, and publishes the CRL and the root through the relay. nfltr node on this machine serves it (it finds the issuer's files), so the node you run anyway keeps it up. nfltr org serve is the same service in the foreground, for a machine without a node:

$ nfltr org serve
level=INFO msg="org issuer: serving enrolments, renewals, the CRL and the root through the relay" a2a_keys=false

If nothing serves the issuer for longer than the CRL's hour, the CRL lapses, and from then on every machine admits no one under that issuer: every organisation session in the fleet is refused and every open one is cut. This is deliberate. A machine cannot tell an issuer that is down from a relay that withholds a revocation, and the safe answer to both is to stop. It recovers by itself once the issuer runs again.

Watch it with nfltr org status. It exits 1 when no process serves the issuer, when the CRL has lapsed or when the issuer certificate has expired, so a cron job or a monitor can alert well before the next update:

$ nfltr org status
organisation o-dg4lusupegx2eytlh7m6xcccmi
root      sha256:19b8ba4a8f21afa2626b3fd9eb884262dfda28701a2da2488867c970d0e34960
recovery  sha256:b343a8935d14b3b1e34b588cb9aa06cb714fda51ddf5c11fc5ead82e601eaee4
issuer certificate until 2026-12-11T17:15:54Z (in 720h0m0s; nfltr org issuer renew before then)
CRL #1 next update 2026-11-11T18:16:05Z (in 1h0m0s)
served: yes (nfltr node or nfltr org serve on this machine)

When nothing serves it, the last lines read served: no (run nfltr node, or nfltr org serve, on this machine) and the error says no process serves the issuer and the CRL lapses at its next update, with exit status 1. A crontab line that alerts every 10 minutes:

*/10 * * * * nfltr org status >/dev/null 2>&1 || your-alert-command "organisation issuer down"

Enrol machines

Names

A machine enrols under its name in your relay account: the name nfltr machines lists for it (on a relay you run, the --name you gave its key). Clients dial another machine as <machine>.<agent>, the same address as any agent of your account, and check the machine part against the certificate. So the names must agree, and every machine needs an API key of its own: machines that share one key are one machine of your account. On a relay you run, make one per machine with nfltr-relay keys generate --name <machine> --account admin. The issuer refuses an enrolment whose token's name is not the name of the machine that sent it in your account (another machine's name, or one your account does not have), and says which, before the token is used up. An enrolled machine's nfltr up, nfltr shell, nfltr node or nfltr tcp --allow-group refuses to start (exit 1) under another machine's key, naming both and the fix.

One machine

On the issuer's machine, one token per machine name:

$ nfltr org token --name web-1 --group web --ttl 1h > web-1.token
Single use, for web-1, until 2026-11-11T18:16:20Z. Provision it with the root sha256:19b8… and the recovery sha256:b343….

The token goes to standard output and nowhere else; the line about it goes to standard error. It is single use: it enrols that one name, once, before --ttl ends. Add --machine-id <id> (the machine's id, from nfltr machines) for a machine that will make agent-to-agent calls: its enrolment then carries its agent-to-agent key (below).

Your provisioning (cloud-init, Ansible, a Kubernetes Secret, MDM) delivers the token with the two fingerprints. On the machine, with the same relay account configured:

$ nfltr org join --root sha256:19b8… --recovery sha256:b343… --token-file /run/secrets/nfltr-token
enrolled as web-1 (groups web) until 2026-11-12T17:16:33Z; nfltr node and nfltr up renew it

--token-file - reads the token from standard input; NFLTR_ORG_ROOT and NFLTR_ORG_RECOVERY can carry the fingerprints. The machine makes its own key, checks the root the relay hands it against the fingerprint you gave it, and keeps its certificate in its config directory (key mode 0600). Never put a token on a command line or in an environment variable: other users of the machine can read those.

From then on nfltr up, nfltr node and nfltr shell renew the certificate and follow the CRL and the root. Every other nfltr command on the machine reads what they keep. A machine that is off for longer than its certificate's 24 hours enrols again with a new token.

Many machines

The same two commands in a loop. Here the issuer's machine reaches each new machine over SSH, and the token travels on standard input from one command to the other, never on a command line:

ROOT=sha256:19b8…   # nfltr org init printed these
REC=sha256:b343…
for m in web-1 web-2 web-3; do
  nfltr org token --name "$m" --group web 2>/dev/null |
    ssh "$m" nfltr org join --root "$ROOT" --recovery "$REC" --token-file -
done

With cloud-init, Ansible or a Kubernetes Secret, write the token to a file only the machine's nfltr user can read and pass --token-file. A token lasts an hour by default (--ttl), so make tokens close to when machines boot.

Use it

Services and clients

A service admits groups. On the machine web-1:

$ nfltr tcp 5432 --allow-group db --name db

or under nfltr up:

agent: db
services:
  pg: { tcp: 5432, e2ee: true, allow_group: [db] }

A tcp service with end-to-end encryption needs allow_group and refuses to start without it, and it refuses to start on a machine that is not enrolled.

A client on an enrolled machine names the machine and its agent. Its sessions are end-to-end encrypted in organisation mode with no flag ("e2ee":true), and it checks that the certificate is the organisation's for the machine part, not revoked:

$ printf hello | nfltr dial web-1.db/pg
{"event":"open","target":"web-1.db/pg","session":"s-d20341fa","e2ee":true,"time":"…"}
hello{"event":"close","session":"s-d20341fa","bytes_in":5,"bytes_out":5,"time":"…"}
$ nfltr tcp-connect web-1.db/pg --listen 127.0.0.1:5432

So is every connect: mapping of its nfltr up:

connect:
  pg: { target: web-1.db/pg, listen: "127.0.0.1:5432" }

A bare agent name (db/pg) is an agent of the client's own account machine. A client outside the service's groups, revoked or expired is refused in the TLS handshake with exit 10 (e2ee_client_refused). The connect sidecar guide shows mappings in a larger setup.

Services by name

A service several machines run is published under a group and dialled by its name, <service>@<group>. Every instance runs the same file, with publish: naming a group its certificate holds:

agent: pg
services:
  pg: { tcp: 5432, e2ee: true, allow_group: [app], publish: db }

A client of the organisation dials the name; the relay picks an online instance for each session, and the client checks that the certificate holds group db and that the session names the service pg, never which machine:

$ nfltr services
NAME   KIND  E2EE  DIRECT  INSTANCES  UP
pg@db  tcp   e2ee  -       2          2
$ nfltr tcp-connect pg@db --listen 127.0.0.1:5432

Each connection of a target: pg@db mapping is its own pick, so a mapping never stays on a machine that went away; an instance the client refuses is skipped and another tried until --open-timeout. nfltr services pg@db lists the instances, --watch follows them. To reach one machine, dial it as <machine>.<agent>/pg. The connect sidecar guide shows mappings in a larger setup.

Direct paths

An organisation-mode session can leave the relay and run straight between the two machines over UDP, under the same end-to-end TLS, falling back to the relay when that path dies. It is off unless both ends ask: direct: true on the service and on the mapping, or --direct on nfltr dial and tcp-connect. Each end then learns the other's public address (and its LAN addresses, unless direct: public). nfltr config set-direct on makes asking the machine's default for every organisation-mode session and service that names no direct setting of its own (direct: false still wins; off unless set). The flags are in the CLI reference.

Plain on purpose

--plain (on nfltr dial, tcp-connect and ssh-proxy) or plain: true (on a mapping) reaches a service that is not end-to-end encrypted, for that call or mapping only. There is no setting that turns it on for a whole machine, and nothing the relay says changes the mode. An enrolled machine that dials a plain service without --plain gets exit 7, and the message names --plain. A machine that is not enrolled opens plain sessions, and an organisation-mode service refuses them (exit 4).

SSH with nfltr shell

nfltr shell on an enrolled machine presents an SSH host certificate for its name, signed by the issuer and renewed with the machine's certificate. On the client, trust the organisation once, then add the machine:

$ nfltr org trust
ssh now trusts organisation o-…'s machines (*.o-….internal) in /home/you/.ssh/known_hosts
per machine: nfltr ssh-config <name>
$ nfltr ssh-config web-1.web-1 --identity ~/.ssh/id_ed25519
$ ssh web-1.web-1 'echo hello from $(hostname)'
hello from web-1

nfltr org trust writes one @cert-authority line, the issuer's key, read from this machine's own organisation files and checked there first, never taken from the relay. nfltr ssh-config writes HostKeyAlias <name>.<org id>.internal and StrictHostKeyChecking yes, so ssh accepts only a certificate for that name and never offers to trust a new key. Its ProxyCommand opens the session with --plain: SSH is the end-to-end layer and checks the certificate itself. web-1.web-1 is the shell agent web-1 (a shell's agent is its machine's name) of the machine web-1; from the same machine, the bare web-1 works. The SSH tutorial walks through it step by step.

Agent-to-agent keys

If the issuer's machine also holds your agent-to-agent root key (a hub makes one on its first start), an enrolment for a token made with --machine-id carries that machine's agent-to-agent key, sealed to the machine's new key: no key file to copy. nfltr org join writes it beside the machine's config, mode 0600. nfltr orch hub machines lists the keys and nfltr orch hub machines revoke revokes one. More in Join machines as nodes.

Manage it

Monthly: renew the issuer

The issuer's certificate lasts 30 days. Once a month, on the issuer's machine:

$ nfltr org issuer renew
Passphrase of the organisation root, to renew the issuer (30 days) and checkpoint the audit log:
Passphrase of the organisation root, to renew the issuer (30 days) and checkpoint the audit log:
issuer renewed: groups ci,db,web, until 2026-12-11T17:21:32Z; log checkpoint c5f0fbb6…

Two signatures (two passphrases or two Touch IDs): the new issuer certificate, and a checkpoint of the audit log signed by the root. --groups changes the policy. nfltr org status shows the days left.

Revoke a machine

$ nfltr org revoke db-1
revoked db-1: no renewal from now; every unexpired certificate of it is in ~/.config/nfltr/org/crl.der

Every unexpired certificate of the name goes into a new CRL, and the name can never renew. The issuer publishes the CRL within 10 seconds. Every machine holding a session with db-1 ends it when the CRL reaches it, and new sessions are refused (exit 10):

• within seconds through the relay's push;
• within 10 minutes if the relay withholds the push: each machine also reads the CRL afresh every 10 minutes;
• within the CRL's hour if the relay withholds everything: a machine whose CRL has expired admits no one under the issuer.

To bring the machine back, enrol it under a new name with a new token.

Someone leaves

Revoke every machine they had a key on (nfltr org revoke <name>), and remove their machines' keys from your relay account (nfltr machines revoke). If they could reach the issuer's machine or the root, rotate the root as below.

A lost or stolen root: rotate

If the root (the Mac, or a copy of the root file and its passphrase) is lost or stolen, rotate with the recovery key on the issuer's machine:

$ nfltr org rotate --recovery-key-file - < /Volumes/USB/recovery.key
rotated: root sha256:e318… (file "org-20261111T172109"), certified by the recovery key; a new issuer. Machines renew into it on their next contact.

The recovery key certifies a new root of the same kind (a file root asks for a new passphrase), which certifies a new issuer. Machines take the new root from the relay, accept it only if it is signed by the recovery key they pinned when they joined, end sessions under the old root and renew into the new issuer by themselves, within seconds. Revoked names stay out. A relay can delay a rotation by withholding it, so a machine stays on the old root until the rotation reaches it.

A machine new after the rotation joins with the new root's fingerprint, the one nfltr org status and nfltr org token print now. Its token names the organisation, which keeps its id across rotations, so the machine finds the organisation's root on the relay and checks it against that fingerprint. Tokens made before v2.1.58 name no organisation and are refused: make a new one.

Audit

$ nfltr org audit --verify
verified 28 entries; head c5f0fbb6…; last root checkpoint 2026-11-11T17:21:32Z

nfltr org audit prints every act: tokens, enrolments, renewals, revocations, CRLs, issuer renewals and rotations. The log is hash-chained, and the monthly issuer renewal signs its head with the root, so a stolen issuer key cannot rewrite what came before. --json prints the raw lines.

Limits

Stated plainly, so you can judge whether they matter for you:

• SSH cannot check revocation. OpenSSH checks the host certificate, not the CRL. A revoked machine's nfltr shell stays trusted by ssh until its host certificate ends: up to 24 hours.
• The CRL fails closed. If nothing serves the issuer for more than an hour, every organisation session in the fleet is refused until it runs again. Run the issuer on a machine that stays on, and alert on nfltr org status.
• The issuer lives with the root. Today the issuer runs where nfltr org init ran. Certifying an issuer on a separate always-on machine, with the root signing it monthly from elsewhere, is not available yet.
• One relay account. Every machine of an organisation uses one relay account: its mailboxes carry enrolment and revocation.
• Tokens only. Machines enrol with single-use tokens. Cloud instance identity and Kubernetes service-account tokens are not supported.
• Names follow the account. A client dials another machine as <machine>.<agent>, or a service by name as <service>@<group>. An organisation machine name that resolves from anywhere in the account is not offered: dial the service by name instead.
• Service health stays on the agent. nfltr up probes each published service's target and logs when it goes down or up; the relay does not see that yet, so it picks among all online instances and nfltr services shows each as up.
• The Secure Enclave root needs a helper that this release does not ship. The file root is the default until it does.
• What the relay still sees. It cannot read or change organisation-mode sessions, but it sees which machine talks to which, when, and how much, and it can refuse to carry anything.

Troubleshooting

Next

• SSH to a machine behind NAT: nfltr shell step by step
• Join machines as nodes: nodes, hubs and agent-to-agent keys
• End-to-end encryption: what each path protects
• Organisations: trusting machines by name, not by pinned key: the design, its threat model and the evidence