From 7bd1e74086a6a36046590451bf9a4952995fe089 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 20:40:35 +0100 Subject: [PATCH 1/6] nftables: serve allow, disallow and allowed, keeping allowances as its own state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The operator, 2026-11-21 20:35: a firewall module has tools to control the firewall beside the provisioning from declarations. The holder keeps one allowance per protocol, port and interface in its state allowances, says every change as allowances-changed, removes an allowance at its until by a timer on its own state (and every expired one at its start, before started), and rules marks each allowance loaded by its comment in the mesh's table. It writes no rule: the node-engine renders the allowances. Builds: ADR 0683; design 33 control-verbs §1-§7, §9; design 47 H H-A-304..310, H-A-312 (2) --- modules/nftables/allowances.ts | 306 +++++++++++++++++++++++ modules/nftables/module.json | 12 +- modules/nftables/package.json | 4 +- modules/nftables/test/allowances.test.ts | 191 ++++++++++++++ modules/nftables/tools/index.ts | 79 +++++- 5 files changed, 582 insertions(+), 10 deletions(-) create mode 100644 modules/nftables/allowances.ts create mode 100644 modules/nftables/test/allowances.test.ts diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts new file mode 100644 index 000000000..c93d74a9d --- /dev/null +++ b/modules/nftables/allowances.ts @@ -0,0 +1,306 @@ +// 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 +// 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 +// its own state, said and journalled, so no expired entry is kept or answered. + +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). */ +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}`; +} + +export type Protocol = "tcp" | "udp"; + +/** One allowance as it is kept: the state's value (§7). */ +export interface Value { + port: number; + protocol: Protocol; + /** Absent: every input interface but the private network's. */ + interface?: string; + /** Absent: any source. */ + source?: string; + /** RFC 3339; absent: never expires. */ + until?: string; + why: string; + by: string; + at: string; +} + +/** One allowance as it is answered: its value with its key. */ +export interface Allowance extends Value { + key: string; +} + +export type Change = "allowed" | "disallowed" | "expired" | "started"; + +/** The event's body (§6). */ +export interface Changed { + node: string; + change: Change; + allowances: Allowance[]; + by?: string; + why?: string; + at: string; +} + +/** What the allowances need of the module's state: the SDK's `state()` serves it. */ +export interface Store { + get(key: string): Promise<{ value: Value } | null>; + put(key: string, value: Value): Promise; + delete(key: string): Promise; + keys(): Promise; +} + +/** One change of the state as its watch hands it over: the SDK's `StateChange`. */ +export interface Watched { + key: string; + op: "put" | "delete"; + value?: Value; +} + +/** Says the event. */ +export type Say = (body: Changed) => Promise; + +/** Runs `fire` after `ms` milliseconds, answering how to cancel it: `setTimeout` on the machine, a fake in tests. */ +export type Schedule = (ms: number, fire: () => void) => () => void; + +/** The longest one timer waits (Node's setTimeout holds 2^31-1 ms); a later until is waited for in steps. */ +export const LONGEST_WAIT_MS = 2 ** 31 - 1; + +export const timers: Schedule = (ms, fire) => { + const t = setTimeout(fire, ms); + return () => clearTimeout(t); +}; + +/** One key of the state: allow.., and . when it names one. */ +export function keyOf(protocol: Protocol, port: number, iface?: string): string { + return iface ? `allow.${protocol}.${port}.${iface}` : `allow.${protocol}.${port}`; +} + +const IFACE = /^[A-Za-z0-9_.-]{1,15}$/; + +function refuse(argument: string, why: string): never { + throw new Error(`${argument}: ${why}; nothing is written`); +} + +function only(args: Record, known: string[]): void { + for (const k of Object.keys(args)) { + if (!known.includes(k)) refuse(k, `not an argument of this verb (${known.join(", ") || "none"})`); + } +} + +function portOf(v: unknown): number { + if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > 65535) { + refuse("port", `${JSON.stringify(v)} is not an integer from 1 to 65535`); + } + return v; +} + +function protocolOf(v: unknown): Protocol { + if (v === undefined) return "tcp"; + if (v === "tcp" || v === "udp") return v; + refuse("protocol", `${JSON.stringify(v)} is neither tcp (the default) nor udp`); +} + +function interfacesOf(v: unknown): (string | undefined)[] { + if (v === undefined) return [undefined]; + if (!Array.isArray(v)) refuse("interfaces", "a list of interface names"); + if (v.length === 0) return [undefined]; + for (const i of v) { + if (typeof i !== "string" || !IFACE.test(i)) { + refuse("interfaces", `${JSON.stringify(i)} is not 1 to 15 letters, digits, _ . or -`); + } + } + return [...new Set(v as string[])]; +} + +function sourceOf(v: unknown): string | undefined { + if (v === undefined) return undefined; + const s = typeof v === "string" ? v : ""; + const [addr, bits, more] = s.split("/"); + const family = isIP(addr); + const max = family === 4 ? 32 : 128; + if (family === 0 || more !== undefined || (bits !== undefined && !(/^\d+$/.test(bits) && Number(bits) <= max))) { + refuse("source", `${JSON.stringify(v)} is not one IPv4 or IPv6 CIDR`); + } + return s; +} + +function untilOf(v: unknown, now: Date): string | undefined { + if (v === undefined) return undefined; + const s = typeof v === "string" ? v : ""; + const t = Date.parse(s); + if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$/.test(s) || Number.isNaN(t)) { + refuse("until", `${JSON.stringify(v)} is not an RFC 3339 time, such as 2026-11-22T08:00:00Z`); + } + if (t <= now.getTime()) refuse("until", `${s} is not in the future`); + return s; +} + +function whyOf(v: unknown): string { + if (typeof v !== "string" || v.length < 1 || v.length > 500) refuse("why", "required, 1 to 500 characters"); + return v; +} + +function answered(key: string, value: Value): Allowance { + return { key, ...value }; +} + +export class Allowances { + private readonly pending = new Map void>(); + private readonly store: Store; + private readonly node: string; + private readonly say: Say; + private readonly now: () => Date; + private readonly schedule: Schedule; + private readonly journal: (line: string) => void; + + constructor( + store: Store, + node: string, + say: Say, + now: () => Date = () => new Date(), + schedule: Schedule = timers, + journal: (line: string) => void = (line) => console.log(`[nftables] ${line}`), + ) { + this.store = store; + this.node = node; + this.say = say; + this.now = now; + this.schedule = schedule; + this.journal = journal; + } + + /** Said once each time the holder starts serving the seat, with every allowance (§6). */ + async started(): Promise { + const { allowances } = await this.allowed(); + await this.say({ node: this.node, change: "started", 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); + if (change.op !== "put" || !change.value?.until) return; + this.arm(change.key, change.value.until); + } + + private arm(key: string, until: string): void { + const left = Date.parse(until) - this.now().getTime(); + if (left <= 0) { + void this.expire(key, until); + return; + } + const step = Math.min(left, LONGEST_WAIT_MS); + this.pending.set(key, this.schedule(step, () => { + this.pending.delete(key); + if (step < left) this.arm(key, until); + else void this.expire(key, until); + })); + } + + /** 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); + if (!entry || entry.value.until !== until || Date.parse(until) > this.now().getTime()) return false; + await this.store.delete(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}` : ""}, ` + + `set by ${a.by} at ${a.at}: ${a.why}) expired at ${until} and is removed`); + return true; + } catch (err) { + this.journal(`the allowance ${key} expired at ${until} and could not be removed: ${err instanceof Error ? err.message : String(err)}`); + return false; + } + } + + /** 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 }> { + only(args, ["port", "protocol", "interfaces", "source", "until", "why"]); + const now = this.now(); + const port = portOf(args.port); + const protocol = protocolOf(args.protocol); + const interfaces = interfacesOf(args.interfaces); + 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.")); + 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}`); + const at = now.toISOString(); + const out: (Allowance & { replaced?: Allowance })[] = []; + for (const iface of interfaces) { + const key = keyOf(protocol, port, iface); + const value: Value = { + port, protocol, + ...(iface ? { interface: iface } : {}), + ...(source ? { source } : {}), + ...(until ? { until } : {}), + why, by, at, + }; + const before = await this.store.get(key); + await this.store.put(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 }); + return { allowances: out, said: true }; + } + + /** 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 }> { + only(args, ["port", "protocol", "interfaces", "why"]); + const port = portOf(args.port); + const protocol = protocolOf(args.protocol); + const interfaces = interfacesOf(args.interfaces); + const why = whyOf(args.why); + const found: Allowance[] = []; + for (const iface of interfaces) { + const key = keyOf(protocol, port, iface); + const entry = await this.store.get(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.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. */ + async allowed(args: Record = {}): Promise<{ allowances: Allowance[] }> { + only(args, []); + 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); + if (!entry) continue; + if (entry.value.until && Date.parse(entry.value.until) <= now) { + await this.expire(key, entry.value.until); + continue; + } + allowances.push(answered(key, entry.value)); + } + 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) })); +} diff --git a/modules/nftables/module.json b/modules/nftables/module.json index 6c6634d86..2a60233d8 100644 --- a/modules/nftables/module.json +++ b/modules/nftables/module.json @@ -15,10 +15,20 @@ "serves": [ "rules", "reload", - "remove" + "remove", + "allow", + "disallow", + "allowed" ] } ], + "requires": [ + { + "name": "allowances", + "storage": "key-value", + "template": "state" + } + ], "filtering": { "into": "/etc/nftables.conf" }, diff --git a/modules/nftables/package.json b/modules/nftables/package.json index 6342c07b6..bff22772a 100644 --- a/modules/nftables/package.json +++ b/modules/nftables/package.json @@ -1,11 +1,11 @@ { "name": "@novox/module-nftables", "version": "0.1.0", - "description": "nftables — loads the mesh's packet filter and holds the node-packet-filter seat: its verbs rules, reload and remove (novox/hq ADR 0045, ADR 0170).", + "description": "nftables — loads the mesh's packet filter and holds the node-packet-filter seat: its verbs rules, reload, remove, allow, disallow and allowed (novox/hq ADR 0045, ADR 0170; design 47 H-A-304).", "type": "module", "private": true, "scripts": { - "build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist", + "build": "tsc client.ts allowances.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist", "test": "node --test --experimental-strip-types 'test/*.test.ts'" }, "dependencies": { diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts new file mode 100644 index 000000000..35efb47d1 --- /dev/null +++ b/modules/nftables/test/allowances.test.ts @@ -0,0 +1,191 @@ +// The operator's allowances against a state in memory (ADR 0683; design 33 control-verbs §9). +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, +} from "../allowances.ts"; + +interface Timer { ms: number; fire: () => void; cancelled: boolean } + +function fake(at = "2026-11-21T20:00:00Z") { + const kept = new Map(); + const said: Changed[] = []; + const journal: string[] = []; + const timers: Timer[] = []; + const clock = { now: new Date(at) }; + const schedule: Schedule = (ms, fire) => { + const t = { ms, fire, cancelled: false }; + timers.push(t); + return () => { t.cancelled = true; }; + }; + const store: Store = { + get: async (k) => (kept.has(k) ? { value: kept.get(k)! } : null), + put: async (k, v) => { kept.set(k, v); return kept.size; }, + 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 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 () => { + const cases: { name: string; args: Record; keys: string[] }[] = [ + { name: "defaults", args: { port: 8000, why: "the operator's dev server" }, keys: ["allow.tcp.8000"] }, + { name: "two interfaces", args: { port: 5353, protocol: "udp", interfaces: ["enp6s0", "wlan0"], source: "192.168.1.0/24", why: "w" }, + keys: ["allow.udp.5353.enp6s0", "allow.udp.5353.wlan0"] }, + { name: "an interface with a dot", args: { port: 1, interfaces: ["enp6s0.10"], why: "w" }, keys: ["allow.tcp.1.enp6s0.10"] }, + ]; + for (const c of cases) { + const { a, kept, said } = fake(); + 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(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()) { + assert.equal(v.by, "lead@shanks", c.name); + assert.equal(v.at, "2026-11-21T20:00:00.000Z", c.name); + assert.equal(v.source, c.args.source, c.name); + if (!c.args.interfaces) assert.equal("interface" in v, false, "the private network's interface is never in the defaults"); + } + } +}); + +test("allow and disallow refuse what is not an allowance, writing nothing", async () => { + const bad: [string, Record, RegExp][] = [ + ["port 0", { port: 0, why: "w" }, /port: /], + ["port 65536", { port: 65536, why: "w" }, /port: /], + ["port 80a", { port: "80a", why: "w" }, /port: /], + ["protocol icmp", { port: 80, protocol: "icmp", why: "w" }, /protocol: /], + ["interface", { port: 80, interfaces: ["a b"], why: "w" }, /interfaces: /], + ["interface too long", { port: 80, interfaces: ["abcdefghijklmnop"], why: "w" }, /interfaces: /], + ["source", { port: 80, source: "10.0.0.0/33", why: "w" }, /source: /], + ["until in the past", { port: 80, until: "2026-11-21T19:00:00Z", why: "w" }, /until: .*not in the future/], + ["until not a time", { port: 80, until: "tomorrow", why: "w" }, /until: /], + ["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/], + ]; + for (const [name, args, want] of bad) { + const { a, kept, said } = fake(); + await assert.rejects(a.allow(args, "x"), want, name); + assert.equal(kept.size, 0, name); + assert.equal(said.length, 0, name); + } + const { a } = fake(); + 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 () => { + 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/); + assert.equal(kept.size, MOST); + await a.allow({ port: 1, why: "again" }, "x"); + assert.equal(kept.get("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"); + 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"]]); +}); + +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"]); + // 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); +}); + +test("a second allow of one key replaces it whole and answers what it replaced; the source is no part of the key", async () => { + const { a, kept } = fake(); + await a.allow({ port: 8000, source: "192.168.1.0/24", until: "2026-11-22T00:00:00Z", why: "first" }, "x"); + 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]]); +}); + +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); + clock.now = new Date("2026-11-21T21:00:00Z"); + timers[0].fire(); + await settle(); + assert.deepEqual([...kept.keys()], ["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"]); +}); + +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" }); + assert.equal(timers.at(-1)!.cancelled, true); + await a.watched({ key: "far", 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")); + // 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 settle(); + assert.ok(!kept.has("allow.tcp.9000")); +}); + +test("at a start every expired allowance is removed before started is said (H-A-312 (2))", async () => { + const { a, kept, said, clock } = fake(); + await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "w" }, "x"); + 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(said.slice(-2).map((b) => [b.change, b.allowances.map((x) => x.key)]), + [["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]); +}); + +test("a start says started with every allowance", async () => { + const { a, said } = fake(); + await a.allow({ port: 8000, why: "w" }, "x"); + await a.started(); + 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("the manifest serves the six verbs and requires the state the code keeps", () => { + 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"); +}); diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index 4f115383e..3b0dcf2ff 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -1,20 +1,41 @@ -// The packet filter's tools: the node-packet-filter seat's three verbs — what the machine enforces, -// reload the mesh's own, remove one thing the mesh did not write — and the module's own reading of -// the mesh's table (novox/hq ADR 0045, ADR 0168, ADR 0170). +// The packet filter's tools: the node-packet-filter seat's six verbs — what the machine enforces, reload the +// mesh's own, remove one thing the mesh did not write, and the operator's allowances (allow, disallow, allowed) — +// and the module's own reading of the mesh's table (novox/hq ADR 0045, ADR 0168, ADR 0170, ADR 0683; design 33 +// 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 { keeps, state } from "@novox/mesh-sdk/state"; import { FirewallClient } from "../client.js"; +import { Allowances, STATE, changedSubject, markLoaded, type Store, type Value } from "../allowances.js"; -export function getSeatVerbs(firewall: FirewallClient): ToolDefinition[] { +const port = { type: "integer", description: "the port, 1-65535" }; +const protocol = { type: "string", description: "tcp (the default) or udp" }; +const interfaces = { + type: "array", + items: { type: "string" }, + description: "the input interfaces, each 1-15 letters, digits, _ . - (optional; none: every input interface but the private network's)", +}; +const why = { type: "string", description: "why, in words the operator reads (1-500 characters)" }; + +export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): ToolDefinition[] { return [ { 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.", + "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 .", input: { table: { type: "string", description: "one nftables table, as `family name` (optional)" }, chain: { type: "string", description: "one chain of that table (optional)" }, }, - run: async (args) => firewall.rules(args.table ? String(args.table) : undefined, args.chain ? String(args.chain) : undefined), + run: async (args) => { + const table = args.table ? String(args.table) : undefined; + 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) }; + }, }, { name: "reload", @@ -30,6 +51,39 @@ export function getSeatVerbs(firewall: FirewallClient): ToolDefinition[] { input: { where: { type: "string", description: "the rule set, as `node show` lists it" } }, run: async (args) => firewall.remove(String(args.where ?? "")), }, + { + name: "allow", + 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.", + input: { + port, + protocol, + interfaces, + source: { type: "string", description: "one IPv4 or IPv6 CIDR it is opened to (optional; none: any)" }, + until: { type: "string", description: "when it expires, an RFC 3339 time in the future (optional)" }, + why, + }, + run: async (args) => allowances.allow(args, callerOf(args)), + }, + { + 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.", + 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. " + + "An allowance is removed at its until, so none answered has expired.", + input: {}, + run: async (args) => allowances.allowed(args), + }, ]; } @@ -45,7 +99,18 @@ 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. +const node = process.env.MESH_NODE ?? ""; +const kept = state(STATE); +const allowances = new Allowances(kept as Store, node, (body) => seatPublish(changedSubject(node), body)); +void (async () => { + await keeps([{ name: STATE }]); + await kept.watch((change) => allowances.watched(change)); + await allowances.started(); +})().catch((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)); +registerModuleTools("node-packet-filter", () => getSeatVerbs(firewall, allowances)); registerModuleTools("nftables", () => getFirewallTools(firewall)); -- 2.54.0 From 83482a4513d5b6bb9aa721169271cc5f82b5d81b Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 20:52:34 +0100 Subject: [PATCH 2/6] 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 +} -- 2.54.0 From 09d575834317243862d10535f735d1f99303b0cb Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 21:04:16 +0100 Subject: [PATCH 3/6] nftables: ask converged through the node-engine seat's generated package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The holder's ask of the node-engine's converged takes the seat's name, the verb's name and the answer's form from the node-engine seat's TypeScript package, as the holder says its own event through its seat's package. Builds: design 33 control-verbs §10, §12; design 47 H H-A-316, H-A-321 --- modules/nftables/allowances.ts | 10 +++------- modules/nftables/package.json | 3 ++- modules/nftables/tools/index.ts | 3 ++- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts index a8f40839a..f5d5269ed 100644 --- a/modules/nftables/allowances.ts +++ b/modules/nftables/allowances.ts @@ -8,6 +8,7 @@ // its own state, said and journalled, so no expired entry is kept or answered. import { isIP } from "node:net"; +import type { ConvergedAnswer } from "@novox/mesh-contracts-node-engine"; /** The state the allowances are kept in, as the seat's definition names it (§7). */ export const STATE = "allowances"; @@ -55,13 +56,8 @@ export interface Changed { at: string; } -/** 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; -} +/** The node's convergence state as the node-engine seat's converged answers it (§10, H-A-316, H-A-321). */ +export type Convergence = ConvergedAnswer; /** 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 { diff --git a/modules/nftables/package.json b/modules/nftables/package.json index 34139c83d..38cc540ba 100644 --- a/modules/nftables/package.json +++ b/modules/nftables/package.json @@ -10,7 +10,8 @@ }, "dependencies": { "@novox/mesh-sdk": "^0.1.1", - "@novox/mesh-connectivity-contracts-node-packet-filter": "^0.1.0" + "@novox/mesh-connectivity-contracts-node-packet-filter": "^0.1.0", + "@novox/mesh-contracts-node-engine": "^0.1.0" }, "devDependencies": { "@types/node": "^22.0.0", diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index 03b3ccdb0..5646e0017 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -8,6 +8,7 @@ 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 { seat as nodeEngine, verbs as nodeEngineVerbs } from "@novox/mesh-contracts-node-engine"; import { FirewallClient } from "../client.js"; import { Allowances, MOST, STATE, markLoaded, type Convergence, type Store, type Value } from "../allowances.js"; @@ -127,7 +128,7 @@ const store: Store = { }, }; const allowances = new Allowances(store, node, (body) => seatPublish(allowancesChangedSubject(node), body), { - converged: async () => (await broker().request(`seat:node-engine.converged@${node}`, {})), + converged: async () => (await broker().request(`seat:${nodeEngine}.${nodeEngineVerbs.converged}@${node}`, {})), handAct: async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }, most: async () => { const v = await config("allowances-max"); -- 2.54.0 From 38ea9ce25c966219068d80cc49e10a24cbb85ee1 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 21:19:03 +0100 Subject: [PATCH 4/6] nftables: allow names the outward link a kept allowance opens MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An allowance with no interface never opens an outward link; one named in interfaces does, and allow now says so: a kept allowance whose interface is in the outward links of the converged answer asked for the call answers with outward, that link. The holder reads no shape of the loaded table to tell an outward link from the tunnel; the event carries no outward. Builds: design 33 control-verbs §4, §14; design 47 H H-A-324, H-A-325 --- modules/nftables/allowances.ts | 24 ++++++++++++++++++------ modules/nftables/test/allowances.test.ts | 11 +++++++++++ 2 files changed, 29 insertions(+), 6 deletions(-) diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts index f5d5269ed..03be25278 100644 --- a/modules/nftables/allowances.ts +++ b/modules/nftables/allowances.ts @@ -56,7 +56,11 @@ export interface Changed { at: string; } -/** The node's convergence state as the node-engine seat's converged answers it (§10, H-A-316, H-A-321). */ +/** One allowance as allow kept it (§4): what it replaced, and the outward link it opens when its named interface is one + * of the outward links the node-engine's converged answered for the call (H-A-324, H-A-325). */ +export type Kept = Allowance & { outward?: string; replaced?: Allowance }; + +/** The node's convergence state as the node-engine seat's converged answers it (§10, H-A-316, H-A-321, H-A-325). */ export type Convergence = ConvergedAnswer; /** One act by hand, as the seat mesh-hand-acts' hand-act takes it (ADR 0565 §10): the SDK's views.HandAct. */ @@ -311,10 +315,14 @@ 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 }> { + async allow(args: Record, by: string): Promise<{ allowances: Kept[]; said: boolean }> { this.proven("allow", by); only(args, ["port", "protocol", "interfaces", "source", "until", "why"]); - this.refuseAdopted("allow", await this.askConverged("allow")); + const convergence = await this.askConverged("allow"); + this.refuseAdopted("allow", convergence); + // The outward links as the node-engine classifies them for its render, from the converged answer of this call; the + // loaded table's shape is never read to tell one from the tunnel (§4, H-A-325). + const outward = new Set(convergence.outward); const now = this.now(); const port = portOf(args.port); const protocol = protocolOf(args.protocol); @@ -334,7 +342,7 @@ export class Allowances { 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 })[] = []; + const out: Kept[] = []; for (const iface of interfaces) { const key = keyOf(protocol, port, iface); const value: Value = { @@ -346,9 +354,13 @@ export class Allowances { }; 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) } : {}) }); + out.push({ + ...answered(key, value), + ...(iface && outward.has(iface) ? { outward: iface } : {}), + ...(before ? { replaced: answered(key, before.value) } : {}), + }); } - await this.say({ node: this.node, change: "allowed", allowances: out.map(({ replaced: _, ...a }) => a), by, why, at }); + await this.say({ node: this.node, change: "allowed", allowances: out.map(({ replaced: _, outward: __, ...a }) => a), by, why, at }); return { allowances: out, said: true }; } diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts index 990f2926c..35dffcc18 100644 --- a/modules/nftables/test/allowances.test.ts +++ b/modules/nftables/test/allowances.test.ts @@ -79,6 +79,17 @@ test("allow keeps one key per interface, and with none the default set's key, wh } }); +test("allow naming an outward link answers it as outward, as converged lists them; another interface and the default set do not (H-A-325)", async () => { + const { a, asks, said } = fake(); + asks.convergence = { state: "converged", since: "2026-11-01T00:00:00Z", tunnel: "mesh0", outward: ["eth1"] }; + const named = await a.allow({ port: 8000, interfaces: ["eth1", "enp6s0"], why: "w" }, "lead@shanks"); + assert.deepEqual(named.allowances.map((x) => [x.key, x.outward]), [["allow.tcp.8000.eth1", "eth1"], ["allow.tcp.8000.enp6s0", undefined]]); + assert.equal("outward" in named.allowances[1], false, "an interface that is no outward link answers without the field"); + const none = await a.allow({ port: 8001, why: "w" }, "lead@shanks"); + assert.equal("outward" in none.allowances[0], false, "the default set opens no outward link"); + assert.equal(said.flatMap((b) => b.allowances).some((x) => "outward" in x), false, "the event's allowances carry no outward"); +}); + test("allow and disallow refuse what is not an allowance, writing nothing", async () => { const bad: [string, Record, RegExp][] = [ ["port 0", { port: 0, why: "w" }, /port: /], -- 2.54.0 From f589b5af5c0e736256feb437f8b253455e57143c Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 21:42:45 +0100 Subject: [PATCH 5/6] nftables: hold the verbs until the start ends; until with seconds; the seat's own forms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review round 1 (1)-(3): an until without seconds was accepted, which the node-engine's RFC 3339 read refuses, withholding every later compose; the verbs answered before started was said and before the watch's expiries ended; and the holder kept its own copies of the seat's names, key forms and value forms, which had drifted from H-A-324. The holder now takes them from the seat's generated package, the tools' inputs are checked against its input types, and every seat verb waits for the start's end. Builds: design 33 control-verbs §2, §3, §11, §12, §14; design 47 H H-A-324, H-A-330 --- modules/nftables/allowances.ts | 109 ++++++++++++----------- modules/nftables/test/allowances.test.ts | 23 ++++- modules/nftables/tools/index.ts | 53 ++++++----- 3 files changed, 108 insertions(+), 77 deletions(-) diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts index 03be25278..ce60ceb39 100644 --- a/modules/nftables/allowances.ts +++ b/modules/nftables/allowances.ts @@ -9,56 +9,29 @@ import { isIP } from "node:net"; import type { ConvergedAnswer } from "@novox/mesh-contracts-node-engine"; +import { + allowancesByNodeAllowProtocolPortInterfaceKey, allowancesByNodeAllowProtocolPortKey, + parseAllowancesByNodeAllowProtocolPortInterfaceKey, parseAllowancesByNodeAllowProtocolPortKey, states, + type Allowance, type AllowanceValue, type AllowancesChanged, type Kept, +} from "@novox/mesh-connectivity-contracts-node-packet-filter"; + +// The seat's names, key forms and value forms are its generated package's (design 33 control-verbs §2, §7, §12): this +// module writes no copy of them. +export type { Allowance, AllowanceValue, AllowancesChanged, Kept }; /** The state the allowances are kept in, as the seat's definition names it (§7). */ -export const STATE = "allowances"; +export const STATE = states.allowances; /** The most allowances one node keeps when the setting allowances-max says none (§3, H-A-314 (5)). */ export const MOST = 100; -/** How long the holder waits for the node-engine's converged (§10). */ +/** How long the holder waits for the node-engine's converged (§10; a value, H-A-330). */ 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"; - -/** One allowance as it is kept: the state's value (§7). */ -export interface Value { - port: number; - protocol: Protocol; - /** Absent: every input interface but the private network's. */ - interface?: string; - /** Absent: any source. */ - source?: string; - /** RFC 3339; absent: never expires. */ - until?: string; - why: string; - by: string; - at: string; -} - -/** One allowance as it is answered: its value with its key. */ -export interface Allowance extends Value { - key: string; -} - -export type Change = "allowed" | "disallowed" | "expired" | "started"; - -/** The event's body (§6). */ -export interface Changed { - node: string; - change: Change; - allowances: Allowance[]; - by?: string; - why?: string; - at: string; -} - -/** One allowance as allow kept it (§4): what it replaced, and the outward link it opens when its named interface is one - * of the outward links the node-engine's converged answered for the call (H-A-324, H-A-325). */ -export type Kept = Allowance & { outward?: string; replaced?: Allowance }; +type Protocol = AllowanceValue["protocol"]; /** The node's convergence state as the node-engine seat's converged answers it (§10, H-A-316, H-A-321, H-A-325). */ export type Convergence = ConvergedAnswer; @@ -82,8 +55,8 @@ export interface Asks { /** 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; + get(key: string): Promise<{ value: AllowanceValue } | null>; + put(key: string, value: AllowanceValue): Promise; delete(key: string): Promise; keys(): Promise; } @@ -92,11 +65,11 @@ export interface Store { export interface Watched { key: string; op: "put" | "delete"; - value?: Value; + value?: AllowanceValue; } /** Says the event. */ -export type Say = (body: Changed) => Promise; +export type Say = (body: AllowancesChanged) => Promise; /** Runs `fire` after `ms` milliseconds, answering how to cancel it: `setTimeout` on the machine, a fake in tests. */ export type Schedule = (ms: number, fire: () => void) => () => void; @@ -109,9 +82,17 @@ export const timers: Schedule = (ms, fire) => { return () => clearTimeout(t); }; -/** One key of the state: allow.., and . when it names one. */ +/** The state's key of an allowance on node, in the seat's key forms (§7, H-A-317): .allow.., and + * . when it names one. */ +function stateKeyOf(node: string, protocol: Protocol, port: number, iface?: string): string { + return iface + ? allowancesByNodeAllowProtocolPortInterfaceKey(node, protocol, String(port), iface) + : allowancesByNodeAllowProtocolPortKey(node, protocol, String(port)); +} + +/** An allowance's key in every answer, the event and the rule's comment: its state's key without the node (§7). */ export function keyOf(protocol: Protocol, port: number, iface?: string): string { - return iface ? `allow.${protocol}.${port}.${iface}` : `allow.${protocol}.${port}`; + return stateKeyOf("", protocol, port, iface).slice(1); } const IFACE = /^[A-Za-z0-9_.-]{1,15}$/; @@ -167,8 +148,10 @@ function untilOf(v: unknown, now: Date): string | undefined { if (v === undefined) return undefined; const s = typeof v === "string" ? v : ""; const t = Date.parse(s); - if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$/.test(s) || Number.isNaN(t)) { - refuse("until", `${JSON.stringify(v)} is not an RFC 3339 time, such as 2026-11-22T08:00:00Z`); + // A full RFC 3339 time, seconds included: the node-engine reads it with Go's time.RFC3339, which refuses a time + // without them, and would withhold every later compose of the filter (§2). + if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?(Z|[+-]\d\d:\d\d)$/.test(s) || Number.isNaN(t)) { + refuse("until", `${JSON.stringify(v)} is not an RFC 3339 time with seconds, such as 2026-11-22T08:00:00Z`); } if (t <= now.getTime()) refuse("until", `${s} is not in the future`); return s; @@ -179,7 +162,7 @@ function whyOf(v: unknown): string { return v; } -function answered(key: string, value: Value): Allowance { +function answered(key: string, value: AllowanceValue): Allowance { return { key, ...value }; } @@ -194,6 +177,8 @@ export class Allowances { private readonly asks: Asks; /** The last answer of converged; undefined while none answered. */ private convergence: Convergence | undefined; + /** The expiries running now (track). */ + private readonly expiring = new Set>(); constructor( store: Store, @@ -220,8 +205,8 @@ export class Allowances { /** 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; + const parts = parseAllowancesByNodeAllowProtocolPortInterfaceKey(stateKey) ?? parseAllowancesByNodeAllowProtocolPortKey(stateKey); + return parts?.node === this.node ? stateKey.slice(this.node.length + 1) : undefined; } /** Ask converged, bound 10 s, keeping its answer; refused, naming why, when it does not answer (§10). */ @@ -268,6 +253,8 @@ export class Allowances { } catch (err) { this.journal(`${err instanceof Error ? err.message : String(err)}; allowed asks it again`); } + // Every expiry the watch handed over ends before started is said (§11). + await Promise.all([...this.expiring]); const allowances = await this.kept(); await this.say({ node: this.node, change: "started", allowances: this.convergence?.state === "adopted" ? [] : allowances, at: this.now().toISOString() }); } @@ -285,17 +272,23 @@ export class Allowances { private arm(key: string, until: string): void { const left = Date.parse(until) - this.now().getTime(); if (left <= 0) { - void this.expire(key, until); + this.track(this.expire(key, until)); return; } const step = Math.min(left, LONGEST_WAIT_MS); this.pending.set(key, this.schedule(step, () => { this.pending.delete(key); if (step < left) this.arm(key, until); - else void this.expire(key, until); + else this.track(this.expire(key, until)); })); } + /** An expiry the watch or a timer started, kept until it ends so a start waits for it (§11). */ + private track(expiring: Promise): void { + this.expiring.add(expiring); + expiring.finally(() => this.expiring.delete(expiring)).catch(() => {}); + } + /** 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 { @@ -345,7 +338,7 @@ export class Allowances { const out: Kept[] = []; for (const iface of interfaces) { const key = keyOf(protocol, port, iface); - const value: Value = { + const value: AllowanceValue = { port, protocol, ...(iface ? { interface: iface } : {}), ...(source ? { source } : {}), @@ -423,6 +416,16 @@ export class Allowances { } } +/** A seat verb held until the holder's start ends (§8, §11): the watch has handed every key over, every expiry it + * started has ended and started is said, so no verb answers before started; a start that failed refuses it with + * the start's error. */ +export function held(start: Promise, run: (...args: A) => Promise): (...args: A) => Promise { + return async (...args) => { + await start; + return run(...args); + }; +} + /** 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): { diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts index 35dffcc18..db7d64803 100644 --- a/modules/nftables/test/allowances.test.ts +++ b/modules/nftables/test/allowances.test.ts @@ -4,8 +4,8 @@ import { test } from "node:test"; import assert from "node:assert/strict"; import { readFileSync } from "node:fs"; import { - Allowances, CONVERGED_BOUND_MS, LONGEST_WAIT_MS, MOST, STATE, markLoaded, privateOnly, - type Changed, type Convergence, type HandAct, type Schedule, type Store, type Value, + Allowances, CONVERGED_BOUND_MS, LONGEST_WAIT_MS, MOST, STATE, held, markLoaded, privateOnly, + type AllowanceValue as Value, type AllowancesChanged as Changed, type Convergence, type HandAct, type Schedule, type Store, } from "../allowances.ts"; interface Timer { ms: number; fire: () => void; cancelled: boolean } @@ -101,6 +101,7 @@ test("allow and disallow refuse what is not an allowance, writing nothing", asyn ["source", { port: 80, source: "10.0.0.0/33", why: "w" }, /source: /], ["until in the past", { port: 80, until: "2026-11-21T19:00:00Z", why: "w" }, /until: .*not in the future/], ["until not a time", { port: 80, until: "tomorrow", why: "w" }, /until: /], + ["until without seconds", { port: 80, until: "2026-11-22T08:00Z", why: "w" }, /until: .* with seconds/], ["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/], @@ -279,6 +280,24 @@ test("at a start every expired allowance is removed before started is said (H-A- [["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]); }); +test("started is said before the first allowed: the verbs are held until the start ends, a failed start refuses them", async () => { + const { a, asks, said, timers } = fake(); + asks.convergence = "silent"; + const start = a.started(); + let answered = false; + const first = held(start, () => a.allowed())().then((r) => { answered = true; return r; }); + await settle(); + assert.equal(answered, false, "allowed answered while the start still waits on converged"); + assert.equal(said.length, 0); + asks.convergence = { state: "converged", tunnel: "mesh0", outward: [] }; + timers.find((t) => t.ms === CONVERGED_BOUND_MS && !t.cancelled)!.fire(); + await first; + assert.deepEqual(said.map((b) => b.change), ["started"], "started was said before allowed answered"); + const failed = Promise.reject(new Error("the allowances did not start: no bus")); + failed.catch(() => {}); + await assert.rejects(held(failed, () => a.allowed())(), /did not start: no bus/); +}); + test("a start says started with every allowance", async () => { const { a, said } = fake(); await a.allow({ port: 8000, why: "w" }, "x"); diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index 5646e0017..eece4b2cd 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -7,24 +7,30 @@ import { callerOf } from "@novox/mesh-sdk/callers"; 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 { + allowancesChangedSubject, seat as packetFilter, verbs, + type AllowInput, type AllowedInput, type DisallowInput, +} from "@novox/mesh-connectivity-contracts-node-packet-filter"; import { seat as nodeEngine, verbs as nodeEngineVerbs } from "@novox/mesh-contracts-node-engine"; import { FirewallClient } from "../client.js"; -import { Allowances, MOST, STATE, markLoaded, type Convergence, type Store, type Value } from "../allowances.js"; +import { Allowances, MOST, STATE, held, markLoaded, type AllowanceValue, type Convergence, type Store } from "../allowances.js"; const port = { type: "integer", description: "the port, 1-65535" }; const protocol = { type: "string", description: "tcp (the default) or udp" }; const interfaces = { type: "array", items: { type: "string" }, - description: "the input interfaces, each 1-15 letters, digits, _ . - (optional; none: every input interface but the private network's)", + description: "the input interfaces, each 1-15 letters, digits, _ . - (optional; none: every input interface that is neither the private network's tunnel nor an outward link, so an outward link is opened only when named)", }; const why = { type: "string", description: "why, in words the operator reads (1-500 characters)" }; -export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): ToolDefinition[] { +// The seat's verbs, held until the holder's start ends (§8, §11): started is said before any answers. The inputs' types +// name exactly the arguments of the seat's generated inputs; the holder validates every value itself. +export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances, start: Promise = Promise.resolve()): ToolDefinition[] { + const allowed = held(start, () => allowances.allowed()); return [ { - name: "rules", + name: verbs.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 only when a rule of the mesh's table carries its comment allowance with an equal at, " + @@ -38,18 +44,18 @@ 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(); - const marked = markLoaded((await allowances.allowed()).allowances, mesh); + const marked = markLoaded((await allowed()).allowances, mesh); return { ...seen, allowances: marked.allowances, "loaded-not-kept": marked.loadedNotKept }; }, }, { - name: "reload", + name: verbs.reload, description: "Load the mesh's own filter again from the file the mesh writes, and answer with the mesh's table as loaded.", input: {}, run: async () => firewall.reload(), }, { - name: "remove", + name: verbs.remove, description: "Remove one rule set the mesh did not write, named exactly as `node show` lists it: `chain X (iptables-legacy)` or `table ip6 filter, chain DOCKER-USER`. " + "Refuses the mesh's tables, the runtime's own chains, a built-in chain and an active found firewall's chains. An operator's act, by name, never a flush.", @@ -57,7 +63,7 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): run: async (args) => firewall.remove(String(args.where ?? "")), }, { - name: "allow", + name: verbs.allow, 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. " + @@ -70,26 +76,26 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): protocol, interfaces, source: { type: "string", description: "one IPv4 or IPv6 CIDR it is opened to (optional; none: any)" }, - until: { type: "string", description: "when it expires, an RFC 3339 time in the future (optional)" }, + until: { type: "string", description: "when it expires, an RFC 3339 time with seconds in the future (optional)" }, why, - }, - run: async (args) => allowances.allow(args, callerOf(args)), + } satisfies Record, + run: held(start, async (args: Readonly>) => allowances.allow({ ...args }, callerOf(args))), }, { - name: "disallow", + name: verbs.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. 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)), + input: { port, protocol, interfaces, why } satisfies Record, + run: held(start, async (args: Readonly>) => allowances.disallow({ ...args }, callerOf(args))), }, { - name: "allowed", + name: verbs.allowed, description: "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), + input: {} satisfies Record, + run: held(start, async (args: Readonly>) => allowances.allowed({ ...args })), }, ]; } @@ -112,7 +118,7 @@ const firewall = FirewallClient.onThisMachine(); // 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 kept = state(STATE); 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 }; @@ -139,7 +145,7 @@ const allowances = new Allowances(store, node, (body) => seatPublish(allowancesC }, meshTable: () => firewall.ruleset(), }); -void (async () => { +const start = (async () => { await keeps([{ name: STATE }]); await kept.watch(async (change) => { if (change.op === "put") own.add(change.key); @@ -149,10 +155,13 @@ void (async () => { watched.done(); await allowances.started(); })().catch((err) => { - watched.failed(new Error(`the allowances did not start: ${err}`)); + const failed = new Error(`the allowances did not start: ${err}`); + watched.failed(failed); console.error(`[nftables] the allowances did not start (no expiry timers, no started said): ${err}`); + throw failed; }); +start.catch(() => {}); // 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)); +registerModuleTools(packetFilter, () => getSeatVerbs(firewall, allowances, start)); registerModuleTools("nftables", () => getFirewallTools(firewall)); -- 2.54.0 From 31abcad907c8513040c8656b0f4499da94b93688 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 22:05:47 +0100 Subject: [PATCH 6/6] nftables: test that a start waits for the watch's expiry; refuse a stale node-engine package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review round 2 (1): the start's wait for the expiries the watch handed over had no test that failed without it; the start test gains a store whose deletes wait, and without the wait the key is said expired twice. The note: a node-engine package naming no verb converged refuses the start loudly instead of asking seat:node-engine.undefined. Builds: design 33 control-verbs §10, §11, §14; design 47 H H-A-312 --- modules/nftables/test/allowances.test.ts | 25 +++++++++++++++++++++--- modules/nftables/tools/index.ts | 5 +++++ 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts index db7d64803..f905db821 100644 --- a/modules/nftables/test/allowances.test.ts +++ b/modules/nftables/test/allowances.test.ts @@ -15,7 +15,8 @@ const TABLE = 'table inet mesh {\n\tchain input {\n\t\ttype filter hook input pr '\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()) { +// gate, when given, holds every delete until it opens, and every get waits a turn of the event loop: a slow store. +function fake(at = "2026-11-21T20:00:00Z", node = "shanks", kept = new Map(), gate?: Promise) { const said: Changed[] = []; const journal: string[] = []; const timers: Timer[] = []; @@ -26,9 +27,12 @@ function fake(at = "2026-11-21T20:00:00Z", node = "shanks", kept = new Map { t.cancelled = true; }; }; const store: Store = { - get: async (k) => (kept.has(k) ? { value: kept.get(k)! } : null), + get: async (k) => { + if (gate) await new Promise((r) => setImmediate(r)); + return kept.has(k) ? { value: kept.get(k)! } : null; + }, put: async (k, v) => { kept.set(k, v); return kept.size; }, - delete: async (k) => { kept.delete(k); }, + delete: async (k) => { await gate; kept.delete(k); }, keys: async () => [...kept.keys()], }; const acts: HandAct[] = []; @@ -278,6 +282,21 @@ test("at a start every expired allowance is removed before started is said (H-A- 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"]]]); + + // §11, §14: a key past its until that the watch hands over while the start runs, through a store whose get and delete + // wait: the start waits for that expiry, so it is removed and said once, and started after it. + let open!: () => void; + const waits = new Promise((r) => { open = r; }); + const slow = fake("2026-11-21T22:00:00Z", "shanks", new Map(), waits); + const past: Value = { port: 7000, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00Z", until: "2026-11-21T21:00:00Z" }; + slow.kept.set(k("allow.tcp.7000"), past); + await slow.a.watched({ key: k("allow.tcp.7000"), op: "put", value: past }); + const start = slow.a.started(); + for (let i = 0; i < 10; i++) await settle(); // the start runs as far as it goes while the expiry's delete waits + open(); + await start; + assert.deepEqual(slow.said.map((b) => [b.change, b.allowances.map((x) => x.key)]), + [["expired", ["allow.tcp.7000"]], ["started", []]]); }); test("started is said before the first allowed: the verbs are held until the start ends, a failed start refuses them", async () => { diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index eece4b2cd..ba26ccb38 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -146,6 +146,11 @@ const allowances = new Allowances(store, node, (body) => seatPublish(allowancesC meshTable: () => firewall.ruleset(), }); const start = (async () => { + // A node-engine package older than the verb converged names none: refused here, loudly, never asked as + // seat:node-engine.undefined (H-A-312). + if (!nodeEngineVerbs.converged) { + throw new Error("the node-engine seat's package names no verb converged (a package older than design 33 control-verbs §10)"); + } await keeps([{ name: STATE }]); await kept.watch(async (change) => { if (change.op === "put") own.add(change.key); -- 2.54.0