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
308 lines
18 KiB
TypeScript
308 lines
18 KiB
TypeScript
// 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, 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 }
|
|
|
|
// 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[] = [];
|
|
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 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: /],
|
|
["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"]]]);
|
|
});
|
|
|
|
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);
|
|
});
|