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)
192 lines
11 KiB
TypeScript
192 lines
11 KiB
TypeScript
// The operator's allowances against a state in memory (ADR 0683; design 33 control-verbs §9).
|
|
import { test } from "node:test";
|
|
import assert from "node:assert/strict";
|
|
import { readFileSync } from "node:fs";
|
|
import {
|
|
Allowances, LONGEST_WAIT_MS, MOST, STATE, changedSubject, markLoaded,
|
|
type Changed, type Schedule, type Store, type Value,
|
|
} from "../allowances.ts";
|
|
|
|
interface Timer { ms: number; fire: () => void; cancelled: boolean }
|
|
|
|
function fake(at = "2026-11-21T20:00:00Z") {
|
|
const kept = new Map<string, Value>();
|
|
const said: Changed[] = [];
|
|
const journal: string[] = [];
|
|
const timers: Timer[] = [];
|
|
const clock = { now: new Date(at) };
|
|
const schedule: Schedule = (ms, fire) => {
|
|
const t = { ms, fire, cancelled: false };
|
|
timers.push(t);
|
|
return () => { t.cancelled = true; };
|
|
};
|
|
const store: Store = {
|
|
get: async (k) => (kept.has(k) ? { value: kept.get(k)! } : null),
|
|
put: async (k, v) => { kept.set(k, v); return kept.size; },
|
|
delete: async (k) => { kept.delete(k); },
|
|
keys: async () => [...kept.keys()],
|
|
};
|
|
const a = new Allowances(store, "shanks", async (b) => { said.push(b); }, () => clock.now, schedule, (l) => journal.push(l));
|
|
return { a, kept, said, clock, timers, journal };
|
|
}
|
|
|
|
const settle = () => new Promise((r) => setImmediate(r));
|
|
|
|
test("allow keeps one key per interface, and with none the default set's key, which names no interface", async () => {
|
|
const cases: { name: string; args: Record<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, c.name);
|
|
assert.deepEqual(said.map((b) => [b.change, b.node, b.by, b.why, b.allowances.map((x) => x.key)]),
|
|
[["allowed", "shanks", "lead@shanks", c.args.why, c.keys]], c.name);
|
|
for (const v of kept.values()) {
|
|
assert.equal(v.by, "lead@shanks", c.name);
|
|
assert.equal(v.at, "2026-11-21T20:00:00.000Z", c.name);
|
|
assert.equal(v.source, c.args.source, c.name);
|
|
if (!c.args.interfaces) assert.equal("interface" in v, false, "the private network's interface is never in the defaults");
|
|
}
|
|
}
|
|
});
|
|
|
|
test("allow and disallow refuse what is not an allowance, writing nothing", async () => {
|
|
const bad: [string, Record<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: /],
|
|
["empty why", { port: 80, why: "" }, /why: /],
|
|
["long why", { port: 80, why: "x".repeat(501) }, /why: /],
|
|
["unknown argument", { port: 80, why: "w", comment: "x" }, /comment: not an argument/],
|
|
];
|
|
for (const [name, args, want] of bad) {
|
|
const { a, kept, said } = fake();
|
|
await assert.rejects(a.allow(args, "x"), want, name);
|
|
assert.equal(kept.size, 0, name);
|
|
assert.equal(said.length, 0, name);
|
|
}
|
|
const { a } = fake();
|
|
await assert.rejects(a.disallow({ port: 80, why: "w", source: "10.0.0.1" }, "x"), /source: not an argument/);
|
|
await assert.rejects(a.disallow({ port: 80 }, "x"), /why: /);
|
|
await assert.rejects(a.allowed({ port: 80 }), /port: not an argument/);
|
|
});
|
|
|
|
test("a 101st allowance is refused; a replacement at the bound is not", async () => {
|
|
const { a, kept } = fake();
|
|
for (let p = 1; p <= MOST; p++) await a.allow({ port: p, why: "w" }, "x");
|
|
await assert.rejects(a.allow({ port: 1000, why: "w" }, "x"), /101 allowances would be kept on this node, more than 100/);
|
|
assert.equal(kept.size, MOST);
|
|
await a.allow({ port: 1, why: "again" }, "x");
|
|
assert.equal(kept.get("allow.tcp.1")!.why, "again");
|
|
});
|
|
|
|
test("allow then disallow writes the key, then deletes it, saying allowed and disallowed", async () => {
|
|
const { a, kept, said } = fake();
|
|
await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "open" }, "x");
|
|
assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]);
|
|
const gone = await a.disallow({ port: 8000, interfaces: ["enp6s0"], why: "done" }, "y");
|
|
assert.deepEqual(gone.allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]);
|
|
assert.equal(gone.said, true);
|
|
assert.equal(kept.size, 0);
|
|
assert.deepEqual(said.map((b) => [b.change, b.by, b.why]), [["allowed", "x", "open"], ["disallowed", "y", "done"]]);
|
|
});
|
|
|
|
test("disallow is all or nothing: a key not kept is refused by name and none is deleted", async () => {
|
|
const { a, kept, said } = fake();
|
|
await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "w" }, "x");
|
|
await assert.rejects(a.disallow({ port: 8000, interfaces: ["enp6s0", "wlan0"], why: "w" }, "x"), /no allowance allow\.tcp\.8000\.wlan0/);
|
|
assert.deepEqual([...kept.keys()], ["allow.tcp.8000.enp6s0"]);
|
|
// no interfaces names the default set's key, never one of an interface
|
|
await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /);
|
|
assert.equal(said.length, 1);
|
|
});
|
|
|
|
test("a second allow of one key replaces it whole and answers what it replaced; the source is no part of the key", async () => {
|
|
const { a, kept } = fake();
|
|
await a.allow({ port: 8000, source: "192.168.1.0/24", until: "2026-11-22T00:00:00Z", why: "first" }, "x");
|
|
const got = await a.allow({ port: 8000, source: "10.0.0.5", why: "second" }, "y");
|
|
assert.deepEqual(got.allowances.map((x) => [x.key, x.source, x.replaced?.source, x.replaced?.why]),
|
|
[["allow.tcp.8000", "10.0.0.5", "192.168.1.0/24", "first"]]);
|
|
assert.deepEqual([...kept.entries()].map(([k, v]) => [k, v.source, v.by, v.until]), [["allow.tcp.8000", "10.0.0.5", "y", undefined]]);
|
|
});
|
|
|
|
test("at its until an allowance is deleted by its timer, says expired, is journalled, and allowed answers without it", async () => {
|
|
const { a, kept, said, clock, timers, journal } = fake();
|
|
await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "for an hour" }, "x");
|
|
await a.allow({ port: 9000, why: "w" }, "x");
|
|
await a.watched({ key: "allow.tcp.8000", op: "put", value: kept.get("allow.tcp.8000")! });
|
|
assert.equal(timers.length, 1);
|
|
assert.equal(timers[0].ms, 3600_000);
|
|
clock.now = new Date("2026-11-21T21:00:00Z");
|
|
timers[0].fire();
|
|
await settle();
|
|
assert.deepEqual([...kept.keys()], ["allow.tcp.9000"]);
|
|
assert.deepEqual([said.at(-1)!.change, said.at(-1)!.allowances.map((x) => x.key)], ["expired", ["allow.tcp.8000"]]);
|
|
assert.match(journal.join("\n"), /the allowance allow\.tcp\.8000 .*for an hour\) expired at 2026-11-21T21:00:00Z and is removed/);
|
|
assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.9000"]);
|
|
});
|
|
|
|
test("the expiry timers follow the state: a delete cancels, a far until waits in steps, a stale timer removes nothing", async () => {
|
|
const { a, kept, clock, timers } = fake();
|
|
const v: Value = { port: 1, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00Z", until: "2026-11-21T22:00:00Z" };
|
|
await a.watched({ key: "k", op: "put", value: v });
|
|
await a.watched({ key: "k", op: "delete" });
|
|
assert.equal(timers.at(-1)!.cancelled, true);
|
|
await a.watched({ key: "far", op: "put", value: { ...v, until: "2027-06-01T00:00:00Z" } });
|
|
assert.equal(timers.at(-1)!.ms, LONGEST_WAIT_MS);
|
|
await a.allow({ port: 9000, until: "2026-11-21T21:30:00Z", why: "w" }, "x");
|
|
await a.allow({ port: 9000, until: "2026-11-21T23:00:00Z", why: "w" }, "x");
|
|
clock.now = new Date("2026-11-21T21:30:00Z");
|
|
assert.equal(await a.expire("allow.tcp.9000", "2026-11-21T21:30:00Z"), false);
|
|
assert.ok(kept.has("allow.tcp.9000"));
|
|
// at a start, a key already past its until is removed at once
|
|
clock.now = new Date("2026-11-22T00:00:00Z");
|
|
await a.watched({ key: "allow.tcp.9000", op: "put", value: kept.get("allow.tcp.9000")! });
|
|
await settle();
|
|
assert.ok(!kept.has("allow.tcp.9000"));
|
|
});
|
|
|
|
test("at a start every expired allowance is removed before started is said (H-A-312 (2))", async () => {
|
|
const { a, kept, said, clock } = fake();
|
|
await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "w" }, "x");
|
|
await a.allow({ port: 9000, why: "w" }, "x");
|
|
clock.now = new Date("2026-11-21T22:00:00Z");
|
|
await a.started();
|
|
assert.deepEqual([...kept.keys()], ["allow.tcp.9000"]);
|
|
assert.deepEqual(said.slice(-2).map((b) => [b.change, b.allowances.map((x) => x.key)]),
|
|
[["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]);
|
|
});
|
|
|
|
test("a start says started with every allowance", async () => {
|
|
const { a, said } = fake();
|
|
await a.allow({ port: 8000, why: "w" }, "x");
|
|
await a.started();
|
|
assert.deepEqual([said.at(-1)!.change, said.at(-1)!.node, said.at(-1)!.allowances.map((x) => x.key)], ["started", "shanks", ["allow.tcp.8000"]]);
|
|
});
|
|
|
|
test("rules marks an allowance loaded only when a rule of the mesh's table carries its comment", () => {
|
|
const table = 'table inet mesh {\n\tchain input {\n\t\tiifname != "mesh0" tcp dport 8000 accept comment "allowance allow.tcp.8000"\n\t}\n}\n';
|
|
const base: Value = { port: 8000, protocol: "tcp", why: "w", by: "x", at: "t" };
|
|
const got = markLoaded([{ key: "allow.tcp.8000", ...base }, { key: "allow.tcp.9000", ...base, port: 9000 }], table);
|
|
assert.deepEqual(got.map((x) => [x.key, x.loaded]), [["allow.tcp.8000", true], ["allow.tcp.9000", false]]);
|
|
});
|
|
|
|
test("the manifest serves the six verbs and requires the state the code keeps", () => {
|
|
const m = JSON.parse(readFileSync(new URL("../module.json", import.meta.url), "utf8"));
|
|
assert.deepEqual(m.claims[0].serves, ["rules", "reload", "remove", "allow", "disallow", "allowed"]);
|
|
assert.deepEqual(m.requires, [{ name: STATE, storage: "key-value", template: "state" }]);
|
|
assert.equal(changedSubject("shanks"), "mesh.seat.node-packet-filter.event.allowances-changed.shanks");
|
|
});
|