diff --git a/00-META/glossary.md b/00-META/glossary.md index 4a71927c..039c06f5 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -1164,9 +1164,9 @@ 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 +- **allowance** — a port of the packet filter opened by the operator, through the seat, 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 `until`, at which it is removed, 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 @@ -1587,7 +1587,7 @@ 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 | +| allowance | a port of the packet filter opened by the operator, through the seat | **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 | diff --git a/03-DESIGN/01-to-be/08-connectivity.md b/03-DESIGN/01-to-be/08-connectivity.md index 240d94d2..ad6164a9 100644 --- a/03-DESIGN/01-to-be/08-connectivity.md +++ b/03-DESIGN/01-to-be/08-connectivity.md @@ -700,10 +700,10 @@ program that reads it, and another proxy may implement the same file. **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, +by the operator, 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 allowance is removed at its `until` 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 +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-316). 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). 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 4b443307..33b1aa6c 100644 --- a/03-DESIGN/01-to-be/08-milestones/control-verbs.md +++ b/03-DESIGN/01-to-be/08-milestones/control-verbs.md @@ -3,7 +3,7 @@ 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] +code: [mesh-host internal/compose (the filter's compose), mesh-catalog modules/nftables, mesh-networking modules/mesh-connectivity-contracts] decisions: - "ADR 0683" - "ADR 0170" @@ -15,72 +15,84 @@ decisions: # 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 +every **allowance** the holder of `node-packet-filter` keeps: a port opened by the operator, through the seat, with +who set it, when, why and an optional `until`. 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 one with an `until` +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, H-A-315 and H-A-316. 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. +**Where.** Built in design 47's milestone H, in one delivery group with design 33 control-verbs, three repositories: +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 verb `converged`). 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-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. + node, within its compose-ask bound, the node-engine's setting `compose-ask-bound`, default 10 s (H-A-314 (5)), and + renders the answer's allowances beside the derived ports. The node-engine's manifest invokes + `seat:node-packet-filter.allowed` and consumes `node-packet-filter.allowances-changed` (H-A-314 (3), H-A-315 (2)). + 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 `, 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. + 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 + 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)). + Each rule carries the comment `allowance `, the allowance's key in the holder's state 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 + 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-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. + `node-packet-filter.allowances-changed` on the subject of its own node (design 33 control-verbs §8), 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. The node-engine drops nothing past an `until` on its + own clock: the holder's answer is the truth (H-A-314 (6)). +4. **An unanswered `allowed` refuses the compose and keeps the loaded filter** (H-A-307 (1), H-A-314 (7), H-A-315 + (6); the rule for a generator that cannot say what it opens, §4). When `allowed` does not answer within the + compose-ask bound or answers an error (the holder not running yet, its tool runner away, no holder on the node, a + rolled-back holder that does not serve the verb, a laptop asleep), the node-engine composes no filter file and + keeps the one loaded. The refusal is a withheld part in H-A-306's form, the holder asked + `node-packet-filter.allowed`: said once in the journal and in `/node-engine.composition`, never "nothing + opened". The next `allowances-changed` (the holder says `started` when it starts serving, design 33 control-verbs + §8) or the next compose tries again; by hand it is recovered with the node-engine's compose verb, and the composed + file is loaded with `reload`. 5. **Allowances are rendered only into a converged node's own table** (H-A-307 (2), H-A-312 (1)). 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. The holder - refuses `allow` and `disallow` there and `allowed` answers none (design 33 control-verbs §9), so the node-engine - renders none. After the node converges, allowances are set with `allow` like on any converged node. -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. While the holder is away, the - loaded filter is kept (line 4), so a port whose allowance expires then stays open until the holder is back and - removes it at its start (design 33 control-verbs §10); that is accepted and said (H-A-312 (2), ADR 0683), rather - than closing every port of the filter. + refuses `allow` and `disallow` there and `allowed` answers none (design 33 control-verbs §3, §6), so the + node-engine renders none. After the node converges, allowances are set with `allow` as on any converged node. +6. **An allowance is removed at its `until`** (H-A-308 (2), H-A-312 (2), H-A-315 (4)). In the loaded filter the + kernel removes its set's element at its `until` (line 2). In the holder's state the holder removes its key at its + `until`, says `allowances-changed` with change `expired` and writes a journal line (design 33 control-verbs §11); + the event composes the filter again (line 3), which leaves its rule out. A holder away at the `until` removes the + key at its next start, before it answers `allowed`; meanwhile the loaded filter is kept (line 4) and the port is + already closed by the kernel. 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. + 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, + 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 withheld part in the composition read; an + `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 + 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 10464401..97eecedb 100644 --- a/03-DESIGN/01-to-be/33-milestones/control-verbs.md +++ b/03-DESIGN/01-to-be/33-milestones/control-verbs.md @@ -3,10 +3,12 @@ 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)] +code: [mesh-networking modules/mesh-connectivity-contracts, mesh-catalog modules/nftables, mesh-host (the node-engine seat's verb converged)] decisions: - "ADR 0683" - "ADR 0170" + - "ADR 0168" + - "ADR 0565" - "ADR 0595" - "ADR 0625" - "ADR 0636" @@ -18,88 +20,115 @@ decisions: **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". +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, H-A-314, H-A-315 and H-A-316; 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". -**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 7 finds the gap, mesh-sdk's TypeScript side. +**Where.** Built in design 47's milestone H, one delivery group with design 08 control-verbs, three repositories: the +networking repository (the seat's whole definition in its contracts module), the catalog repository (the nftables +module, the holder) and the node-engine's repository (the verb `converged`, and the render of design 08 +control-verbs). mesh-sdk is not in the group: its TypeScript `state()` asks the runtime's state methods as a Go bundle +does (H-A-314 (4)). ## 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 required from the start, in the one delivery group that adds them: §7's three steps (ADR 0246) end for a - seat defined in a contracts module (ADR 0683; H-A-310), since the group's check builds the definition and its holder - together. Each is a node verb, called `/node-packet-filter.`. + seat defined in a contracts module (ADR 0683; H-A-310), since the group's check builds the definition and its + holder together. Each is a node verb, called `/node-packet-filter.`. Their classes: `allow` and + `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); `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 ` (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 + `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 + 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. +3. **What `allow` refuses**, naming the argument and writing nothing: a caller whose proof is `unproven` (H-A-315 + (3)); a node that `converged` (line 10) says is adopted, naming the adoption, or a `converged` that does not answer + (line 10); 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`; a port that a derived rule of the loaded mesh table + admits from the private network only (the store's port, the broker's management port), unless a `source` is given + (H-A-315 (7), ADR 0683 §3); 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 + 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). +5. **`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 refuses as `allow` does an `unproven` caller, an adopted node and an unanswered `converged`. It deletes + every key named, or, when one does not exist, refuses naming it and deletes none, and says `allowances-changed` with + change `disallowed`, its who and its why. +6. **`allowed` reads every allowance.** No arguments. It answers every allowance kept for its own node only (line 7), + each with its key, `port`, `protocol`, `interface` (absent for the default set), `source` (absent for any), `until` + (absent for none), `why`, `by` (who) and `at` (when). The node-engine is its caller at every compose of the filter, + within its compose-ask bound (design 08 control-verbs §1). On an adopted node it answers none (H-A-312 (1)), so no + answer says a port is open that is not. +7. **`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` only when a rule of the mesh's table carries + its comment `allowance ` with an equal `at` (design 08 control-verbs §2), and not loaded otherwise; and + every loaded allowance comment whose key is not kept, listed as "loaded, not kept" (H-A-315 (5)). So a kept + allowance the loaded filter does not carry, and a loaded one nobody keeps, are both visible in one call. +8. **The event `node-packet-filter.allowances-changed`.** The holder says it after every write or delete of its + state, in the seat's family `node-packet-filter.events` on the shared events stream, `max-age-days` 7, its subject + `allowances-changed.` (as the node-engine seat's `composed.`; H-A-314 (2)). 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..` for the default set (every input interface but the private network's), `allow...` - 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. **On an adopted node the holder keeps no allowance** (H-A-312 (1); ADR 0683). `allow` and `disallow` are refused - there, naming the adoption (the mesh speaks the found firewall's terms, design 08 adoption §2, §3), and `allowed` - answers none, so no answer says a port is open that is not. Whether its node is adopted is the node's convergence - state, which the node-engine keeps (ADR 0168); the verb that answers it to the holder is not yet named (a design - question for the lead). -10. **At every start the holder removes every expired allowance first** (H-A-312 (2)). Before it answers `allowed`, - it deletes every key whose `until` has passed, writes a journal line for each, and says `allowances-changed` with - change `expired` for them, then `started` (line 6). -11. **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`, and a start with a key past its `until` deletes it and says - `expired` before its first `allowed` answers; on a node reported adopted, `allow` and `disallow` are refused naming - the adoption and `allowed` answers none. The seat's contract test holds every holder to the six verbs, and - the generated packages to the definition. + 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. +9. **The holder keeps the allowances in its own state on the bus, one bucket per machine.** A state `allowances` + asked for in the holder's manifest's `requires` by the template `state` (ADR 0595 §1, §2) with the template's + 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)). 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 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 the removal at + its `until` (line 11) delete a key; no render, restart or delivery does. The bus module's own tools read the state's + fill against its cap. The holder's manifest serves the six verbs, emits the event and requires the state (H-A-314 + (3)). +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 + for an adopted node `found`, the found firewall's kind. 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: it never + assumes converged. +11. **An allowance is removed at its `until`, by the holder.** The holder keeps an in-process timer per allowance with + an `until`, armed from the watch of its own state at every start (H-A-314 (6)). At an allowance's `until` it + deletes the key, says `allowances-changed` with change `expired` and writes a journal line naming the + allowance (H-A-308 (2)); no removed entry is kept, so `allowed` never answers one. At its start it first deletes + every key whose `until` has passed, with the same event and journal line, then says `started`, then answers + `allowed` (H-A-312 (2)). The kernel closes the port at its `until` even while the holder is away (design 08 + control-verbs §2). +12. **The seat's definition becomes whole** (H-A-307 (3), H-A-314 (2); 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 class, its arguments and its answer form as lines 1 to 7 say, the family and event of line + 8, the state's value of line 9 as a layout, and the generated Go and TypeScript packages. Its model is the + `node-engine` and `git` seats' whole definitions. 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. +13. **A running holder keeps the seat while its definition grows** (H-A-315 (6)). A holder running before this group + is not withdrawn when the seat's definition gains the three verbs; it holds the seat until it is replaced. While a + node's holder does not serve `allowed` (a rollback, a laptop asleep), the node-engine refuses the filter's + composes and keeps the loaded filter (design 08 control-verbs §4). +14. **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, 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 (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 + 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 + adoption and `allowed` answers none; with one that never answers, both are refused; an allowance kept on one node + is absent from another node's `allowed`; `rules` over a fixture ruleset marks an allowance loaded only on an equal + `at` and lists a comment with no kept key as "loaded, not kept". The node-engine's test of `converged` answers both + states. The seat's contract test holds every holder to the six verbs, and the generated packages to the definition. 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 117d7101..1653bb74 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 @@ -220,12 +220,14 @@ through the seat, recorded on the bus, instead of a shell on the machine. *How i 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 +`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 +it keeps an allowance. 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. +[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, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-316; *how it is checked* is its line 14. ## The intrusion seat's verbs, 2026-10-02