@camstack/system 1.0.2

package/dist/builtins/local-network/local-network.addon.js

@@ -0,0 +1,489 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_chunk = require("../../chunk-Cek0wNdY.js");
+let _camstack_types = require("@camstack/types");
+let node_os = require("node:os");
+node_os = require_chunk.__toESM(node_os);
+//#region src/builtins/local-network/local-network.addon.ts
+/**
+* local-network — hub-only system cap implementation.
+*
+* Wraps `os.networkInterfaces()` with:
+*   - Coarse kind classification (lan/wifi/docker/vpn/loopback/other)
+*   - Auto-select heuristic for the outbound interface
+*   - Periodic poll (30s) + diff to emit `LocalNetworkChanged` events
+*     so subscribers can react to DHCP renewals, VPN connect, etc.
+*   - `getConnectionEndpoints()` — ranked URL list for SDK clients
+*
+* Does NOT poll the cloudflare-tunnel state directly; the public
+* tunnel hostname (if any) is provided by `network-access` consumers
+* via `NetworkTunnelStarted/Stopped` events on the bus, so the cap
+* stays free of cross-addon dependencies.
+*/
+/**
+* Forked `mesh-network` provider addon ids `local-network` pull-reconciles
+* against. `mesh-network` is a COLLECTION cap, so a hub builtin's local
+* registry can't enumerate forked providers — we resolve each by addonId
+* via `getProviderByAddon`. New mesh providers (Headscale, ZeroTier) add
+* their id here.
+*/
+var MESH_PROVIDER_ADDON_IDS = ["tailscale-client"];
+var POLL_INTERVAL_MS = 3e4;
+var LocalNetworkAddon = class extends _camstack_types.BaseAddon {
+	pollTimer = null;
+	lastSnapshotKey = "";
+	/** Optional public hostname tracked from `NetworkTunnelStarted`/
+	*  `Stopped` events on the bus. */
+	publicHostname = "";
+	/**
+	* Mesh-reachable endpoint (Tailscale MagicDNS / 100.x), learned from
+	* the `MeshNetworkChanged` event-tail and refreshed by a pull-reconcile
+	* before each `getConnectionEndpoints` build (events are lossy — D8).
+	* `null` when no mesh provider is joined.
+	*/
+	meshEndpoint = null;
+	constructor() {
+		super({
+			allowedAddresses: [],
+			bootSeeded: false
+		});
+	}
+	async onInitialize() {
+		if (!this.config.bootSeeded) {
+			const seed = autoSeedAllowlist(this.enumerate());
+			await this.updateGlobalSettings({
+				allowedAddresses: seed,
+				bootSeeded: true
+			});
+			this.ctx.logger.info("local-network: first-boot auto-seed", { meta: { addresses: seed } });
+		}
+		const provider = {
+			list: async () => ({
+				interfaces: this.enumerate(),
+				probedAt: Date.now()
+			}),
+			getPreferred: async () => pickPreferred(applyAllowlist(this.enumerate(), this.config.allowedAddresses)),
+			getConnectionEndpoints: async (input) => {
+				const includeLoopback = input.includeLoopback ?? true;
+				const ipv4Only = input.ipv4Only ?? false;
+				const scheme = input.scheme ?? "http";
+				const allow = this.config.allowedAddresses;
+				const interfaces = applyAllowlist(this.enumerate(), allow);
+				await this.reconcileMeshEndpoint();
+				return { endpoints: buildEndpoints(interfaces, input.port, includeLoopback, ipv4Only, this.publicHostname, scheme, this.meshEndpoint) };
+			},
+			getAllowedAddresses: async () => ({ addresses: this.config.allowedAddresses }),
+			resetAllowlistToBestMatch: async () => {
+				const seed = autoSeedAllowlist(this.enumerate());
+				await this.updateGlobalSettings({
+					allowedAddresses: seed,
+					bootSeeded: true
+				});
+				this.ctx.logger.info("local-network: allowlist reset to auto-seed", { meta: { count: seed.length } });
+				return { addresses: seed };
+			},
+			setAllowedAddresses: async ({ addresses }) => {
+				const known = new Set(this.enumerate().map((i) => i.address));
+				const cleaned = [...new Set(addresses)].filter((a) => known.has(a));
+				await this.updateGlobalSettings({ allowedAddresses: cleaned });
+				this.ctx.logger.info("local-network: allowlist updated", { meta: {
+					count: cleaned.length,
+					dropped: addresses.length - cleaned.length
+				} });
+				return { success: true };
+			}
+		};
+		this.lastSnapshotKey = snapshotKey(this.enumerate());
+		this.pollTimer = setInterval(() => this.detectChanges(), POLL_INTERVAL_MS);
+		this.pollTimer.unref?.();
+		this.ctx.eventBus?.subscribe({ category: _camstack_types.EventCategory.NetworkTunnelStarted }, (event) => {
+			const data = event.data ?? {};
+			if (typeof data.url === "string") try {
+				const hostname = new URL(data.url).hostname;
+				if (hostname && !hostname.endsWith(".placeholder") && !hostname.startsWith("pending.")) this.setPublicHostname(hostname);
+			} catch {}
+		});
+		this.ctx.eventBus?.subscribe({ category: _camstack_types.EventCategory.NetworkTunnelStopped }, () => this.setPublicHostname(""));
+		this.ctx.eventBus?.subscribe({ category: _camstack_types.EventCategory.MeshNetworkChanged }, (event) => {
+			const data = event.data ?? {};
+			const host = typeof data.host === "string" ? data.host : "";
+			const port = typeof data.port === "number" ? data.port : 0;
+			this.setMeshEndpoint(host && port > 0 ? {
+				host,
+				port
+			} : null);
+		});
+		this.ctx.logger.info("local-network initialized", { meta: { interfaceCount: this.enumerate().length } });
+		return [{
+			capability: _camstack_types.localNetworkCapability,
+			provider
+		}];
+	}
+	async onShutdown() {
+		if (this.pollTimer) {
+			clearInterval(this.pollTimer);
+			this.pollTimer = null;
+		}
+	}
+	/**
+	* Other hub addons (e.g. cloudflare-tunnel) signal the active public
+	* FQDN by emitting `NetworkTunnelStarted` on the bus — handled in
+	* `onInitialize`. This setter exists for tests + future direct
+	* callers; cleared by passing an empty string.
+	*/
+	setPublicHostname(hostname) {
+		if (this.publicHostname === hostname) return;
+		this.publicHostname = hostname;
+		this.ctx.logger.info("local-network: public hostname updated", { meta: { hostname: hostname || "(cleared)" } });
+	}
+	/**
+	* Replace the cached mesh endpoint. Set from the `MeshNetworkChanged`
+	* event-tail + the pull-reconcile; exposed for tests + future direct
+	* callers. Pass `null` to clear (mesh left / no provider joined).
+	*/
+	setMeshEndpoint(endpoint) {
+		const prev = this.meshEndpoint;
+		if (prev?.host === endpoint?.host && prev?.port === endpoint?.port) return;
+		this.meshEndpoint = endpoint;
+		this.ctx.logger.info("local-network: mesh endpoint updated", { meta: {
+			host: endpoint?.host || "(cleared)",
+			port: endpoint?.port ?? 0
+		} });
+	}
+	/**
+	* Refresh the cached mesh endpoint from the authoritative forked
+	* `mesh-network` provider(s). `mesh-network` is a COLLECTION cap on a
+	* forked addon, so the hub builtin can't see it via `ctx.api` /
+	* `getCollectionEntries` — we resolve each provider by addonId through
+	* the hub-side `capabilityRegistry.getProviderByAddon` resolver (the
+	* same mechanism `device-manager` uses for cross-process exporter
+	* contributions). Best-effort: a provider that's absent / errors /
+	* not joined simply contributes nothing.
+	*/
+	async reconcileMeshEndpoint() {
+		const registry = this.ctx.kernel.capabilityRegistry;
+		if (!registry) return;
+		for (const addonId of MESH_PROVIDER_ADDON_IDS) {
+			const provider = registry.getProviderByAddon("mesh-network", addonId);
+			if (!provider) continue;
+			try {
+				const status = await provider.getStatus();
+				if (!status.joined) {
+					this.setMeshEndpoint(null);
+					continue;
+				}
+				const host = status.magicDnsHostname || status.meshIp;
+				const port = (status.endpoints.find((e) => e.id === "magicdns") ?? status.endpoints.find((e) => e.id === "mesh-ipv4"))?.port ?? 0;
+				this.setMeshEndpoint(host && port > 0 ? {
+					host,
+					port
+				} : null);
+				return;
+			} catch (err) {
+				this.ctx.logger.debug("local-network: mesh reconcile skipped", { meta: {
+					addonId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+	}
+	enumerate() {
+		return enumerateOsInterfaces(node_os.networkInterfaces());
+	}
+	detectChanges() {
+		const interfaces = this.enumerate();
+		const key = snapshotKey(interfaces);
+		if (key === this.lastSnapshotKey) return;
+		this.ctx.logger.info("local-network: interface set changed", { meta: {
+			count: interfaces.length,
+			key
+		} });
+		this.lastSnapshotKey = key;
+		this.ctx.eventBus?.emit({
+			id: `local-network-changed-${Date.now()}`,
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "core",
+				id: "local-network"
+			},
+			category: _camstack_types.EventCategory.LocalNetworkChanged,
+			data: { count: interfaces.length }
+		});
+	}
+};
+function enumerateOsInterfaces(ifaces) {
+	const raw = [];
+	for (const [name, addrs] of Object.entries(ifaces)) {
+		if (!addrs) continue;
+		for (const a of addrs) {
+			if (a.family !== "IPv4" && a.family !== "IPv6") continue;
+			raw.push({
+				name,
+				family: a.family,
+				address: a.address,
+				cidr: a.cidr ?? "",
+				netmask: a.netmask,
+				internal: a.internal,
+				mac: a.mac
+			});
+		}
+	}
+	const classified = raw.map((r) => {
+		const kind = classifyKind(r.name, r.address, r.internal);
+		const reachableKind = kind === "lan" || kind === "wifi";
+		const plausible = !r.internal && reachableKind && isPlausibleAutoSeed(r.address, r.family);
+		const plausibleReason = plausible ? "" : explainNonPlausible({
+			kind,
+			family: r.family,
+			address: r.address,
+			internal: r.internal
+		});
+		return {
+			name: r.name,
+			family: r.family,
+			address: r.address,
+			cidr: r.cidr,
+			netmask: r.netmask,
+			internal: r.internal,
+			mac: r.mac,
+			kind,
+			preferred: false,
+			plausible,
+			plausibleReason
+		};
+	});
+	const preferred = pickPreferred(classified);
+	return classified.map((iface) => ({
+		...iface,
+		preferred: preferred !== null && iface.name === preferred.name && iface.address === preferred.address
+	}));
+}
+/**
+* Filter the interface list by the operator's allowlist. Empty
+* allowlist = no-op (every interface passes); otherwise only entries
+* whose `address` matches an allowlist entry remain. Loopback always
+* survives so the SDK keeps `127.0.0.1` as the last-resort fallback.
+*/
+function applyAllowlist(interfaces, allowed) {
+	if (allowed.length === 0) return interfaces;
+	const set = new Set(allowed);
+	return interfaces.filter((i) => i.kind === "loopback" || set.has(i.address));
+}
+/**
+* Rank interfaces and pick the auto-selected outbound one. See the
+* cap's `getPreferred` doc for the heuristic.
+*/
+function pickPreferred(interfaces) {
+	const candidates = interfaces.filter((i) => !i.internal && i.family === "IPv4" && !i.address.startsWith("169.254.") && i.kind !== "loopback");
+	if (candidates.length === 0) return null;
+	const kindRank = {
+		lan: 1,
+		wifi: 2,
+		vpn: 3,
+		docker: 4,
+		other: 5,
+		loopback: 99
+	};
+	return [...candidates].toSorted((a, b) => {
+		const ra = kindRank[a.kind];
+		const rb = kindRank[b.kind];
+		if (ra !== rb) return ra - rb;
+		return prefixLen(b.netmask) - prefixLen(a.netmask);
+	})[0] ?? null;
+}
+/**
+* Build the ordered candidate URL list. Priority schema:
+*   0       — preferred LAN IPv4
+*   10+     — other LAN IPv4
+*   100     — public tunnel hostname (always HTTPS)
+*   150     — mesh endpoint (Tailscale MagicDNS / 100.x, always HTTPS)
+*   200+    — LAN IPv6
+*   1000    — loopback (last resort)
+*
+* The mesh endpoint ranks just below a true public funnel (a Funnel is
+* reachable by ANY client; the mesh needs the peer on the same tailnet)
+* but above the IPv6 / loopback fallbacks — giving remote, mesh-joined
+* clients a working candidate when no public tunnel is up.
+*
+* `scheme` controls LAN + loopback URLs. Browsers running over HTTPS
+* block `http://` candidates as mixed content, so callers loaded over
+* HTTPS should pass `scheme: 'https'` even when probing a LAN IP — the
+* hub's cert manager already issues a SAN-multi cert covering local
+* interfaces. The public tunnel + mesh endpoint always emit `https://`
+* (the tunnel edge / the hub itself terminates TLS).
+*/
+function buildEndpoints(interfaces, port, includeLoopback, ipv4Only, publicHostname, scheme = "http", meshEndpoint = null) {
+	const out = [];
+	let priority = 0;
+	const preferred = pickPreferred(interfaces);
+	const emit = (iface, kind, label, baseUrl, pri) => {
+		out.push({
+			label,
+			baseUrl,
+			kind,
+			interfaceKind: iface.kind,
+			plausible: iface.plausible,
+			plausibleReason: iface.plausibleReason,
+			priority: pri
+		});
+	};
+	if (preferred) emit(preferred, "lan-ipv4", `${formatKind(preferred.kind)} — ${preferred.name}`, `${scheme}://${preferred.address}:${port}`, priority++);
+	for (const iface of interfaces) {
+		if (iface.internal || iface.family !== "IPv4") continue;
+		if (iface.kind === "loopback") continue;
+		if (preferred && iface.name === preferred.name && iface.address === preferred.address) continue;
+		if (iface.address.startsWith("169.254.")) continue;
+		emit(iface, "lan-ipv4", `${formatKind(iface.kind)} — ${iface.name}`, `${scheme}://${iface.address}:${port}`, 10 + priority++);
+	}
+	if (publicHostname) out.push({
+		label: "Public tunnel",
+		baseUrl: `https://${publicHostname}`,
+		kind: "public",
+		interfaceKind: "public",
+		plausible: true,
+		plausibleReason: "",
+		priority: 100
+	});
+	if (meshEndpoint && meshEndpoint.host) out.push({
+		label: "Mesh (Tailscale)",
+		baseUrl: `https://${meshEndpoint.host}:${meshEndpoint.port}`,
+		kind: "public",
+		interfaceKind: "vpn",
+		plausible: true,
+		plausibleReason: "",
+		priority: 150
+	});
+	if (!ipv4Only) {
+		let v6prio = 200;
+		for (const iface of interfaces) {
+			if (iface.internal || iface.family !== "IPv6") continue;
+			if (iface.kind === "loopback") continue;
+			if (iface.address.startsWith("fe80:")) continue;
+			emit(iface, "lan-ipv6", `${formatKind(iface.kind)} — ${iface.name} (IPv6)`, `${scheme}://[${iface.address}]:${port}`, v6prio++);
+		}
+	}
+	if (includeLoopback) out.push({
+		label: "Loopback",
+		baseUrl: `${scheme}://127.0.0.1:${port}`,
+		kind: "loopback",
+		interfaceKind: "loopback",
+		plausible: false,
+		plausibleReason: "Loopback — last-resort fallback when no other endpoint responds.",
+		priority: 1e3
+	});
+	return out.toSorted((a, b) => a.priority - b.priority);
+}
+/**
+* First-boot heuristic: which addresses should the allowlist start
+* with? Includes LAN + Wi-Fi IPv4 addresses + plausible IPv6:
+*
+*   - **IPv4**: skip link-local (`169.254.*`), keep the rest.
+*   - **IPv6**: skip link-local (`fe80::*`), unspecified, and
+*     multicast. Keep ULAs (`fc00::/7` → `fc??:` / `fd??:`) and Global
+*     Unicast addresses (`2000::/3` → `2???`/`3???`). Privacy-extension
+*     temporary addresses get included by default; the operator can
+*     prune them from the Network Addresses tab if the rotating IPs
+*     become a nuisance.
+*
+* Skips docker/vpn/loopback/other entirely — those stay opt-in.
+*/
+function autoSeedAllowlist(interfaces) {
+	return [...new Set(interfaces.filter((i) => !i.internal && (i.kind === "lan" || i.kind === "wifi") && isPlausibleAutoSeed(i.address, i.family)).map((i) => i.address))];
+}
+/**
+* Per-interface tooltip text surfaced on the "Unlikely usable" badge.
+* Server-side so the UI doesn't re-derive the rationale (single source
+* of truth). Returns `''` for plausible entries; the addon overlays
+* this on the `LocalInterface.plausibleReason` field.
+*/
+function explainNonPlausible(input) {
+	if (input.internal) return "Internal interface (loopback) — not reachable from clients.";
+	if (input.kind === "docker") return "Docker bridge — only reachable from inside the container network.";
+	if (input.kind === "vpn") return "VPN tunnel — only reachable while the VPN is connected.";
+	if (input.kind === "other") return "Unrecognised interface kind — verify reachability before pinning.";
+	if (input.family === "IPv6") {
+		const a = input.address.toLowerCase();
+		if (a.startsWith("fe80:")) return "IPv6 link-local — only reachable on the same link, not routed.";
+		if (a.startsWith("ff")) return "IPv6 multicast — not a unicast address.";
+		if (a === "::" || a === "::1") return "IPv6 loopback / unspecified — not a public address.";
+		return "IPv6 address outside the ULA / GUA ranges — verify before pinning.";
+	}
+	if (input.address.startsWith("169.254.")) return "IPv4 link-local (RFC 3927) — only valid when DHCP fails.";
+	return "Address looks unusual for client traffic — verify before pinning.";
+}
+/**
+* Per-address gate used by `autoSeedAllowlist`. Exposed for tests so
+* we can pin every classification rule without standing up the addon.
+*/
+function isPlausibleAutoSeed(address, family) {
+	if (family === "IPv4") {
+		if (address.startsWith("169.254.")) return false;
+		return true;
+	}
+	const a = address.toLowerCase();
+	if (a === "::" || a === "::1") return false;
+	if (a.startsWith("fe80:")) return false;
+	if (a.startsWith("ff")) return false;
+	if (/^f[cd][0-9a-f]{0,2}:/.test(a)) return true;
+	if (/^[23][0-9a-f]{0,3}:/.test(a)) return true;
+	return false;
+}
+function classifyKind(name, address, internal) {
+	if (internal || name === "lo" || name.startsWith("lo")) return "loopback";
+	const n = name.toLowerCase();
+	if (n.startsWith("docker") || n.startsWith("br-") || n.startsWith("veth")) return "docker";
+	if (n.startsWith("tun") || n.startsWith("utun") || n.startsWith("wg") || n.startsWith("tap")) return "vpn";
+	if (n.startsWith("wlan") || n.startsWith("wlp") || n.startsWith("wlx")) return "wifi";
+	if (n.startsWith("eth") || /^en\d+$/.test(n)) {
+		if (process.platform === "darwin" && /^en[1-9]\d*$/.test(n)) return "wifi";
+		return "lan";
+	}
+	if (address === "127.0.0.1" || address === "::1") return "loopback";
+	return "other";
+}
+/** Convert an IPv4/IPv6 netmask string to its prefix length (CIDR). */
+function prefixLen(netmask) {
+	if (!netmask) return 0;
+	if (netmask.includes(":")) {
+		let bits = 0;
+		for (const group of netmask.split(":")) {
+			if (!group) continue;
+			const n = parseInt(group, 16);
+			if (!Number.isFinite(n)) break;
+			for (let mask = 32768; mask; mask >>= 1) if (n & mask) bits++;
+			else return bits;
+		}
+		return bits;
+	}
+	let bits = 0;
+	for (const part of netmask.split(".")) {
+		const n = parseInt(part, 10);
+		if (!Number.isFinite(n)) break;
+		for (let mask = 128; mask; mask >>= 1) if (n & mask) bits++;
+		else return bits;
+	}
+	return bits;
+}
+function snapshotKey(interfaces) {
+	return [...interfaces].map((i) => `${i.name}|${i.family}|${i.address}|${i.netmask}`).toSorted().join("\n");
+}
+function formatKind(kind) {
+	switch (kind) {
+		case "lan": return "LAN";
+		case "wifi": return "Wi-Fi";
+		case "vpn": return "VPN";
+		case "docker": return "Docker";
+		case "loopback": return "Loopback";
+		case "other": return "Other";
+	}
+}
+//#endregion
+exports.LocalNetworkAddon = LocalNetworkAddon;
+exports.applyAllowlist = applyAllowlist;
+exports.autoSeedAllowlist = autoSeedAllowlist;
+exports.buildEndpoints = buildEndpoints;
+exports.classifyKind = classifyKind;
+exports.enumerateOsInterfaces = enumerateOsInterfaces;
+exports.explainNonPlausible = explainNonPlausible;
+exports.isPlausibleAutoSeed = isPlausibleAutoSeed;
+exports.pickPreferred = pickPreferred;
+exports.prefixLen = prefixLen;