feat: finish the tailscale plugin, including SSH auth (B3)

plugins/tailscale/src/backend/host-metrics-manager.ts

@@ -0,0 +1,269 @@
+import type { Router } from "express";
+import type { Request, Response } from "express";
+import type { PluginContext } from "@termix/plugin-sdk/backend";
+import type { AuthenticatedRequest } from "../../../../src/types/index.js";
+import { DataCrypto } from "../../../../src/backend/utils/data-crypto.js";
+import { PermissionManager } from "../../../../src/backend/utils/permission-manager.js";
+import { resolveHostById } from "../../../../src/backend/hosts/host-resolver.js";
+import { execCommand } from "../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { execElevated } from "../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { isValidTailscaleAction } from "../../../../src/backend/hosts/metrics-shared/validation.js";
+import { withSshConnection } from "./ssh.js";
+
+export interface TailscalePeer {
+  hostname: string;
+  tailscaleIPs: string[];
+  online: boolean;
+  isExitNode: boolean;
+}
+
+export interface TailscaleData {
+  installed: boolean;
+  running: boolean;
+  tailscaleIPs: string[];
+  hostname: string | null;
+  peers: TailscalePeer[];
+  exitNodeInUse: boolean;
+}
+
+const PROBE_CMD = [
+  "command -v tailscale >/dev/null 2>&1 && echo ts_installed=1 || echo ts_installed=0",
+  "tailscale status --json 2>/dev/null",
+].join("; ");
+
+export function parseTailscaleData(output: string): TailscaleData {
+  const notInstalled: TailscaleData = {
+    installed: false,
+    running: false,
+    tailscaleIPs: [],
+    hostname: null,
+    peers: [],
+    exitNodeInUse: false,
+  };
+
+  if (output.includes("ts_installed=0")) return notInstalled;
+
+  const lines = output.split("\n");
+  const jsonLines = lines.filter(
+    (l) => !l.startsWith("ts_installed=") && l.trim() !== "",
+  );
+  const jsonStr = jsonLines.join("\n");
+
+  try {
+    const parsed = JSON.parse(jsonStr) as {
+      BackendState?: string;
+      Self?: { HostName?: string; TailscaleIPs?: string[] };
+      Peer?: Record<
+        string,
+        {
+          HostName?: string;
+          TailscaleIPs?: string[];
+          Online?: boolean;
+          ExitNode?: boolean;
+        }
+      >;
+      CurrentExitNode?: string;
+    };
+
+    const peers: TailscalePeer[] = Object.values(parsed.Peer ?? {}).map(
+      (p) => ({
+        hostname: p.HostName ?? "",
+        tailscaleIPs: p.TailscaleIPs ?? [],
+        online: p.Online ?? false,
+        isExitNode: p.ExitNode ?? false,
+      }),
+    );
+
+    return {
+      installed: true,
+      running: parsed.BackendState === "Running",
+      tailscaleIPs: parsed.Self?.TailscaleIPs ?? [],
+      hostname: parsed.Self?.HostName ?? null,
+      peers,
+      exitNodeInUse:
+        typeof parsed.CurrentExitNode === "string" &&
+        parsed.CurrentExitNode !== "",
+    };
+  } catch {
+    return {
+      installed: true,
+      running: false,
+      tailscaleIPs: [],
+      hostname: null,
+      peers: [],
+      exitNodeInUse: false,
+    };
+  }
+}
+
+class AccessDeniedError extends Error {
+  constructor(message = "No access to this host") {
+    super(message);
+    this.name = "AccessDeniedError";
+  }
+}
+
+class ManagerInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ManagerInputError";
+  }
+}
+
+interface ManagerHost {
+  id: number;
+  userId: string;
+  sudoPassword?: string;
+}
+
+async function resolveManagerHost(
+  hostId: number,
+  userId: string,
+): Promise<ManagerHost> {
+  const access = await PermissionManager.getInstance().canAccessHost(
+    userId,
+    hostId,
+    "connect",
+  );
+  if (!access.hasAccess) throw new AccessDeniedError();
+
+  if (DataCrypto.getUserDataKey(userId) === null) {
+    throw new AccessDeniedError();
+  }
+  const host = await resolveHostById(hostId, userId);
+  if (!host) throw new AccessDeniedError("Host not found");
+
+  let sudoPassword = (host as { sudoPassword?: string }).sudoPassword;
+  const ownerId = (host as { userId?: string }).userId;
+  if (ownerId && ownerId !== userId) {
+    const ownerHost = await resolveHostById(hostId, ownerId);
+    sudoPassword = (ownerHost as { sudoPassword?: string } | null)
+      ?.sudoPassword;
+  }
+
+  return { id: hostId, userId, sudoPassword };
+}
+
+function managerErrorResponse(
+  res: Response,
+  operation: string,
+  error: unknown,
+) {
+  if (error instanceof ManagerInputError) {
+    return res.status(400).json({ error: error.message });
+  }
+  if (error instanceof AccessDeniedError) {
+    return res.status(403).json({ error: error.message });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return res.status(500).json({ error: message || `${operation} failed` });
+}
+
+export function registerTailscaleHostMetricsManager(
+  router: Router,
+  ctx: PluginContext,
+): void {
+  /**
+   * @openapi
+   * /plugin-api/tailscale/host-metrics-manager/{id}:
+   *   get:
+   *     summary: Get Tailscale status and IPs for a host
+   *     tags:
+   *       - Tailscale
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: integer
+   *     responses:
+   *       200:
+   *         description: Tailscale installation status, running state, IPs, and peer count.
+   */
+  router.get(
+    "/host-metrics-manager/:id",
+    async (req: Request, res: Response) => {
+      const userId = (req as AuthenticatedRequest).userId;
+      const hostId = parseInt(String(req.params.id), 10);
+      try {
+        const host = await resolveManagerHost(hostId, userId);
+        const data = await withSshConnection(
+          host.id,
+          { pool: "tailscale", purpose: "metrics" },
+          async (client) => {
+            const { stdout } = await execCommand(client, PROBE_CMD, 15000);
+            return parseTailscaleData(stdout);
+          },
+        );
+        res.json(data);
+      } catch (error) {
+        ctx.log.error(
+          "Failed to read Tailscale status",
+          error instanceof Error ? error : undefined,
+        );
+        managerErrorResponse(res, "tailscale_read", error);
+      }
+    },
+  );
+
+  /**
+   * @openapi
+   * /plugin-api/tailscale/host-metrics-manager/{id}/action:
+   *   post:
+   *     summary: Connect or disconnect Tailscale on a host
+   *     tags:
+   *       - Tailscale
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: integer
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               action:
+   *                 type: string
+   *                 enum: [up, down]
+   *     responses:
+   *       200:
+   *         description: Action result.
+   */
+  router.post(
+    "/host-metrics-manager/:id/action",
+    async (req: Request, res: Response) => {
+      const userId = (req as AuthenticatedRequest).userId;
+      const hostId = parseInt(String(req.params.id), 10);
+      try {
+        const host = await resolveManagerHost(hostId, userId);
+        const { action } = req.body as { action: unknown };
+        if (!isValidTailscaleAction(action)) {
+          throw new ManagerInputError("Invalid action, must be 'up' or 'down'");
+        }
+        const result = await withSshConnection(
+          host.id,
+          { pool: "tailscale", purpose: "metrics" },
+          (client) =>
+            execElevated(client, `tailscale ${action}`, host.sudoPassword, {
+              forceSudo: false,
+              timeoutMs: 30000,
+            }),
+        );
+        res.json({
+          success: result.code === 0,
+          output: (result.stdout + result.stderr).trim(),
+        });
+      } catch (error) {
+        ctx.log.error(
+          "Failed to run Tailscale action",
+          error instanceof Error ? error : undefined,
+        );
+        managerErrorResponse(res, "tailscale_action", error);
+      }
+    },
+  );
+}

plugins/tailscale/src/backend/index.ts

@@ -1,11 +1,20 @@
+import type { Router } from "express";
 import type { PluginContext } from "@termix/plugin-sdk/backend";
 import { startTailscaleService, stopTailscaleService } from "./routes.js";
+import { registerTailscaleSshAuth } from "./ssh-auth-provider.js";
+import { registerTailscaleHostMetricsManager } from "./host-metrics-manager.js";
+import { setPluginSsh } from "./ssh.js";
 
 export async function activate(ctx: PluginContext) {
-  startTailscaleService(ctx.http.router(), ctx);
+  const router = ctx.http.router<Router>();
+  startTailscaleService(router, ctx);
+  registerTailscaleHostMetricsManager(router, ctx);
+  setPluginSsh(ctx.ssh);
+  registerTailscaleSshAuth(ctx);
   ctx.log.info("Tailscale routes mounted at /plugin-api/tailscale");
 }
 
 export async function deactivate() {
+  setPluginSsh(null);
   stopTailscaleService();
 }

plugins/tailscale/src/backend/routes.ts

@@ -1,11 +1,4 @@
-// Was src/backend/database/routes/tailscale-routes.ts, moved here and
-// rewritten to register itself via the shared /tailscale dispatcher
-// (src/backend/database/routes/tailscale-dispatch.ts) instead of taking a
-// direct reference to the app instance, the same way fleets does.
-
 import { Router } from "express";
-import { AuthManager } from "../../../../src/backend/utils/auth-manager.js";
-import { PermissionManager } from "../../../../src/backend/utils/permission-manager.js";
 import { apiLogger } from "../../../../src/backend/utils/logger.js";
 import { fetchWithProxy } from "../../../../src/backend/utils/proxy-agent.js";
 import type { PluginContext } from "@termix/plugin-sdk/backend";
@@ -31,145 +24,127 @@ interface TailscaleAPIDevice {
 
 const DEFAULT_TAILSCALE_API_BASE = "https://api.tailscale.com/api/v2";
 
-export const router = Router();
-
-/**
- * Set by activate(). The API key and base URL are this plugin's own settings
- * now, read through ctx rather than out of the core settings table.
- */
-let context: PluginContext | null = null;
-
-const authManager = AuthManager.getInstance();
-const authenticateJWT = authManager.createAuthMiddleware();
-
-/**
- * Listing the tailnet uses the admin-stored API key, so it needs more than a
- * session. Writing the key is already admin-only and reading it back is
- * masked, but using it to enumerate every device was open to any logged-in
- * user, which handed out an internal network inventory.
- */
-const requireDeviceAccess = PermissionManager.getInstance().requirePermission(
-  "tailscale.devices.view",
-);
-
 function normalizeApiBase(raw: string | null): string {
   const trimmed = (raw ?? "").trim().replace(/\/+$/, "");
   return trimmed || DEFAULT_TAILSCALE_API_BASE;
 }
 
 /**
- * @openapi
- * /tailscale/devices:
- *   get:
- *     summary: List Tailscale devices
- *     description: >
- *       Returns the devices in the configured tailnet using the stored admin
- *       API key. Requires the tailscale.devices.view permission, because the
- *       response is a full inventory of the tailnet.
- *     tags:
- *       - Tailscale
- *     responses:
- *       200:
- *         description: List of tailnet devices.
- *       403:
- *         description: The caller lacks tailscale.devices.view.
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 devices:
- *                   type: array
- *                   items:
- *                     type: object
- *       500:
- *         description: Failed to fetch Tailscale devices.
+ * Set by activate(). Dropped on deactivate so a request arriving mid-teardown
+ * cannot read settings through a context the runtime has already torn down.
  */
-router.get(
-  "/devices",
-  authenticateJWT,
-  requireDeviceAccess,
-  async (_req, res) => {
-    try {
-      if (!context) {
-        return res
-          .status(503)
-          .json({ error: "Plugin is not running", devices: [] });
-      }
-      const apiKey = (await context.settings.get<string>("apiKey")) ?? "";
-      if (!apiKey) {
-        return res.json({ devices: [], hasApiKey: false });
-      }
-      const apiBase = normalizeApiBase(
-        (await context.settings.get<string>("apiBaseUrl")) ?? null,
-      );
+let context: PluginContext | null = null;
 
-      const url = `${apiBase}/tailnet/-/devices?fields=all`;
-      const response = await fetchWithProxy(url, {
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-          "User-Agent": "Termix/1.0",
-        },
-      });
-
-      if (!response.ok) {
-        apiLogger.warn("Tailscale API returned non-OK status", {
-          operation: "tailscale_devices",
-          status: response.status,
-        });
-        if (response.status === 401 || response.status === 403) {
-          return res.status(401).json({
-            error: "Invalid Tailscale API key",
-            devices: [],
-            hasApiKey: true,
-          });
-        }
-        return res.status(502).json({
-          error: "Tailscale API error",
-          devices: [],
-          hasApiKey: true,
-        });
-      }
-
-      const data = (await response.json()) as { devices: TailscaleAPIDevice[] };
-
-      const devices: TailscaleDevice[] = (data.devices ?? []).map((d) => ({
-        id: d.id,
-        name: d.name,
-        hostname: d.hostname,
-        addresses: d.addresses ?? [],
-        os: d.os,
-        lastSeen: d.lastSeen,
-      }));
-
-      res.json({ devices, hasApiKey: true });
-    } catch (err) {
-      apiLogger.error("Failed to fetch Tailscale devices", err, {
-        operation: "tailscale_devices",
-      });
-      res.status(500).json({
-        error: "Failed to fetch Tailscale devices",
-        devices: [],
-        hasApiKey: true,
-      });
-    }
-  },
-);
-
-/** Called from activate(). Mounts this router at /tailscale via the shared
- * dispatcher. */
+/** Called from activate(). Mounts the plugin's routes on ctx.http.router(). */
 export function startTailscaleService(
   mountOn: Router,
   ctx: PluginContext,
 ): void {
   context = ctx;
-  mountOn.use(router);
+
+  /**
+   * @openapi
+   * /plugin-api/tailscale/devices:
+   *   get:
+   *     summary: List Tailscale devices
+   *     description: >
+   *       Returns the devices in the configured tailnet using the stored admin
+   *       API key. Requires the tailscale.devices.view permission, because the
+   *       response is a full inventory of the tailnet.
+   *     tags:
+   *       - Tailscale
+   *     responses:
+   *       200:
+   *         description: List of tailnet devices.
+   *       403:
+   *         description: The caller lacks tailscale.devices.view.
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 devices:
+   *                   type: array
+   *                   items:
+   *                     type: object
+   *       500:
+   *         description: Failed to fetch Tailscale devices.
+   */
+  mountOn.get(
+    "/devices",
+    ctx.rbac.require("devices.view") as never,
+    async (_req, res) => {
+      try {
+        if (!context) {
+          return res
+            .status(503)
+            .json({ error: "Plugin is not running", devices: [] });
+        }
+        const apiKey = (await context.settings.get<string>("apiKey")) ?? "";
+        if (!apiKey) {
+          return res.json({ devices: [], hasApiKey: false });
+        }
+        const apiBase = normalizeApiBase(
+          (await context.settings.get<string>("apiBaseUrl")) ?? null,
+        );
+
+        const url = `${apiBase}/tailnet/-/devices?fields=all`;
+        const response = await fetchWithProxy(url, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "User-Agent": "Termix/1.0",
+          },
+        });
+
+        if (!response.ok) {
+          apiLogger.warn("Tailscale API returned non-OK status", {
+            operation: "tailscale_devices",
+            status: response.status,
+          });
+          if (response.status === 401 || response.status === 403) {
+            return res.status(401).json({
+              error: "Invalid Tailscale API key",
+              devices: [],
+              hasApiKey: true,
+            });
+          }
+          return res.status(502).json({
+            error: "Tailscale API error",
+            devices: [],
+            hasApiKey: true,
+          });
+        }
+
+        const data = (await response.json()) as {
+          devices: TailscaleAPIDevice[];
+        };
+
+        const devices: TailscaleDevice[] = (data.devices ?? []).map((d) => ({
+          id: d.id,
+          name: d.name,
+          hostname: d.hostname,
+          addresses: d.addresses ?? [],
+          os: d.os,
+          lastSeen: d.lastSeen,
+        }));
+
+        res.json({ devices, hasApiKey: true });
+      } catch (err) {
+        apiLogger.error("Failed to fetch Tailscale devices", err, {
+          operation: "tailscale_devices",
+        });
+        res.status(500).json({
+          error: "Failed to fetch Tailscale devices",
+          devices: [],
+          hasApiKey: true,
+        });
+      }
+    },
+  );
 }
 
-/** Called from deactivate(). /tailscale/* falls back to 404 until
+/** Called from deactivate(). /plugin-api/tailscale/* falls back to 404 until
  * reactivated. */
 export function stopTailscaleService(): void {
-  // Dropped so a request arriving mid-teardown cannot read settings through a
-  // context the runtime has already torn down.
   context = null;
 }

plugins/tailscale/src/backend/ssh-auth-provider.ts

@@ -0,0 +1,74 @@
+import type {
+  PluginContext,
+  PluginSshAuthProvider,
+} from "@termix/plugin-sdk/backend";
+import {
+  isTailscaleCheckCompleteBanner,
+  parseTailscaleCheckBanner,
+  TAILSCALE_CHECK_TIMEOUT_MS,
+} from "./tailscale-check.js";
+
+const AUTH_FAILED_PATTERN = /All configured authentication methods failed/i;
+
+export const tailscaleSshAuthProvider: PluginSshAuthProvider = {
+  type: "tailscale",
+  labelKey: "hosts.filterAuthTailscale",
+  connectOptions: (_host, purpose) =>
+    purpose === "terminal"
+      ? {
+          tryKeyboard: false,
+          readyTimeout: TAILSCALE_CHECK_TIMEOUT_MS,
+          // The socket sits idle while a check-mode login is pending.
+          timeout: TAILSCALE_CHECK_TIMEOUT_MS,
+        }
+      : { tryKeyboard: false },
+  prepare: async (_config, _host, env) => {
+    env.log("info", "Using Tailscale SSH");
+    return { status: "ready" };
+  },
+  onBanner: (banner) => {
+    const check = parseTailscaleCheckBanner(banner);
+    if (check) {
+      return {
+        action: "hold",
+        timeoutMs: TAILSCALE_CHECK_TIMEOUT_MS,
+        message: `Tailscale SSH requires an additional check. Waiting for browser authentication at ${check.url}`,
+        details: { url: check.url, message: check.message },
+      };
+    }
+    if (isTailscaleCheckCompleteBanner(banner)) {
+      return { action: "release" };
+    }
+    return undefined;
+  },
+  onAuthFailed: (host, _env, context) => {
+    const failed =
+      context.methodNotAvailable ||
+      AUTH_FAILED_PATTERN.test(context.error.message);
+    if (!failed) return;
+
+    // Tailscale documents the "+password" suffix for clients that mishandle a
+    // successful "none" reply. The password value is ignored.
+    if (context.retries === 0 && context.canRetry) {
+      return {
+        status: "retry",
+        message: "Retrying Tailscale SSH in forced password mode",
+        patch: {
+          username: `${host.username}+password`,
+          password: "termix",
+          tryKeyboard: false,
+        },
+      };
+    }
+
+    return {
+      status: "error",
+      code: "failed",
+      message: `Tailscale SSH authentication failed for user "${host.username}". Ensure Tailscale is running on the server, SSH is advertised (tailscale set --ssh), and your ACL policy grants the "${host.username}" user to your identity. If your Tailscale identity maps to a different Unix user, update the username on this host.`,
+    };
+  },
+};
+
+export function registerTailscaleSshAuth(ctx: PluginContext): void {
+  ctx.auth.registerSshAuthProvider(tailscaleSshAuthProvider);
+}

plugins/tailscale/src/backend/ssh.ts

@@ -0,0 +1,27 @@
+import type { Client } from "ssh2";
+import type {
+  PluginSsh,
+  PluginSshConnectOptions,
+  PluginSshHost,
+} from "@termix/plugin-sdk/backend";
+
+let current: PluginSsh | null = null;
+
+/** Set in activate, cleared on deactivate. */
+export function setPluginSsh(ssh: PluginSsh | null): void {
+  current = ssh;
+}
+
+export function pluginSsh(): PluginSsh {
+  if (!current) throw new Error("The plugin is not active");
+  return current;
+}
+
+/** withConnection with ssh2's Client type filled in. */
+export function withSshConnection<T>(
+  host: number | PluginSshHost,
+  options: PluginSshConnectOptions & { pool: string },
+  fn: (client: Client) => Promise<T>,
+): Promise<T> {
+  return pluginSsh().withConnection<T, Client>(host, options, fn);
+}

plugins/tailscale/src/backend/tailscale-check.ts

@@ -0,0 +1,45 @@
+// Tailscale SSH "check mode" sends its re-authentication prompt as an SSH auth
+// banner during the "none" auth method, then long-polls its control plane while
+// the connection stays open. The banner text itself comes from the control plane
+// (it is not in the tailscaled source), so match on the login URL rather than the
+// surrounding wording, which can change without notice.
+
+const TAILSCALE_CHECK_URL = /https:\/\/login\.tailscale\.com\/a\/[A-Za-z0-9]+/;
+
+const CHECK_COMPLETE = /authentication checked/i;
+
+/** How long a Tailscale check-mode login may sit waiting for approval. */
+export const TAILSCALE_CHECK_TIMEOUT_MS = 1_800_000;
+
+export interface TailscaleCheckBanner {
+  url: string;
+  message: string;
+}
+
+function stripCommentMarkers(banner: string): string {
+  return banner
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^\s*#\s?/, "").trim())
+    .filter((line) => line.length > 0)
+    .join("\n")
+    .trim();
+}
+
+export function parseTailscaleCheckBanner(
+  banner: string,
+): TailscaleCheckBanner | null {
+  if (!banner) return null;
+
+  const match = banner.match(TAILSCALE_CHECK_URL);
+  if (!match) return null;
+
+  return {
+    url: match[0],
+    message: stripCommentMarkers(banner),
+  };
+}
+
+export function isTailscaleCheckCompleteBanner(banner: string): boolean {
+  if (!banner) return false;
+  return CHECK_COMPLETE.test(banner);
+}