diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts new file mode 100644 index 000000000..ce60ceb39 --- /dev/null +++ b/modules/nftables/allowances.ts @@ -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..[.]), kept one bucket per machine under its node's keys +// (.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; + handAct: (act: HandAct) => Promise; + most: () => Promise; + /** The mesh's table as loaded (`nft list table inet mesh`). */ + meshTable: () => Promise; +} + +/** 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; + delete(key: string): Promise; + keys(): Promise; +} + +/** 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; + +/** 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): .allow.., and + * . 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, 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 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>(); + + 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 { + let stop: () => void = () => {}; + const late = new Promise((_, 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 { + 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 { + 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 { + 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): 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 { + 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, 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, 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 { + 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 = {}): 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 { + 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(start: Promise, run: (...args: A) => Promise): (...args: A) => Promise { + 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 ` 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(); + 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; +} diff --git a/modules/nftables/module.json b/modules/nftables/module.json index 6c6634d86..68964f4fa 100644 --- a/modules/nftables/module.json +++ b/modules/nftables/module.json @@ -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": [ { diff --git a/modules/nftables/package.json b/modules/nftables/package.json index 6342c07b6..38cc540ba 100644 --- a/modules/nftables/package.json +++ b/modules/nftables/package.json @@ -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", diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts new file mode 100644 index 000000000..f905db821 --- /dev/null +++ b/modules/nftables/test/allowances.test.ts @@ -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(), gate?: Promise) { + 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(() => {}) : 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; 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, 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(); + 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((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); +}); diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index 4f115383e..ba26ccb38 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -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 = 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 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, + run: held(start, async (args: Readonly>) => 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, + run: held(start, async (args: Readonly>) => 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, + run: held(start, async (args: Readonly>) => 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(STATE); +const own = new Set(); +// 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((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(`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)); diff --git a/modules/nftables/tsconfig.json b/modules/nftables/tsconfig.json index 91d5b91c5..1829ad694 100644 --- a/modules/nftables/tsconfig.json +++ b/modules/nftables/tsconfig.json @@ -10,6 +10,7 @@ }, "include": [ "client.ts", + "allowances.ts", "tools/index.ts" ] -} \ No newline at end of file +}