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)
117 lines
6.3 KiB
TypeScript
117 lines
6.3 KiB
TypeScript
// 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 { seatPublish } from "@novox/mesh-sdk/runtime";
|
|
import { keeps, state } from "@novox/mesh-sdk/state";
|
|
import { FirewallClient } from "../client.js";
|
|
import { Allowances, STATE, changedSubject, markLoaded, type Store, type Value } from "../allowances.js";
|
|
|
|
const port = { type: "integer", description: "the port, 1-65535" };
|
|
const protocol = { type: "string", description: "tcp (the default) or udp" };
|
|
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)",
|
|
};
|
|
const why = { type: "string", description: "why, in words the operator reads (1-500 characters)" };
|
|
|
|
export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): ToolDefinition[] {
|
|
return [
|
|
{
|
|
name: "rules",
|
|
description:
|
|
"The packet filter as this machine enforces it now: the nftables ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or chain when asked. " +
|
|
"Beside it every allowance, marked loaded when a rule of the mesh's table carries its comment allowance <key>.",
|
|
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) => {
|
|
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();
|
|
return { ...seen, allowances: markLoaded((await allowances.allowed()).allowances, mesh) };
|
|
},
|
|
},
|
|
{
|
|
name: "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",
|
|
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: "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. " +
|
|
"A key that exists is replaced whole and answered. Refuses, naming the argument and writing nothing, a bad port, protocol, interface, source or until, " +
|
|
"an empty or longer why, an unknown argument, and more than 100 allowances on the node. Whether the loaded chain carries it is read with rules.",
|
|
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 in the future (optional)" },
|
|
why,
|
|
},
|
|
run: async (args) => allowances.allow(args, callerOf(args)),
|
|
},
|
|
{
|
|
name: "disallow",
|
|
description:
|
|
"Take back allowances: the keys the protocol, port and interfaces name (none: the default set's key) are deleted, or, when one does not exist, " +
|
|
"it is refused by name and none is deleted.",
|
|
input: { port, protocol, interfaces, why },
|
|
run: async (args) => allowances.disallow(args, callerOf(args)),
|
|
},
|
|
{
|
|
name: "allowed",
|
|
description:
|
|
"Every allowance kept on this machine, with its key, port, protocol, interface, source, until, why, by and at. " +
|
|
"An allowance is removed at its until, so none answered has expired.",
|
|
input: {},
|
|
run: async (args) => allowances.allowed(args),
|
|
},
|
|
];
|
|
}
|
|
|
|
export function getFirewallTools(firewall: FirewallClient): ToolDefinition[] {
|
|
return [
|
|
{
|
|
name: "firewall_rules",
|
|
description: "The mesh's live nftables table on this node — what the mesh's own filter is accepting and dropping.",
|
|
input: {},
|
|
run: async () => ({ ruleset: await firewall.ruleset() }),
|
|
},
|
|
];
|
|
}
|
|
|
|
const firewall = FirewallClient.onThisMachine();
|
|
// The allowances are this module's own state, announced as kept (ADR 0495), every change said as the seat's event
|
|
// allowances-changed of this node; watching its own state gives every key with an until its timer, at every start
|
|
// too; and a start says started, so a node-engine that refused a compose for want of an answer composes again.
|
|
const node = process.env.MESH_NODE ?? "";
|
|
const kept = state<Value>(STATE);
|
|
const allowances = new Allowances(kept as Store, node, (body) => seatPublish(changedSubject(node), body));
|
|
void (async () => {
|
|
await keeps([{ name: STATE }]);
|
|
await kept.watch((change) => allowances.watched(change));
|
|
await allowances.started();
|
|
})().catch((err) => console.error(`[nftables] the allowances did not start (no expiry timers, no started said): ${err}`));
|
|
// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
|
|
// module holds it (ADR 0159, 0160). The module's own under its own.
|
|
registerModuleTools("node-packet-filter", () => getSeatVerbs(firewall, allowances));
|
|
registerModuleTools("nftables", () => getFirewallTools(firewall));
|