Compare commits
9
Commits
go/v0.1.26
...
go/v0.1.28
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
32e1ed6c55 | ||
|
|
d7b23f50b4 | ||
|
|
6527ebd077 | ||
|
|
31abcad907 | ||
|
|
f589b5af5c | ||
|
|
38ea9ce25c | ||
|
|
09d5758343 | ||
|
|
83482a4513 | ||
|
|
7bd1e74086 |
@@ -58,17 +58,33 @@ func realMachine(t *testing.T) (*Module, string) {
|
||||
t.Fatalf("the toolchain copied from %s cannot be used: %v", from, err)
|
||||
}
|
||||
for _, id := range []string{"w1", "w2", "w3"} {
|
||||
for p, body := range map[string]string{
|
||||
files := map[string]string{
|
||||
"modules/m/module.json": `{"module":"m","build":{"artifacts":[{"name":"tools","kind":"bundle","language":"typescript","entrypoints":["tools/index.js"]}]}}`,
|
||||
"modules/m/package.json": `{"name":"m","type":"module","scripts":{"test":"node -e \"process.exit(0)\""}}`,
|
||||
"modules/m/tools/index.ts": "import { serveRegisteredOverStdio } from \"@novox/mesh-sdk/stdio\";\nexport const f: () => Promise<void> = serveRegisteredOverStdio as () => Promise<void>;\n",
|
||||
} {
|
||||
}
|
||||
for p, body := range fetchedSDK {
|
||||
files["modules/m/node_modules/@novox/mesh-sdk/"+p] = body
|
||||
}
|
||||
for p, body := range files {
|
||||
write(t, filepath.Join(work, id, "tree", filepath.FromSlash(p)), body, 0o644)
|
||||
}
|
||||
}
|
||||
return m, work
|
||||
}
|
||||
|
||||
// fetchedSDK is the SDK the fixture's workspaces hold where the fetch step places it, in the module's node_modules
|
||||
// (fetch.go, placeSDK: the latest published release, ADR 0573 §2; design 47 G §571), made here because the integration
|
||||
// level has no registry to fetch it from. The toolchain's lock names no SDK since §571, so a fixture that leaves it out
|
||||
// reads one only from a toolchain installed before (main.137 and main.155: TS2307 once a build node installed the
|
||||
// lock). It holds the one export the fixture and the launchers import.
|
||||
var fetchedSDK = map[string]string{
|
||||
"package.json": `{"name":"@novox/mesh-sdk","version":"9.9.9","type":"module",` +
|
||||
`"exports":{"./stdio":{"types":"./dist/stdio.d.ts","default":"./dist/stdio.js"}}}`,
|
||||
"dist/stdio.js": "export async function serveRegisteredOverStdio() {}\n",
|
||||
"dist/stdio.d.ts": "export declare function serveRegisteredOverStdio(): Promise<void>;\n",
|
||||
}
|
||||
|
||||
// 1490/AC2, 1491 and issue 1869, in one test so the toolchain is copied once: the real type-check and test script of the
|
||||
// fixture pass the unit level; a package whose test imports its own build output (as mesh-sdk's do) passes the unit level,
|
||||
// the test step emitting it with the real tsc, shut off, before the test script runs; and the fixture TypeScript bundle
|
||||
|
||||
@@ -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.<protocol>.<port>[.<interface>]), kept one bucket per machine under its node's keys
|
||||
// (<node>.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<Convergence>;
|
||||
handAct: (act: HandAct) => Promise<void>;
|
||||
most: () => Promise<number>;
|
||||
/** The mesh's table as loaded (`nft list table inet mesh`). */
|
||||
meshTable: () => Promise<string>;
|
||||
}
|
||||
|
||||
/** 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<number>;
|
||||
delete(key: string): Promise<void>;
|
||||
keys(): Promise<string[]>;
|
||||
}
|
||||
|
||||
/** 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<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;
|
||||
|
||||
/** 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): <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 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<string, unknown>, 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<string, () => 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<Promise<boolean>>();
|
||||
|
||||
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<Convergence> {
|
||||
let stop: () => void = () => {};
|
||||
const late = new Promise<never>((_, 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<string[]> {
|
||||
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<void> {
|
||||
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<void> {
|
||||
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<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 {
|
||||
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<string, unknown>, 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<string, unknown>, 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<void> {
|
||||
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<string, unknown> = {}): 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<Allowance[]> {
|
||||
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<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): {
|
||||
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<string>();
|
||||
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;
|
||||
}
|
||||
@@ -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": [
|
||||
{
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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<string, Value>(), gate?: Promise<void>) {
|
||||
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<Convergence>(() => {}) : Promise.resolve(asks.convergence);
|
||||
},
|
||||
handAct: async (act) => { acts.push(act); },
|
||||
most: async () => asks.most,
|
||||
meshTable: async () => asks.table,
|
||||
}, () => clock.now, schedule, (l) => journal.push(l));
|
||||
return { a, kept, said, clock, timers, journal, acts, asks };
|
||||
}
|
||||
|
||||
/** The state's key of an allowance's key on shanks (H-A-317). */
|
||||
const k = (key: string) => `shanks.${key}`;
|
||||
|
||||
const settle = () => new Promise((r) => setImmediate(r));
|
||||
|
||||
test("allow keeps one key per interface, and with none the default set's key, which names no interface", async () => {
|
||||
const cases: { name: string; args: Record<string, unknown>; keys: string[] }[] = [
|
||||
{ name: "defaults", args: { port: 8000, why: "the operator's dev server" }, keys: ["allow.tcp.8000"] },
|
||||
{ name: "two interfaces", args: { port: 5353, protocol: "udp", interfaces: ["enp6s0", "wlan0"], source: "192.168.1.0/24", why: "w" },
|
||||
keys: ["allow.udp.5353.enp6s0", "allow.udp.5353.wlan0"] },
|
||||
{ name: "an interface with a dot", args: { port: 1, interfaces: ["enp6s0.10"], why: "w" }, keys: ["allow.tcp.1.enp6s0.10"] },
|
||||
];
|
||||
for (const c of cases) {
|
||||
const { a, kept, said } = fake();
|
||||
const got = await a.allow(c.args, "lead@shanks");
|
||||
assert.deepEqual(got.allowances.map((x) => x.key), c.keys, c.name);
|
||||
assert.equal(got.said, true, c.name);
|
||||
assert.deepEqual([...kept.keys()].sort(), c.keys.map(k), c.name);
|
||||
assert.deepEqual(said.map((b) => [b.change, b.node, b.by, b.why, b.allowances.map((x) => x.key)]),
|
||||
[["allowed", "shanks", "lead@shanks", c.args.why, c.keys]], c.name);
|
||||
for (const v of kept.values()) {
|
||||
assert.equal(v.by, "lead@shanks", c.name);
|
||||
assert.equal(v.at, "2026-11-21T20:00:00.000Z", c.name);
|
||||
assert.equal(v.source, c.args.source, c.name);
|
||||
if (!c.args.interfaces) assert.equal("interface" in v, false, "the private network's interface is never in the defaults");
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("allow naming an outward link answers it as outward, as converged lists them; another interface and the default set do not (H-A-325)", async () => {
|
||||
const { a, asks, said } = fake();
|
||||
asks.convergence = { state: "converged", since: "2026-11-01T00:00:00Z", tunnel: "mesh0", outward: ["eth1"] };
|
||||
const named = await a.allow({ port: 8000, interfaces: ["eth1", "enp6s0"], why: "w" }, "lead@shanks");
|
||||
assert.deepEqual(named.allowances.map((x) => [x.key, x.outward]), [["allow.tcp.8000.eth1", "eth1"], ["allow.tcp.8000.enp6s0", undefined]]);
|
||||
assert.equal("outward" in named.allowances[1], false, "an interface that is no outward link answers without the field");
|
||||
const none = await a.allow({ port: 8001, why: "w" }, "lead@shanks");
|
||||
assert.equal("outward" in none.allowances[0], false, "the default set opens no outward link");
|
||||
assert.equal(said.flatMap((b) => b.allowances).some((x) => "outward" in x), false, "the event's allowances carry no outward");
|
||||
});
|
||||
|
||||
test("allow and disallow refuse what is not an allowance, writing nothing", async () => {
|
||||
const bad: [string, Record<string, unknown>, RegExp][] = [
|
||||
["port 0", { port: 0, why: "w" }, /port: /],
|
||||
["port 65536", { port: 65536, why: "w" }, /port: /],
|
||||
["port 80a", { port: "80a", why: "w" }, /port: /],
|
||||
["protocol icmp", { port: 80, protocol: "icmp", why: "w" }, /protocol: /],
|
||||
["interface", { port: 80, interfaces: ["a b"], why: "w" }, /interfaces: /],
|
||||
["interface too long", { port: 80, interfaces: ["abcdefghijklmnop"], why: "w" }, /interfaces: /],
|
||||
["source", { port: 80, source: "10.0.0.0/33", why: "w" }, /source: /],
|
||||
["until in the past", { port: 80, until: "2026-11-21T19:00:00Z", why: "w" }, /until: .*not in the future/],
|
||||
["until not a time", { port: 80, until: "tomorrow", why: "w" }, /until: /],
|
||||
["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<string, Value>();
|
||||
const shanks = fake(undefined, "shanks", shared);
|
||||
const ace = fake(undefined, "ace", shared);
|
||||
ace.asks.most = 1;
|
||||
await shanks.a.allow({ port: 8000, why: "w" }, "x");
|
||||
assert.deepEqual((await ace.a.allowed()).allowances, []);
|
||||
await ace.a.allow({ port: 9000, why: "w" }, "x");
|
||||
assert.deepEqual([...shared.keys()].sort(), ["ace.allow.tcp.9000", "shanks.allow.tcp.8000"]);
|
||||
assert.deepEqual((await shanks.a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000"]);
|
||||
await assert.rejects(ace.a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /);
|
||||
});
|
||||
|
||||
test("on an adopted node allow and disallow are refused naming the adoption and allowed answers none; a silent converged refuses both", async () => {
|
||||
const { a, kept, asks, timers, said } = fake();
|
||||
await a.allow({ port: 8000, why: "w" }, "x");
|
||||
asks.convergence = { state: "adopted", since: "2026-11-20T10:00:00Z", found: "ufw" };
|
||||
await assert.rejects(a.allow({ port: 9000, why: "w" }, "x"), /allow: refused: this node is adopted \(the found firewall ufw, since 2026-11-20T10:00:00Z\)/);
|
||||
await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /disallow: refused: this node is adopted/);
|
||||
assert.deepEqual((await a.allowed()).allowances, []);
|
||||
assert.deepEqual([...kept.keys()], [k("allow.tcp.8000")]);
|
||||
asks.convergence = "silent";
|
||||
const pending = a.allow({ port: 9000, why: "w" }, "x");
|
||||
const bound = timers.at(-1)!;
|
||||
assert.equal(bound.ms, CONVERGED_BOUND_MS);
|
||||
bound.fire();
|
||||
await assert.rejects(pending, /allow: refused: the node-engine's converged did not answer \(no answer within 10 s\)/);
|
||||
const gone = a.disallow({ port: 8000, why: "w" }, "x");
|
||||
timers.at(-1)!.fire();
|
||||
await assert.rejects(gone, /disallow: refused: the node-engine's converged did not answer/);
|
||||
assert.equal(said.length, 1);
|
||||
});
|
||||
|
||||
test("allowed asks converged again while none answered, and refuses when it does not answer (H-A-318)", async () => {
|
||||
const { a, asks, timers, said, journal } = fake();
|
||||
asks.convergence = "silent";
|
||||
const start = a.started();
|
||||
timers.at(-1)!.fire();
|
||||
await start;
|
||||
assert.match(journal.join("\n"), /start: refused: the node-engine's converged did not answer/);
|
||||
assert.equal(said.at(-1)!.change, "started");
|
||||
const asked = asks.asked;
|
||||
const pending = a.allowed();
|
||||
timers.at(-1)!.fire();
|
||||
await assert.rejects(pending, /allowed: refused: the node-engine's converged did not answer/);
|
||||
assert.equal(asks.asked, asked + 1);
|
||||
asks.convergence = { state: "converged" };
|
||||
assert.deepEqual((await a.allowed()).allowances, []);
|
||||
await a.allowed();
|
||||
assert.equal(asks.asked, asked + 2, "an answer held is not asked again");
|
||||
});
|
||||
|
||||
test("privateOnly: a port accepted only with a source match, never from any source", () => {
|
||||
assert.equal(privateOnly(TABLE, "tcp", 5432), true);
|
||||
assert.equal(privateOnly(TABLE, "tcp", 9550), true, "a range of a set");
|
||||
assert.equal(privateOnly(TABLE, "tcp", 80), false);
|
||||
assert.equal(privateOnly(TABLE, "tcp", 8443), false, "accepted from anywhere too");
|
||||
assert.equal(privateOnly(TABLE, "udp", 5432), false);
|
||||
assert.equal(privateOnly(TABLE, "tcp", 8000), false, "no derived rule");
|
||||
});
|
||||
|
||||
test("allow then disallow writes the key, then deletes it, saying allowed and disallowed, with two hand-act log lines", async () => {
|
||||
const { a, kept, said, acts } = fake();
|
||||
const got = await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "open" }, "x");
|
||||
assert.equal(got.said, true);
|
||||
assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]);
|
||||
const gone = await a.disallow({ port: 8000, interfaces: ["enp6s0"], why: "done" }, "y");
|
||||
assert.deepEqual(gone.allowances.map((x) => x.key), ["allow.tcp.8000.enp6s0"]);
|
||||
assert.equal(gone.said, true);
|
||||
assert.equal(kept.size, 0);
|
||||
assert.deepEqual(said.map((b) => [b.change, b.by, b.why]), [["allowed", "x", "open"], ["disallowed", "y", "done"]]);
|
||||
assert.deepEqual(acts, [
|
||||
{ what: "allowed allow.tcp.8000.enp6s0 on shanks", why: "open (x)", cause: "allowance-set", verb: "allow" },
|
||||
{ what: "disallowed allow.tcp.8000.enp6s0 on shanks", why: "done (y)", cause: "allowance-taken-back", verb: "disallow" },
|
||||
]);
|
||||
});
|
||||
|
||||
test("disallow is all or nothing: a key not kept is refused by name and none is deleted", async () => {
|
||||
const { a, kept, said } = fake();
|
||||
await a.allow({ port: 8000, interfaces: ["enp6s0"], why: "w" }, "x");
|
||||
await assert.rejects(a.disallow({ port: 8000, interfaces: ["enp6s0", "wlan0"], why: "w" }, "x"), /no allowance allow\.tcp\.8000\.wlan0/);
|
||||
assert.deepEqual([...kept.keys()], [k("allow.tcp.8000.enp6s0")]);
|
||||
// no interfaces names the default set's key, never one of an interface
|
||||
await assert.rejects(a.disallow({ port: 8000, why: "w" }, "x"), /no allowance allow\.tcp\.8000 /);
|
||||
assert.equal(said.length, 1);
|
||||
});
|
||||
|
||||
test("a second allow of one key replaces it whole and answers what it replaced; the source is no part of the key", async () => {
|
||||
const { a, kept } = fake();
|
||||
await a.allow({ port: 8000, source: "192.168.1.0/24", until: "2026-11-22T00:00:00Z", why: "first" }, "x");
|
||||
const got = await a.allow({ port: 8000, source: "10.0.0.5", why: "second" }, "y");
|
||||
assert.deepEqual(got.allowances.map((x) => [x.key, x.source, x.replaced?.source, x.replaced?.why]),
|
||||
[["allow.tcp.8000", "10.0.0.5", "192.168.1.0/24", "first"]]);
|
||||
assert.deepEqual([...kept.entries()].map(([key, v]) => [key, v.source, v.by, v.until]), [[k("allow.tcp.8000"), "10.0.0.5", "y", undefined]]);
|
||||
});
|
||||
|
||||
test("at its until an allowance is deleted by its timer, says expired, is journalled, and allowed answers without it", async () => {
|
||||
const { a, kept, said, clock, timers, journal } = fake();
|
||||
await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "for an hour" }, "x");
|
||||
await a.allow({ port: 9000, why: "w" }, "x");
|
||||
await a.watched({ key: k("allow.tcp.8000"), op: "put", value: kept.get(k("allow.tcp.8000"))! });
|
||||
const live = timers.filter((t) => !t.cancelled);
|
||||
assert.equal(live.length, 1, "one expiry timer; every converged bound is cancelled once answered");
|
||||
assert.equal(live[0].ms, 3600_000);
|
||||
clock.now = new Date("2026-11-21T21:00:00Z");
|
||||
live[0].fire();
|
||||
await settle();
|
||||
assert.deepEqual([...kept.keys()], [k("allow.tcp.9000")]);
|
||||
assert.deepEqual([said.at(-1)!.change, said.at(-1)!.allowances.map((x) => x.key)], ["expired", ["allow.tcp.8000"]]);
|
||||
assert.match(journal.join("\n"), /the allowance allow\.tcp\.8000 .*for an hour\) expired at 2026-11-21T21:00:00Z and is removed/);
|
||||
assert.deepEqual((await a.allowed()).allowances.map((x) => x.key), ["allow.tcp.9000"]);
|
||||
});
|
||||
|
||||
test("the expiry timers follow the state: a delete cancels, a far until waits in steps, a stale timer removes nothing", async () => {
|
||||
const { a, kept, clock, timers } = fake();
|
||||
const v: Value = { port: 1, protocol: "tcp", why: "w", by: "x", at: "2026-11-21T20:00:00Z", until: "2026-11-21T22:00:00Z" };
|
||||
await a.watched({ key: k("allow.tcp.1"), op: "put", value: v });
|
||||
await a.watched({ key: k("allow.tcp.1"), op: "delete" });
|
||||
assert.equal(timers.at(-1)!.cancelled, true);
|
||||
const armed = timers.length;
|
||||
await a.watched({ key: "ace.allow.tcp.1", op: "put", value: v });
|
||||
assert.equal(timers.length, armed, "another node's key arms no timer");
|
||||
await a.watched({ key: k("allow.tcp.2"), op: "put", value: { ...v, until: "2027-06-01T00:00:00Z" } });
|
||||
assert.equal(timers.at(-1)!.ms, LONGEST_WAIT_MS);
|
||||
await a.allow({ port: 9000, until: "2026-11-21T21:30:00Z", why: "w" }, "x");
|
||||
await a.allow({ port: 9000, until: "2026-11-21T23:00:00Z", why: "w" }, "x");
|
||||
clock.now = new Date("2026-11-21T21:30:00Z");
|
||||
assert.equal(await a.expire("allow.tcp.9000", "2026-11-21T21:30:00Z"), false);
|
||||
assert.ok(kept.has(k("allow.tcp.9000")));
|
||||
// at a start, a key already past its until is removed at once
|
||||
clock.now = new Date("2026-11-22T00:00:00Z");
|
||||
await a.watched({ key: k("allow.tcp.9000"), op: "put", value: kept.get(k("allow.tcp.9000"))! });
|
||||
await settle();
|
||||
assert.ok(!kept.has(k("allow.tcp.9000")));
|
||||
});
|
||||
|
||||
test("at a start every expired allowance is removed before started is said (H-A-312 (2))", async () => {
|
||||
const { a, kept, said, clock } = fake();
|
||||
await a.allow({ port: 8000, until: "2026-11-21T21:00:00Z", why: "w" }, "x");
|
||||
await a.allow({ port: 9000, why: "w" }, "x");
|
||||
clock.now = new Date("2026-11-21T22:00:00Z");
|
||||
await a.started();
|
||||
assert.deepEqual([...kept.keys()], [k("allow.tcp.9000")]);
|
||||
assert.deepEqual(said.slice(-2).map((b) => [b.change, b.allowances.map((x) => x.key)]),
|
||||
[["expired", ["allow.tcp.8000"]], ["started", ["allow.tcp.9000"]]]);
|
||||
|
||||
// §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<void>((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);
|
||||
});
|
||||
+131
-10
@@ -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<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.",
|
||||
"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, " +
|
||||
"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<keyof AllowInput, object>,
|
||||
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<keyof DisallowInput, object>,
|
||||
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<keyof AllowedInput, object>,
|
||||
run: held(start, async (args: Readonly<Record<string, unknown>>) => 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<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 };
|
||||
const watching = new Promise<void>((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<object, Convergence>(`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));
|
||||
|
||||
@@ -10,6 +10,7 @@
|
||||
},
|
||||
"include": [
|
||||
"client.ts",
|
||||
"allowances.ts",
|
||||
"tools/index.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user