nftables: hold the verbs until the start ends; until with seconds; the seat's own forms
Review round 1 (1)-(3): an until without seconds was accepted, which the node-engine's RFC 3339 read refuses, withholding every later compose; the verbs answered before started was said and before the watch's expiries ended; and the holder kept its own copies of the seat's names, key forms and value forms, which had drifted from H-A-324. The holder now takes them from the seat's generated package, the tools' inputs are checked against its input types, and every seat verb waits for the start's end. Builds: design 33 control-verbs §2, §3, §11, §12, §14; design 47 H H-A-324, H-A-330
This commit is contained in:
@@ -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<number>;
|
||||
get(key: string): Promise<{ value: AllowanceValue } | null>;
|
||||
put(key: string, value: AllowanceValue): Promise<number>;
|
||||
delete(key: string): Promise<void>;
|
||||
keys(): Promise<string[]>;
|
||||
}
|
||||
@@ -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<void>;
|
||||
export type Say = (body: AllowancesChanged) => Promise<void>;
|
||||
|
||||
/** 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.<protocol>.<port>, and .<interface> when it names one. */
|
||||
/** The state's key of an allowance on node, in the seat's key forms (§7, H-A-317): <node>.allow.<protocol>.<port>, and
|
||||
* .<interface> 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<Promise<boolean>>();
|
||||
|
||||
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<boolean>): 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<boolean> {
|
||||
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<A extends unknown[], R>(start: Promise<unknown>, run: (...args: A) => Promise<R>): (...args: A) => Promise<R> {
|
||||
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 <key> <at>` 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): {
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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<unknown> = 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 <key> <at> 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<keyof AllowInput, object>,
|
||||
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<keyof DisallowInput, object>,
|
||||
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<keyof AllowedInput, object>,
|
||||
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<Value>(STATE);
|
||||
const kept = state<AllowanceValue>(STATE);
|
||||
const own = new Set<string>();
|
||||
// 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));
|
||||
|
||||
Reference in New Issue
Block a user