Compare commits

..
Author SHA1 Message Date
mesh-tools 32e1ed6c55 Merge pull request 'The Node build module's integration tests supply the SDK the skipped fetch would place (design 47 G §571)' (#732) from fix/47-H1-build-node-tests-under-load into main 2026-11-21 21:44:31 +00:00
mesh-tools d7b23f50b4 Merge pull request 'Packet filter control verbs: the nftables holder serves the verbs, keeps allowances in its state and arms expiries (ADR 0683)' (#731) from feat/packet-filter-allow into main 2026-11-21 21:36:38 +00:00
jschoubben 6527ebd077 mesh-build-node: the real-toolchain tests' fixture holds the SDK where the fetch places it
Since the toolchain lock pins no SDK (design 47 G §571), only the fetch puts
@novox/mesh-sdk in a module's node_modules. The three tests that build with
the real tsc and esbuild skip the fetch, so they read the SDK from an older
installed toolchain that still carried one. Once a build node installed the
current lock (shanks 19:26, then g14), they failed with TS2307 (main.137,
main.155). The fixture now lays a minimal SDK of its own where the fetch
would, so the tests no longer depend on which toolchains a node still keeps.

Builds: design 47 G §571
2026-11-21 22:25:38 +01:00
jschoubben 31abcad907 nftables: test that a start waits for the watch's expiry; refuse a stale node-engine package
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
2026-11-21 22:05:47 +01:00
jschoubben f589b5af5c 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
2026-11-21 21:42:45 +01:00
jschoubben 38ea9ce25c nftables: allow names the outward link a kept allowance opens
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
2026-11-21 21:19:03 +01:00
jschoubben 09d5758343 nftables: ask converged through the node-engine seat's generated package
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
2026-11-21 21:04:16 +01:00
jschoubben 83482a4513 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
2026-11-21 20:52:34 +01:00
jschoubben 7bd1e74086 nftables: serve allow, disallow and allowed, keeping allowances as its own state
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)
2026-11-21 20:40:35 +01:00
7 changed files with 992 additions and 17 deletions
@@ -58,17 +58,33 @@ func realMachine(t *testing.T) (*Module, string) {
t.Fatalf("the toolchain copied from %s cannot be used: %v", from, err)
}
for _, id := range []string{"w1", "w2", "w3"} {
for p, body := range map[string]string{
files := map[string]string{
"modules/m/module.json": `{"module":"m","build":{"artifacts":[{"name":"tools","kind":"bundle","language":"typescript","entrypoints":["tools/index.js"]}]}}`,
"modules/m/package.json": `{"name":"m","type":"module","scripts":{"test":"node -e \"process.exit(0)\""}}`,
"modules/m/tools/index.ts": "import { serveRegisteredOverStdio } from \"@novox/mesh-sdk/stdio\";\nexport const f: () => Promise<void> = serveRegisteredOverStdio as () => Promise<void>;\n",
} {
}
for p, body := range fetchedSDK {
files["modules/m/node_modules/@novox/mesh-sdk/"+p] = body
}
for p, body := range files {
write(t, filepath.Join(work, id, "tree", filepath.FromSlash(p)), body, 0o644)
}
}
return m, work
}
// fetchedSDK is the SDK the fixture's workspaces hold where the fetch step places it, in the module's node_modules
// (fetch.go, placeSDK: the latest published release, ADR 0573 §2; design 47 G §571), made here because the integration
// level has no registry to fetch it from. The toolchain's lock names no SDK since §571, so a fixture that leaves it out
// reads one only from a toolchain installed before (main.137 and main.155: TS2307 once a build node installed the
// lock). It holds the one export the fixture and the launchers import.
var fetchedSDK = map[string]string{
"package.json": `{"name":"@novox/mesh-sdk","version":"9.9.9","type":"module",` +
`"exports":{"./stdio":{"types":"./dist/stdio.d.ts","default":"./dist/stdio.js"}}}`,
"dist/stdio.js": "export async function serveRegisteredOverStdio() {}\n",
"dist/stdio.d.ts": "export declare function serveRegisteredOverStdio(): Promise<void>;\n",
}
// 1490/AC2, 1491 and issue 1869, in one test so the toolchain is copied once: the real type-check and test script of the
// fixture pass the unit level; a package whose test imports its own build output (as mesh-sdk's do) passes the unit level,
// the test step emitting it with the real tsc, shut off, before the test script runs; and the fixture TypeScript bundle
+464
View File
@@ -0,0 +1,464 @@
// 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>]), 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
// 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";
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 = 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; 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";
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;
/** 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: AllowanceValue } | null>;
put(key: string, value: AllowanceValue): Promise<number>;
delete(key: string): Promise<void>;
keys(): Promise<string[]>;
}
/** One change of the state as its watch hands it over: the SDK's `StateChange`. */
export interface Watched {
key: string;
op: "put" | "delete";
value?: AllowanceValue;
}
/** Says the event. */
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;
/** 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);
};
/** 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 stateKeyOf("", protocol, port, iface).slice(1);
}
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<string, unknown>, 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);
// 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;
}
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: AllowanceValue): Allowance {
return { key, ...value };
}
export class Allowances {
private readonly pending = new Map<string, () => 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;
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,
node: string,
say: Say,
asks: Asks,
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.asks = asks;
this.now = now;
this.schedule = schedule;
this.journal = journal;
}
/** 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 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). */
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> {
try {
await this.askConverged("start");
} 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() });
}
/** 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> {
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(key, change.value.until);
}
private arm(key: string, until: string): void {
const left = Date.parse(until) - this.now().getTime();
if (left <= 0) {
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 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 {
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(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}` : ""}, ` +
`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<string, unknown>, by: string): Promise<{ allowances: Kept[]; said: boolean }> {
this.proven("allow", by);
only(args, ["port", "protocol", "interfaces", "source", "until", "why"]);
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);
const interfaces = interfacesOf(args.interfaces);
const source = sourceOf(args.source);
const until = untilOf(args.until, now);
const why = whyOf(args.why);
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 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: Kept[] = [];
for (const iface of interfaces) {
const key = keyOf(protocol, port, iface);
const value: AllowanceValue = {
port, protocol,
...(iface ? { interface: iface } : {}),
...(source ? { source } : {}),
...(until ? { until } : {}),
why, by, at,
};
const before = await this.store.get(this.stored(key));
await this.store.put(this.stored(key), 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: _, outward: __, ...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<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);
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(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));
}
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 };
}
/** 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.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);
continue;
}
allowances.push(answered(key, entry.value));
}
return 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): {
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;
}
+27 -1
View File
@@ -15,10 +15,28 @@
"serves": [
"rules",
"reload",
"remove"
"remove",
"allow",
"disallow",
"allowed"
]
}
],
"requires": [
{
"name": "allowances",
"storage": "key-value",
"template": "state",
"options": {
"history": 1,
"per-machine": true
}
}
],
"invokes": [
"seat:node-engine.converged",
"seat:mesh-hand-acts.hand-act"
],
"filtering": {
"into": "/etc/nftables.conf"
},
@@ -71,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": [
{
+5 -3
View File
@@ -1,15 +1,17 @@
{
"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": {
"@novox/mesh-sdk": "^0.1.1"
"@novox/mesh-sdk": "^0.1.1",
"@novox/mesh-connectivity-contracts-node-packet-filter": "^0.1.0",
"@novox/mesh-contracts-node-engine": "^0.1.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
+345
View File
@@ -0,0 +1,345 @@
// 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, 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 }
// 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';
// 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<string, Value>(), gate?: Promise<void>) {
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) => {
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) => { await gate; kept.delete(k); },
keys: async () => [...kept.keys()],
};
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 () => {
const cases: { name: string; args: Record<string, unknown>; 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.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()) {
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 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<string, unknown>, 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: /],
["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/],
["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, 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, 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 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 allowances-max 100/);
assert.equal(kept.size, MOST);
await a.allow({ port: 1, why: "again" }, "x");
assert.equal(kept.get(k("allow.tcp.1"))!.why, "again");
});
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()], [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);
});
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(([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: 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");
live[0].fire();
await settle();
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"]);
});
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("allow.tcp.1"), op: "put", value: v });
await a.watched({ key: k("allow.tcp.1"), op: "delete" });
assert.equal(timers.at(-1)!.cancelled, true);
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(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: k("allow.tcp.9000"), op: "put", value: kept.get(k("allow.tcp.9000"))! });
await settle();
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 () => {
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()], [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<void>((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 () => {
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");
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 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, 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", 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);
});
+131 -10
View File
@@ -1,35 +1,102 @@
// 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 { broker } from "@novox/mesh-sdk/messaging";
import { config, seatPublish } from "@novox/mesh-sdk/runtime";
import { keeps, state } from "@novox/mesh-sdk/state";
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, held, markLoaded, type AllowanceValue, type Convergence, type Store } 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 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)" };
// 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.",
"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, " +
"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)" },
},
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();
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.",
input: { where: { type: "string", description: "the rule set, as `node show` lists it" } },
run: async (args) => firewall.remove(String(args.where ?? "")),
},
{
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. " +
"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,
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 with seconds in the future (optional)" },
why,
} satisfies Record<keyof AllowInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => allowances.allow({ ...args }, callerOf(args))),
},
{
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 } satisfies Record<keyof DisallowInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => allowances.disallow({ ...args }, callerOf(args))),
},
{
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: {} satisfies Record<keyof AllowedInput, object>,
run: held(start, async (args: Readonly<Record<string, unknown>>) => allowances.allowed({ ...args })),
},
];
}
@@ -45,7 +112,61 @@ export function getFirewallTools(firewall: FirewallClient): ToolDefinition[] {
}
const firewall = FirewallClient.onThisMachine();
// 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<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 };
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:${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");
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(),
});
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);
else own.delete(change.key);
await allowances.watched(change);
}, { key: `${node}.**` });
watched.done();
await allowances.started();
})().catch((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));
registerModuleTools(packetFilter, () => getSeatVerbs(firewall, allowances, start));
registerModuleTools("nftables", () => getFirewallTools(firewall));
+2 -1
View File
@@ -10,6 +10,7 @@
},
"include": [
"client.ts",
"allowances.ts",
"tools/index.ts"
]
}
}