From 83482a4513d5b6bb9aa721169271cc5f82b5d81b Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 20:52:34 +0100 Subject: [PATCH] nftables: allowances per machine, refused unproven or adopted, written in the hand-act log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The security and seams reviews of the packet filter's control verbs: the allowances state is one bucket per machine whose keys carry the node, so a holder lists and writes its own node's only; allow and disallow refuse an unproven caller, an adopted node and a converged that does not answer within 10 s, and are written in the hand-act log before the state is; allow refuses a port the loaded mesh table accepts from given sources only unless a source is given, and more than the setting allowances-max; allowed answers none on an adopted node and asks converged again while none answered; rules marks loaded only on an equal at and lists loaded allowance comments nobody keeps. The event is said through the seat's generated package; the claim says it, so emits stays without it. Builds: design 33 control-verbs §1-§11, §14; ADR 0683; design 47 H H-A-314 (3), (5), (6), H-A-315 (1)-(3), (5), (7), H-A-316, H-A-317, H-A-318, H-A-319 --- modules/nftables/allowances.ts | 209 +++++++++++++++++++---- modules/nftables/module.json | 18 +- modules/nftables/package.json | 3 +- modules/nftables/test/allowances.test.ts | 181 +++++++++++++++----- modules/nftables/tools/index.ts | 69 ++++++-- modules/nftables/tsconfig.json | 3 +- 6 files changed, 397 insertions(+), 86 deletions(-) diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts index c93d74a9d..a8f40839a 100644 --- a/modules/nftables/allowances.ts +++ b/modules/nftables/allowances.ts @@ -1,6 +1,7 @@ // The operator's allowances (ADR 0683; design 33 control-verbs): a port opened by hand on this machine, beside the // ports derived from the modules' listens. An allowance is this module's own state on the bus, one key per protocol, -// port and interface (allow..[.]); the node-engine asks `allowed` at every compose of a +// port and interface (allow..[.]), kept one bucket per machine under its node's keys +// (.allow.…, H-A-317), so a holder reads and writes its own node's only; the node-engine asks `allowed` at every compose of a // converged node's filter and renders it into the inet mesh table's input chain (design 08 control-verbs), so this // code writes no rule. Every change is said as the seat's event allowances-changed, which the node-engine hears to // compose the filter again; at its until an allowance is removed by a timer this module keeps per key from watching @@ -11,13 +12,14 @@ import { isIP } from "node:net"; /** The state the allowances are kept in, as the seat's definition names it (§7). */ export const STATE = "allowances"; -/** The most allowances one node keeps (§2). */ +/** The most allowances one node keeps when the setting allowances-max says none (§3, H-A-314 (5)). */ export const MOST = 100; -/** The seat's event, on mesh.seat.node-packet-filter.event.allowances-changed. (§6). */ -export function changedSubject(node: string): string { - return `mesh.seat.node-packet-filter.event.allowances-changed.${node}`; -} +/** How long the holder waits for the node-engine's converged (§10). */ +export const CONVERGED_BOUND_MS = 10_000; + +/** The caller of a call the runtime named no caller for (the SDK's callers.UNPROVEN). */ +export const UNPROVEN = "unproven"; export type Protocol = "tcp" | "udp"; @@ -53,7 +55,32 @@ export interface Changed { at: string; } -/** What the allowances need of the module's state: the SDK's `state()` serves it. */ +/** The node's convergence state as the node-engine seat's converged answers it (§10, H-A-316). */ +export interface Convergence { + state: "adopted" | "converged"; + since?: string; + /** The found firewall's kind, for an adopted node. */ + found?: string; +} + +/** One act by hand, as the seat mesh-hand-acts' hand-act takes it (ADR 0565 §10): the SDK's views.HandAct. */ +export interface HandAct { + what: string; + why: string; + cause: string; + verb: string; +} + +/** What the holder asks beside its state: the node's convergence, the hand-act log and its setting allowances-max. */ +export interface Asks { + converged: () => Promise; + handAct: (act: HandAct) => Promise; + most: () => Promise; + /** The mesh's table as loaded (`nft list table inet mesh`). */ + meshTable: () => Promise; +} + +/** What the allowances need of the module's state: the SDK's `state()` serves it, keys from a watch of the node's own. */ export interface Store { get(key: string): Promise<{ value: Value } | null>; put(key: string, value: Value): Promise; @@ -164,11 +191,15 @@ export class Allowances { private readonly now: () => Date; private readonly schedule: Schedule; private readonly journal: (line: string) => void; + private readonly asks: Asks; + /** The last answer of converged; undefined while none answered. */ + private convergence: Convergence | undefined; constructor( store: Store, node: string, say: Say, + asks: Asks, now: () => Date = () => new Date(), schedule: Schedule = timers, journal: (line: string) => void = (line) => console.log(`[nftables] ${line}`), @@ -176,23 +207,79 @@ export class Allowances { this.store = store; this.node = node; this.say = say; + this.asks = asks; this.now = now; this.schedule = schedule; this.journal = journal; } - /** Said once each time the holder starts serving the seat, with every allowance (§6). */ + /** The state's key of an allowance's key: under this node's (H-A-317). */ + private stored(key: string): string { + return `${this.node}.${key}`; + } + + /** The allowance's key of a state's key of this node, or undefined for another node's or another form. */ + private own(stateKey: string): string | undefined { + const prefix = `${this.node}.`; + return stateKey.startsWith(prefix + "allow.") ? stateKey.slice(prefix.length) : undefined; + } + + /** Ask converged, bound 10 s, keeping its answer; refused, naming why, when it does not answer (§10). */ + private async askConverged(verb: string): Promise { + let stop: () => void = () => {}; + const late = new Promise((_, no) => { + stop = this.schedule(CONVERGED_BOUND_MS, () => no(new Error(`no answer within ${CONVERGED_BOUND_MS / 1000} s`))); + }); + try { + const c = await Promise.race([this.asks.converged(), late]); + if (c?.state !== "adopted" && c?.state !== "converged") throw new Error(`it answered no convergence state (${JSON.stringify(c)})`); + this.convergence = c; + return c; + } catch (err) { + throw new Error(`${verb}: refused: the node-engine's converged did not answer (${err instanceof Error ? err.message : String(err)}), ` + + "and the holder never assumes the node converged; nothing is written"); + } finally { + stop(); + } + } + + private refuseAdopted(verb: string, c: Convergence): void { + if (c.state !== "adopted") return; + const about = [c.found ? `the found firewall ${c.found}` : "", c.since ? `since ${c.since}` : ""].filter(Boolean).join(", "); + throw new Error(`${verb}: refused: this node is adopted${about ? ` (${about})` : ""}, and the mesh speaks the found firewall's terms: ` + + "no allowance is kept on an adopted node; nothing is written"); + } + + /** The caller as the runtime proved it; an unproven one is refused (§3, H-A-315 (3)). */ + private proven(verb: string, by: string): void { + if (!by || by === UNPROVEN) throw new Error(`${verb}: refused: the request carries no caller the tool runner proved; nothing is written`); + } + + /** Every allowance kept for this node, by its key, sorted. */ + private async ownKeys(): Promise { + return (await this.store.keys()).map((k) => this.own(k)).filter((k): k is string => k !== undefined).sort(); + } + + /** Said once each time the holder starts serving the seat, with every allowance (§8): converged asked first, every + * key past its until removed first (§11). */ async started(): Promise { - const { allowances } = await this.allowed(); - await this.say({ node: this.node, change: "started", allowances, at: this.now().toISOString() }); + try { + await this.askConverged("start"); + } catch (err) { + this.journal(`${err instanceof Error ? err.message : String(err)}; allowed asks it again`); + } + const allowances = await this.kept(); + await this.say({ node: this.node, change: "started", allowances: this.convergence?.state === "adopted" ? [] : allowances, at: this.now().toISOString() }); } /** One change of the module's own state, from its watch: a key with an until gets its timer, a removed key loses it. */ async watched(change: Watched): Promise { - this.pending.get(change.key)?.(); - this.pending.delete(change.key); + const key = this.own(change.key); + if (key === undefined) return; + this.pending.get(key)?.(); + this.pending.delete(key); if (change.op !== "put" || !change.value?.until) return; - this.arm(change.key, change.value.until); + this.arm(key, change.value.until); } private arm(key: string, until: string): void { @@ -212,9 +299,9 @@ export class Allowances { /** Remove a key at its until, when it still holds that until (a later allow replaced it otherwise) (§4). */ async expire(key: string, until: string): Promise { try { - const entry = await this.store.get(key); + const entry = await this.store.get(this.stored(key)); if (!entry || entry.value.until !== until || Date.parse(until) > this.now().getTime()) return false; - await this.store.delete(key); + await this.store.delete(this.stored(key)); const a = answered(key, entry.value); await this.say({ node: this.node, change: "expired", allowances: [a], at: this.now().toISOString() }); this.journal(`the allowance ${key} (${a.protocol} ${a.port}${a.interface ? ` on ${a.interface}` : ""}${a.source ? ` from ${a.source}` : ""}, ` + @@ -229,7 +316,9 @@ export class Allowances { /** Open a port (§2): one key per named interface, or the default set's one key; a key there already is replaced * whole and answered. */ async allow(args: Record, by: string): Promise<{ allowances: (Allowance & { replaced?: Allowance })[]; said: boolean }> { + this.proven("allow", by); only(args, ["port", "protocol", "interfaces", "source", "until", "why"]); + this.refuseAdopted("allow", await this.askConverged("allow")); const now = this.now(); const port = portOf(args.port); const protocol = protocolOf(args.protocol); @@ -237,10 +326,18 @@ export class Allowances { const source = sourceOf(args.source); const until = untilOf(args.until, now); const why = whyOf(args.why); - const kept = (await this.store.keys()).filter((k) => k.startsWith("allow.")); + if (!source && privateOnly(await this.asks.meshTable(), protocol, port)) { + refuse("port", `${protocol} ${port} is admitted by a derived rule of the loaded mesh table from given sources only (the private network's, such as the store's ` + + "port or the broker's management port); an allowance from any source would widen it: give a source"); + } + const most = await this.asks.most(); + const kept = await this.ownKeys(); const after = new Set([...kept, ...interfaces.map((i) => keyOf(protocol, port, i))]).size; - if (after > MOST) refuse("port", `${after} allowances would be kept on this node, more than ${MOST}`); + if (after > most) refuse("port", `${after} allowances would be kept on this node, more than allowances-max ${most}`); const at = now.toISOString(); + const keys = interfaces.map((i) => keyOf(protocol, port, i)); + await this.recorded({ what: `allowed ${keys.join(", ")} on ${this.node}${source ? ` from ${source}` : ""}${until ? ` until ${until}` : ""}`, + why: `${why} (${by})`, cause: "allowance-set", verb: "allow" }); const out: (Allowance & { replaced?: Allowance })[] = []; for (const iface of interfaces) { const key = keyOf(protocol, port, iface); @@ -251,8 +348,8 @@ export class Allowances { ...(until ? { until } : {}), why, by, at, }; - const before = await this.store.get(key); - await this.store.put(key, value); + const before = await this.store.get(this.stored(key)); + await this.store.put(this.stored(key), value); out.push({ ...answered(key, value), ...(before ? { replaced: answered(key, before.value) } : {}) }); } await this.say({ node: this.node, change: "allowed", allowances: out.map(({ replaced: _, ...a }) => a), by, why, at }); @@ -262,7 +359,9 @@ export class Allowances { /** Take back allowances (§3): every key named is deleted, or, when one does not exist, it is refused by name and * none is deleted. */ async disallow(args: Record, by: string): Promise<{ allowances: Allowance[]; said: boolean }> { + this.proven("disallow", by); only(args, ["port", "protocol", "interfaces", "why"]); + this.refuseAdopted("disallow", await this.askConverged("disallow")); const port = portOf(args.port); const protocol = protocolOf(args.protocol); const interfaces = interfacesOf(args.interfaces); @@ -270,24 +369,41 @@ export class Allowances { const found: Allowance[] = []; for (const iface of interfaces) { const key = keyOf(protocol, port, iface); - const entry = await this.store.get(key); + const entry = await this.store.get(this.stored(key)); if (!entry) throw new Error(`no allowance ${key} is kept on this node; nothing is deleted`); found.push(answered(key, entry.value)); } - for (const a of found) await this.store.delete(a.key); + await this.recorded({ what: `disallowed ${found.map((a) => a.key).join(", ")} on ${this.node}`, why: `${why} (${by})`, cause: "allowance-taken-back", verb: "disallow" }); + for (const a of found) await this.store.delete(this.stored(a.key)); await this.say({ node: this.node, change: "disallowed", allowances: found, by, why, at: this.now().toISOString() }); return { allowances: found, said: true }; } - /** Every allowance kept, sorted by key (§4). One whose until passed before its timer fired is removed, said and - * left out, so none answered has expired. */ + /** Written in the hand-act log before the state is written; not written, the call is refused (§4, ADR 0565 §10). */ + private async recorded(act: HandAct): Promise { + try { + await this.asks.handAct(act); + } catch (err) { + throw new Error(`${act.verb}: the hand act was not recorded, so nothing is written: ${err instanceof Error ? err.message : String(err)}`); + } + } + + /** Every allowance kept for this node only, sorted by key (§6); none on an adopted node, and refused while converged + * has never answered and does not answer now (H-A-318). One whose until passed before its timer fired is removed, + * said and left out, so none answered has expired. */ async allowed(args: Record = {}): Promise<{ allowances: Allowance[] }> { only(args, []); + const c = this.convergence ?? (await this.askConverged("allowed")); + if (c.state === "adopted") return { allowances: [] }; + return { allowances: await this.kept() }; + } + + /** This node's allowances, every one past its until removed first (§11). */ + private async kept(): Promise { const now = this.now().getTime(); const allowances: Allowance[] = []; - for (const key of [...(await this.store.keys())].sort()) { - if (!key.startsWith("allow.")) continue; - const entry = await this.store.get(key); + for (const key of await this.ownKeys()) { + const entry = await this.store.get(this.stored(key)); if (!entry) continue; if (entry.value.until && Date.parse(entry.value.until) <= now) { await this.expire(key, entry.value.until); @@ -295,12 +411,43 @@ export class Allowances { } allowances.push(answered(key, entry.value)); } - return { allowances }; + return allowances; } } -/** Each allowance marked loaded when a rule of the mesh's table carries its comment `allowance ` (§5). */ -export function markLoaded(allowances: Allowance[], meshTable: string): (Allowance & { loaded: boolean })[] { - const comments = new Set([...meshTable.matchAll(/comment "allowance ([^"]+)"/g)].map((m) => m[1])); - return allowances.map((a) => ({ ...a, loaded: comments.has(a.key) })); +/** Each allowance marked loaded only when a rule of the mesh's table carries its comment `allowance ` with + * an equal at, and every such comment whose key is not kept: loaded, not kept (§7, H-A-315 (5)). */ +export function markLoaded(allowances: Allowance[], meshTable: string): { + allowances: (Allowance & { loaded: boolean })[]; + loadedNotKept: { key: string; at: string }[]; +} { + const comments = [...meshTable.matchAll(/comment "allowance (\S+) (\S+)"/g)].map((m) => ({ key: m[1], at: m[2] })); + const kept = new Set(allowances.map((a) => a.key)); + const seen = new Set(); + const loadedNotKept = comments.filter((c) => !kept.has(c.key) && !seen.has(c.key) && seen.add(c.key)); + return { + allowances: allowances.map((a) => ({ ...a, loaded: comments.some((c) => c.key === a.key && c.at === a.at) })), + loadedNotKept, + }; +} + +/** Whether the loaded mesh table's input chain accepts `protocol` `port` only with a source match (`ip saddr` or `ip6 + * saddr`) and never from any source: a port a derived rule admits from the private network only (§3, H-A-315 (7), + * H-A-319). */ +export function privateOnly(meshTable: string, protocol: Protocol, port: number): boolean { + const input = /chain input \{([\s\S]*?)\n\t?\}/.exec(meshTable)?.[1] ?? ""; + let withSource = false; + for (const line of input.split("\n")) { + if (!/\baccept\b/.test(line) || !line.includes(`${protocol} dport `)) continue; + const ports = /dport (\{[^}]*\}|\S+)/.exec(line)?.[1] ?? ""; + const names = ports.replace(/[{}]/g, "").split(",").map((p) => p.trim()).filter(Boolean); + const named = names.some((p) => { + const [lo, hi] = p.split("-").map(Number); + return hi === undefined ? lo === port : lo <= port && port <= hi; + }); + if (!named) continue; + if (!/\bip6? saddr\b/.test(line)) return false; + withSource = true; + } + return withSource; } diff --git a/modules/nftables/module.json b/modules/nftables/module.json index 2a60233d8..68964f4fa 100644 --- a/modules/nftables/module.json +++ b/modules/nftables/module.json @@ -26,9 +26,17 @@ { "name": "allowances", "storage": "key-value", - "template": "state" + "template": "state", + "options": { + "history": 1, + "per-machine": true + } } ], + "invokes": [ + "seat:node-engine.converged", + "seat:mesh-hand-acts.hand-act" + ], "filtering": { "into": "/etc/nftables.conf" }, @@ -81,6 +89,14 @@ "tools": [ "firewall_rules" ], + "config": { + "allowances-max": { + "type": "number", + "description": "The most allowances this machine keeps, which allow refuses past (design 33 control-verbs §3): it keeps the rendered chain readable and allowed in one answer.", + "trusted": false, + "default": 100 + } + }, "build": { "artifacts": [ { diff --git a/modules/nftables/package.json b/modules/nftables/package.json index bff22772a..34139c83d 100644 --- a/modules/nftables/package.json +++ b/modules/nftables/package.json @@ -9,7 +9,8 @@ "test": "node --test --experimental-strip-types 'test/*.test.ts'" }, "dependencies": { - "@novox/mesh-sdk": "^0.1.1" + "@novox/mesh-sdk": "^0.1.1", + "@novox/mesh-connectivity-contracts-node-packet-filter": "^0.1.0" }, "devDependencies": { "@types/node": "^22.0.0", diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts index 35efb47d1..990f2926c 100644 --- a/modules/nftables/test/allowances.test.ts +++ b/modules/nftables/test/allowances.test.ts @@ -1,16 +1,21 @@ -// The operator's allowances against a state in memory (ADR 0683; design 33 control-verbs §9). +// The operator's allowances against a state in memory (ADR 0683; design 33 control-verbs §14; design 47 H-A-315, +// H-A-317, H-A-318, H-A-319). import { test } from "node:test"; import assert from "node:assert/strict"; import { readFileSync } from "node:fs"; import { - Allowances, LONGEST_WAIT_MS, MOST, STATE, changedSubject, markLoaded, - type Changed, type Schedule, type Store, type Value, + Allowances, CONVERGED_BOUND_MS, LONGEST_WAIT_MS, MOST, STATE, markLoaded, privateOnly, + type Changed, type Convergence, type HandAct, type Schedule, type Store, type Value, } from "../allowances.ts"; interface Timer { ms: number; fire: () => void; cancelled: boolean } -function fake(at = "2026-11-21T20:00:00Z") { - const kept = new Map(); +// The loaded mesh table: the store's port from the private network only, 80 from anywhere and 8443 from both. +const TABLE = 'table inet mesh {\n\tchain input {\n\t\ttype filter hook input priority filter; policy drop;\n' + + '\t\tip saddr { 10.77.0.1, 10.77.0.2 } tcp dport 5432 accept\n\t\tip6 saddr { fd77::1 } tcp dport 5432 accept\n' + + '\t\ttcp dport 80 accept\n\t\tip saddr { 10.77.0.1 } tcp dport { 8443, 9500-9600 } accept\n\t\ttcp dport 8443 accept\n\t}\n}\n'; + +function fake(at = "2026-11-21T20:00:00Z", node = "shanks", kept = new Map()) { const said: Changed[] = []; const journal: string[] = []; const timers: Timer[] = []; @@ -26,10 +31,28 @@ function fake(at = "2026-11-21T20:00:00Z") { delete: async (k) => { kept.delete(k); }, keys: async () => [...kept.keys()], }; - const a = new Allowances(store, "shanks", async (b) => { said.push(b); }, () => clock.now, schedule, (l) => journal.push(l)); - return { a, kept, said, clock, timers, journal }; + const acts: HandAct[] = []; + const asks = { + convergence: { state: "converged", since: "2026-11-01T00:00:00Z" } as Convergence | "silent", + asked: 0, + most: MOST, + table: TABLE, + }; + const a = new Allowances(store, node, async (b) => { said.push(b); }, { + converged: () => { + asks.asked++; + return asks.convergence === "silent" ? new Promise(() => {}) : Promise.resolve(asks.convergence); + }, + handAct: async (act) => { acts.push(act); }, + most: async () => asks.most, + meshTable: async () => asks.table, + }, () => clock.now, schedule, (l) => journal.push(l)); + return { a, kept, said, clock, timers, journal, acts, asks }; } +/** The state's key of an allowance's key on shanks (H-A-317). */ +const k = (key: string) => `shanks.${key}`; + const settle = () => new Promise((r) => setImmediate(r)); test("allow keeps one key per interface, and with none the default set's key, which names no interface", async () => { @@ -44,7 +67,7 @@ test("allow keeps one key per interface, and with none the default set's key, wh const got = await a.allow(c.args, "lead@shanks"); assert.deepEqual(got.allowances.map((x) => x.key), c.keys, c.name); assert.equal(got.said, true, c.name); - assert.deepEqual([...kept.keys()].sort(), c.keys, c.name); + assert.deepEqual([...kept.keys()].sort(), c.keys.map(k), c.name); assert.deepEqual(said.map((b) => [b.change, b.node, b.by, b.why, b.allowances.map((x) => x.key)]), [["allowed", "shanks", "lead@shanks", c.args.why, c.keys]], c.name); for (const v of kept.values()) { @@ -70,44 +93,116 @@ test("allow and disallow refuse what is not an allowance, writing nothing", asyn ["empty why", { port: 80, why: "" }, /why: /], ["long why", { port: 80, why: "x".repeat(501) }, /why: /], ["unknown argument", { port: 80, why: "w", comment: "x" }, /comment: not an argument/], + ["the store's port with no source", { port: 5432, why: "w" }, /port: tcp 5432 is admitted .* from given sources only/], ]; for (const [name, args, want] of bad) { - const { a, kept, said } = fake(); + const { a, kept, said, acts } = fake(); await assert.rejects(a.allow(args, "x"), want, name); assert.equal(kept.size, 0, name); assert.equal(said.length, 0, name); + assert.equal(acts.length, 0, name); } - const { a } = fake(); + const { a, kept } = fake(); + await assert.rejects(a.allow({ port: 80, why: "w" }, "unproven"), /allow: refused: the request carries no caller the tool runner proved/); + await assert.rejects(a.disallow({ port: 80, why: "w" }, "unproven"), /disallow: refused: the request carries no caller/); + await a.allow({ port: 5432, source: "192.168.1.0/24", why: "the store from the home network" }, "x"); + assert.deepEqual([...kept.keys()], [k("allow.tcp.5432")]); await assert.rejects(a.disallow({ port: 80, why: "w", source: "10.0.0.1" }, "x"), /source: not an argument/); await assert.rejects(a.disallow({ port: 80 }, "x"), /why: /); await assert.rejects(a.allowed({ port: 80 }), /port: not an argument/); }); -test("a 101st allowance is refused; a replacement at the bound is not", async () => { +test("a 101st allowance is refused at the default allowances-max; a replacement at the bound is not", async () => { const { a, kept } = fake(); for (let p = 1; p <= MOST; p++) await a.allow({ port: p, why: "w" }, "x"); - await assert.rejects(a.allow({ port: 1000, why: "w" }, "x"), /101 allowances would be kept on this node, more than 100/); + await assert.rejects(a.allow({ port: 1000, why: "w" }, "x"), /101 allowances would be kept on this node, more than allowances-max 100/); assert.equal(kept.size, MOST); await a.allow({ port: 1, why: "again" }, "x"); - assert.equal(kept.get("allow.tcp.1")!.why, "again"); + assert.equal(kept.get(k("allow.tcp.1"))!.why, "again"); }); -test("allow then disallow writes the key, then deletes it, saying allowed and disallowed", async () => { - const { a, kept, said } = fake(); - await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "open" }, "x"); +test("an allowance kept on one node is absent from another node's allowed, and counts not toward its bound", async () => { + const shared = new Map(); + const shanks = fake(undefined, "shanks", shared); + const ace = fake(undefined, "ace", shared); + ace.asks.most = 1; + await shanks.a.allow({ port: 8000, why: "w" }, "x"); + assert.deepEqual((await ace.a.allowed()).allowances, []); + await ace.a.allow({ port: 9000, why: "w" }, "x"); + assert.deepEqual([...shared.keys()].sort(), ["ace.allow.tcp.9000", "shanks.allow.tcp.8000"]); + assert.deepEqual((await shanks.a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000"]); + await assert.rejects(ace.a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /); +}); + +test("on an adopted node allow and disallow are refused naming the adoption and allowed answers none; a silent converged refuses both", async () => { + const { a, kept, asks, timers, said } = fake(); + await a.allow({ port: 8000, why: "w" }, "x"); + asks.convergence = { state: "adopted", since: "2026-11-20T10:00:00Z", found: "ufw" }; + await assert.rejects(a.allow({ port: 9000, why: "w" }, "x"), /allow: refused: this node is adopted \(the found firewall ufw, since 2026-11-20T10:00:00Z\)/); + await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /disallow: refused: this node is adopted/); + assert.deepEqual((await a.allowed()).allowances, []); + assert.deepEqual([...kept.keys()], [k("allow.tcp.8000")]); + asks.convergence = "silent"; + const pending = a.allow({ port: 9000, why: "w" }, "x"); + const bound = timers.at(-1)!; + assert.equal(bound.ms, CONVERGED_BOUND_MS); + bound.fire(); + await assert.rejects(pending, /allow: refused: the node-engine's converged did not answer \(no answer within 10 s\)/); + const gone = a.disallow({ port: 8000, why: "w" }, "x"); + timers.at(-1)!.fire(); + await assert.rejects(gone, /disallow: refused: the node-engine's converged did not answer/); + assert.equal(said.length, 1); +}); + +test("allowed asks converged again while none answered, and refuses when it does not answer (H-A-318)", async () => { + const { a, asks, timers, said, journal } = fake(); + asks.convergence = "silent"; + const start = a.started(); + timers.at(-1)!.fire(); + await start; + assert.match(journal.join("\n"), /start: refused: the node-engine's converged did not answer/); + assert.equal(said.at(-1)!.change, "started"); + const asked = asks.asked; + const pending = a.allowed(); + timers.at(-1)!.fire(); + await assert.rejects(pending, /allowed: refused: the node-engine's converged did not answer/); + assert.equal(asks.asked, asked + 1); + asks.convergence = { state: "converged" }; + assert.deepEqual((await a.allowed()).allowances, []); + await a.allowed(); + assert.equal(asks.asked, asked + 2, "an answer held is not asked again"); +}); + +test("privateOnly: a port accepted only with a source match, never from any source", () => { + assert.equal(privateOnly(TABLE, "tcp", 5432), true); + assert.equal(privateOnly(TABLE, "tcp", 9550), true, "a range of a set"); + assert.equal(privateOnly(TABLE, "tcp", 80), false); + assert.equal(privateOnly(TABLE, "tcp", 8443), false, "accepted from anywhere too"); + assert.equal(privateOnly(TABLE, "udp", 5432), false); + assert.equal(privateOnly(TABLE, "tcp", 8000), false, "no derived rule"); +}); + +test("allow then disallow writes the key, then deletes it, saying allowed and disallowed, with two hand-act log lines", async () => { + const { a, kept, said, acts } = fake(); + const got = await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "open" }, "x"); + assert.equal(got.said, true); assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]); const gone = await a.disallow({ port: 8000, interfaces: ["enp6s0"], why: "done" }, "y"); assert.deepEqual(gone.allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]); assert.equal(gone.said, true); assert.equal(kept.size, 0); assert.deepEqual(said.map((b) => [b.change, b.by, b.why]), [["allowed", "x", "open"], ["disallowed", "y", "done"]]); + assert.deepEqual(acts, [ + { what: "allowed allow.tcp.8000.enp6s0 on shanks", why: "open (x)", cause: "allowance-set", verb: "allow" }, + { what: "disallowed allow.tcp.8000.enp6s0 on shanks", why: "done (y)", cause: "allowance-taken-back", verb: "disallow" }, + ]); }); test("disallow is all or nothing: a key not kept is refused by name and none is deleted", async () => { const { a, kept, said } = fake(); await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "w" }, "x"); await assert.rejects(a.disallow({ port: 8000, interfaces: ["enp6s0", "wlan0"], why: "w" }, "x"), /no allowance allow\.tcp\.8000\.wlan0/); - assert.deepEqual([...kept.keys()], ["allow.tcp.8000.enp6s0"]); + assert.deepEqual([...kept.keys()], [k("allow.tcp.8000.enp6s0")]); // no interfaces names the default set's key, never one of an interface await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /); assert.equal(said.length, 1); @@ -119,20 +214,21 @@ test("a second allow of one key replaces it whole and answers what it replaced; const got = await a.allow({ port: 8000, source: "10.0.0.5", why: "second" }, "y"); assert.deepEqual(got.allowances.map((x) => [x.key, x.source, x.replaced?.source, x.replaced?.why]), [["allow.tcp.8000", "10.0.0.5", "192.168.1.0/24", "first"]]); - assert.deepEqual([...kept.entries()].map(([k, v]) => [k, v.source, v.by, v.until]), [["allow.tcp.8000", "10.0.0.5", "y", undefined]]); + assert.deepEqual([...kept.entries()].map(([key, v]) => [key, v.source, v.by, v.until]), [[k("allow.tcp.8000"), "10.0.0.5", "y", undefined]]); }); test("at its until an allowance is deleted by its timer, says expired, is journalled, and allowed answers without it", async () => { const { a, kept, said, clock, timers, journal } = fake(); await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "for an hour" }, "x"); await a.allow({ port: 9000, why: "w" }, "x"); - await a.watched({ key: "allow.tcp.8000", op: "put", value: kept.get("allow.tcp.8000")! }); - assert.equal(timers.length, 1); - assert.equal(timers[0].ms, 3600_000); + await a.watched({ key: k("allow.tcp.8000"), op: "put", value: kept.get(k("allow.tcp.8000"))! }); + const live = timers.filter((t) => !t.cancelled); + assert.equal(live.length, 1, "one expiry timer; every converged bound is cancelled once answered"); + assert.equal(live[0].ms, 3600_000); clock.now = new Date("2026-11-21T21:00:00Z"); - timers[0].fire(); + live[0].fire(); await settle(); - assert.deepEqual([...kept.keys()], ["allow.tcp.9000"]); + assert.deepEqual([...kept.keys()], [k("allow.tcp.9000")]); assert.deepEqual([said.at(-1)!.change, said.at(-1)!.allowances.map((x) => x.key)], ["expired", ["allow.tcp.8000"]]); assert.match(journal.join("\n"), /the allowance allow\.tcp\.8000 .*for an hour\) expired at 2026-11-21T21:00:00Z and is removed/); assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.9000"]); @@ -141,21 +237,24 @@ test("at its until an allowance is deleted by its timer, says expired, is journa test("the expiry timers follow the state: a delete cancels, a far until waits in steps, a stale timer removes nothing", async () => { const { a, kept, clock, timers } = fake(); const v: Value = { port: 1, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00Z", until: "2026-11-21T22:00:00Z" }; - await a.watched({ key: "k", op: "put", value: v }); - await a.watched({ key: "k", op: "delete" }); + await a.watched({ key: k("allow.tcp.1"), op: "put", value: v }); + await a.watched({ key: k("allow.tcp.1"), op: "delete" }); assert.equal(timers.at(-1)!.cancelled, true); - await a.watched({ key: "far", op: "put", value: { ...v, until: "2027-06-01T00:00:00Z" } }); + const armed = timers.length; + await a.watched({ key: "ace.allow.tcp.1", op: "put", value: v }); + assert.equal(timers.length, armed, "another node's key arms no timer"); + await a.watched({ key: k("allow.tcp.2"), op: "put", value: { ...v, until: "2027-06-01T00:00:00Z" } }); assert.equal(timers.at(-1)!.ms, LONGEST_WAIT_MS); await a.allow({ port: 9000, until: "2026-11-21T21:30:00Z", why: "w" }, "x"); await a.allow({ port: 9000, until: "2026-11-21T23:00:00Z", why: "w" }, "x"); clock.now = new Date("2026-11-21T21:30:00Z"); assert.equal(await a.expire("allow.tcp.9000", "2026-11-21T21:30:00Z"), false); - assert.ok(kept.has("allow.tcp.9000")); + assert.ok(kept.has(k("allow.tcp.9000"))); // at a start, a key already past its until is removed at once clock.now = new Date("2026-11-22T00:00:00Z"); - await a.watched({ key: "allow.tcp.9000", op: "put", value: kept.get("allow.tcp.9000")! }); + await a.watched({ key: k("allow.tcp.9000"), op: "put", value: kept.get(k("allow.tcp.9000"))! }); await settle(); - assert.ok(!kept.has("allow.tcp.9000")); + assert.ok(!kept.has(k("allow.tcp.9000"))); }); test("at a start every expired allowance is removed before started is said (H-A-312 (2))", async () => { @@ -164,7 +263,7 @@ test("at a start every expired allowance is removed before started is said (H-A- await a.allow({ port: 9000, why: "w" }, "x"); clock.now = new Date("2026-11-21T22:00:00Z"); await a.started(); - assert.deepEqual([...kept.keys()], ["allow.tcp.9000"]); + assert.deepEqual([...kept.keys()], [k("allow.tcp.9000")]); assert.deepEqual(said.slice(-2).map((b) => [b.change, b.allowances.map((x) => x.key)]), [["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]); }); @@ -176,16 +275,22 @@ test("a start says started with every allowance", async () => { assert.deepEqual([said.at(-1)!.change, said.at(-1)!.node, said.at(-1)!.allowances.map((x) => x.key)], ["started", "shanks", ["allow.tcp.8000"]]); }); -test("rules marks an allowance loaded only when a rule of the mesh's table carries its comment", () => { - const table = 'table inet mesh {\n\tchain input {\n\t\tiifname != "mesh0" tcp dport 8000 accept comment "allowance allow.tcp.8000"\n\t}\n}\n'; - const base: Value = { port: 8000, protocol: "tcp", why: "w", by: "x", at: "t" }; - const got = markLoaded([{ key: "allow.tcp.8000", ...base }, { key: "allow.tcp.9000", ...base, port: 9000 }], table); - assert.deepEqual(got.map((x) => [x.key, x.loaded]), [["allow.tcp.8000", true], ["allow.tcp.9000", false]]); +test("rules marks an allowance loaded only on a comment with an equal at, and lists a comment with no kept key as loaded, not kept", () => { + const table = 'table inet mesh {\n\tchain input {\n' + + '\t\tiifname != "mesh0" tcp dport 8000 accept comment "allowance allow.tcp.8000 2026-11-21T20:00:00.000Z"\n' + + '\t\tiifname != "mesh0" tcp dport 8001 accept comment "allowance allow.tcp.8001 2026-11-21T19:00:00.000Z"\n' + + '\t\tiifname != "mesh0" tcp dport 7000 accept comment "allowance allow.tcp.7000 2026-11-20T08:00:00.000Z"\n\t}\n}\n'; + const base: Value = { port: 8000, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00.000Z" }; + const got = markLoaded([{ key: "allow.tcp.8000", ...base }, { key: "allow.tcp.8001", ...base, port: 8001 }, { key: "allow.tcp.9000", ...base, port: 9000 }], table); + assert.deepEqual(got.allowances.map((x) => [x.key, x.loaded]), [["allow.tcp.8000", true], ["allow.tcp.8001", false], ["allow.tcp.9000", false]]); + assert.deepEqual(got.loadedNotKept, [{ key: "allow.tcp.7000", at: "2026-11-20T08:00:00.000Z" }]); }); -test("the manifest serves the six verbs and requires the state the code keeps", () => { +test("the manifest serves the six verbs, requires the state per machine, invokes converged and the hand-act log, and sets allowances-max", () => { const m = JSON.parse(readFileSync(new URL("../module.json", import.meta.url), "utf8")); assert.deepEqual(m.claims[0].serves, ["rules", "reload", "remove", "allow", "disallow", "allowed"]); - assert.deepEqual(m.requires, [{ name: STATE, storage: "key-value", template: "state" }]); - assert.equal(changedSubject("shanks"), "mesh.seat.node-packet-filter.event.allowances-changed.shanks"); + assert.deepEqual(m.requires, [{ name: STATE, storage: "key-value", template: "state", options: { history: 1, "per-machine": true } }]); + assert.deepEqual(m.invokes, ["seat:node-engine.converged", "seat:mesh-hand-acts.hand-act"]); + assert.equal(m.emits, undefined, "the claim says the seat's event (H-A-317)"); + assert.equal(m.config["allowances-max"].default, MOST); }); diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index 3b0dcf2ff..03b3ccdb0 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -4,10 +4,12 @@ // control-verbs). import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools"; import { callerOf } from "@novox/mesh-sdk/callers"; -import { seatPublish } from "@novox/mesh-sdk/runtime"; +import { broker } from "@novox/mesh-sdk/messaging"; +import { config, seatPublish } from "@novox/mesh-sdk/runtime"; import { keeps, state } from "@novox/mesh-sdk/state"; +import { allowancesChangedSubject } from "@novox/mesh-connectivity-contracts-node-packet-filter"; import { FirewallClient } from "../client.js"; -import { Allowances, STATE, changedSubject, markLoaded, type Store, type Value } from "../allowances.js"; +import { Allowances, MOST, STATE, markLoaded, type Convergence, type Store, type Value } from "../allowances.js"; const port = { type: "integer", description: "the port, 1-65535" }; const protocol = { type: "string", description: "tcp (the default) or udp" }; @@ -24,7 +26,8 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): name: "rules", description: "The packet filter as this machine enforces it now: the nftables ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or chain when asked. " + - "Beside it every allowance, marked loaded when a rule of the mesh's table carries its comment allowance .", + "Beside it every allowance, marked loaded only when a rule of the mesh's table carries its comment allowance with an equal at, " + + "and every loaded allowance comment whose key is not kept, listed as loaded, not kept.", input: { table: { type: "string", description: "one nftables table, as `family name` (optional)" }, chain: { type: "string", description: "one chain of that table (optional)" }, @@ -34,7 +37,8 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): const seen = await firewall.rules(table, args.chain ? String(args.chain) : undefined); // The mark reads the mesh's own table whole, whatever the listing was narrowed to. const mesh = !table && !args.chain ? seen.nftables : await firewall.ruleset(); - return { ...seen, allowances: markLoaded((await allowances.allowed()).allowances, mesh) }; + const marked = markLoaded((await allowances.allowed()).allowances, mesh); + return { ...seen, allowances: marked.allowances, "loaded-not-kept": marked.loadedNotKept }; }, }, { @@ -56,8 +60,10 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): description: "Open a port by hand on this machine, beside the ports derived from the modules' listens: one allowance per protocol, port and interface, " + "kept as this module's state and rendered by the node-engine into the inet mesh table's input chain at its next compose of the filter. " + - "A key that exists is replaced whole and answered. Refuses, naming the argument and writing nothing, a bad port, protocol, interface, source or until, " + - "an empty or longer why, an unknown argument, and more than 100 allowances on the node. Whether the loaded chain carries it is read with rules.", + "Who set it is the caller the bus proved. A key that exists is replaced whole and answered. Written in the hand-act log. " + + "Refuses, naming the argument and writing nothing, an unproven caller, an adopted node or a converged that does not answer, a bad port, protocol, interface, source or until, " + + "an empty or longer why, an unknown argument, a port the loaded mesh table admits from given sources only unless a source is given, " + + "and more allowances on the node than the setting allowances-max (default 100). Whether the loaded chain carries it is read with rules.", input: { port, protocol, @@ -72,14 +78,14 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): name: "disallow", description: "Take back allowances: the keys the protocol, port and interfaces name (none: the default set's key) are deleted, or, when one does not exist, " + - "it is refused by name and none is deleted.", + "it is refused by name and none is deleted. Written in the hand-act log. Refuses as allow does an unproven caller, an adopted node and a converged that does not answer.", input: { port, protocol, interfaces, why }, run: async (args) => allowances.disallow(args, callerOf(args)), }, { name: "allowed", description: - "Every allowance kept on this machine, with its key, port, protocol, interface, source, until, why, by and at. " + + "Every allowance kept for this machine only, with its key, port, protocol, interface, source, until, why, by and at; none on an adopted node. " + "An allowance is removed at its until, so none answered has expired.", input: {}, run: async (args) => allowances.allowed(args), @@ -99,17 +105,52 @@ export function getFirewallTools(firewall: FirewallClient): ToolDefinition[] { } const firewall = FirewallClient.onThisMachine(); -// The allowances are this module's own state, announced as kept (ADR 0495), every change said as the seat's event -// allowances-changed of this node; watching its own state gives every key with an until its timer, at every start -// too; and a start says started, so a node-engine that refused a compose for want of an answer composes again. +// The allowances are this module's own state, announced as kept (ADR 0495), one bucket per machine whose keys carry +// the node, so this holder watches and lists its own node's keys only (H-A-317); every change is said as the seat's +// event allowances-changed of this node; watching its own state gives every key with an until its timer, at every +// start too; and a start asks the node-engine's converged and says started, so a node-engine that refused a compose +// for want of an answer composes again. const node = process.env.MESH_NODE ?? ""; const kept = state(STATE); -const allowances = new Allowances(kept as Store, node, (body) => seatPublish(changedSubject(node), body)); +const own = new Set(); +// The node's keys are known once the watch handed every current value over; a start that failed refuses every listing. +let watched!: { done: () => void; failed: (err: unknown) => void }; +const watching = new Promise((done, failed) => { watched = { done, failed }; }); +watching.catch(() => {}); +const store: Store = { + get: (key) => kept.get(key), + put: (key, value) => kept.put(key, value), + delete: (key) => kept.delete(key), + keys: async () => { + await watching; + return [...own]; + }, +}; +const allowances = new Allowances(store, node, (body) => seatPublish(allowancesChangedSubject(node), body), { + converged: async () => (await broker().request(`seat:node-engine.converged@${node}`, {})), + handAct: async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }, + most: async () => { + const v = await config("allowances-max"); + if (v === undefined || v === null || v === "") return MOST; + const n = Number(v); + if (!Number.isInteger(n) || n < 1) throw new Error(`the setting allowances-max is ${JSON.stringify(v)}, not a whole number of allowances`); + return n; + }, + meshTable: () => firewall.ruleset(), +}); void (async () => { await keeps([{ name: STATE }]); - await kept.watch((change) => allowances.watched(change)); + await kept.watch(async (change) => { + if (change.op === "put") own.add(change.key); + else own.delete(change.key); + await allowances.watched(change); + }, { key: `${node}.**` }); + watched.done(); await allowances.started(); -})().catch((err) => console.error(`[nftables] the allowances did not start (no expiry timers, no started said): ${err}`)); +})().catch((err) => { + watched.failed(new Error(`the allowances did not start: ${err}`)); + console.error(`[nftables] the allowances did not start (no expiry timers, no started said): ${err}`); +}); // The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this // module holds it (ADR 0159, 0160). The module's own under its own. registerModuleTools("node-packet-filter", () => getSeatVerbs(firewall, allowances)); diff --git a/modules/nftables/tsconfig.json b/modules/nftables/tsconfig.json index 91d5b91c5..1829ad694 100644 --- a/modules/nftables/tsconfig.json +++ b/modules/nftables/tsconfig.json @@ -10,6 +10,7 @@ }, "include": [ "client.ts", + "allowances.ts", "tools/index.ts" ] -} \ No newline at end of file +}