Designs 08 and 33: the firewall seat's control verbs beside the derived ports (the operator, 2026-11-21)
The operator decided that the packet filter's module must have tools to control it beside what is derived from the modules' declarations: deriving every open port from listens left no way to open a port no manifest names. Design 08 section 4 keeps the derived ports as the automatic part and adds allowances set by hand; the node-engine stays the one renderer, asks the holder's allowed verb at every compose, refuses the compose and keeps the loaded filter when it gets no answer, and renders allowances only on a converged node. Design 33 gives the seat allow, disallow and allowed, widens rules, and adds the event allowances-changed and the holder's state: one allowance per protocol, port and interface, removed and journalled at its expiry. Both follow ADR 0683 and design 47 H's lead answers H-A-304, H-A-305, H-A-307 and H-A-308. Both designs are put in playbook 02's shape: their new lines live in milestone parts, and design 08's adoption lines move to a delivered part so the main file stays under 80 KB. The glossary gains allowance.
This commit is contained in:
@@ -1164,6 +1164,11 @@ it should not. **Recorded by** the controller. **Upstream of** Provisioning and
|
||||
- **packet filter** — what the mesh enforces on a node about which packets pass, the
|
||||
`node-packet-filter` seat and its verb `rules`. A **found firewall** is a program the mesh found on a
|
||||
machine and keeps retired or in force; *firewall* says that, and a wrapped program's firewall is its own.
|
||||
- **allowance** — a port the packet filter keeps open by hand beside the ports derived from the modules' `listens`:
|
||||
set with the `node-packet-filter` seat's verb `allow`, taken back with `disallow`, read with `allowed`, each with
|
||||
who set it, when, why and an optional expiry, and rendered by the node-engine into a converged node's input chain
|
||||
(design 08 §4, design 33). It is not an `opening`, the resource the node-engine converges through a found firewall.
|
||||
*Not:* ~~pinhole~~ (hq), ~~hand rule~~ (hq)
|
||||
- **intrusion prevention** and **ban** — refusing a source that misbehaved, and the refusal itself; the node seat
|
||||
`node-intrusion-prevention` is of this domain.
|
||||
- **reach** — how far an assignment's endpoint may be reached from: the node, the private network, or
|
||||
@@ -1582,6 +1587,8 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
|
||||
| | a human | **operator** or **person** | words every domain uses |
|
||||
| firewall | what the mesh enforces | **packet filter** | Connectivity |
|
||||
| | what was found on a machine | **found firewall** | Connectivity |
|
||||
| allowance | a port the packet filter keeps open by hand | **allowance** | Connectivity |
|
||||
| | the share of model use every session draws on in a week (playbook 07's report) | **weekly allowance** | — |
|
||||
| ticket | an answer's one-time token (ADR 0258) | **answer ticket** | Operator and conversation |
|
||||
| | a question someone must answer | **issue** | The record |
|
||||
| deploy | the per-node part of a delivery plan | **deploy plan** | Delivery |
|
||||
|
||||
@@ -22,7 +22,7 @@ code:
|
||||
- mesh-host internal/apply (the service that reflects a rule set; a whole file handed to its new owner)
|
||||
- mesh-controller cmd/mesh-controller/nodes.go (a token issued for a machine's tunnel key, ADR 0169)
|
||||
- mesh-host cmd/mesh-host/join_tunnel.go (a machine joins through the tunnel, ADR 0169)
|
||||
updated: 2026-10-14
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0241"
|
||||
- "ADR 0117"
|
||||
@@ -36,6 +36,7 @@ decisions:
|
||||
- "ADR 0194"
|
||||
- "ADR 0191"
|
||||
- "ADR 0180"
|
||||
- "ADR 0683"
|
||||
- "ADR 0170"
|
||||
- "ADR 0169"
|
||||
- "ADR 0168"
|
||||
@@ -696,10 +697,14 @@ program that reads it, and another proxy may implement the same file.
|
||||
|
||||
## 4 — Filtering
|
||||
|
||||
**Derived from what is assigned here, and from the private network's shape** — a node's open ports are a
|
||||
consequence of what runs on it and who must reach it, not an independent declaration to keep in
|
||||
step by hand. That is true of a converged node; an adopted one keeps the firewall it was found
|
||||
with until it converges (below).
|
||||
**Derived from what is assigned here and from the private network's shape, with allowances set by hand beside
|
||||
them.** The automatic part of a node's open ports is a consequence of what runs on it and who must reach it, not a
|
||||
declaration to keep in step by hand. Beside it, the holder of `node-packet-filter` keeps **allowances**: ports opened
|
||||
by hand through the seat's verbs, each with who set it, when, why and an optional expiry, rendered into the same input
|
||||
chain and surviving every render and restart; an expired allowance is removed at the next render and said (ADR 0683,
|
||||
the firewall's control verbs, amending ADR 0170; the operator, 2026-11-21; design 47 H's lead
|
||||
answers H-A-304, H-A-305, H-A-307, H-A-308). That is true of a converged node; an adopted one keeps the firewall it was found
|
||||
with until it converges, and takes no allowance (design 08 adoption §2 to §6).
|
||||
|
||||
**A rule names its source** (ADR 0007).
|
||||
A rule with no source is open, and must say so rather than appear to restrict something. `scope:`
|
||||
@@ -790,57 +795,25 @@ undeclared one does not — then the module is removed and the port closes with
|
||||
rule. *A rule set that is written but never loaded passes every check that reads the file, which
|
||||
is why the check reads packets.*
|
||||
|
||||
### While a predecessor still serves the same thing
|
||||
### By hand, beside the derived ports
|
||||
|
||||
*2026-09-22, ADR 0104.*
|
||||
The mesh's proxy owns the two public ports and derives its routes from what modules contributed, so
|
||||
it cannot stand beside a predecessor's proxy and cannot serve the predecessor's names. During a
|
||||
migration a provision of this shape — one provider, a scarce machine-wide resource — may instead be
|
||||
answered by an **adapter**: a module that provides `route` and writes each contribution into the
|
||||
predecessor's own configuration, pointing at the machine port the contributing module publishes.
|
||||
The predecessor's proxy goes on serving every name and renewing every certificate; the mesh's proxy
|
||||
is taken last, when every route is one the mesh contributed. The adapter is refused on a converged
|
||||
node, and removed when the predecessor's proxy retires. *How it is checked:* the adoption bed takes
|
||||
a module behind the adapter and asserts the name answers and the predecessor's own names still do.
|
||||
*2026-11-21, ADR 0683.* Deriving every open port from the modules' `listens` left no way to open a port no manifest
|
||||
names (a program the operator runs by hand on the workstation, for a while). One renderer stays: the node-engine
|
||||
composes the filter file, and nothing else writes the input chain.
|
||||
|
||||
### On an adopted node
|
||||
```
|
||||
caller ── allow / disallow ──▶ node-packet-filter (holder) state allowances, one key per allowance
|
||||
│ event node-packet-filter.allowances-changed (node)
|
||||
▼
|
||||
node-engine ── allowed ──▶ holder composes the filter: derived ports + allowances, input chain only
|
||||
│ writes the filter file; the holder's unit loads it (reload)
|
||||
```
|
||||
|
||||
*2026-09-22, ADR 0100.* **The firewall found on the machine stays in force**, and the mesh
|
||||
loads no table there that drops by default or holds an accept — neither genesis's base ruleset nor
|
||||
the derived one. Every base chain at a hook runs and a drop in any is final, whatever the other
|
||||
firewall is written in, so a second, stricter table would close every port the machine serves, and
|
||||
an accept in one would open nothing the found firewall drops. What the mesh needs reachable it
|
||||
declares as **openings**: a port, from where, on the incoming path or the forwarded path — a
|
||||
published container port is forwarded, and a firewall that filters only incoming traffic never
|
||||
sees it. The controller derives them from what the filter would be derived from, each from where
|
||||
the filter would admit it: the assigned modules' `listens`, the hub's port, the bus and the registry
|
||||
from anywhere; the store's port and the broker's management port from the private network. The node-engine converges each opening through
|
||||
the found firewall in that firewall's own terms, marks it as the mesh's, removes only what it
|
||||
marked, and re-checks every opening on each reconcile so a reload or a reboot does not lose it for
|
||||
longer than one reconcile. An opening is state, not a command, so it travels over the link like any
|
||||
other resource. **The mesh guards its own ports in a table of its own that only refuses** —
|
||||
passing everything by default and holding nothing but refusals, and the found firewall's reload
|
||||
does not touch it. Its ports are derived (ADR 0103): every machine port a
|
||||
*taken* module publishes that the filter admits from the private network only, with the store's
|
||||
port and the broker's management port. A port of a module not yet taken may still be the
|
||||
predecessor's, so it is not guarded; and only packets addressed to this machine are matched, so
|
||||
traffic it routes for others passes. An opening a found rule already answers is not added, so
|
||||
removing it never removes the operator's rule. It refuses those ports except from
|
||||
the private network and the machine itself — loopback and the container runtime's networks, known by the interface a packet arrives on, never by
|
||||
its source address alone — at
|
||||
the prerouting hook, before the container runtime redirects the packet, so it matches the port the
|
||||
packet was sent to, for both address families; the
|
||||
bus, the registry and the hub's port stay reachable from anywhere, as a node enrols and pulls
|
||||
before it has a private-network address. One kind of found firewall is spoken; a machine with none
|
||||
needs no openings, and a machine with another kind is refused adoption. Converging the node refuses
|
||||
while a found container is still held; otherwise it previews what is reachable now — listening
|
||||
sockets and published ports — what will close and which modules it will take, then loads the
|
||||
derived filter in place of the refusal-only table and disables the found firewall without flushing
|
||||
it. *How it is checked:* the adoption bed asserts the found firewall's rules differ only by the
|
||||
mesh's marked rules, that the store is unreachable from off the private network before and after
|
||||
the found firewall reloads and reachable from a container on the node, that a machine not yet enrolled reaches the bus, that a second machine
|
||||
enrols through the openings before and after a reload and a reboot, and that after the flip the
|
||||
declared port is open and the undeclared one closed.
|
||||
The holder keeps each allowance in its own state on the bus and says every change as an event; the node-engine of
|
||||
that node hears it, asks `allowed` and composes the filter again. An unanswered `allowed` refuses the compose and
|
||||
keeps the loaded filter, said once, never read as "nothing opened" (the rule for a generator above). Allowances are
|
||||
rendered only into a converged node's own table. The seat's verbs and event are design 33's (*The firewall seat's
|
||||
verbs*); every line the milestone builds is in [design 08 control-verbs](08-milestones/control-verbs.md).
|
||||
|
||||
### It filters what arrives from outside, and not what the machine's own guests send
|
||||
|
||||
@@ -1245,27 +1218,15 @@ The list is worth having in one place, because it is most of the argument:
|
||||
|
||||
## Open
|
||||
|
||||
- **One resolver (ADR 0194).** *Correction of fact,
|
||||
2026-10-05:* no node holds `node-dns-resolver` any more, and
|
||||
ADR 0220 deletes the seat. What stood here before: *"Not built: every node still runs
|
||||
`node-dns-resolver`. The migration's four steps are in the record, in order."* Nor did it
|
||||
stay true that *"the workstation moves to the one resolver only once"* zones and the `hosts` file's
|
||||
holder (ADR 0199)
|
||||
exist: every node, the workstation included, asks the one resolver, and every node holds
|
||||
`node-hosts-file`.
|
||||
- **One resolver (ADR 0194), settled** (2026-10-05): ADR 0220 deletes the seat `node-dns-resolver`; every node, the
|
||||
workstation included, asks the one resolver and holds `node-hosts-file` (ADR 0199).
|
||||
|
||||
- **When the hub is down nothing takes over** (ADR 0006): non-co-located paths stop, co-located direct peers and
|
||||
every assigned workload keep running; recovery is restore, before certificate renewal.
|
||||
|
||||
- ~~**What happens when the hub is down.**~~ **Resolved** by
|
||||
ADR 0006, together with `06`'s
|
||||
matching question — they were one question. Nothing takes over. WireGuard has no failover, the
|
||||
hub is declared rather than elected, and non-co-located paths stop while co-located direct peers
|
||||
and every already-assigned workload keep running. The recovery path is restore, and its deadline
|
||||
is certificate renewal.
|
||||
- **Renumbering the private network.** Made *possible* by declaring the hub rather than inferring it from
|
||||
an address, but no procedure exists, and a graph delivered node by node has an ordering problem
|
||||
while it is half-applied.
|
||||
- ~~**Revoking a route** when a module is unassigned.~~ **Resolved** 2026-08-31 — see §3. The file
|
||||
a proxy is given is the whole truth about who has a route, so a route does not outlive the module
|
||||
that asked for it.
|
||||
- **IPv6.** ADR 0007 makes
|
||||
it expressible; nothing here says the private network or the resolver handle it.
|
||||
- **Reporting declared-versus-observed.** ADR 0007 makes the disagreement detectable and does not
|
||||
@@ -1276,28 +1237,6 @@ The list is worth having in one place, because it is most of the argument:
|
||||
the composition is a per-node override rather than the design. The interpolation that would let a
|
||||
module carry a label and a node carry the domain, and the mesh join them, does not yet exist.
|
||||
|
||||
## The hub adopts the predecessor's tunnel
|
||||
|
||||
*2026-09-23, ADR 0105.*
|
||||
|
||||
On an adopted node that is the hub, the private network is not raised beside the tunnel it finds;
|
||||
it **takes it over**: the found interface's private key, its port, its address and range, and every
|
||||
peer it had, carried as peers not yet enrolled. The found interface is stopped, its configuration
|
||||
kept on disk. A predecessor machine sees the same server key at the same endpoint and cannot tell
|
||||
the tunnel changed hands; when it enrols, it keeps the address the tunnel already held for its key.
|
||||
|
||||
The mesh's own addresses are the adopted range's — every binding, hosts entry and endpoint the
|
||||
controller composes follows it, as readers of a setting. ADR 0100's non-overlap rule applies only
|
||||
where a found tunnel is left running beside the mesh's; where it is adopted there is one tunnel.
|
||||
The guard admits the mesh's ports from that one interface, and the predecessor's peers arrive on
|
||||
it.
|
||||
|
||||
*2026-09-27, ADR 0119.* The
|
||||
found configuration is kept only until the take is proven — the found unit down, the mesh's
|
||||
interface up and handshaking with a peer. Then it is removed from where the found unit reads it
|
||||
(its original stays kept), the hold ends, and the predecessor's tunnel cannot be raised again by
|
||||
anything but a person restoring it by hand. Undeclaring the private network does not bring it back.
|
||||
|
||||
## The bus is NATS
|
||||
|
||||
*2026-09-23, ADR 0106. Architecture to be written
|
||||
@@ -1308,3 +1247,13 @@ NATS account with permissions derived from `emits`/`consumes`, declared as confi
|
||||
writes and the server reloads. The sdk's contract is unchanged. The adopted AMQP broker stays as
|
||||
the predecessor's compatibility broker until its last client is gone. Built in the lab beside the
|
||||
migration; cut over in one switch-over after the core; the person's client is designed on it.
|
||||
|
||||
## Milestones
|
||||
|
||||
Each milestone's lines are in its part, cited as "design 08 <milestone> §n"; the rest of this file records what was
|
||||
built before milestone parts existed.
|
||||
|
||||
| Milestone | Part | State |
|
||||
|---|---|---|
|
||||
| adoption: a node the mesh adopted, before it converges (ADR 0100, 0103, 0104, 0105, 0119) | [adoption](08-milestones/adoption.md) | delivered |
|
||||
| control-verbs: allowances set by hand beside the derived ports, built in design 47's milestone H (ADR 0683) | [control-verbs](08-milestones/control-verbs.md) | to build |
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
layer: to-be
|
||||
design: 08
|
||||
milestone: adoption (delivered)
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0100"
|
||||
- "ADR 0103"
|
||||
- "ADR 0104"
|
||||
- "ADR 0105"
|
||||
- "ADR 0119"
|
||||
---
|
||||
|
||||
# Design 08, milestone adoption — a node the mesh adopted, before it converges
|
||||
|
||||
**What it built.** How the mesh stands beside what it found on an adopted node: a predecessor's proxy, the found
|
||||
firewall and the predecessor's tunnel, each until the node converges. This part is delivered: it records what was
|
||||
intended, moved whole from the main file when design 08 was put in the shape of playbook 02 (2026-11-21), and no
|
||||
builder reads it again. Cited as "design 08 adoption §n".
|
||||
|
||||
## Lines
|
||||
|
||||
1. **While a predecessor still serves the same thing, an adapter answers the provision** (2026-09-22, ADR 0104).
|
||||
The mesh's proxy owns the two public ports and derives its routes from what modules contributed, so it cannot
|
||||
stand beside a predecessor's proxy and cannot serve the predecessor's names. During a migration a provision of
|
||||
this shape (one provider, a scarce machine-wide resource) may instead be answered by an **adapter**: a module
|
||||
that provides `route` and writes each contribution into the predecessor's own configuration, pointing at the
|
||||
machine port the contributing module publishes. The predecessor's proxy goes on serving every name and renewing
|
||||
every certificate; the mesh's proxy is taken last, when every route is one the mesh contributed. The adapter is
|
||||
refused on a converged node, and removed when the predecessor's proxy retires. *How it is checked:* the adoption
|
||||
bed takes a module behind the adapter and asserts the name answers and the predecessor's own names still do.
|
||||
2. **On an adopted node the found firewall stays in force** (2026-09-22, ADR 0100), and the mesh loads no table
|
||||
there that drops by default or holds an accept: neither genesis's base ruleset nor the derived one. Every base
|
||||
chain at a hook runs and a drop in any is final, whatever the other firewall is written in, so a second, stricter
|
||||
table would close every port the machine serves, and an accept in one would open nothing the found firewall
|
||||
drops.
|
||||
3. **What the mesh needs reachable it declares as openings**: a port, from where, on the incoming path or the
|
||||
forwarded path (a published container port is forwarded, and a firewall that filters only incoming traffic never
|
||||
sees it). The controller derives them from what the filter would be derived from, each from where the filter
|
||||
would admit it: the assigned modules' `listens`, the hub's port, the bus and the registry from anywhere; the
|
||||
store's port and the broker's management port from the private network. The node-engine converges each opening
|
||||
through the found firewall in that firewall's own terms, marks it as the mesh's, removes only what it marked, and
|
||||
re-checks every opening on each reconcile so a reload or a reboot does not lose it for longer than one
|
||||
reconcile. An opening is state, not a command, so it travels over the link like any other resource. An opening a
|
||||
found rule already answers is not added, so removing it never removes the operator's rule.
|
||||
4. **The mesh guards its own ports in a table of its own that only refuses**: passing everything by default and
|
||||
holding nothing but refusals, and the found firewall's reload does not touch it. Its ports are derived (ADR
|
||||
0103): every machine port a *taken* module publishes that the filter admits from the private network only, with
|
||||
the store's port and the broker's management port. A port of a module not yet taken may still be the
|
||||
predecessor's, so it is not guarded; and only packets addressed to this machine are matched, so traffic it routes
|
||||
for others passes. It refuses those ports except from the private network and the machine itself (loopback and
|
||||
the container runtime's networks, known by the interface a packet arrives on, never by its source address alone)
|
||||
at the prerouting hook, before the container runtime redirects the packet, so it matches the port the packet was
|
||||
sent to, for both address families; the bus, the registry and the hub's port stay reachable from anywhere, as a
|
||||
node enrols and pulls before it has a private-network address.
|
||||
5. **One kind of found firewall is spoken**; a machine with none needs no openings, and a machine with another kind
|
||||
is refused adoption.
|
||||
6. **Converging the node refuses while a found container is still held**; otherwise it previews what is reachable
|
||||
now (listening sockets and published ports), what will close and which modules it will take, then loads the
|
||||
derived filter in place of the refusal-only table and disables the found firewall without flushing it. *How
|
||||
lines 2 to 6 are checked:* the adoption bed asserts the found firewall's rules differ only by the mesh's marked
|
||||
rules, that the store is unreachable from off the private network before and after the found firewall reloads
|
||||
and reachable from a container on the node, that a machine not yet enrolled reaches the bus, that a second
|
||||
machine enrols through the openings before and after a reload and a reboot, and that after the flip the declared
|
||||
port is open and the undeclared one closed.
|
||||
7. **The hub adopts the predecessor's tunnel** (2026-09-23, ADR 0105). On an adopted node that is the hub, the
|
||||
private network is not raised beside the tunnel it finds; it **takes it over**: the found interface's private
|
||||
key, its port, its address and range, and every peer it had, carried as peers not yet enrolled. The found
|
||||
interface is stopped, its configuration kept on disk. A predecessor machine sees the same server key at the same
|
||||
endpoint and cannot tell the tunnel changed hands; when it enrols, it keeps the address the tunnel already held
|
||||
for its key.
|
||||
8. **The mesh's own addresses are the adopted range's**: every binding, hosts entry and endpoint the controller
|
||||
composes follows it, as readers of a setting. ADR 0100's non-overlap rule applies only where a found tunnel is
|
||||
left running beside the mesh's; where it is adopted there is one tunnel. The guard admits the mesh's ports from
|
||||
that one interface, and the predecessor's peers arrive on it.
|
||||
9. **The found tunnel's configuration is kept only until the take is proven** (2026-09-27, ADR 0119): the found
|
||||
unit down, the mesh's interface up and handshaking with a peer. Then it is removed from where the found unit
|
||||
reads it (its original stays kept), the hold ends, and the predecessor's tunnel cannot be raised again by
|
||||
anything but a person restoring it by hand. Undeclaring the private network does not bring it back.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
layer: to-be
|
||||
design: 08
|
||||
milestone: control-verbs
|
||||
updated: 2026-11-21
|
||||
code: [mesh-host internal/compose (the filter's compose), mesh-catalog modules/nftables]
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0170"
|
||||
- "ADR 0168"
|
||||
- "ADR 0595"
|
||||
- "ADR 0100"
|
||||
---
|
||||
|
||||
# Design 08, milestone control-verbs — allowances set by hand, rendered beside the derived ports
|
||||
|
||||
**What it builds.** The packet filter of a converged node opens, beside the ports derived from the modules' `listens`,
|
||||
every **allowance** the holder of `node-packet-filter` keeps: a port opened by hand through the seat's verbs, with who
|
||||
set it, when, why and an optional expiry. The node-engine renders both into the mesh's own table, in the same input
|
||||
chain, at every compose of the filter; an allowance survives every render and restart and is gone at the first render
|
||||
after its expiry, said by the holder. This follows ADR 0683 (the firewall's control verbs, amending ADR
|
||||
0170) and the operator's word of
|
||||
2026-11-21 20:35 CET (the packet filter's module has tools to control it beside the automatic provisioning from
|
||||
declarations), written from design 47 H's lead answers H-A-304, H-A-305, H-A-307 and H-A-308. The seat's verbs, its event and
|
||||
its state are design 33 control-verbs; this part holds the render. Cited as "design 08 control-verbs §n".
|
||||
|
||||
**Where.** Built in design 47's milestone H, in one delivery group with design 33 control-verbs: the networking
|
||||
repository (the seat's contracts module), the catalog repository (the nftables module, the holder) and the
|
||||
node-engine's repository (the compose of the filter). The ordering edge is the served verb: the node-engine asks
|
||||
`allowed`, so the holder serving it comes first in the delivery plan. First use: tcp 8000 on the workstation's
|
||||
home-network interfaces.
|
||||
|
||||
## Lines
|
||||
|
||||
1. **The node-engine is the one renderer of the filter file** (H-A-305; P7). At every compose of the packet filter
|
||||
(each compose it makes today, and each one line 3 starts) it asks `<node>/node-packet-filter.allowed` of its own
|
||||
node, bound 10 s, and renders the answer's allowances beside the derived ports. Nothing else writes the input
|
||||
chain: the holder writes no rule and loads the file as today (`reload`, ADR 0170 §3). The derived part is unchanged:
|
||||
the modules' `listens`, the hub's port, the foundation's ports and their sources stay as §4 *What was built* says.
|
||||
2. **Where an allowance is rendered.** In the mesh's own table (family `inet`, name `mesh`), its input chain, after
|
||||
the derived ports' rules and before the chain's drop policy: one accept rule per allowance, matching its protocol
|
||||
and destination port; its interface by name, or for an allowance with no interface (the default set, resolved here at
|
||||
compose, H-A-308 (1)) every input interface but the private network's, rendered as a negated match on that one interface (so an interface that comes up later is
|
||||
covered and the tunnel never is); its source when it has one, for the family of its CIDR, and no source match when
|
||||
it has none (both families). Each rule carries the comment `allowance <key>`, the allowance's key in its state
|
||||
(design 33 control-verbs §7), which is how `rules` tells a loaded allowance (design 33 control-verbs §5). An
|
||||
allowance opens the input path only: a container's published port is forwarded traffic and stays its module's
|
||||
`listens`' (§4, *It filters what arrives from outside*). An allowance and a derived rule on the same port are both
|
||||
rendered; neither removes or narrows the other.
|
||||
3. **The node-engine composes the filter again on every change of the allowances.** It hears the event
|
||||
`node-packet-filter.allowances-changed` whose node is its own (design 33 control-verbs §6), asks `allowed` and
|
||||
composes the filter; no timer and no poll. The event's body is not rendered: `allowed`'s answer is the one input,
|
||||
so an event missed is made good at the next compose.
|
||||
4. **An unanswered `allowed` refuses the compose and keeps the loaded filter** (H-A-307 (1); the rule for a generator
|
||||
that cannot say what it opens, §4). When `allowed` does not answer within its bound or answers an error (the holder
|
||||
not running yet, its tool runner away, no holder on the node), the node-engine composes no filter file, keeps the
|
||||
one loaded, and says it once in the outcome of its compose of the filter, read with `<node>/node-engine.composition`
|
||||
for the holder's module: the refusal and the reason, never "nothing opened". It says it again only after a compose
|
||||
with an answer in between. The next `allowances-changed` (the holder says one when it starts serving, design 33
|
||||
control-verbs §6) or the next compose tries again.
|
||||
5. **Allowances are rendered only into a converged node's own table** (H-A-307 (2)). On an adopted node the mesh
|
||||
loads no table that holds an accept (design 08 adoption §2) and speaks the found firewall's terms through openings
|
||||
derived from what the filter would be derived from (adoption §3); an allowance is none of them, so the node-engine
|
||||
renders none there and its compose outcome names the allowances it left out. They stay kept by the holder and are
|
||||
rendered at the first compose after the node converges.
|
||||
6. **An expired allowance is gone at the next render, and said by the holder** (H-A-308 (2)). At its `until` the
|
||||
holder deletes its key, says `allowances-changed` with change `expired` and writes a journal line (design 33
|
||||
control-verbs §4, §6); the event composes the filter again (line 3), so the port closes when the expiry passes, not
|
||||
at an unrelated compose. No expired entry is kept, and `allowed` never answers one.
|
||||
7. **An allowance survives every render and restart because it lives in one place.** The holder's state on the bus is
|
||||
the only copy; the rendered file is output, rewritten whole at each compose and never read back. A restart of the
|
||||
node-engine, of the holder or of the machine renders the allowances again from `allowed`; a delivery of either
|
||||
module removes none.
|
||||
8. **How it is checked.** The node-engine's compose tests assert on the input chain's text: with no allowance the
|
||||
file is byte for byte today's derived file; with one allowance of no interface, a rule with the negated match on
|
||||
the private network's interface and no positive match on it; with three (one interface named, one with an IPv4
|
||||
source, one udp), three rules in that form after the derived ones, each with its comment. A fake `allowed` that
|
||||
never answers leaves the loaded file untouched and one refusal in the outcome; an `allowances-changed` for the
|
||||
node composes again and one for another node does not; an allowance past its `until` is absent from the render; an
|
||||
adopted node renders none. Live, read in packets as §4 reads them: after `allow` of tcp 8000 on the workstation's
|
||||
home-network interfaces, a machine on the home network reaches the port and a machine reaching the workstation
|
||||
over the private network does not; after `disallow` neither does; a node-engine restart between the two keeps it
|
||||
open.
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
layer: to-be
|
||||
design: 33
|
||||
milestone: control-verbs
|
||||
updated: 2026-11-21
|
||||
code: [mesh-networking modules/mesh-connectivity-contracts, mesh-catalog modules/nftables, mesh-sdk (TypeScript state)]
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0170"
|
||||
- "ADR 0595"
|
||||
- "ADR 0625"
|
||||
- "ADR 0636"
|
||||
- "ADR 0246"
|
||||
---
|
||||
|
||||
# Design 33, milestone control-verbs — the packet filter seat's allow, disallow and allowed
|
||||
|
||||
**What it builds.** The node seat `node-packet-filter` serves, beside `rules`, `reload` and `remove` (ADR 0170), three
|
||||
verbs that control the packet filter by hand: `allow`, `disallow` and `allowed`; `rules` lists the allowances beside
|
||||
the ruleset; and the seat says every change of its allowances as the event `node-packet-filter.allowances-changed`.
|
||||
An **allowance** is a port opened by hand beside the ports derived from the modules' `listens`. This follows ADR 0683
|
||||
(the firewall's control verbs, amending ADR 0170) and the operator's word of 2026-11-21 20:35 CET, written from design 47 H's lead answers
|
||||
H-A-304, H-A-305, H-A-307 and H-A-308; P7 and the instruction that tools are how a module is spoken to (every act by hand has
|
||||
its verb, every kept thing its read). How the node-engine renders allowances is design 08 control-verbs. Cited as
|
||||
"design 33 control-verbs §n".
|
||||
|
||||
**Where.** Built in design 47's milestone H, one delivery group with design 08 control-verbs: the networking
|
||||
repository (the seat's whole definition in its contracts module), the catalog repository (the nftables module, the
|
||||
holder) and, where line 8 finds the gap, mesh-sdk's TypeScript side.
|
||||
|
||||
## Lines
|
||||
|
||||
1. **The seat serves six verbs, and every holder serves all six** (§3). `rules`, `reload` and `remove` as ADR 0170
|
||||
§1 to §7 say, with `rules`' answer widened by line 5; `allow`, `disallow` and `allowed` as lines 2 to 4 say. The
|
||||
three are added to the seat as §7 says. Each is a node verb, called `<node>/node-packet-filter.<verb>`.
|
||||
2. **`allow` opens a port by hand.** Arguments: `port`, an integer 1 to 65535, required; `protocol`, `tcp` or `udp`,
|
||||
default `tcp`; `interfaces`, a list of interface names, each 1 to 15 characters of letters, digits, `_`, `.` and
|
||||
`-`, default none, which means every input interface but the private network's (design 08 control-verbs §2);
|
||||
`source`, one IPv4 or IPv6 CIDR, default none, which means any; `until`, an RFC 3339 time in the future, optional;
|
||||
`why`, 1 to 500 characters, required. Any other argument is refused. Who set it is the caller as the bus names it
|
||||
on the request, never an argument; when is the holder's clock at the write. It keeps one allowance per protocol, port and
|
||||
interface (H-A-308 (1)): one key per named interface, each with the same source, who, when, why and `until`, or for
|
||||
none the one key of the default set (line 7), resolved by the node-engine at compose. An `allow` for a key that
|
||||
exists replaces it whole and answers what it replaced. It refuses,
|
||||
naming the argument and writing nothing: a port out of range or not an integer, another protocol, a bad interface
|
||||
name, a source that is not a CIDR, an `until` not in the future, an empty or longer `why`, and a write that would
|
||||
make more than 100 allowances on the node (the bound keeps the rendered chain readable and `allowed` in one
|
||||
answer). It answers with each allowance as kept, with its key and what it replaced, and that `allowances-changed` (line 6)
|
||||
was said (H-A-308 (3)); whether the loaded chain carries it is read with `rules` (line 5).
|
||||
3. **`disallow` takes back an allowance.** Arguments: `port`, `protocol` and `interfaces` with `allow`'s forms and
|
||||
defaults, which name the same keys (no `interfaces`: the default set's key), and `why`, required as for `allow`; any other
|
||||
argument is refused, the source among them, since it is a property and not part of an allowance's identity. It
|
||||
deletes every key named, or, when one does not exist, refuses naming it and deletes none. It answers with each
|
||||
allowance as removed and that `allowances-changed` was said with change `disallowed`, its who and its why.
|
||||
4. **`allowed` reads every allowance.** No arguments. It answers every allowance kept on the node, each with its key,
|
||||
`port`, `protocol`, `interface` (absent for every input interface but the private network's), `source` (absent for
|
||||
any), `until` (absent for none), `why`, `by` (who) and `at` (when). At an allowance's `until` the holder removes its key
|
||||
from its own state, by a timer on that state, says `allowances-changed` with change `expired` and writes a journal
|
||||
line naming the allowance (H-A-308 (2)); the expired entry is not kept, so `allowed` never answers one, and the
|
||||
filter closes the port then (design 08 control-verbs §6). The node-engine is its caller at every compose of the filter, bound 10 s.
|
||||
5. **`rules` lists the allowances beside the ruleset.** Its answer keeps the filter as the machine enforces it (ADR
|
||||
0170 §2) and adds `allowances`: `allowed`'s answer, each marked `loaded` when a rule of the mesh's table carries its
|
||||
comment `allowance <key>` (design 08 control-verbs §2) and not loaded otherwise, so a kept allowance the loaded
|
||||
filter does not carry is visible in one call.
|
||||
6. **The event `node-packet-filter.allowances-changed`.** The holder says it after every write or delete of its
|
||||
state, as a family of the seat on the shared events stream, its subject carrying the node. Its body: `node`;
|
||||
`change`, one of `allowed`, `disallowed`, `expired` and `started`; `allowances`, the ones concerned (all of them for
|
||||
`started`); `by` and `why` for `allowed` and `disallowed`; `at`. The holder says `started` once each time it starts
|
||||
serving the seat, so a node-engine that refused a compose for want of an answer composes again. The node-engine of
|
||||
that node hears it (design 08 control-verbs §3); nothing else needs to.
|
||||
7. **The holder keeps the allowances in its own state on the bus.** A state `allowances` asked for in the holder's
|
||||
manifest's `requires` by the template `state` (ADR 0595 §1, §2), reached only by its owner. One key per allowance:
|
||||
`allow.<protocol>.<port>` for the default set (every input interface but the private network's), `allow.<protocol>.<port>.<interface>`
|
||||
for a named one (the interface is every token after the third, since a name may hold a dot). Its value: `port`,
|
||||
`protocol`, `interface`, `source`, `until`, `why`, `by`, `at`; the source is a property of the value, never part
|
||||
of the key. Only `disallow` and an expiry (line 4) delete a key;
|
||||
no render, restart or delivery does. The bus module's own tools read the state's fill against its cap. When
|
||||
mesh-sdk's TypeScript side gives a module no state yet, that is built there first and the holder uses it, never a
|
||||
file or a store of its own (H-A-305).
|
||||
8. **The seat's definition becomes whole** (H-A-307 (3); ADR 0625 §1, ADR 0636 §5, §6). It lives in the Connectivity
|
||||
domain's contracts module, `mesh-connectivity-contracts`, in the networking repository: every one of the six verbs
|
||||
with its arguments and its answer form as lines 2 to 5 say, the event of line 6 with its family on the shared events
|
||||
stream, the state's value of line 7 as a layout, and the generated Go and TypeScript packages, as the private
|
||||
network's seat has them. The node-engine calls `allowed` and hears the event through the Go package; the holder
|
||||
serves the verbs and says the event through the TypeScript one.
|
||||
9. **How it is checked.** The holder's tests, against a state in memory: `allow` then `disallow` writes the key, then
|
||||
deletes it, with an `allowed` and a `disallowed` event; port 0, 65536 and `80a` are refused, as are protocol `icmp`,
|
||||
an `until` in the past, an empty `why`, an unknown argument and a 101st allowance; `allow` with no `interfaces`
|
||||
stores no interface, so the private network's interface is never in the defaults; an allowance whose `until` passes is
|
||||
deleted from the state at that time, says `expired` and writes its journal line, and `allowed` then answers
|
||||
without it; a second `allow` of one key answers what it replaced; `allow` with two interfaces keeps two keys; `rules` marks an allowance with no rule in a fixture
|
||||
ruleset as not loaded; a start says `started`. The seat's contract test holds every holder to the six verbs, and
|
||||
the generated packages to the definition.
|
||||
@@ -1,9 +1,10 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: implemented
|
||||
status: in-progress
|
||||
code: [mesh-controller, mesh-tools]
|
||||
updated: 2026-10-07
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0246"
|
||||
- "ADR 0170"
|
||||
- "ADR 0179"
|
||||
@@ -214,6 +215,18 @@ container to declare a capability. Removing a predecessor's rule set is an opera
|
||||
through the seat, recorded on the bus, instead of a shell on the machine. *How it is checked:* ADR
|
||||
0169's table.
|
||||
|
||||
*2026-11-21, ADR 0683 (the firewall's control verbs, amending ADR 0170); the operator,
|
||||
2026-11-21: the packet filter's module has tools to control it beside the automatic provisioning from declarations.*
|
||||
The seat serves three more verbs: `allow` (a port 1 to 65535, protocol `tcp` by default or `udp`, interfaces by
|
||||
default every input interface but the private network's, a source CIDR by default any, an optional `until`, a
|
||||
required `why`), `disallow` (the same keys) and `allowed` (every **allowance** with who set it, when, why and its
|
||||
expiry); `rules` lists the allowances beside the ruleset. The holder keeps them in its own state on the bus and says
|
||||
every change as the event `node-packet-filter.allowances-changed`, which the node-engine hears to compose the filter
|
||||
again; the node-engine stays the one renderer (design 08 §4, *By hand, beside the derived ports*). The seat's
|
||||
definition becomes whole in its domain's contracts module. Every holder serves the six verbs. Every line is in
|
||||
[design 33 control-verbs](33-milestones/control-verbs.md), from design 47 H's lead answers H-A-304, H-A-305,
|
||||
H-A-307 and H-A-308; *how it is checked* is its line 9.
|
||||
|
||||
## The intrusion seat's verbs, 2026-10-02
|
||||
|
||||
ADR 0179.
|
||||
@@ -226,6 +239,15 @@ per-module container ADR 0175
|
||||
retires; the verbs and the client are the same code once the node's own runtime loads them as a bundle.
|
||||
The module's own tool beside them reads one jail's effective settings. *How it is checked:* ADR 0179's table.
|
||||
|
||||
## Milestones
|
||||
|
||||
Each milestone not yet delivered has its part, cited as "design 33 <milestone> §n"; what is above was built before
|
||||
milestone parts existed.
|
||||
|
||||
| Milestone | Part | State |
|
||||
|---|---|---|
|
||||
| control-verbs: the packet filter seat's `allow`, `disallow` and `allowed`, built in design 47's milestone H (ADR 0683) | [control-verbs](33-milestones/control-verbs.md) | to build |
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user