nftables: allowances per machine, refused unproven or adopted, written in the hand-act log

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
This commit is contained in:
2026-11-21 20:52:34 +01:00
parent 7bd1e74086
commit 83482a4513
6 changed files with 397 additions and 86 deletions
+178 -31
View File
@@ -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.<protocol>.<port>[.<interface>]); the node-engine asks `allowed` at every compose of a
// port and interface (allow.<protocol>.<port>[.<interface>]), kept one bucket per machine under its node's keys
// (<node>.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.<node> (§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<Convergence>;
handAct: (act: HandAct) => Promise<void>;
most: () => Promise<number>;
/** The mesh's table as loaded (`nft list table inet mesh`). */
meshTable: () => Promise<string>;
}
/** 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<number>;
@@ -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<Convergence> {
let stop: () => void = () => {};
const late = new Promise<never>((_, 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<string[]> {
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<void> {
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<void> {
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<boolean> {
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<string, unknown>, 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<string, unknown>, 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<void> {
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<string, unknown> = {}): 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<Allowance[]> {
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 <key>` (§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 <key> <at>` 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<string>();
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;
}
+17 -1
View File
@@ -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": [
{
+2 -1
View File
@@ -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",
+143 -38
View File
@@ -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<string, Value>();
// 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<string, Value>()) {
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<Convergence>(() => {}) : 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<string, Value>();
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);
});
+55 -14
View File
@@ -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 <key>.",
"Beside it every allowance, marked loaded only when a rule of the mesh's table carries its comment allowance <key> <at> 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<Value>(STATE);
const allowances = new Allowances(kept as Store, node, (body) => seatPublish(changedSubject(node), body));
const own = new Set<string>();
// 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<void>((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<object, Convergence>(`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));
+2 -1
View File
@@ -10,6 +10,7 @@
},
"include": [
"client.ts",
"allowances.ts",
"tools/index.ts"
]
}
}