hq/02-DECISIONS/0039-the-link-is-the-security-boundary.md

status, date, deciders, reconstructed, extends

status	date	deciders	reconstructed	extends
accepted	2026-08-25	jochen	false	0038-a-node-joins-by-linking-first.md

39. The link is the security boundary

Context

ADR 0038 makes the link the one channel a node takes declarations from, and names the gap it leaves: "everything a node applies arrives through it, so what may be pushed, and how a joining node proves it is entitled to join, is now a question worth its own record."

This is that record. It is a design decision about a boundary that does not exist yet — but what it replaces is measured, and that is the argument.

Settled as: a node owns no password. It owns an identity, and that identity is what it presents to the broker.

What adoption does today

install.d/adopt.sh asks the operator to paste credentials in by hand:

The meshware module needs registry database and minio credentials.
  REGISTRY_DB_PASSWORD=<postgres password from novox>
  REGISTRY_MINIO_PASSWORD=<minio password from novox>

plus an NPM_TOKEN for the private registry. These are not adoption-time credentials that are then discarded: wireguard and traefik open a pg connection on every reconcile (ADR 0037).

So every node permanently holds a credential to the control plane's database, and to the object store. They are the same credentials on every node. There is no rotation — 00-as-is/06 records that "there is no mechanism that rotates one and informs everything holding it. Where a rotation has been done, it has been done by hand, and doing it wrong has taken services down."

Compromise of any node is therefore compromise of the mesh's database, and there is no mechanism to recover from it.

The link is not new

Written first as though the link were a thing to build. It is not. ADR 0001 already has it: every node connects outbound to a single broker; nothing ever connects to a node, each node declaring an exchange named for itself and consuming from its own queue (00-as-is/01).

That is already outbound-only, already per-node addressed, and already the one channel everything arrives through. This record is not proposing a channel. It is proposing that the channel carry per-node identity instead of one shared credential.

The same as-is records the fault, for the broker rather than the database: "the broker is a single point of failure and a single point of trust. Its credential is mesh-wide, so rotating it is a mesh-wide operation, and doing it wrong has taken the broker down."

Considered options

1. Keep shared credentials, scope them per node. Least change: give each node its own database role. Rejected — it makes the blast radius smaller without changing its shape, and it keeps tier 0 speaking the control plane's schema, which ADR 0037 forbids for reasons that are not about security at all.
2. Accept the exposure as the cost of simplicity. A shared credential is one thing to understand and nothing to build, and the objection to replacing it is real: mutual authentication fails opaquely, and a node that cannot link is harder to debug than a node with a wrong password. Rejected on the ground that the simplicity is what makes it unrotatable — the credential cannot be changed because everything holds the same one, so the arrangement's convenience and its unfixability are the same property.
3. Mutual authority on a node-initiated link, with the node holding nothing but its own identity. Chosen.

Decision

The link is the only way anything reaches a node, and four properties make it a boundary rather than a pipe.

It is outbound and node-initiated

The node dials the control plane. Nothing dials a node. This is not only defensive — it is what the topology already requires: most nodes sit behind a household connection with no forwarded port (research 004), so an inbound control channel would work for the hosted node and not for the rest, and the difference would be invisible until it mattered.

A node therefore has no listening control surface at all.

A node holds its own identity and nothing else

No shared secret, no credential to anything it does not own. A node's identity authenticates it to the control plane and grants access to nothing else.

Compromise of a node is compromise of that node. That is the property today's arrangement does not have, and it is the main reason for this record.

Authority is mutual

The node proves it may join, and the control plane proves it is the mesh. One-way is not enough here: the host applies whatever the link delivers, so a node that cannot tell the mesh from something impersonating it will apply that something's declarations. Given ADR 0038, an attacker who can answer a joining node's first call owns the machine.

What may be pushed is bounded by form, not by trust

The control plane may push declarations of known shape and nothing else. It may not push a command to run. The host's vocabulary is finite, versioned and auditable, and anything outside it is refused rather than best-effort interpreted.

Stated honestly: this bounds form, not impact. A compromised control plane can declare harmful state — a malicious package, an open firewall — and the host will apply it faithfully, because that is what it is for. What the property buys is that the blast radius is describable: it is exactly what the declaration language can express, which can be reviewed. An arbitrary command channel has no such bound. This is a real limit and not a defence-in-depth story.

Joining is a deliberate, bounded act

A joining node presents a one-time, short-lived enrolment token issued by the mesh for that purpose, and exchanges it for its own durable identity. The token grants exactly one thing: the right to become a node. It is not a credential to any service, it does not persist after exchange, and it expires whether used or not.

This replaces hand-carried shared secrets with a thing that is useless once used and useless after a while.

What this actually costs

The objection to weigh is overhead, and it is smaller than it looks because most of it is already running.

Property	Where it comes from
outbound, node-initiated	already true — ADR 0001
per-node addressing	already true — per-node exchange and queue
per-node credential	a broker user per node; the broker already has users, virtual hosts and per-queue permissions
mutual authority	transport-level certificates on a connection that already exists
bounded by form	already true — three message shapes and only three
enrolment	the one genuinely new mechanism

And ADR 0037 subtracts rather than adds: under it a node holds no database credential at all, so this record replaces three hand-carried shared secrets with one per-node identity that grants only identity.

It must fail legibly. A boundary that refuses a node without saying why is worse than the credential it replaced, because a wrong password at least announces itself. A node that cannot link must report which side rejected it and on what grounds, in terms someone can act on. This is how-we-build §5 applied to a security mechanism: a refusal that proves only that something went wrong is transport reported as effect.

Consequences

• ADR 0037 removes a standing exposure as a side effect. Its rule — the host never queries the mesh database — was chosen for tier discipline. It also removes the reason every node holds the database password. Worth recording because the two arguments are independent and both hold.
• Rotation becomes possible and is still not designed. Per-node identities can be revoked individually, which is what makes rotation tractable at all. The mechanism — what rotates, on what trigger, and how holders learn — is not decided here and remains the open weakness 00-as-is/06 records.
• The enrolment token has to come from somewhere. Issuing it is a control-plane operation and the first node has no control plane, so the first node's identity is self-issued and becomes the root of trust when the mesh comes up. That is a real asymmetry — the one place ADR 0038's "no special first node" does not fully hold — and it is named here rather than hidden.
• A declaration vocabulary is now a security artefact, not only a design one. Every addition widens what a compromised control plane can express. That is a reason to keep it small and a reason for additions to be reviewed as such.
• Offline nodes need identities that survive disconnection. Per ADR 0036 disconnection is ordinary, so an identity that must be refreshed to remain valid would make a laptop fail for being a laptop. What expires and what does not is not decided here.
• This is a boundary that does not exist yet. Nothing in the current mesh implements any of it, and the migration from shared credentials to per-node identity touches every node and the substrate. No estimate is offered.

References

• ADR 0038 — the link, and the gap this fills.
• ADR 0037 — why the host stops holding database credentials at all.
• ADR 0036 — disconnection as ordinary, which constrains what may expire.
• 00-as-is/06-configuration-and-secrets.md — secrets today, and the absence of rotation.
• Research 004 — why most nodes cannot accept an inbound connection.