diff --git a/modules/nftables/allowances.ts b/modules/nftables/allowances.ts index 03be25278..ce60ceb39 100644 --- a/modules/nftables/allowances.ts +++ b/modules/nftables/allowances.ts @@ -9,56 +9,29 @@ 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 = "allowances"; +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). */ +/** 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"; -export type Protocol = "tcp" | "udp"; - -/** One allowance as it is kept: the state's value (§7). */ -export interface Value { - port: number; - protocol: Protocol; - /** Absent: every input interface but the private network's. */ - interface?: string; - /** Absent: any source. */ - source?: string; - /** RFC 3339; absent: never expires. */ - until?: string; - why: string; - by: string; - at: string; -} - -/** One allowance as it is answered: its value with its key. */ -export interface Allowance extends Value { - key: string; -} - -export type Change = "allowed" | "disallowed" | "expired" | "started"; - -/** The event's body (§6). */ -export interface Changed { - node: string; - change: Change; - allowances: Allowance[]; - by?: string; - why?: string; - at: string; -} - -/** One allowance as allow kept it (§4): what it replaced, and the outward link it opens when its named interface is one - * of the outward links the node-engine's converged answered for the call (H-A-324, H-A-325). */ -export type Kept = Allowance & { outward?: string; replaced?: Allowance }; +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; @@ -82,8 +55,8 @@ export interface Asks { /** 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: Value } | null>; - put(key: string, value: Value): Promise; + get(key: string): Promise<{ value: AllowanceValue } | null>; + put(key: string, value: AllowanceValue): Promise; delete(key: string): Promise; keys(): Promise; } @@ -92,11 +65,11 @@ export interface Store { export interface Watched { key: string; op: "put" | "delete"; - value?: Value; + value?: AllowanceValue; } /** Says the event. */ -export type Say = (body: Changed) => Promise; +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; @@ -109,9 +82,17 @@ export const timers: Schedule = (ms, fire) => { return () => clearTimeout(t); }; -/** One key of the state: allow.., and . when it names one. */ +/** 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 iface ? `allow.${protocol}.${port}.${iface}` : `allow.${protocol}.${port}`; + return stateKeyOf("", protocol, port, iface).slice(1); } const IFACE = /^[A-Za-z0-9_.-]{1,15}$/; @@ -167,8 +148,10 @@ function untilOf(v: unknown, now: Date): string | undefined { if (v === undefined) return undefined; const s = typeof v === "string" ? v : ""; const t = Date.parse(s); - 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, such as 2026-11-22T08:00:00Z`); + // 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; @@ -179,7 +162,7 @@ function whyOf(v: unknown): string { return v; } -function answered(key: string, value: Value): Allowance { +function answered(key: string, value: AllowanceValue): Allowance { return { key, ...value }; } @@ -194,6 +177,8 @@ export class Allowances { 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, @@ -220,8 +205,8 @@ export class Allowances { /** 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 prefix = `${this.node}.`; - return stateKey.startsWith(prefix + "allow.") ? stateKey.slice(prefix.length) : 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). */ @@ -268,6 +253,8 @@ export class Allowances { } 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() }); } @@ -285,17 +272,23 @@ export class Allowances { private arm(key: string, until: string): void { const left = Date.parse(until) - this.now().getTime(); if (left <= 0) { - void this.expire(key, until); + 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 void this.expire(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 { @@ -345,7 +338,7 @@ export class Allowances { const out: Kept[] = []; for (const iface of interfaces) { const key = keyOf(protocol, port, iface); - const value: Value = { + const value: AllowanceValue = { port, protocol, ...(iface ? { interface: iface } : {}), ...(source ? { source } : {}), @@ -423,6 +416,16 @@ export class 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): { diff --git a/modules/nftables/test/allowances.test.ts b/modules/nftables/test/allowances.test.ts index 35dffcc18..db7d64803 100644 --- a/modules/nftables/test/allowances.test.ts +++ b/modules/nftables/test/allowances.test.ts @@ -4,8 +4,8 @@ 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, + 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 } @@ -101,6 +101,7 @@ test("allow and disallow refuse what is not an allowance, writing nothing", asyn ["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/], @@ -279,6 +280,24 @@ test("at a start every expired allowance is removed before started is said (H-A- [["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]); }); +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"); diff --git a/modules/nftables/tools/index.ts b/modules/nftables/tools/index.ts index 5646e0017..eece4b2cd 100644 --- a/modules/nftables/tools/index.ts +++ b/modules/nftables/tools/index.ts @@ -7,24 +7,30 @@ 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 } from "@novox/mesh-connectivity-contracts-node-packet-filter"; +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, markLoaded, type Convergence, type Store, type Value } from "../allowances.js"; +import { Allowances, MOST, STATE, held, markLoaded, type AllowanceValue, type Convergence, type Store } 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)", + 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)" }; -export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): ToolDefinition[] { +// 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. " + "Beside it every allowance, marked loaded only when a rule of the mesh's table carries its comment allowance with an equal at, " + @@ -38,18 +44,18 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): 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 allowances.allowed()).allowances, mesh); + 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.", @@ -57,7 +63,7 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): run: async (args) => firewall.remove(String(args.where ?? "")), }, { - name: "allow", + 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. " + @@ -70,26 +76,26 @@ export function getSeatVerbs(firewall: FirewallClient, allowances: Allowances): 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)" }, + until: { type: "string", description: "when it expires, an RFC 3339 time with seconds in the future (optional)" }, why, - }, - run: async (args) => allowances.allow(args, callerOf(args)), + } satisfies Record, + run: held(start, async (args: Readonly>) => allowances.allow({ ...args }, callerOf(args))), }, { - name: "disallow", + 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 }, - run: async (args) => allowances.disallow(args, callerOf(args)), + input: { port, protocol, interfaces, why } satisfies Record, + run: held(start, async (args: Readonly>) => allowances.disallow({ ...args }, callerOf(args))), }, { - name: "allowed", + 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: {}, - run: async (args) => allowances.allowed(args), + input: {} satisfies Record, + run: held(start, async (args: Readonly>) => allowances.allowed({ ...args })), }, ]; } @@ -112,7 +118,7 @@ const firewall = FirewallClient.onThisMachine(); // 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 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 }; @@ -139,7 +145,7 @@ const allowances = new Allowances(store, node, (body) => seatPublish(allowancesC }, meshTable: () => firewall.ruleset(), }); -void (async () => { +const start = (async () => { await keeps([{ name: STATE }]); await kept.watch(async (change) => { if (change.op === "put") own.add(change.key); @@ -149,10 +155,13 @@ void (async () => { watched.done(); await allowances.started(); })().catch((err) => { - watched.failed(new Error(`the allowances did not start: ${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, allowances)); +registerModuleTools(packetFilter, () => getSeatVerbs(firewall, allowances, start)); registerModuleTools("nftables", () => getFirewallTools(firewall));