diff --git a/03-DESIGN/01-to-be/08-milestones/control-verbs.md b/03-DESIGN/01-to-be/08-milestones/control-verbs.md index bd5fcc21..ce27e90b 100644 --- a/03-DESIGN/01-to-be/08-milestones/control-verbs.md +++ b/03-DESIGN/01-to-be/08-milestones/control-verbs.md @@ -21,7 +21,7 @@ input chain, at every compose of the filter; an allowance survives every render is removed at its `until`, by the kernel in the loaded filter and by the holder in its state. 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, H-A-308, H-A-312, H-A-314 to H-A-316 and H-A-321. The seat's verbs, its event and +answers H-A-304, H-A-305, H-A-307, H-A-308, H-A-312, H-A-314 to H-A-316, H-A-321 and H-A-324. 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, three repositories: @@ -43,11 +43,14 @@ on the workstation's home-network interfaces. 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 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 + input interface that is neither the private network's tunnel nor an outward link (a hub's internet-facing link + included; H-A-324), rendered as a negated match on the tunnel and on each outward link the node reports (§4, *It + filters what arrives from outside*), so an interface that comes up later is covered and neither the tunnel nor an + outward link ever is; an outward link is opened only by an allowance that names it; its source when it has one, for the family of its CIDR, and no source match when it has none (both families). An allowance with an `until` matches its port as the one element of a set of the mesh's table with the `timeout` flag, the element's timeout the time left to its `until` at the - compose, at least 1 s, so the kernel closes the port at its `until` even while the holder is away (H-A-315 (4)). + compose, at least 1 s, so the kernel closes the port at its `until` even while the holder is away (H-A-315 (4)); a re-render reloads the + filter and re-arms the time left, which is the right time (H-A-324). Each rule carries the comment `allowance `, the allowance's key as its answers give it (without the node) and the time it was set (design 33 control-verbs §7, §9). 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 @@ -86,8 +89,8 @@ on the workstation's home-network interfaces. module removes none. A running holder keeps the seat while the seat's definition grows (design 33 control-verbs §13). 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 the default set, 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, + is byte for byte today's derived file; with one allowance of the default set, a rule with negated matches on the + private network's interface and on each outward link and no positive match on either; 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 `allowance `; one with an `until` renders a timeout set whose element's timeout is the time left. A fake `allowed` that never answers within the bound leaves the loaded file untouched and one entry in `withheld-parts` of the composition answer, `node-packet-filter.allowed` with its why, and the @@ -95,8 +98,9 @@ on the workstation's home-network interfaces. `allowances-changed` for the node composes again and one for another node does not; an allowance the fake answers with an `until` already past is rendered as answered, the node-engine dropping none on its own clock; an adopted node renders none. Live, read in packets as §4 reads them: before `allow`, a machine on the home network is refused - on tcp 8000 at the workstation (today's render accepts every link that is neither outward nor the tunnel, so the - test proves the drop first and fails there until it holds, H-A-314 (8)); after `allow` of tcp 8000 on the workstation's home-network interfaces it + on tcp 8000 at the workstation (this holds where the home-network links are outward in the node's render, as the + workstation reports them; H-A-314 (8), H-A-324); after `allow` of tcp 8000 with no interface the home-network + machine is still refused, since an outward link is not in the default set; after `allow` of tcp 8000 on the workstation's home-network interfaces it reaches the port and a machine reaching the workstation over the private network does not; a node-engine restart keeps it open; after `disallow` neither reaches it; an `allow` with an `until` a minute ahead closes at its `until` with the holder stopped. diff --git a/03-DESIGN/01-to-be/33-milestones/control-verbs.md b/03-DESIGN/01-to-be/33-milestones/control-verbs.md index 71dfe661..1fcae392 100644 --- a/03-DESIGN/01-to-be/33-milestones/control-verbs.md +++ b/03-DESIGN/01-to-be/33-milestones/control-verbs.md @@ -23,7 +23,7 @@ the ruleset; and the seat says every change of its allowances as the event `node The node seat `node-engine` gains the read verb `converged`. An **allowance** is a port opened by the operator, through the seat, 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, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-321; P7, P11 and the instruction that tools are +H-A-305, H-A-307, H-A-308, H-A-310, H-A-312, H-A-314 to H-A-321 and H-A-324; P7, P11 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". @@ -43,7 +43,8 @@ does (H-A-314 (4)). `disallow` are class `act`, by-caller; `allowed` is class `read` (H-A-315 (2)). 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); + `-`, default none, which means the default set: every input interface that is neither the private network's tunnel nor an outward link (a hub's internet-facing link + included), so an outward link is opened only when named here (H-A-324; 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; for a session's call that is the tool runner's account (H-A-315 (3)). When is the @@ -61,7 +62,9 @@ does (H-A-314 (4)). holder reads scope and not shape, is owed to milestone H2 and not built here); and a write that would make more than `allowances-max` allowances on the node, the holder's setting, default 100 (H-A-314 (5); the bound keeps the rendered chain readable and `allowed` in one answer). -4. **`allow` and `disallow` answer what they did, and are written in the hand-act log.** `allow` answers each +4. **`allow` and `disallow` answer what they did, and are written in the hand-act log.** When a named interface is + an outward link, as the loaded mesh table names the node's outward links (read as `rules` shows it), `allow`'s + answer says that this allowance opens an outward link, naming it (H-A-324). `allow` answers each allowance as kept, with its key and what it replaced, and that `allowances-changed` (line 6) was said; `disallow` answers each allowance as removed and that the event was said (H-A-308 (3)). Whether the loaded chain carries an allowance is read with `rules` (line 5). Each call of either is written in the hand-act log (ADR 0565 §10; H-A-315). @@ -93,8 +96,7 @@ does (H-A-314 (4)). option of one bucket per machine, `history` 1, reached only by its owner; a node's holder answers its own node's allowances only (H-A-315 (1)). The per-machine option is one bucket whose keys carry the node, `` and `.>` reached only by that machine's holder, so each holder reads and writes its own node's prefix only - (H-A-317). One key per allowance: `.allow..` for the default set (every input interface but - the private network's), `.allow...` for a named one (the interface is every token + (H-A-317). One key per allowance: `.allow..` for the default set (line 2), `.allow...` for a named one (the interface is every token after the fourth, since a name may hold a dot). The allowance's key in every answer, in the event and in the rule's comment is the same key without the node, `allow..[.]`. 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 the removal at @@ -103,7 +105,7 @@ does (H-A-314 (4)). `emits`, which the manifest check refuses for a claimed seat's event: the claim of `node-packet-filter` says the event, and the holder says it with the seat's publish (H-A-314 (3), H-A-317). 10. **The node seat `node-engine` gains the read verb `converged`** (H-A-316). It answers the node's convergence - state, which the node-engine keeps (ADR 0168): `state`, `adopted` or `converged`; `since`, when it became so; and + state, which the node-engine keeps (ADR 0168): `state`, `adopted` or `converged`; `since`, when it became so, optional and absent for a record written before this change (H-A-324); and for an adopted node `found`, the found firewall's kind (H-A-321). Class `read`, built in the group's node-engine part, added to the node-engine seat's whole definition. The holder asks it at its start and at every `allow` and `disallow`, bound 10 s (the default of the node-engine's compose-ask bound), and refuses when it does not answer. When it @@ -131,8 +133,8 @@ does (H-A-314 (4)). deletes it, with an `allowed` and a `disallowed` event, both answers saying the event was said, and two hand-act log lines; port 0, 65536 and `80a` are refused, as are protocol `icmp`, an `until` in the past, an empty `why`, an unknown argument, an `unproven` caller, the 101st allowance at the default `allowances-max`, and the store's port - with no source when the fixture chain accepts it only with a source match (accepted with one); `allow` with no `interfaces` stores no interface, so the private network's - interface is never in the defaults; `allow` with two interfaces keeps two keys; a second `allow` of one key answers + with no source when the fixture chain accepts it only with a source match (accepted with one); `allow` with no `interfaces` stores no interface, so neither the private network's + interface nor an outward link is ever in the defaults; `allow` naming an outward link says so in its answer; `allow` with two interfaces keeps two keys; a second `allow` of one key answers what it replaced; an allowance is removed at its `until`, says `expired`, writes its journal line, and `allowed` then answers without it; a start with a key past its `until` deletes it and says so before `started` and before its first `allowed`; with a fake `converged` saying adopted, `allow` and `disallow` are refused naming the diff --git a/03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md b/03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md index 1653bb74..7f985642 100644 --- a/03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md +++ b/03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md @@ -218,7 +218,7 @@ through the seat, recorded on the bus, instead of a shell on the machine. *How i *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 +default every input interface but the private network's tunnel and the outward links, 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 `until`, at which it is removed); `rules` lists the allowances beside the ruleset. The node seat `node-engine` gains the read verb `converged` (adopted or converged, since when, the found firewall's kind), which the holder asks before