ADR 0169: the firewall seat serves its verbs, and a foreign rule set is removed through one of them

Designs 33 and 08 revised. The first node-scoped seat with verbs: rules,
reload, remove; the nftables module holds it from a runtime with NET_ADMIN,
the first container to declare a capability.

02-DECISIONS/0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md

@@ -0,0 +1,89 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-02
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0004-a-node-and-how-it-joins.md
+---
+
+# 169. A machine joins through the tunnel, and the bus is never public
+
+## Context
+
+The bus is the one channel every machine depends on: enrolment, every declaration, every tool. The
+`nats` module declares it reachable from the mesh only. The controller still opens it to the whole
+internet on the machine that runs it, as a *foundation* port that no module declares and nothing may
+close ([issue 051](../04-ISSUES/051-the-mesh-cannot-update-what-it-depends-on/00-report.md)).
+The reason is joining. [ADR 0004](0004-a-node-and-how-it-joins.md) has a new machine enrol over the bus
+**before** it has a tunnel. [ADR 0007](0007-connectivity.md) states it as a requirement: the node
+running the broker must be reachable from wherever nodes are, at a stable address.
+
+So the bus listens on the internet permanently, for an event that happens a few times a year. A
+sweep of every machine on 2026-10-02 found no client using the public path. Every connection arrives
+over the tunnel or from the machine itself. The join token does not use it either: it carries the
+controller's configured broker address, a mesh name with the old broker's port.
+
+ADR 0004 already says what a joining machine needs: *an identity, an address, and one peer to reach*.
+The tunnel can be that peer, if the hub knows the new machine's key before the machine first knocks.
+WireGuard answers nothing to a key it does not know, which is why the tunnel's own port is safe to
+leave open where the bus's is not.
+
+## Considered Options
+
+1. **Keep the bus public.** It is authenticated and encrypted, but every exposure of it, and of the
+   server behind it, is exposure of the one thing everything depends on.
+2. **Open the bus publicly only while a join token is live.** Small, and the hub is open only during a
+   join window. But the window is real, the rule is about time rather than about who may reach the
+   bus, and the opening and closing are pushes that can fail between them.
+3. **The controller makes the new machine's tunnel key and puts it in the token.** One step for the
+   operator, but the private half leaves a machine it does not belong to. ADR 0004 refuses that for
+   every key a node holds.
+4. **The machine makes its key first, and the token is issued for it.** The machine prints the public
+   half of its tunnel key. The operator issues the token for that key. The controller gives the
+   machine its address and adds it as a peer on the hub. The token carries the hub's tunnel endpoint
+   and key, the machine's address, and the bus's address on the private network. The machine brings
+   up its tunnel and enrols over it.
+
+## Decision
+
+**Option 4.**
+
+- **A machine makes its own tunnel key before it has a token**, and prints the public half. The private
+  half never leaves it, as ADR 0004 says of every key a node holds.
+- **A token is issued for a tunnel key.** Issuing it assigns the machine's address on the private
+  network, records the key, and makes the machine a peer of the hub. The hub is sent that before the
+  token is shown, so the tunnel answers the moment the machine first uses it.
+- **The token carries the one peer.** It adds the hub's tunnel endpoint and public key and the
+  machine's own address. **Where** becomes the bus's address on the private network, which needs no
+  name resolution.
+- **The machine joins through the tunnel.** It brings the tunnel up from the token alone, then enrols
+  over it exactly as before. The enrolment checks that the key it is offered is the one the token was
+  issued for.
+- **The bus is never public.** It is no longer a foundation port. Its reach is what the `nats` module
+  declares: the mesh. The tunnel's port stays open, as the one way in.
+
+This changes three things earlier records say. ADR 0004's *where* is the bus's private address, and the
+token carries the peer. ADR 0007's requirement that the broker be reachable from wherever nodes are
+becomes: **the hub's tunnel is**. Issue 051's broker port stops being a foundation port.
+
+## Consequences
+
+- Joining is two commands on the new machine, with the token issued between them. A token issued for
+  the wrong key gives a tunnel that never answers, and the machine says so rather than timing out at
+  the bus.
+- An unused token leaves a peer on the hub until it expires. Expiry removes it, the same way it voids
+  the secret.
+- A machine already in the mesh is unaffected: it reaches the bus over its tunnel today.
+- The genesis machine, the first one, raises the bus on itself and needs no tunnel to reach it.
+
+## How this is checked
+
+| Rule | Checked by |
+|---|---|
+| A token is refused without a tunnel key, and carries the hub's peer and the machine's address | a controller test |
+| Issuing a token makes the machine a peer of the hub before the token is shown | a controller test over the hub's composed tunnel |
+| An expired, unused token's peer is gone from the hub | a controller test |
+| Enrolment refuses a tunnel key other than the one the token was issued for | a controller test |
+| No machine's filter opens the bus to anywhere | a controller test over the composed filter, and the live sweep from outside the mesh |
+| A new machine joins from outside the hub's network with the bus closed to it | the lab, then by hand |

02-DECISIONS/0169-the-firewall-seat-serves-its-verbs.md

@@ -0,0 +1,84 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-02
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md
+---
+
+# 169. The firewall seat serves its verbs, and a foreign rule set is removed through one of them
+
+## Context
+
+[ADR 0168](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md) made the mesh say truthfully
+what filters a converged machine, and left the removal of what it did not write to the operator's
+hand. The first time that hand was needed — two machines, five rule sets a predecessor and a
+retired front end had left — there was no mesh way to lend it: the packet filter is a seat
+([ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)), a seat's
+holder serves its verbs ([ADR 0154](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md),
+[ADR 0159](0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md)), and the
+firewall seat declared none. The only remaining path was a shell on the machine, which is the path
+the mesh exists to replace, and which the operator's own tooling rightly refused to an agent.
+
+A seat's verbs are the contract every holder implements, whatever filter it speaks. What a person
+asks a machine's packet filter is the same whether nftables, a front end or a legacy filter answers:
+what are the rules, reload the mesh's own, remove this thing the mesh did not write. What differs by
+filter is the holder's own business and may be its own tools beside the seat's.
+
+## Decision
+
+**1. The `node-packet-filter` seat serves three verbs**, and a module that claims it serves all
+three or is refused the claim, as with every seat:
+
+- `rules` — the packet filter as the machine enforces it now: the nftables ruleset, and the legacy
+  filter's listings where that tool exists; narrowed to one table or chain when asked. Read-only.
+- `reload` — load the mesh's own filter again from the file the mesh writes, and answer with the
+  mesh's table as loaded. The holder's own act on the holder's own rules.
+- `remove` — remove one rule set the mesh did not write, named exactly as the host reports it under
+  ADR 0168 (`chain HAL-MESH-ONLY (iptables-legacy)`, `table ip6 filter, chain DOCKER-USER`), and
+  answer with what was done. It refuses the mesh's own tables, the container runtime's own chains,
+  a built-in chain other than the runtime's user chain, and any chain of a found firewall that is
+  in force. The runtime's user chain is emptied back to its one return; another chain loses the
+  jumps into it, is flushed and deleted; a table of the machine's own is deleted whole. Each is an
+  operator's act, by name, on one thing the mesh reported — never a flush, never a rule the mesh
+  itself marked.
+
+**2. A holder may serve its own tools beside the seat's.** The nftables module keeps its reading of
+the mesh's table as its own tool, and a holder speaking a filter with specifics of its own may add
+tools for them; the seat's three are what every holder owes.
+
+**3. A container may ask for a capability.** Serving `remove` and `reload` needs the machine's
+network namespace and the right to change its packet filter; a holder's runtime declares
+`capabilities: ["NET_ADMIN"]` on its container and runs on the machine's network. The host grants
+exactly the capabilities declared, names them in the container's spec so a change recreates it, and
+refuses a name that is not a capability's. A privileged container stays undeclarable.
+
+**4. ADR 0168's "by hand" is read as "by the operator, through the seat".** Removing what the mesh
+reports as *other* is still the operator's act and is still never the mesh's own doing; the verb is
+how the act reaches the machine, recorded on the bus like every other, instead of a shell.
+
+## Consequences
+
+- The seat's row gains the three verbs; a mesh that already runs widens its row at the next
+  controller start. The nftables module claims them and gains a runtime — a tool server with the
+  packet filter's tools in its image, on the machine's network, with `NET_ADMIN`.
+- The host's container vocabulary grows by `capabilities`; an older host refuses a declaration that
+  carries it, so the host rolls before the module.
+- The two machines of this mesh that ADR 0168 found not filtered by the mesh alone are cleaned
+  through `remove`, and read *the mesh alone* afterwards; `status` returns to well without a hand on
+  either machine.
+
+## How this is checked
+
+| Rule | Checked by |
+|---|---|
+| The seat declares the three verbs; a claim that serves fewer is refused by name | the catalogue's seat tests |
+| `remove` refuses the mesh's tables, the runtime's chains, a built-in chain and an active front end's chains, and removes a user chain with its jumps, empties the user chain, deletes an own table | the module's tests over a fake command runner, with the shapes the host reported live |
+| A container's capabilities reach the runtime and its spec; an unknown name is refused | host tests |
+| Live | `node-packet-filter.remove@<node>` on the home server and the control node; `node show` reads *the mesh alone* on both; `status` is well |
+
+## References
+
+- [ADR 0168](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md), [ADR 0154](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md), [ADR 0159](0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md), [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)
+- [Design 33 — The tools the mesh answers](../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md), [Design 08 — Connectivity](../03-DESIGN/01-to-be/08-connectivity.md)

02-DECISIONS/README.md

@@ -179,6 +179,8 @@ python3 00-META/checks/index.py            fail if stale
 - **0163** — [Taking a module over is a comparison: what it compares, what it refuses, and what it carries](0163-taking-a-module-over-is-a-comparison.md)
 - **0167** — [A membership carries what its module receives, and who the mesh is](0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
 - **0168** — [A converged machine is filtered by the mesh alone, and the host says what else refuses](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)
+- **0169** — [A machine joins through the tunnel, and the bus is never public](0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md)
+- **0169** — [The firewall seat serves its verbs, and a foreign rule set is removed through one of them](0169-the-firewall-seat-serves-its-verbs.md)
 
 ### Its tiers, from the bottom up
 

03-DESIGN/01-to-be/08-connectivity.md

@@ -9,6 +9,8 @@ code:
   - mesh-host internal/apply (the service that reflects a rule set)
 updated: 2026-10-02
 decisions:
+  - 02-DECISIONS/0169-the-firewall-seat-serves-its-verbs.md
+  - 02-DECISIONS/0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md
   - 02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md
   - 02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md
   - 02-DECISIONS/0148-the-meshs-names-are-resolved-not-copied-into-containers.md
@@ -173,6 +175,28 @@ the broker's node must be dialable by every node, at a stable address, and so mu
 reachable; on one network it does not. A mesh whose nodes are all behind NAT cannot be raised, and
 a broker node whose address moves invalidates every token issued for it.
 
+*2026-10-02.* **The order changes at step 1: the tunnel comes first, from the token**
+([ADR 0169](../../02-DECISIONS/0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md)).
+The circularity above is real, and it is broken differently. The overlay is configured by the mesh,
+except for the one peer a joining machine needs, and the token carries that peer. So the sequence
+becomes:
+
+```
+0  the node has an underlay address     the machine's own
+1  the node makes its tunnel key        before any token; it prints the public half
+2  a token is issued for that key       its address assigned, and the hub sent it as a peer
+3  the tunnel comes up to the hub       from the token alone: the hub's endpoint and key, its address
+4  the node dials the bus               OVER THE TUNNEL, at the bus's private address
+5  it proves itself, and is proved to   enrolment, checking the key is the one the token named
+6  the rest of the overlay              the whole peer set, delivered as files
+7  names, filtering, routes             as before
+```
+
+The link no longer stays on the underlay. The bus is reached over the tunnel by every machine,
+including one that is joining, so it is never opened to the internet. The precondition becomes: **the
+hub's tunnel must be dialable by every node, at a stable address.** That port answers nothing to a
+key it does not know.
+
 **Whether the link should later move onto the overlay, with the underlay as fallback, is
 [open](../../02-DECISIONS/0007-connectivity.md).** It is a decision rather than a derivation: the
 gain is which network carries bytes, not what an attacker can reach, since the link is already
@@ -743,6 +767,11 @@ tests over a fixture report check the recording, the preview's fates, the status
 predicate. Live: the home server's record names the predecessor's chain as *other* and `status`
 names the machine until the chain is removed by hand.
 
+*2026-10-02, [ADR 0169](../../02-DECISIONS/0169-the-firewall-seat-serves-its-verbs.md):* removing what
+the host reports as *other* is reached through the packet filter seat's `remove` verb, an operator's act
+by name on the bus; the seat also serves `rules` and `reload`, and its holder's runtime declares the
+`NET_ADMIN` capability on the machine's network. See design 33.
+
 ## 5 — Certificates
 
 **Two authorities, kept separate on purpose.**

03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md

@@ -2,8 +2,9 @@
 layer: to-be
 status: implemented
 code: [mesh-controller, mesh-tools]
-updated: 2026-10-01
+updated: 2026-10-02
 decisions:
+  - 02-DECISIONS/0169-the-firewall-seat-serves-its-verbs.md
   - 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
   - 02-DECISIONS/0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md
   - 02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md
@@ -169,6 +170,18 @@ either way.
 What stays as designed and not built: which verbs any *other* seat serves, and §3 for module-declared
 seats' schemas beyond the names their manifests already list.
 
+## The firewall seat's verbs, 2026-10-02
+
+[ADR 0169](../../02-DECISIONS/0169-the-firewall-seat-serves-its-verbs.md). The first node-scoped seat
+to carry verbs: `node-packet-filter` serves `rules` (the filter as the machine enforces it, nftables
+and legacy), `reload` (the mesh's own filter from its file) and `remove` (one rule set the mesh did
+not write, named as the host reports it under ADR 0168; refusing the mesh's tables, the runtime's
+own chains, a built-in chain and an active found firewall's). Every holder serves all three; the
+nftables module does so from a runtime on the machine's network with `NET_ADMIN`, which is the first
+container to declare a capability. Removing a predecessor's rule set is an operator's act reached
+through the seat, recorded on the bus, instead of a shell on the machine. *How it is checked:* ADR
+0169's table.
+
 ## What this does not settle
 
 - Which verbs each seat should serve. That is a decision per seat, and the reason to do it slowly: a

04-ISSUES/198-the-lans-dns-server-ran-outside-the-mesh-and-its-filter-closed-it/00-report.md

@@ -0,0 +1,71 @@
+---
+status: resolved
+opened: 2026-10-02
+located-in: [mesh-catalog modules/dnsmasq (listens on loopback and the machine's mesh address only), the home-server's DNS (a predecessor's dnsmasq configuration the mesh did not own), the home network's DHCP (hands out the home-server as every device's DNS)]
+fixed-by: mesh-catalog PR 214 (dnsmasq listens on addresses from a setting; docker's file takes no settings), mesh-controller PR 210 (the settings verb), mesh-catalog PR 215 (unifi network DNS tools), live 2026-10-02
+amended-design: []
+---
+
+# 198 — The home network's DNS server ran outside the mesh, and the mesh's filter closed it
+
+## What was observed
+
+Every phone on the home Wi-Fi had no internet, while a laptop on the same Wi-Fi did. The router's
+DHCP hands every device the home-server's LAN address as its DNS server. The home-server's DNS daemon
+was listening on that address, and every query to it timed out. The router itself answered the same
+query at once. The laptop worked because it resolves through its own local resolver, not through the
+server DHCP names.
+
+## Why it happened
+
+The DNS daemon on the home-server was not the mesh's. It ran under a configuration file a predecessor
+generated, listening on loopback, the mesh address and the LAN address. The mesh's `dnsmasq` module was
+assigned to the other three machines and not to this one, so no module on the home-server declared
+port 53. Its filter opens only what a module declares, so DNS from the LAN was dropped. It started when
+the home-server applied the filter this morning, after nine hours of applying nothing
+([issue 194](../194-the-hosts-own-former-archive-stops-every-apply/00-report.md)).
+
+Nothing said so. The daemon reported running, the filter applied cleanly, and the mesh had no record
+that the home network depended on a service it did not know.
+
+## Why it matters
+
+**A service the mesh does not know is closed by the mesh's filter, by design, and nothing asks whether
+something depends on it.** That is the right default for an unknown port. It is the wrong outcome for
+the one service a whole network was told to use. The gap is that a machine can run something
+important outside the mesh with nothing to show it.
+
+**The mesh's `dnsmasq` could not have served the LAN either.** It listened on loopback and the mesh
+address only. The reach of its DNS endpoints opens the filter, but the daemon would not have been
+listening on the LAN address anyway.
+
+## Open questions
+
+- Should a machine report the listening services the mesh does not own, the way it reports the links
+  that face outside? This one would have been visible before the filter closed it.
+- The LAN address the home-server answers on is now a setting, beside the reach that opens the filter.
+  Two statements that must agree. Should reach `public` on a DNS endpoint imply listening beyond the
+  mesh?
+
+## Resolved (2026-10-02)
+
+The home network was pointed at the gateway for DNS while the fix was built, which got the phones back
+within minutes. Then:
+
+- the mesh's `dnsmasq` takes the addresses it listens on beside the machine's from a setting, with
+  loopback as the mesh-wide default, so no other machine changed;
+- the home-server's layer adds its LAN address, and its DNS endpoints' reach is `public`. The router
+  forwards no DNS, so that means the LAN;
+- the module and its sibling `resolv-conf` were assigned to the home-server, replacing the
+  predecessor's daemon and configuration, which were kept aside;
+- the home network was pointed back at the home-server, through a new `unifi` tool.
+
+Checked live: from another machine on the LAN, public names and mesh names both resolve through the
+home-server's LAN address, and the mesh and the machine itself resolve as before.
+
+**One fault found on the way, and caught before it reached any machine.** A module's settings are
+merged into every mergeable file the module owns. The first attempt therefore put the new setting into
+docker's `daemon.json` as well as into dnsmasq's config, and dockerd refuses keys it does not know. The
+plan showed it before any push. The change was reverted and redone with docker's file declared to take
+no settings. The general fault, a module's settings reaching files they were not meant for, is still
+there for any module with more than one file.