nftables: hold the verbs until the start ends; until with seconds; the seat's own forms

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
This commit is contained in:
2026-11-21 21:42:45 +01:00
parent 38ea9ce25c
commit f589b5af5c
3 changed files with 108 additions and 77 deletions
+56 -53
View File
@@ -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<number>;
get(key: string): Promise<{ value: AllowanceValue } | null>;
put(key: string, value: AllowanceValue): Promise<number>;
delete(key: string): Promise<void>;
keys(): Promise<string[]>;
}
@@ -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<void>;
export type Say = (body: AllowancesChanged) => Promise<void>;
/** 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.<protocol>.<port>, and .<interface> when it names one. */
/** The state's key of an allowance on node, in the seat's key forms (§7, H-A-317): <node>.allow.<protocol>.<port>, and
* .<interface> 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<Promise<boolean>>();
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<boolean>): 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<boolean> {
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<A extends unknown[], R>(start: Promise<unknown>, run: (...args: A) => Promise<R>): (...args: A) => Promise<R> {
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 <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): {
+21 -2
View File
@@ -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");
+31 -22
View File
@@ -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<unknown> = 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 <key> <at> 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<keyof AllowInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<keyof DisallowInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<keyof AllowedInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<Value>(STATE);
const kept = state<AllowanceValue>(STATE);
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 };
@@ -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));