@camstack/addon-tailscale-client 0.1.12

package/dist/tailscale.addon.mjs

@@ -0,0 +1,627 @@
+import { BaseAddon, addonPagesSourceCapability, meshNetworkCapability } from "@camstack/types";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/tailscale-cli.ts
+/**
+* Thin wrapper around the `tailscale` CLI.
+*
+* Why CLI rather than the local API socket: `tailscaled` exposes its
+* control plane at `/var/run/tailscale/tailscaled.sock` but the wire
+* protocol is undocumented + the Go client is gnarly to port. The
+* `tailscale` CLI is the supported public interface, it covers every
+* action we need (`up`/`down`/`status --json`/`serve`/`funnel`), and
+* its output is stable JSON for `status` + non-fatal stderr for the
+* others.
+*
+* The wrapper:
+*   - resolves the binary path once (PATH lookup + macOS GUI install
+*     fallback at `/Applications/Tailscale.app/Contents/MacOS/Tailscale`).
+*   - exposes Promise-based methods returning typed shapes.
+*   - never spawns long-lived processes — every call is one-shot.
+*
+* Operator-side prerequisite: `tailscaled` must be installed +
+* running. The addon surfaces "binary missing" / "daemon not running"
+* errors verbatim so the operator can act.
+*/
+var execFileP = promisify(execFile);
+var TAILSCALE_CANDIDATES = [
+	"tailscale",
+	"/usr/bin/tailscale",
+	"/usr/local/bin/tailscale",
+	"/opt/homebrew/bin/tailscale",
+	"/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+];
+var TailscaleCliError = class extends Error {
+	stderr;
+	constructor(message, stderr = "") {
+		super(message);
+		this.stderr = stderr;
+		this.name = "TailscaleCliError";
+	}
+};
+var TailscaleCli = class {
+	resolvedBin = null;
+	/** Locate the `tailscale` binary once and cache the result. */
+	async resolveBin() {
+		if (this.resolvedBin) return this.resolvedBin;
+		for (const candidate of TAILSCALE_CANDIDATES) try {
+			await execFileP(candidate, ["version"], { timeout: 3e3 });
+			this.resolvedBin = candidate;
+			return candidate;
+		} catch {}
+		throw new TailscaleCliError("tailscale binary not found — install Tailscale from https://tailscale.com/download");
+	}
+	async version() {
+		const { stdout } = await execFileP(await this.resolveBin(), ["version"], { timeout: 5e3 });
+		return stdout.trim().split("\n")[0] ?? "";
+	}
+	async status() {
+		const bin = await this.resolveBin();
+		try {
+			const { stdout } = await execFileP(bin, ["status", "--json"], { timeout: 1e4 });
+			return JSON.parse(stdout);
+		} catch (err) {
+			const e = err;
+			throw new TailscaleCliError(`tailscale status failed: ${e.message}`, e.stderr ?? "");
+		}
+	}
+	/** Bring the daemon up with an auth key. Idempotent — calling
+	*  while already joined returns immediately. */
+	async up(input) {
+		const bin = await this.resolveBin();
+		const args = [
+			"up",
+			"--auth-key",
+			input.authKey,
+			"--reset"
+		];
+		if (input.hostname) args.push(`--hostname=${input.hostname}`);
+		try {
+			await execFileP(bin, args, { timeout: 6e4 });
+		} catch (err) {
+			const e = err;
+			throw new TailscaleCliError(`tailscale up failed: ${e.message}`, e.stderr ?? "");
+		}
+	}
+	/**
+	* Start an interactive `tailscale up` (no `--auth-key`) and resolve
+	* with the verification URL the daemon prints to stdout/stderr.
+	*
+	* The returned handle keeps the child process alive — it self-exits
+	* once the user authenticates in the browser, and `cancel()` kills
+	* it if the operator gives up.
+	*
+	* Times out (and kills the child) when no URL is observed within
+	* `timeoutMs` (default 5_000).
+	*/
+	async startInteractiveLogin(input = {}) {
+		const bin = await this.resolveBin();
+		const args = ["up"];
+		if (input.hostname) args.push(`--hostname=${input.hostname}`);
+		const timeoutMs = input.timeoutMs ?? 5e3;
+		const child = spawn(bin, args, { stdio: "pipe" });
+		const loginUrlPattern = /https:\/\/login\.tailscale\.com\/a\/[a-z0-9]+/i;
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			let stderrBuf = "";
+			const cancel = () => {
+				if (!child.killed) child.kill();
+			};
+			const timer = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				cancel();
+				reject(new TailscaleCliError(`tailscale up did not print a login URL within ${timeoutMs}ms`, stderrBuf));
+			}, timeoutMs);
+			const onData = (chunk) => {
+				if (settled) return;
+				const text = chunk.toString("utf8");
+				stderrBuf += text;
+				const match = text.match(loginUrlPattern);
+				if (match) {
+					settled = true;
+					clearTimeout(timer);
+					child.stdout.off("data", onData);
+					child.stderr.off("data", onData);
+					resolve({
+						loginUrl: match[0],
+						cancel
+					});
+				}
+			};
+			child.stdout.on("data", onData);
+			child.stderr.on("data", onData);
+			child.on("error", (err) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				reject(new TailscaleCliError(`tailscale up failed to spawn: ${err.message}`, stderrBuf));
+			});
+			child.on("exit", (code) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				reject(new TailscaleCliError(`tailscale up exited (code=${code ?? "null"}) before printing a login URL`, stderrBuf));
+			});
+		});
+	}
+	/** Leave the tailnet. After this the host's `100.x` address is
+	*  released until the next `up`. */
+	async down() {
+		const bin = await this.resolveBin();
+		try {
+			await execFileP(bin, ["down"], { timeout: 15e3 });
+		} catch (err) {
+			const e = err;
+			throw new TailscaleCliError(`tailscale down failed: ${e.message}`, e.stderr ?? "");
+		}
+	}
+	/** `tailscale serve` — exposes a local port to peers in the same
+	*  tailnet over HTTPS with auto-issued cert. Mutating call; the
+	*  daemon persists the rule across restarts. */
+	async serve(input) {
+		const bin = await this.resolveBin();
+		const args = input.enabled ? [
+			"serve",
+			"--bg",
+			`http://127.0.0.1:${input.port}`
+		] : [
+			"serve",
+			"--bg",
+			"off"
+		];
+		try {
+			await execFileP(bin, args, { timeout: 15e3 });
+		} catch (err) {
+			const e = err;
+			throw new TailscaleCliError(`tailscale serve failed: ${e.message}`, e.stderr ?? "");
+		}
+	}
+	/** `tailscale funnel` — exposes a local port to the open internet
+	*  via Tailscale's edge. Requires Funnel ACL grant in the tailnet
+	*  policy. Same shape as `serve`. */
+	async funnel(input) {
+		const bin = await this.resolveBin();
+		const args = input.enabled ? [
+			"funnel",
+			"--bg",
+			`http://127.0.0.1:${input.port}`
+		] : [
+			"funnel",
+			"--bg",
+			"off"
+		];
+		try {
+			await execFileP(bin, args, { timeout: 15e3 });
+		} catch (err) {
+			const e = err;
+			throw new TailscaleCliError(`tailscale funnel failed: ${e.message}`, e.stderr ?? "");
+		}
+	}
+};
+//#endregion
+//#region src/tailscale.addon.ts
+/**
+* Module-federation page declaration — picked up by the
+* `addon-pages-source` aggregator and surfaced on admin-ui once the
+* federation bundle is built. See `src/page/TailscaleClientOverviewPage.tsx`.
+*/
+var TAILSCALE_OVERVIEW_PAGES = [{
+	id: "tailscale-client",
+	label: "Tailscale",
+	icon: "network",
+	path: "/addon/tailscale-client",
+	remoteName: "addon_tailscale_client_page",
+	bundle: "remoteEntry.js"
+}];
+/**
+* Auto-rejoin backoff (#174). Five attempts at 5m → 15m → 30m → 60m → 60m,
+* then we stop retrying until either the operator manually joins (which
+* resets the counter) or the addon is restarted.
+*/
+var AUTO_REJOIN_BACKOFF_MS = [
+	5 * 6e4,
+	15 * 6e4,
+	30 * 6e4,
+	60 * 6e4,
+	60 * 6e4
+];
+var TailscaleClientAddon = class extends BaseAddon {
+	cli = new TailscaleCli();
+	/** Used by the orchestrator + UI labels. */
+	displayName = "Tailscale Client";
+	kind = "tailscale-client";
+	/** Index into AUTO_REJOIN_BACKOFF_MS for the next retry. Resets on success. */
+	rejoinAttempt = 0;
+	/** Timer handle for the next pending rejoin tick. `null` = idle. */
+	rejoinTimer = null;
+	/**
+	* Set while `startLogin` is in flight. The auto-rejoin loop skips when
+	* truthy so a silent `up --auth-key` doesn't collide with the
+	* browser-redirect login session.
+	*/
+	loginInFlight = false;
+	constructor() {
+		super({
+			authKey: "",
+			hostname: ""
+		});
+	}
+	async onInitialize() {
+		let cliReachable = false;
+		try {
+			const v = await this.cli.version();
+			cliReachable = true;
+			this.ctx.logger.info("Tailscale CLI ready", { meta: { version: v } });
+		} catch (err) {
+			this.ctx.logger.warn("Tailscale CLI not found — install from https://tailscale.com/download", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tailscale",
+					phase: "cli-missing"
+				}
+			});
+		}
+		if (cliReachable) setImmediate(() => {
+			this.tryAutoRejoin();
+		});
+		this.ctx.addDisposer(() => {
+			if (this.rejoinTimer !== null) {
+				clearTimeout(this.rejoinTimer);
+				this.rejoinTimer = null;
+			}
+		});
+		return [{
+			capability: meshNetworkCapability,
+			provider: {
+				getStatus: () => this.getStatus(),
+				join: ({ authKey, hostname }) => this.join({
+					authKey,
+					...hostname ? { hostname } : {}
+				}),
+				startLogin: ({ hostname }) => this.startLogin({ ...hostname ? { hostname } : {} }),
+				leave: () => this.leave(),
+				listPeers: () => this.listPeers(),
+				testConnection: ({ authKey }) => this.testConnection(authKey)
+			}
+		}, {
+			capability: addonPagesSourceCapability,
+			provider: {
+				id: "tailscale-client",
+				listPages: () => TAILSCALE_OVERVIEW_PAGES
+			}
+		}];
+	}
+	async getStatus() {
+		try {
+			const s = await this.cli.status();
+			const joined = s.BackendState === "Running";
+			const meshIp = s.Self?.TailscaleIPs?.[0] ?? "";
+			const magicDnsHostname = (s.Self?.DNSName ?? "").replace(/\.$/, "");
+			return {
+				joined,
+				meshIp,
+				magicDnsHostname,
+				peerCount: s.Peer ? Object.keys(s.Peer).length : 0,
+				endpoints: this.buildEndpoints(s, meshIp, magicDnsHostname)
+			};
+		} catch (err) {
+			return {
+				joined: false,
+				meshIp: "",
+				magicDnsHostname: "",
+				peerCount: 0,
+				endpoints: [],
+				error: err instanceof TailscaleCliError ? err.message : String(err)
+			};
+		}
+	}
+	buildEndpoints(s, meshIp, magicDnsHostname) {
+		const out = [];
+		if (meshIp) out.push({
+			id: "mesh-ipv4",
+			label: "Mesh IPv4",
+			scope: "mesh",
+			url: `http://${meshIp}`,
+			hostname: meshIp,
+			port: 0,
+			protocol: "http"
+		});
+		if (magicDnsHostname) out.push({
+			id: "magicdns",
+			label: "MagicDNS",
+			scope: "mesh",
+			url: `https://${magicDnsHostname}`,
+			hostname: magicDnsHostname,
+			port: 0,
+			protocol: "https"
+		});
+		return out;
+	}
+	async join(input) {
+		this.ctx.logger.info("tailscale: joining tailnet", {
+			meta: { hasHostname: !!input.hostname },
+			tags: {
+				topic: "tailscale",
+				phase: "join"
+			}
+		});
+		await this.cli.up({
+			authKey: input.authKey,
+			...input.hostname ? { hostname: input.hostname } : {}
+		});
+		await this.updateGlobalSettings({
+			authKey: input.authKey,
+			hostname: input.hostname ?? this.config.hostname
+		});
+		this.resetAutoRejoinBackoff();
+		this.ctx.logger.info("tailscale: joined", { tags: {
+			topic: "tailscale",
+			phase: "joined"
+		} });
+		return { joined: true };
+	}
+	/**
+	* Spawn `tailscale up` (no `--auth-key`) and return the login URL
+	* printed by the daemon. The child process keeps running until the
+	* operator authenticates in their browser — at which point it
+	* self-terminates. Caller polls `getStatus()` for `joined: true`.
+	*/
+	async startLogin(input) {
+		this.ctx.logger.info("tailscale: starting interactive login", {
+			meta: { hasHostname: !!input.hostname },
+			tags: {
+				topic: "tailscale",
+				phase: "login-start"
+			}
+		});
+		this.loginInFlight = true;
+		try {
+			const handle = await this.cli.startInteractiveLogin({ ...input.hostname ? { hostname: input.hostname } : {} });
+			if (input.hostname && input.hostname !== this.config.hostname) await this.updateGlobalSettings({
+				authKey: this.config.authKey,
+				hostname: input.hostname
+			});
+			this.ctx.logger.info("tailscale: login URL ready", { tags: {
+				topic: "tailscale",
+				phase: "login-url"
+			} });
+			this.loginInFlight = false;
+			return { loginUrl: handle.loginUrl };
+		} catch (err) {
+			this.loginInFlight = false;
+			throw err;
+		}
+	}
+	async leave() {
+		this.ctx.logger.info("tailscale: leaving tailnet", { tags: {
+			topic: "tailscale",
+			phase: "leave"
+		} });
+		await this.cli.down();
+		return { left: true };
+	}
+	/**
+	* Test the daemon + auth key WITHOUT committing to a join.
+	*/
+	async testConnection(authKey) {
+		let daemonVersion;
+		try {
+			daemonVersion = await this.cli.version();
+		} catch (err) {
+			return {
+				ok: false,
+				error: `tailscaled CLI not reachable: ${err instanceof Error ? err.message : String(err)}. Install Tailscale on the host.`
+			};
+		}
+		let tenant;
+		try {
+			const status = await this.cli.status();
+			if (status.MagicDNSSuffix) tenant = status.MagicDNSSuffix;
+		} catch {}
+		if (authKey !== void 0) {
+			const trimmed = authKey.trim();
+			if (!trimmed) return {
+				ok: false,
+				...tenant ? { tenant } : {},
+				...daemonVersion ? { daemonVersion } : {},
+				error: "Auth key is empty."
+			};
+			if (!trimmed.startsWith("tskey-auth-") && !trimmed.startsWith("tskey-client-")) return {
+				ok: false,
+				...tenant ? { tenant } : {},
+				...daemonVersion ? { daemonVersion } : {},
+				error: "Auth key does not look like a Tailscale key (expected prefix `tskey-auth-` or `tskey-client-`)."
+			};
+		}
+		return {
+			ok: true,
+			...tenant ? { tenant } : {},
+			...daemonVersion ? { daemonVersion } : {}
+		};
+	}
+	async listPeers() {
+		const s = await this.cli.status();
+		const peers = [];
+		if (s.Self) peers.push({
+			id: s.Self.ID,
+			hostname: s.Self.HostName,
+			addresses: s.Self.TailscaleIPs ?? [],
+			os: s.Self.OS,
+			online: s.Self.Online,
+			lastSeenMs: Date.now(),
+			isSelf: true
+		});
+		for (const p of Object.values(s.Peer ?? {})) {
+			const lastSeen = p.LastSeen ? Date.parse(p.LastSeen) : 0;
+			peers.push({
+				id: p.ID,
+				hostname: p.HostName,
+				addresses: p.TailscaleIPs ?? [],
+				os: p.OS,
+				online: p.Online,
+				lastSeenMs: Number.isFinite(lastSeen) ? lastSeen : 0,
+				isSelf: false
+			});
+		}
+		return { peers };
+	}
+	/**
+	* Single pass of the auto-rejoin probe. Called once on boot and then
+	* on the backoff timer. Internal contract:
+	*   - reads `BackendState` via the CLI
+	*   - skips when CLI unreachable / NoState / Running / no authKey /
+	*     login-redirect in flight
+	*   - otherwise runs `tailscale up --auth-key=<stored>` and resets
+	*     the backoff index on success
+	*   - on failure / continued non-Running state schedules the next
+	*     attempt with the configured backoff
+	*/
+	async tryAutoRejoin() {
+		if (this.rejoinTimer !== null) return;
+		if (this.loginInFlight) {
+			this.ctx.logger.info("auto-rejoin: skipping — redirect login in flight", { tags: {
+				topic: "tailscale",
+				phase: "auto-rejoin-skip"
+			} });
+			this.scheduleNextAutoRejoin();
+			return;
+		}
+		if (!this.config.authKey) return;
+		let state;
+		try {
+			state = (await this.cli.status()).BackendState;
+		} catch (err) {
+			this.ctx.logger.warn("auto-rejoin: status probe failed — CLI unreachable, skipping", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tailscale",
+					phase: "auto-rejoin-cli-missing"
+				}
+			});
+			return;
+		}
+		if (state === "Running") {
+			this.resetAutoRejoinBackoff();
+			return;
+		}
+		if (state === "NoState") {
+			this.ctx.logger.info("auto-rejoin: skipping — daemon NoState (first-time install)", { tags: {
+				topic: "tailscale",
+				phase: "auto-rejoin-no-state"
+			} });
+			return;
+		}
+		this.ctx.logger.info("auto-rejoin: attempting silent rejoin", {
+			meta: {
+				state,
+				attempt: this.rejoinAttempt + 1
+			},
+			tags: {
+				topic: "tailscale",
+				phase: "auto-rejoin-attempt"
+			}
+		});
+		try {
+			await this.cli.up({
+				authKey: this.config.authKey,
+				...this.config.hostname ? { hostname: this.config.hostname } : {}
+			});
+			this.ctx.logger.info("auto-rejoin: succeeded", { tags: {
+				topic: "tailscale",
+				phase: "auto-rejoin-ok"
+			} });
+			this.resetAutoRejoinBackoff();
+		} catch (err) {
+			this.ctx.logger.warn("auto-rejoin: tailscale up failed — will retry on backoff", {
+				meta: {
+					error: err instanceof Error ? err.message : String(err),
+					nextAttempt: this.rejoinAttempt + 1
+				},
+				tags: {
+					topic: "tailscale",
+					phase: "auto-rejoin-error"
+				}
+			});
+			this.scheduleNextAutoRejoin();
+		}
+	}
+	/** Reset the backoff index — used after a successful join (manual or auto). */
+	resetAutoRejoinBackoff() {
+		this.rejoinAttempt = 0;
+		if (this.rejoinTimer !== null) {
+			clearTimeout(this.rejoinTimer);
+			this.rejoinTimer = null;
+		}
+	}
+	/** Queue the next attempt or stop retrying once we hit the cap. */
+	scheduleNextAutoRejoin() {
+		if (this.rejoinAttempt >= AUTO_REJOIN_BACKOFF_MS.length) {
+			this.ctx.logger.warn("auto-rejoin: cap reached — giving up until next boot or manual join", {
+				meta: { attempts: this.rejoinAttempt },
+				tags: {
+					topic: "tailscale",
+					phase: "auto-rejoin-cap-reached"
+				}
+			});
+			return;
+		}
+		const delay = AUTO_REJOIN_BACKOFF_MS[this.rejoinAttempt] ?? AUTO_REJOIN_BACKOFF_MS[AUTO_REJOIN_BACKOFF_MS.length - 1] ?? 60 * 6e4;
+		this.rejoinAttempt += 1;
+		this.rejoinTimer = setTimeout(() => {
+			this.rejoinTimer = null;
+			this.tryAutoRejoin();
+		}, delay);
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "auth",
+			title: "Tailscale",
+			immediate: true,
+			description: "Joins the host to a Tailscale tailnet. Click \"Connect to Tailscale\" to open the Tailscale login page in your browser.",
+			fields: [
+				{
+					type: "info",
+					key: "tailscaleHelp",
+					label: "Prerequisites",
+					format: "html",
+					content: "Install <code>tailscaled</code> from <a href=\"https://tailscale.com/download\">tailscale.com/download</a>. On macOS the GUI app ships the CLI inside the .app bundle. For Serve / Funnel ingress, install <code>@camstack/addon-tailscale-ingress</code> separately.",
+					variant: "info"
+				},
+				this.field({
+					type: "text",
+					key: "hostname",
+					label: "Device Hostname (optional)",
+					description: "Override the hostname advertised in the tailnet. Empty = use the OS hostname.",
+					placeholder: "camstack-hub"
+				}),
+				{
+					type: "info",
+					key: "tailscaleConnectHint",
+					label: "Connect",
+					format: "html",
+					content: "Use the <strong>Connect to Tailscale</strong> action on the addon page to start the browser-redirect login flow. The admin UI will open a one-time Tailscale URL in a new tab; the host joins the tailnet once you authenticate.",
+					variant: "info"
+				}
+			]
+		}, {
+			id: "auth-advanced",
+			title: "Advanced / Headless",
+			style: "accordion",
+			defaultCollapsed: true,
+			immediate: true,
+			description: "Use a pre-generated auth key from admin.tailscale.com → Settings → Keys for headless / CI flows where opening a browser is not possible. When set, the addon also auto-rejoins on boot if the daemon dropped offline (5/15/30/60/60 min backoff).",
+			fields: [this.field({
+				type: "password",
+				key: "authKey",
+				label: "Pre-auth Key",
+				description: "tskey-auth-* token from the Tailscale admin console. Leave empty when using the browser-redirect flow above.",
+				showToggle: true
+			})]
+		}] });
+	}
+};
+//#endregion
+export { TailscaleClientAddon, TailscaleClientAddon as default, TailscaleCliError as n, TailscaleCli as t };
+
+//# sourceMappingURL=tailscale.addon.mjs.map