Designs 08 and 33: the reviews by domain (H-A-314, H-A-315, H-A-316)
This commit is contained in:
+4
-4
@@ -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 |
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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>/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 <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.
|
||||
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 <key> <at>`, 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>/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>/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 <key> <at>`; 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.
|
||||
|
||||
@@ -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>/node-packet-filter.<verb>`.
|
||||
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>/node-packet-filter.<verb>`. 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 <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
|
||||
`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 <key> <at>` 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.<node>` (as the node-engine seat's `composed.<node>`; 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.<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. **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.<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 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user