@kici-dev/shared 0.6.1 → 0.7.0

package/dist/env/define-env.d.ts

@@ -122,7 +122,10 @@ export declare function defineEnv<TShape extends z.ZodRawShape>(opts: DefineEnvO
  *
  * Keep this list small and well-justified. Every addition is a typo we can
  * no longer catch, so only list things that are (a) actually set in the
- * wild by our own tooling and (b) could never be a config typo.
+ * wild by our own tooling and (b) could never be a config typo. A variable
+ * only one service reads belongs in that service's `extraKnown` instead —
+ * `KICI_CONFIG` is the reference case, allowlisted at the orchestrator's own
+ * call site so the agent and Platform catchers still reject it.
  */
 export declare const RESERVED_NON_SCHEMA_KICI_VARS: readonly string[];
 /**
@@ -176,6 +179,16 @@ export interface ValidateUnknownKiciVarsOptions {
     warnOnly?: boolean;
     /** Logger callback for warn-mode (defaults to `console.warn`). */
     onWarn?: (msg: string) => void;
+    /**
+     * Advice text for names the caller recognises but does not accept — a
+     * documented variable that belongs to some other layer. A rejected name
+     * found here is reported with its advice instead of a Levenshtein guess,
+     * which finds nothing for exactly these names because they are not near
+     * misses of a schema name.
+     *
+     * This changes the message only. A name listed here is still rejected.
+     */
+    notStartupVars?: Record<string, string>;
 }
 /**
  * Inspect `env` for KICI_* keys that are not in `known`. Throws (or warns,

package/dist/env/define-env.js

@@ -241,7 +241,10 @@ function suggestClosest(name, candidates) {
 *
 * Keep this list small and well-justified. Every addition is a typo we can
 * no longer catch, so only list things that are (a) actually set in the
-* wild by our own tooling and (b) could never be a config typo.
+* wild by our own tooling and (b) could never be a config typo. A variable
+* only one service reads belongs in that service's `extraKnown` instead —
+* `KICI_CONFIG` is the reference case, allowlisted at the orchestrator's own
+* call site so the agent and Platform catchers still reject it.
 */
 const RESERVED_NON_SCHEMA_KICI_VARS = [
 	"KICI_CACHE",
@@ -305,21 +308,27 @@ function validateUnknownKiciVars(known, options = {}, env = process.env) {
 		...options.extraKnown ?? [],
 		...RESERVED_NON_SCHEMA_KICI_VARS
 	]);
+	const advice = options.notStartupVars ?? {};
 	const unknown = [];
 	for (const key of Object.keys(env)) {
 		if (!key.startsWith("KICI_")) continue;
 		if (knownSet.has(key)) continue;
 		if (RESERVED_NON_SCHEMA_KICI_PREFIXES.some((p) => key.startsWith(p))) continue;
 		if (RESERVED_NON_SCHEMA_KICI_SUFFIXES.some((s) => key.endsWith(s) || key.includes(`${s}_`))) continue;
+		const note = advice[key];
 		unknown.push({
 			name: key,
-			suggestion: suggestClosest(key, [...knownSet])
+			note,
+			suggestion: note ? void 0 : suggestClosest(key, [...knownSet])
 		});
 	}
 	if (unknown.length === 0) return;
 	const header = `Unknown KICI_* env var(s) detected — refusing to start.
 Set KICI_DEV=true to downgrade this check to a warning.
-Unknown vars:\n${unknown.map(({ name, suggestion }) => suggestion ? `  - ${name}    (did you mean ${suggestion}?)` : `  - ${name}    (no close match in the schema)`).join("\n")}`;
+Unknown vars:\n${unknown.map(({ name, suggestion, note }) => {
+		if (note) return `  - ${name}    (${note})`;
+		return suggestion ? `  - ${name}    (did you mean ${suggestion}?)` : `  - ${name}    (no close match in the schema)`;
+	}).join("\n")}`;
 	if (options.warnOnly ?? env.KICI_DEV === "true") {
 		(options.onWarn ?? console.warn)(header);
 		return;

package/dist/net/nftables.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Programmatic nftables rule management for agent network isolation.
+ *
+ * Manages RFC1918 + cloud metadata blocking rules per-interface (Firecracker/container)
+ * or per-UID (bare-metal). All operations use `nft` CLI via child_process.execFile.
+ *
+ * Table layout:
+ *   table ip kici {
+ *     chain forward { type filter hook forward priority 0; policy accept; }
+ *     chain input   { type filter hook input priority 0; policy accept; }
+ *     chain output  { type filter hook output priority 0; policy accept; }
+ *   }
+ *
+ * `forward` and `input` answer different questions and both are needed. A
+ * packet a sandbox sends to one of the host's OWN addresses — a bridge gateway,
+ * the host's LAN address — is delivered on the input hook and never traverses
+ * forward, so a forward rule cannot see it. `forward` governs what a sandbox
+ * reaches THROUGH the host; `input` governs what it reaches ON the host.
+ */
+/**
+ * Network policy controlling RFC1918 and internet access for the agents or job
+ * containers in one label set.
+ *
+ * Lives here rather than beside the scaler's own types because both the
+ * orchestrator's scaler (agent containers and Firecracker VMs) and the agent's
+ * container backend (nested job containers) build rules from it. The
+ * orchestrator re-exports it from `scaler/types.ts` so its call sites are
+ * unchanged.
+ */
+export interface NetworkPolicy {
+    /** CIDR ranges allowed as exceptions to the default RFC1918 block */
+    allowlist?: string[];
+    /** Block all outbound traffic except allowlisted ranges */
+    denyAll?: boolean;
+    /**
+     * What this source class may reach on the HOST itself, in the
+     * `<cidr|address|*>[:<port|*>]` vocabulary {@link parseHostAccess} reads.
+     * Everything else host-destined is dropped.
+     *
+     * Distinct from {@link allowlist}, which governs the `forward` hook and so
+     * answers what a sandbox reaches *through* the host. Leaving this undefined
+     * means the caller supplies its own class default; an empty array means
+     * "reach nothing on the host".
+     */
+    hostAccess?: string[];
+}
+/**
+ * One parsed {@link NetworkPolicy.hostAccess} entry.
+ *
+ * `null` means "unconstrained" on both fields: a `daddr` of `null` matches
+ * every host address (nft omits the `ip daddr` clause), and a `port` of
+ * `null` matches every port.
+ */
+export interface HostAccessRule {
+    daddr: string | null;
+    port: number | null;
+}
+/**
+ * Parse one host-access entry.
+ *
+ * Grammar: `<cidr|address|*>` optionally followed by `:<port|*>`. A bare number
+ * is a port on any host address, which is the common case — an operator naming
+ * a host-local registry mirror knows its port, not the host's dynamic
+ * addresses.
+ *
+ * Hostnames are rejected on purpose: nftables matches addresses, so resolving a
+ * name at rule-build time produces a rule that goes stale silently the next
+ * time the name moves.
+ *
+ * @throws Error naming the entry and what is wrong with it
+ */
+export declare function parseHostAccess(entry: string): HostAccessRule;
+/**
+ * Build the host-access rules for one identifier, in final head-to-tail order:
+ * the conntrack exception, every accept, then one terminal drop.
+ *
+ * The conntrack rule leads because the chain is keyed on the sandbox as the
+ * SOURCE, so it also sees the reply leg of a connection the HOST opened toward
+ * the sandbox — a readiness probe, a metrics scrape. Without the exception
+ * those replies fall through to the terminal drop and the host's own connection
+ * dies as an opaque timeout. It widens nothing a sandbox can initiate:
+ * `established` is reached only by a flow whose first packet was already
+ * accepted, so a sandbox connecting to a port with no accept still has its SYN
+ * dropped and never reaches that state.
+ *
+ * A port-scoped entry emits an accept per protocol in
+ * {@link HOST_ACCESS_PROTOCOLS}. UDP is not optional: a container whose
+ * resolver is the bridge gateway — which is what rootful podman with
+ * aardvark-dns gives it — resolves over UDP, so a tcp-only accept on port 53
+ * leaves it unable to resolve any name.
+ *
+ * @returns one token list per rule, in final head-to-tail order
+ */
+export declare function buildHostAccessRuleOps(matchClause: string[], hostAccess: string[]): string[][];
+/**
+ * Match mode for nftables isolation rules.
+ * - 'iifname': Match on input interface name (Firecracker TAP devices)
+ * - 'saddr': Match on source IP address (container backends)
+ */
+export type NftMatchMode = 'iifname' | 'saddr';
+/** RFC1918 private address ranges. */
+export declare const RFC1918_RANGES: string[];
+/** Cloud metadata service range (AWS/GCP/Azure link-local). */
+export declare const METADATA_RANGE = "169.254.0.0/16";
+/**
+ * Subnet of the agent's `kici-jobs` bridge, on which the agent keys ONE drop set
+ * covering every nested job container — including one that does not exist yet.
+ *
+ * It lives here rather than beside the agent's own network constants because
+ * the Firecracker host provisioner has to recognise those rules to leave them
+ * alone, and the orchestrator carries `@kici-dev/agent` only as a devDependency.
+ * The agent module re-exports it, so its own call sites are unchanged.
+ */
+export declare const JOB_NETWORK_SUBNET = "172.31.0.0/16";
+/**
+ * Options for nft command execution.
+ */
+interface NftOptions {
+    /**
+     * Wrap the `nft` invocation with `sudo -n` so non-root orchestrators (e.g.
+     * Pi user-mode systemd) can manage rules. Operators must have a NOPASSWD
+     * sudoers entry for /usr/sbin/nft. Default false.
+     */
+    requireSudo?: boolean;
+    /**
+     * nftables table these rules live in. Defaults to {@link DEFAULT_NFT_TABLE}.
+     *
+     * The Firecracker backend exposes this as an operator knob so two
+     * coordinators on one host get disjoint tables; the per-VM rules must follow
+     * the same knob as the bridge baseline, or coordinator B's rules land in
+     * coordinator A's table and A's next provision wipes them.
+     */
+    table?: string;
+}
+/** Table used when {@link NftOptions.table} is not set. */
+export declare const DEFAULT_NFT_TABLE = "kici";
+/**
+ * Validate that nftables is available and the process has NET_ADMIN capability.
+ * Attempts `nft list tables` -- if it fails:
+ *   - ENOENT: nft binary not installed
+ *   - EPERM: nft binary present but NET_ADMIN capability missing
+ * Throws with a clear error message in both cases.
+ */
+export declare function validateNftablesAvailability(opts?: NftOptions): Promise<void>;
+/**
+ * Ensure the nftables table and the chains this module writes to exist.
+ * Idempotent -- safe to call multiple times.
+ *
+ * Every chain is verified individually. A bare "does the table exist?" check is
+ * not enough: the Firecracker host provisioner creates the table before this
+ * module ever runs, so a table with no `forward` chain satisfied the old early
+ * return — and then every `addIsolationRules` failed with nft's "No such file
+ * or directory", leaving every VM on that host with no isolation rules at all.
+ *
+ * @param opts - `table` selects the table; `requireBaselineChain` additionally
+ * ensures the regular {@link BASELINE_CHAIN} exists (Firecracker hosts, whose
+ * `forward` chain ends in a jump to it).
+ */
+export declare function ensureKiciTable(opts?: NftOptions & {
+    requireBaselineChain?: boolean;
+}): Promise<void>;
+/** Chain in the kici table that filters host-destined sandbox traffic. */
+export declare const INPUT_CHAIN = "input";
+/**
+ * Ensure the kici table and its `input` chain exist. Idempotent — `nft add` is
+ * a create-or-noop for both, so there is no check-then-create window.
+ *
+ * The chain's policy is `accept` because it is a base chain on the host's own
+ * input hook: everything the host itself receives passes through it, and a
+ * default-deny there would take the machine off the network. The deny lives in
+ * the per-identifier terminal drop {@link buildHostAccessRuleOps} emits.
+ */
+export declare function ensureKiciInputChain(opts?: NftOptions): Promise<void>;
+/**
+ * Apply one identifier's host-access rules to the `input` chain, replacing
+ * whatever it had.
+ *
+ * The pre-clean is not an optimisation. Bridge networks recycle addresses, so a
+ * crash or a `kill -9` leaves the previous holder's accepts behind for the next
+ * container on that IP to inherit — which is the boundary this chain exists to
+ * hold. Applying without removing first would also stack a second terminal drop
+ * above the first run's accepts, shadowing every one of them.
+ *
+ * Rules are `insert`ed in reverse so the block lands at the chain head in the
+ * order {@link buildHostAccessRuleOps} returns: accepts first, terminal drop
+ * last. Inserting forwards would put the drop above the accepts and deny
+ * everything.
+ */
+export declare function addHostIsolationRules(identifier: string, hostAccess: string[], matchMode?: NftMatchMode, opts?: NftOptions): Promise<void>;
+/**
+ * A table's `input` chain, as `nft -a list chain` prints it, or `null` when the
+ * table or the chain does not exist yet.
+ *
+ * Returning `null` rather than throwing keeps "the chain is not there" distinct
+ * from "the chain is there and holds nothing", which a caller deciding whether
+ * a rule set is already installed has to be able to tell apart.
+ */
+export declare function readInputChain(opts?: NftOptions): Promise<string | null>;
+/**
+ * Remove one identifier's rules from the `input` chain.
+ *
+ * Best-effort: a missing chain, or a rule another path already deleted, must
+ * not abort a teardown.
+ */
+export declare function removeHostIsolationRules(identifier: string, opts?: NftOptions): Promise<void>;
+/**
+ * Name of the regular (non-hooked) chain holding the host baseline rules.
+ *
+ * The Firecracker host provisioner puts its six source-scoped baseline rules
+ * here and reaches them with a `jump` appended as the `forward` chain's LAST
+ * rule. Two properties follow, and both are load-bearing:
+ *
+ *  - **Per-VM rules always win.** They are inserted at the `forward` head, so
+ *    every one of them is evaluated before the jump. A per-VM `accept`
+ *    terminates the hook before the baseline can re-drop an allowlisted
+ *    destination, and a per-VM `denyAll` drop is terminal before the
+ *    baseline's blanket internet `accept` can let the packet out.
+ *  - **A self-heal can rebuild the baseline without touching live VMs.** The
+ *    provisioner flushes and refills only this chain, so it never has to
+ *    `delete table` — which used to drop every running VM's isolation rules
+ *    fail-open.
+ *
+ * A regular chain reached by `jump` rather than a second base chain at a lower
+ * priority: in netfilter an `accept` ends only the current base chain, so an
+ * allowlist accept in an earlier base chain would still be re-evaluated — and
+ * dropped — by the baseline's 10.0.0.0/8 rule in the later one.
+ */
+export declare const BASELINE_CHAIN = "baseline";
+/**
+ * Build the per-identifier isolation rules in their final head-to-tail order.
+ *
+ * nftables is first-match-wins within a chain and `accept` is terminal, so the
+ * order below is the whole security property:
+ *
+ *  1. gateway accept
+ *  2. allowlisted CIDR accepts — ahead of the drops, so an allowlisted
+ *     destination inside a dropped range (a 10.x registry endpoint behind the
+ *     10.0.0.0/8 drop) is accepted before the drop is evaluated
+ *  3. RFC1918 drops
+ *  4. cloud-metadata drop
+ *  5. `denyAll` drop
+ *
+ * {@link addIsolationRules} lands them in exactly this order by applying the
+ * list in REVERSE with `insert`, which puts the whole block at the chain head —
+ * ahead of the tail `jump` to {@link BASELINE_CHAIN}.
+ *
+ * @returns one token list per rule, in final head-to-tail order
+ */
+export declare function buildIsolationRuleOps(matchClause: string[], gatewayIp: string, networkPolicy?: NetworkPolicy): string[][];
+/**
+ * Add network isolation rules for one identifier (a TAP interface name, or a
+ * container's source IP).
+ *
+ * Every rule is `insert`ed, applying {@link buildIsolationRuleOps} in reverse,
+ * so the block lands at the chain head in its documented order — ahead of any
+ * host baseline reached by a tail `jump`.
+ *
+ * @param identifier - Network interface name or source IP to match (e.g., "veth-abc123" or "172.30.0.5")
+ * @param gatewayIp - Gateway IP that must remain accessible (e.g., "10.0.0.1")
+ * @param networkPolicy - Optional policy with allowlist and denyAll settings
+ * @param matchMode - How to match traffic: 'iifname' for interface name (default), 'saddr' for source IP
+ */
+export declare function addIsolationRules(identifier: string, gatewayIp: string, networkPolicy?: NetworkPolicy, matchMode?: NftMatchMode, opts?: NftOptions): Promise<void>;
+/**
+ * A table's `forward` chain, as `nft -a list chain` prints it, or `null` when
+ * the table or the chain does not exist yet.
+ *
+ * The text form is what {@link parseRuleHandles} reads, and it is also what a
+ * caller asking whether a rule set is ALREADY installed — rather than deleting
+ * it — compares against the rule text {@link buildIsolationRuleOps} emits.
+ * {@link listForwardRules} cannot answer for a subnet identifier: nft reports a
+ * subnet source as a prefix object, which its classifier treats as "not a
+ * per-agent rule" on purpose.
+ *
+ * Returning `null` rather than throwing keeps "the chain is not there" distinct
+ * from "the chain is there and holds nothing", exactly as {@link readInputChain}
+ * does for the sibling chain. The distinction is load-bearing in the install
+ * direction: a caller checking whether a rule set is present must read a missing
+ * chain as NOT installed and go install it, and a throw instead aborts the whole
+ * ensure path — which for the agent's job network degrades to a container on an
+ * unfiltered bridge.
+ */
+export declare function readForwardChain(opts?: NftOptions): Promise<string | null>;
+/**
+ * Remove every isolation rule this identifier owns, in both the `forward` and
+ * the `input` chain. Called during agent cleanup, and as the pre-clean before a
+ * re-add.
+ *
+ * Both chains are swept because they are one boundary: an identifier is a
+ * container IP or a TAP name, addresses are recycled, and leaving the input
+ * chain's accepts behind hands the next tenant on that address the previous
+ * one's host reachability.
+ *
+ * Best-effort: logs errors but does not throw (cleanup must not block
+ * destruction).
+ *
+ * @param interfaceName - Network interface name or source IP whose rules should be removed
+ */
+export declare function removeIsolationRules(interfaceName: string, opts?: NftOptions): Promise<void>;
+/**
+ * Re-export NftOptions type for use by callers (Firecracker / container backends)
+ * that need to pass the requireSudo flag through to these functions.
+ */
+export type { NftOptions };
+/** One rule in the forward chain, as reported by `nft -j -a list chain`. */
+export interface NftForwardRule {
+    /** nft rule handle, for `nft delete rule … handle N`. */
+    handle: number;
+    /**
+     * The per-identifier value this rule matches on — a concrete source IP or a
+     * concrete interface name — or `null` for a rule that is not per-identifier
+     * (a host baseline rule matching a whole subnet or a `kici-*` wildcard, or a
+     * `jump`).
+     */
+    identifier: string | null;
+}
+/**
+ * Read every rule in a table's forward chain, with its handle and the per-agent
+ * identifier it matches on.
+ *
+ * This is the enumerate-what-is-there half of rule management; the
+ * identifier-known delete path is {@link parseRuleHandles}. Reconciliation
+ * needs this one: rules are removed only on the synchronous teardown paths this
+ * process drives, so an orchestrator crash, a `kill -9`, or a VM that dies
+ * while the orchestrator is down strands `ip saddr <ip> …` rules in the shared
+ * chain forever. The allocator then hands that IP to another tenant, who
+ * inherits the dead job's allowlist.
+ *
+ * Returns an empty list rather than throwing when the chain cannot be read —
+ * the caller is a best-effort sweep, and a failed read must not be mistaken
+ * for "nothing is there".
+ */
+export declare function listForwardRules(opts?: NftOptions): Promise<NftForwardRule[]>;
+/**
+ * Every per-agent identifier currently present in the forward chain, mapped to
+ * the handles of the rules that carry it.
+ */
+export declare function listIsolationRules(opts?: NftOptions): Promise<Map<string, number[]>>;
+/**
+ * Delete rules from a table's forward chain by handle, highest first so earlier
+ * deletions cannot shift the handles still to come.
+ *
+ * Best-effort per handle: a rule another path already removed must not abort
+ * the rest of the sweep.
+ */
+export declare function deleteForwardRules(handles: number[], opts?: NftOptions): Promise<number>;
+/**
+ * Parse nft rule listing output and extract handles for rules matching a given identifier.
+ * Handles lines like: `  iifname "veth-abc" ip daddr 10.0.0.0/8 drop # handle 42`
+ *
+ * @param nftOutput - Raw output from `nft -a list chain ip kici <chain>`
+ * @param identifier - String to search for in each rule line (interface name or UID)
+ * @returns Array of numeric rule handles
+ */
+export declare function parseRuleHandles(nftOutput: string, identifier: string): number[];
+//# sourceMappingURL=nftables.d.ts.map

package/dist/net/nftables.js

@@ -0,0 +1,587 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { createLogger, toErrorMessage } from "@kici-dev/core";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/net/nftables.ts
+/**
+* Programmatic nftables rule management for agent network isolation.
+*
+* Manages RFC1918 + cloud metadata blocking rules per-interface (Firecracker/container)
+* or per-UID (bare-metal). All operations use `nft` CLI via child_process.execFile.
+*
+* Table layout:
+*   table ip kici {
+*     chain forward { type filter hook forward priority 0; policy accept; }
+*     chain input   { type filter hook input priority 0; policy accept; }
+*     chain output  { type filter hook output priority 0; policy accept; }
+*   }
+*
+* `forward` and `input` answer different questions and both are needed. A
+* packet a sandbox sends to one of the host's OWN addresses — a bridge gateway,
+* the host's LAN address — is delivered on the input hook and never traverses
+* forward, so a forward rule cannot see it. `forward` governs what a sandbox
+* reaches THROUGH the host; `input` governs what it reaches ON the host.
+*/
+/** Transport protocols a port-scoped host-access accept is emitted for. */
+const HOST_ACCESS_PROTOCOLS = ["tcp", "udp"];
+/** An IPv4 dotted quad, optionally with a CIDR prefix length. */
+const IPV4_OR_CIDR_RE = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})(?:\/(\d{1,2}))?$/;
+/** True when every octet is in range and the prefix length, if any, is 0-32. */
+function isIpv4OrCidr(value) {
+	const match = IPV4_OR_CIDR_RE.exec(value);
+	if (!match) return false;
+	for (let i = 1; i <= 4; i++) {
+		const octet = Number(match[i]);
+		if (!Number.isInteger(octet) || octet > 255) return false;
+	}
+	if (match[5] !== void 0) {
+		const prefix = Number(match[5]);
+		if (!Number.isInteger(prefix) || prefix > 32) return false;
+	}
+	return true;
+}
+/**
+* Parse one host-access entry.
+*
+* Grammar: `<cidr|address|*>` optionally followed by `:<port|*>`. A bare number
+* is a port on any host address, which is the common case — an operator naming
+* a host-local registry mirror knows its port, not the host's dynamic
+* addresses.
+*
+* Hostnames are rejected on purpose: nftables matches addresses, so resolving a
+* name at rule-build time produces a rule that goes stale silently the next
+* time the name moves.
+*
+* @throws Error naming the entry and what is wrong with it
+*/
+function parseHostAccess(entry) {
+	const trimmed = entry.trim();
+	if (trimmed.length === 0) throw new Error("hostAccess entry is empty");
+	if (/^\d+$/.test(trimmed)) return {
+		daddr: null,
+		port: parseHostAccessPort(trimmed, entry)
+	};
+	const colon = trimmed.lastIndexOf(":");
+	const addressPart = colon === -1 ? trimmed : trimmed.slice(0, colon);
+	const portPart = colon === -1 ? null : trimmed.slice(colon + 1);
+	if (addressPart !== "*" && !isIpv4OrCidr(addressPart)) throw new Error(`hostAccess entry "${entry}" names "${addressPart}", which is not an IPv4 address, an IPv4 CIDR, or "*". Hostnames are not accepted — nftables matches addresses, and a name resolved at rule-build time goes stale without warning.`);
+	const port = portPart === null || portPart === "*" ? null : parseHostAccessPort(portPart, entry);
+	return {
+		daddr: addressPart === "*" ? null : addressPart,
+		port
+	};
+}
+/** Parse and range-check the port half of a host-access entry. */
+function parseHostAccessPort(value, entry) {
+	if (!/^\d+$/.test(value)) throw new Error(`hostAccess entry "${entry}" has a non-numeric port "${value}"`);
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`hostAccess entry "${entry}" has port ${value}, outside 1-65535`);
+	return port;
+}
+/**
+* Build the host-access rules for one identifier, in final head-to-tail order:
+* the conntrack exception, every accept, then one terminal drop.
+*
+* The conntrack rule leads because the chain is keyed on the sandbox as the
+* SOURCE, so it also sees the reply leg of a connection the HOST opened toward
+* the sandbox — a readiness probe, a metrics scrape. Without the exception
+* those replies fall through to the terminal drop and the host's own connection
+* dies as an opaque timeout. It widens nothing a sandbox can initiate:
+* `established` is reached only by a flow whose first packet was already
+* accepted, so a sandbox connecting to a port with no accept still has its SYN
+* dropped and never reaches that state.
+*
+* A port-scoped entry emits an accept per protocol in
+* {@link HOST_ACCESS_PROTOCOLS}. UDP is not optional: a container whose
+* resolver is the bridge gateway — which is what rootful podman with
+* aardvark-dns gives it — resolves over UDP, so a tcp-only accept on port 53
+* leaves it unable to resolve any name.
+*
+* @returns one token list per rule, in final head-to-tail order
+*/
+function buildHostAccessRuleOps(matchClause, hostAccess) {
+	const rules = [[
+		...matchClause,
+		"ct",
+		"state",
+		"established,related",
+		"accept"
+	]];
+	for (const entry of hostAccess) {
+		const { daddr, port } = parseHostAccess(entry);
+		const scoped = daddr === null ? matchClause : [
+			...matchClause,
+			"ip",
+			"daddr",
+			daddr
+		];
+		if (port === null) {
+			rules.push([...scoped, "accept"]);
+			continue;
+		}
+		for (const protocol of HOST_ACCESS_PROTOCOLS) rules.push([
+			...scoped,
+			protocol,
+			"dport",
+			String(port),
+			"accept"
+		]);
+	}
+	rules.push([...matchClause, "drop"]);
+	return rules;
+}
+const execFile$1 = promisify(execFile);
+const logger = createLogger({ prefix: "nftables" });
+/** Timeout for nft commands in milliseconds. */
+const NFT_TIMEOUT_MS = 1e4;
+/** RFC1918 private address ranges. */
+const RFC1918_RANGES = [
+	"10.0.0.0/8",
+	"172.16.0.0/12",
+	"192.168.0.0/16"
+];
+/** Cloud metadata service range (AWS/GCP/Azure link-local). */
+const METADATA_RANGE = "169.254.0.0/16";
+/**
+* Subnet of the agent's `kici-jobs` bridge, on which the agent keys ONE drop set
+* covering every nested job container — including one that does not exist yet.
+*
+* It lives here rather than beside the agent's own network constants because
+* the Firecracker host provisioner has to recognise those rules to leave them
+* alone, and the orchestrator carries `@kici-dev/agent` only as a devDependency.
+* The agent module re-exports it, so its own call sites are unchanged.
+*/
+const JOB_NETWORK_SUBNET = "172.31.0.0/16";
+/** Table used when {@link NftOptions.table} is not set. */
+const DEFAULT_NFT_TABLE = "kici";
+/** The configured table, or the default. */
+function tableOf(opts) {
+	return opts.table ?? "kici";
+}
+/**
+* Execute an nft command with timeout.
+* @returns stdout from the command
+* @throws Error on non-zero exit or timeout
+*/
+async function nft(opts, ...args) {
+	const { stdout } = opts.requireSudo === true ? await execFile$1("sudo", [
+		"-n",
+		"nft",
+		...args
+	], { timeout: NFT_TIMEOUT_MS }) : await execFile$1("nft", args, { timeout: NFT_TIMEOUT_MS });
+	return stdout;
+}
+/**
+* Validate that nftables is available and the process has NET_ADMIN capability.
+* Attempts `nft list tables` -- if it fails:
+*   - ENOENT: nft binary not installed
+*   - EPERM: nft binary present but NET_ADMIN capability missing
+* Throws with a clear error message in both cases.
+*/
+async function validateNftablesAvailability(opts = {}) {
+	try {
+		await nft(opts, "list", "tables");
+	} catch (err) {
+		const message = toErrorMessage(err);
+		if (message.includes("ENOENT") || message.includes("not found")) throw new Error("nftables binary not found at /usr/sbin/nft. The orchestrator container image must include nftables (apk add nftables). Network isolation for agents cannot be established without nftables.");
+		if (message.includes("EPERM") || message.includes("Operation not permitted")) throw new Error("nftables operation denied -- missing NET_ADMIN capability. Start the orchestrator container with --cap-add=NET_ADMIN. Network isolation for agents requires this capability.");
+		throw new Error(`nftables validation failed: ${message}`);
+	}
+}
+/**
+* Ensure the nftables table and the chains this module writes to exist.
+* Idempotent -- safe to call multiple times.
+*
+* Every chain is verified individually. A bare "does the table exist?" check is
+* not enough: the Firecracker host provisioner creates the table before this
+* module ever runs, so a table with no `forward` chain satisfied the old early
+* return — and then every `addIsolationRules` failed with nft's "No such file
+* or directory", leaving every VM on that host with no isolation rules at all.
+*
+* @param opts - `table` selects the table; `requireBaselineChain` additionally
+* ensures the regular {@link BASELINE_CHAIN} exists (Firecracker hosts, whose
+* `forward` chain ends in a jump to it).
+*/
+async function ensureKiciTable(opts = {}) {
+	const table = tableOf(opts);
+	await nft(opts, "add", "table", "ip", table);
+	await nft(opts, "add", "chain", "ip", table, "forward", "{ type filter hook forward priority 0; policy accept; }");
+	await ensureKiciInputChain(opts);
+	await nft(opts, "add", "chain", "ip", table, "output", "{ type filter hook output priority 0; policy accept; }");
+	if (opts.requireBaselineChain === true) await nft(opts, "add", "chain", "ip", table, BASELINE_CHAIN);
+	logger.debug(`nftables table ip ${table} and chains ready`);
+}
+/** Chain in the kici table that filters host-destined sandbox traffic. */
+const INPUT_CHAIN = "input";
+/**
+* Ensure the kici table and its `input` chain exist. Idempotent — `nft add` is
+* a create-or-noop for both, so there is no check-then-create window.
+*
+* The chain's policy is `accept` because it is a base chain on the host's own
+* input hook: everything the host itself receives passes through it, and a
+* default-deny there would take the machine off the network. The deny lives in
+* the per-identifier terminal drop {@link buildHostAccessRuleOps} emits.
+*/
+async function ensureKiciInputChain(opts = {}) {
+	const table = tableOf(opts);
+	await nft(opts, "add", "table", "ip", table);
+	await nft(opts, "add", "chain", "ip", table, INPUT_CHAIN, "{ type filter hook input priority 0; policy accept; }");
+}
+/**
+* Apply one identifier's host-access rules to the `input` chain, replacing
+* whatever it had.
+*
+* The pre-clean is not an optimisation. Bridge networks recycle addresses, so a
+* crash or a `kill -9` leaves the previous holder's accepts behind for the next
+* container on that IP to inherit — which is the boundary this chain exists to
+* hold. Applying without removing first would also stack a second terminal drop
+* above the first run's accepts, shadowing every one of them.
+*
+* Rules are `insert`ed in reverse so the block lands at the chain head in the
+* order {@link buildHostAccessRuleOps} returns: accepts first, terminal drop
+* last. Inserting forwards would put the drop above the accepts and deny
+* everything.
+*/
+async function addHostIsolationRules(identifier, hostAccess, matchMode = "saddr", opts = {}) {
+	await ensureKiciInputChain(opts);
+	await removeHostIsolationRules(identifier, opts);
+	const rules = buildHostAccessRuleOps(matchMode === "iifname" ? ["iifname", identifier] : [
+		"ip",
+		"saddr",
+		identifier
+	], hostAccess);
+	for (const tokens of [...rules].reverse()) await nft(opts, "insert", "rule", "ip", tableOf(opts), INPUT_CHAIN, ...tokens);
+	logger.info(`Host-access rules applied for ${identifier}: ${hostAccess.length > 0 ? hostAccess.join(", ") : "nothing (host fully denied)"}`);
+}
+/**
+* A table's `input` chain, as `nft -a list chain` prints it, or `null` when the
+* table or the chain does not exist yet.
+*
+* Returning `null` rather than throwing keeps "the chain is not there" distinct
+* from "the chain is there and holds nothing", which a caller deciding whether
+* a rule set is already installed has to be able to tell apart.
+*/
+async function readInputChain(opts = {}) {
+	try {
+		return await nft(opts, "-a", "list", "chain", "ip", tableOf(opts), INPUT_CHAIN);
+	} catch {
+		return null;
+	}
+}
+/**
+* Remove one identifier's rules from the `input` chain.
+*
+* Best-effort: a missing chain, or a rule another path already deleted, must
+* not abort a teardown.
+*/
+async function removeHostIsolationRules(identifier, opts = {}) {
+	const table = tableOf(opts);
+	const output = await readInputChain(opts);
+	if (output === null) return;
+	const handles = parseRuleHandles(output, identifier);
+	if (handles.length === 0) return;
+	for (const handle of handles.sort((a, b) => b - a)) try {
+		await nft(opts, "delete", "rule", "ip", table, INPUT_CHAIN, "handle", String(handle));
+	} catch (err) {
+		logger.warn(`Failed to delete input rule handle ${handle}: ${toErrorMessage(err)}`);
+	}
+	logger.info(`Removed ${handles.length} host-access rules for ${identifier}`);
+}
+/**
+* Name of the regular (non-hooked) chain holding the host baseline rules.
+*
+* The Firecracker host provisioner puts its six source-scoped baseline rules
+* here and reaches them with a `jump` appended as the `forward` chain's LAST
+* rule. Two properties follow, and both are load-bearing:
+*
+*  - **Per-VM rules always win.** They are inserted at the `forward` head, so
+*    every one of them is evaluated before the jump. A per-VM `accept`
+*    terminates the hook before the baseline can re-drop an allowlisted
+*    destination, and a per-VM `denyAll` drop is terminal before the
+*    baseline's blanket internet `accept` can let the packet out.
+*  - **A self-heal can rebuild the baseline without touching live VMs.** The
+*    provisioner flushes and refills only this chain, so it never has to
+*    `delete table` — which used to drop every running VM's isolation rules
+*    fail-open.
+*
+* A regular chain reached by `jump` rather than a second base chain at a lower
+* priority: in netfilter an `accept` ends only the current base chain, so an
+* allowlist accept in an earlier base chain would still be re-evaluated — and
+* dropped — by the baseline's 10.0.0.0/8 rule in the later one.
+*/
+const BASELINE_CHAIN = "baseline";
+/**
+* Build the per-identifier isolation rules in their final head-to-tail order.
+*
+* nftables is first-match-wins within a chain and `accept` is terminal, so the
+* order below is the whole security property:
+*
+*  1. gateway accept
+*  2. allowlisted CIDR accepts — ahead of the drops, so an allowlisted
+*     destination inside a dropped range (a 10.x registry endpoint behind the
+*     10.0.0.0/8 drop) is accepted before the drop is evaluated
+*  3. RFC1918 drops
+*  4. cloud-metadata drop
+*  5. `denyAll` drop
+*
+* {@link addIsolationRules} lands them in exactly this order by applying the
+* list in REVERSE with `insert`, which puts the whole block at the chain head —
+* ahead of the tail `jump` to {@link BASELINE_CHAIN}.
+*
+* @returns one token list per rule, in final head-to-tail order
+*/
+function buildIsolationRuleOps(matchClause, gatewayIp, networkPolicy) {
+	const rules = [];
+	rules.push([
+		...matchClause,
+		"ip",
+		"daddr",
+		gatewayIp,
+		"accept"
+	]);
+	for (const cidr of networkPolicy?.allowlist ?? []) rules.push([
+		...matchClause,
+		"ip",
+		"daddr",
+		cidr,
+		"accept"
+	]);
+	for (const range of RFC1918_RANGES) rules.push([
+		...matchClause,
+		"ip",
+		"daddr",
+		range,
+		"drop"
+	]);
+	rules.push([
+		...matchClause,
+		"ip",
+		"daddr",
+		METADATA_RANGE,
+		"drop"
+	]);
+	if (networkPolicy?.denyAll) rules.push([...matchClause, "drop"]);
+	return rules;
+}
+/**
+* Add network isolation rules for one identifier (a TAP interface name, or a
+* container's source IP).
+*
+* Every rule is `insert`ed, applying {@link buildIsolationRuleOps} in reverse,
+* so the block lands at the chain head in its documented order — ahead of any
+* host baseline reached by a tail `jump`.
+*
+* @param identifier - Network interface name or source IP to match (e.g., "veth-abc123" or "172.30.0.5")
+* @param gatewayIp - Gateway IP that must remain accessible (e.g., "10.0.0.1")
+* @param networkPolicy - Optional policy with allowlist and denyAll settings
+* @param matchMode - How to match traffic: 'iifname' for interface name (default), 'saddr' for source IP
+*/
+async function addIsolationRules(identifier, gatewayIp, networkPolicy, matchMode = "iifname", opts = {}) {
+	const matchLabel = matchMode === "iifname" ? `interface ${identifier}` : `source IP ${identifier}`;
+	logger.info(`Adding isolation rules for ${matchLabel} (gateway: ${gatewayIp})`);
+	const matchClause = matchMode === "iifname" ? ["iifname", identifier] : [
+		"ip",
+		"saddr",
+		identifier
+	];
+	if (networkPolicy?.allowlist) for (const cidr of networkPolicy.allowlist) logger.debug(`Allowlisting ${cidr} for ${matchLabel}`);
+	if (networkPolicy?.denyAll) logger.info(`Blocking all outbound traffic for ${matchLabel} (denyAll)`);
+	const rules = buildIsolationRuleOps(matchClause, gatewayIp, networkPolicy);
+	for (const tokens of [...rules].reverse()) await nft(opts, "insert", "rule", "ip", tableOf(opts), "forward", ...tokens);
+	logger.info(`Isolation rules applied for ${matchLabel}`);
+}
+/**
+* A table's `forward` chain, as `nft -a list chain` prints it, or `null` when
+* the table or the chain does not exist yet.
+*
+* The text form is what {@link parseRuleHandles} reads, and it is also what a
+* caller asking whether a rule set is ALREADY installed — rather than deleting
+* it — compares against the rule text {@link buildIsolationRuleOps} emits.
+* {@link listForwardRules} cannot answer for a subnet identifier: nft reports a
+* subnet source as a prefix object, which its classifier treats as "not a
+* per-agent rule" on purpose.
+*
+* Returning `null` rather than throwing keeps "the chain is not there" distinct
+* from "the chain is there and holds nothing", exactly as {@link readInputChain}
+* does for the sibling chain. The distinction is load-bearing in the install
+* direction: a caller checking whether a rule set is present must read a missing
+* chain as NOT installed and go install it, and a throw instead aborts the whole
+* ensure path — which for the agent's job network degrades to a container on an
+* unfiltered bridge.
+*/
+async function readForwardChain(opts = {}) {
+	try {
+		return await nft(opts, "-a", "list", "chain", "ip", tableOf(opts), "forward");
+	} catch {
+		return null;
+	}
+}
+/**
+* Remove every isolation rule this identifier owns, in both the `forward` and
+* the `input` chain. Called during agent cleanup, and as the pre-clean before a
+* re-add.
+*
+* Both chains are swept because they are one boundary: an identifier is a
+* container IP or a TAP name, addresses are recycled, and leaving the input
+* chain's accepts behind hands the next tenant on that address the previous
+* one's host reachability.
+*
+* Best-effort: logs errors but does not throw (cleanup must not block
+* destruction).
+*
+* @param interfaceName - Network interface name or source IP whose rules should be removed
+*/
+async function removeIsolationRules(interfaceName, opts = {}) {
+	logger.info(`Removing isolation rules for interface ${interfaceName}`);
+	await removeHostIsolationRules(interfaceName, opts);
+	try {
+		const table = tableOf(opts);
+		const output = await readForwardChain(opts);
+		if (output === null) return;
+		const handles = parseRuleHandles(output, interfaceName);
+		if (handles.length === 0) {
+			logger.debug(`No rules found for interface ${interfaceName}`);
+			return;
+		}
+		for (const handle of handles.sort((a, b) => b - a)) try {
+			await nft(opts, "delete", "rule", "ip", table, "forward", "handle", String(handle));
+		} catch (err) {
+			logger.warn(`Failed to delete rule handle ${handle}: ${err}`);
+		}
+		logger.info(`Removed ${handles.length} rules for interface ${interfaceName}`);
+	} catch (err) {
+		logger.warn(`Failed to list/remove rules for ${interfaceName}: ${err}`);
+	}
+}
+/**
+* Read every rule in a table's forward chain, with its handle and the per-agent
+* identifier it matches on.
+*
+* This is the enumerate-what-is-there half of rule management; the
+* identifier-known delete path is {@link parseRuleHandles}. Reconciliation
+* needs this one: rules are removed only on the synchronous teardown paths this
+* process drives, so an orchestrator crash, a `kill -9`, or a VM that dies
+* while the orchestrator is down strands `ip saddr <ip> …` rules in the shared
+* chain forever. The allocator then hands that IP to another tenant, who
+* inherits the dead job's allowlist.
+*
+* Returns an empty list rather than throwing when the chain cannot be read —
+* the caller is a best-effort sweep, and a failed read must not be mistaken
+* for "nothing is there".
+*/
+async function listForwardRules(opts = {}) {
+	const table = tableOf(opts);
+	let parsed;
+	try {
+		const output = await nft(opts, "-j", "-a", "list", "chain", "ip", table, "forward");
+		parsed = JSON.parse(output);
+	} catch (err) {
+		logger.warn(`Failed to list forward rules in ip ${table}: ${toErrorMessage(err)}`);
+		return [];
+	}
+	const entries = parsed?.nftables;
+	if (!Array.isArray(entries)) return [];
+	const rules = [];
+	for (const entry of entries) {
+		const rule = entry.rule;
+		if (!rule || typeof rule.handle !== "number") continue;
+		rules.push({
+			handle: rule.handle,
+			identifier: identifierOf(rule.expr)
+		});
+	}
+	return rules;
+}
+/**
+* The concrete per-agent identifier a rule's expression list matches on.
+*
+* A per-agent rule matches a single host — `ip saddr 10.0.0.5` — or one exact
+* interface — `iifname "kici-a1b2c3d4"`. A host baseline rule matches a whole
+* subnet, which nft reports as a `{ prefix: … }` object, and every one of them
+* also names the `kici-*` interface wildcard. That difference is the only thing
+* separating "a live agent owns this" from "the host installed this".
+*
+* The whole rule is scanned before answering, and a wildcard anywhere in it
+* settles the question. Position is why: the host's inbound established/related
+* rule LEADS with `iifname "<egress iface>"` — a concrete name carrying no `*`
+* — and names the wildcard only later, in `oifname`. Returning on the first
+* concrete interface therefore claimed that rule for a nonexistent agent named
+* after the host NIC, so the provisioning sweep spared it and every re-provision
+* left another stale copy behind.
+*/
+function identifierOf(expr) {
+	if (!Array.isArray(expr)) return null;
+	let candidate = null;
+	for (const node of expr) {
+		const match = node.match;
+		if (!match) continue;
+		const left = match.left;
+		const right = match.right;
+		if (typeof right !== "string") {
+			if (left?.payload?.field === "saddr") return null;
+			continue;
+		}
+		if (right.includes("*")) return null;
+		if (candidate !== null) continue;
+		if (left?.payload?.field === "saddr") candidate = right;
+		else if (left?.meta?.key === "iifname") candidate = right;
+	}
+	return candidate;
+}
+/**
+* Every per-agent identifier currently present in the forward chain, mapped to
+* the handles of the rules that carry it.
+*/
+async function listIsolationRules(opts = {}) {
+	const byIdentifier = /* @__PURE__ */ new Map();
+	for (const rule of await listForwardRules(opts)) {
+		if (rule.identifier === null) continue;
+		const handles = byIdentifier.get(rule.identifier);
+		if (handles) handles.push(rule.handle);
+		else byIdentifier.set(rule.identifier, [rule.handle]);
+	}
+	return byIdentifier;
+}
+/**
+* Delete rules from a table's forward chain by handle, highest first so earlier
+* deletions cannot shift the handles still to come.
+*
+* Best-effort per handle: a rule another path already removed must not abort
+* the rest of the sweep.
+*/
+async function deleteForwardRules(handles, opts = {}) {
+	const table = tableOf(opts);
+	let deleted = 0;
+	for (const handle of [...handles].sort((a, b) => b - a)) try {
+		await nft(opts, "delete", "rule", "ip", table, "forward", "handle", String(handle));
+		deleted++;
+	} catch (err) {
+		logger.warn(`Failed to delete rule handle ${handle} in ip ${table}: ${toErrorMessage(err)}`);
+	}
+	return deleted;
+}
+/**
+* Parse nft rule listing output and extract handles for rules matching a given identifier.
+* Handles lines like: `  iifname "veth-abc" ip daddr 10.0.0.0/8 drop # handle 42`
+*
+* @param nftOutput - Raw output from `nft -a list chain ip kici <chain>`
+* @param identifier - String to search for in each rule line (interface name or UID)
+* @returns Array of numeric rule handles
+*/
+function parseRuleHandles(nftOutput, identifier) {
+	const handles = [];
+	const lines = nftOutput.split("\n");
+	const escaped = identifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const boundaryRe = new RegExp(`(^|[\\s"])${escaped}([\\s"]|$)`);
+	for (const line of lines) {
+		if (!line.includes("# handle")) continue;
+		if (!boundaryRe.test(line)) continue;
+		const match = line.match(/# handle (\d+)/);
+		if (match) handles.push(parseInt(match[1], 10));
+	}
+	return handles;
+}
+//#endregion
+export { BASELINE_CHAIN, DEFAULT_NFT_TABLE, INPUT_CHAIN, JOB_NETWORK_SUBNET, METADATA_RANGE, RFC1918_RANGES, addHostIsolationRules, addIsolationRules, buildHostAccessRuleOps, buildIsolationRuleOps, deleteForwardRules, ensureKiciInputChain, ensureKiciTable, listForwardRules, listIsolationRules, parseHostAccess, parseRuleHandles, readForwardChain, readInputChain, removeHostIsolationRules, removeIsolationRules, validateNftablesAvailability };
+
+//# sourceMappingURL=nftables.js.map

package/dist/net/nftables.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=nftables.test.d.ts.map

package/dist/net.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Node-only network primitives, kept off the main barrel.
+ *
+ * `nftables.ts` promisifies `child_process.execFile` at module scope, so
+ * exporting it from `index.ts` would pull `node:child_process` into the module
+ * graph of every `@kici-dev/shared` consumer — including ones that only wanted
+ * a logger. Importers ask for it explicitly: `@kici-dev/shared/net`.
+ */
+export * from './net/nftables.js';
+//# sourceMappingURL=net.d.ts.map

package/dist/net.js

@@ -0,0 +1,3 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { BASELINE_CHAIN, DEFAULT_NFT_TABLE, INPUT_CHAIN, JOB_NETWORK_SUBNET, METADATA_RANGE, RFC1918_RANGES, addHostIsolationRules, addIsolationRules, buildHostAccessRuleOps, buildIsolationRuleOps, deleteForwardRules, ensureKiciInputChain, ensureKiciTable, listForwardRules, listIsolationRules, parseHostAccess, parseRuleHandles, readForwardChain, readInputChain, removeHostIsolationRules, removeIsolationRules, validateNftablesAvailability } from "./net/nftables.js";
+export { BASELINE_CHAIN, DEFAULT_NFT_TABLE, INPUT_CHAIN, JOB_NETWORK_SUBNET, METADATA_RANGE, RFC1918_RANGES, addHostIsolationRules, addIsolationRules, buildHostAccessRuleOps, buildIsolationRuleOps, deleteForwardRules, ensureKiciInputChain, ensureKiciTable, listForwardRules, listIsolationRules, parseHostAccess, parseRuleHandles, readForwardChain, readInputChain, removeHostIsolationRules, removeIsolationRules, validateNftablesAvailability };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/shared",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
   "keywords": [
     "ci",
@@ -93,6 +93,10 @@
     "./container-runtime": {
       "import": "./dist/container-runtime.js",
       "types": "./dist/container-runtime.d.ts"
+    },
+    "./net": {
+      "import": "./dist/net.js",
+      "types": "./dist/net.d.ts"
     }
   },
   "dependencies": {
@@ -117,8 +121,8 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.6.1",
-    "@kici-dev/engine": "0.6.1"
+    "@kici-dev/core": "0.7.0",
+    "@kici-dev/engine": "0.7.0"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "^2.10.0",

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/shared@0.6.1",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.6.1/db48b18d-53cd-4d58-81a0-e1d8e98d6c91",
+  "name": "@kici-dev/shared@0.7.0",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.7.0/b2f87154-22b3-4a53-b9e7-67876075dc20",
   "creationInfo": {
-    "created": "2026-09-02T03:01:10Z",
+    "created": "2026-09-11T07:37:23Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -564,9 +564,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.7.0",
       "name": "@kici-dev/core",
-      "versionInfo": "0.6.1",
+      "versionInfo": "0.7.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -577,16 +577,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.6.1"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.7.0"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.6.1",
+      "versionInfo": "0.7.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -597,7 +597,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.6.1"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.7.0"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
@@ -606,7 +606,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/shared",
-      "versionInfo": "0.6.1",
+      "versionInfo": "0.7.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -617,7 +617,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.6.1"
+          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.7.0"
         }
       ],
       "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
@@ -4896,62 +4896,62 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.140.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.10",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.7",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-yaml-2.9.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
@@ -4962,12 +4962,12 @@
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.6.1",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.7.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.6.1",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.7.0",
       "relationshipType": "DEPENDS_ON"
     },
     {