feat: make each plugin an npm workspace built by a termix-plugin CLI

plugins/host-metrics/src/backend/managers/cron.ts

@@ -0,0 +1,127 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import { shellSingleQuote } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export interface CronEntry {
+  raw: string;
+  enabled: boolean;
+  schedule: string;
+  command: string;
+}
+
+const READ_CRONTAB_CMD = "crontab -l 2>/dev/null";
+
+/** Parse a crontab into entries (comments/blank lines are dropped except as toggles). */
+export function parseCrontab(output: string): CronEntry[] {
+  const entries: CronEntry[] = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line.trim()) continue;
+    // A commented-out job: "# <schedule> <command>" (our toggle convention).
+    const disabled = line.match(
+      /^#\s*((?:@\w+|\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+.+)$/,
+    );
+    if (disabled) {
+      const { schedule, command } = splitScheduleCommand(disabled[1]);
+      if (command) {
+        entries.push({ raw: line, enabled: false, schedule, command });
+        continue;
+      }
+    }
+    // Skip pure comments / env assignments.
+    if (line.trimStart().startsWith("#")) continue;
+    if (/^\s*[A-Z_]+=/.test(line)) continue;
+    const { schedule, command } = splitScheduleCommand(line.trim());
+    if (!command) continue;
+    entries.push({ raw: line, enabled: true, schedule, command });
+  }
+  return entries;
+}
+
+function splitScheduleCommand(line: string): {
+  schedule: string;
+  command: string;
+} {
+  if (line.startsWith("@")) {
+    const [sched, ...rest] = line.split(/\s+/);
+    return { schedule: sched, command: rest.join(" ") };
+  }
+  const parts = line.split(/\s+/);
+  if (parts.length < 6) return { schedule: "", command: "" };
+  return {
+    schedule: parts.slice(0, 5).join(" "),
+    command: parts.slice(5).join(" "),
+  };
+}
+
+const CRON_SCHEDULE_RE =
+  /^(@(reboot|yearly|annually|monthly|weekly|daily|midnight|hourly)|[\d*/,-]+\s+[\d*/,-]+\s+[\d*/,-]+\s+[\d*/,A-Za-z-]+\s+[\d*/,A-Za-z-]+)$/;
+
+export function isValidCronSchedule(schedule: string): boolean {
+  return CRON_SCHEDULE_RE.test(schedule.trim());
+}
+
+/** Serialize entries into a full crontab body (toggled entries are commented). */
+export function serializeCrontab(entries: CronEntry[]): string {
+  const lines = entries.map((e) => {
+    const body = `${e.schedule} ${e.command}`.trim();
+    return e.enabled ? body : `# ${body}`;
+  });
+  return lines.join("\n") + (lines.length ? "\n" : "");
+}
+
+/** Build a command that atomically replaces the user crontab from the given body. */
+export function buildApplyCrontabCommand(body: string): string {
+  // printf the exact bytes into `crontab -` (reads new crontab from stdin).
+  return `printf '%s' ${shellSingleQuote(body)} | crontab -`;
+}
+
+export function registerCronRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/cron/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "cron_list", async (client) => {
+      const { stdout } = await execCommand(client, READ_CRONTAB_CMD, 15000);
+      return { entries: parseCrontab(stdout) };
+    }),
+  );
+
+  app.post(
+    "/host-metrics/managers/cron/:id",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "cron_replace",
+      async (client, _host, req) => {
+        const { entries } = req.body as { entries?: CronEntry[] };
+        if (!Array.isArray(entries)) {
+          throw new ManagerInputError("entries must be an array");
+        }
+        for (const e of entries) {
+          if (typeof e?.command !== "string" || !e.command.trim()) {
+            throw new ManagerInputError("Each entry needs a command");
+          }
+          if (e.command.includes("\n")) {
+            throw new ManagerInputError("Commands cannot contain newlines");
+          }
+          if (!isValidCronSchedule(String(e.schedule))) {
+            throw new ManagerInputError(`Invalid schedule: ${e.schedule}`);
+          }
+        }
+        const body = serializeCrontab(entries);
+        const { stdout, stderr, code } = await execCommand(
+          client,
+          buildApplyCrontabCommand(body),
+          15000,
+        );
+        return { success: code === 0, output: stdout || stderr };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/firewall.ts

@@ -0,0 +1,129 @@
+import type { Express } from "express";
+import { collectFirewallMetrics } from "../widgets/firewall-collector.js";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import {
+  isValidPort,
+  isValidIpProtocol,
+  isValidFirewallTarget,
+  type IpProtocol,
+  type FirewallTarget,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import { detectPlatform } from "../../../../../src/backend/hosts/metrics-shared/platform.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export interface FirewallRuleSpec {
+  protocol: IpProtocol;
+  port: number;
+  target: FirewallTarget;
+}
+
+/**
+ * Build an iptables add/delete for an INPUT rule. We only ever touch INPUT for a
+ * specific dport with an explicit target, and never the chain policy, so an
+ * existing ESTABLISHED/SSH rule is left intact.
+ */
+export function buildIptablesRuleCommand(
+  op: "add" | "delete",
+  spec: FirewallRuleSpec,
+): string {
+  const flag = op === "add" ? "-A" : "-D";
+  return `iptables ${flag} INPUT -p ${spec.protocol} --dport ${spec.port} -j ${spec.target}`;
+}
+
+export function buildNftRuleCommand(
+  op: "add" | "delete",
+  spec: FirewallRuleSpec,
+): string {
+  // nftables uses the inet filter table's input chain by convention.
+  const verb = op === "add" ? "add" : "delete";
+  const action =
+    spec.target.toLowerCase() === "reject"
+      ? "reject"
+      : spec.target.toLowerCase();
+  return `nft ${verb} rule inet filter input ${spec.protocol} dport ${spec.port} ${action}`;
+}
+
+export function registerFirewallRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/firewall/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "firewall_read", async (client) => {
+      return await collectFirewallMetrics(client);
+    }),
+  );
+
+  app.post(
+    "/host-metrics/managers/firewall/:id/rule",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "firewall_rule",
+      async (client, host, req) => {
+        const { op, protocol, port, target } = req.body as {
+          op?: "add" | "delete";
+          protocol?: string;
+          port?: number;
+          target?: string;
+        };
+        if (op !== "add" && op !== "delete") {
+          throw new ManagerInputError("Invalid op");
+        }
+        if (!isValidIpProtocol(protocol))
+          throw new ManagerInputError("Invalid protocol");
+        if (!isValidPort(port)) throw new ManagerInputError("Invalid port");
+        if (!isValidFirewallTarget(target))
+          throw new ManagerInputError("Invalid target");
+
+        const spec: FirewallRuleSpec = {
+          protocol,
+          port: Number(port),
+          target,
+        };
+        const fw = await collectFirewallMetrics(client);
+        const cmd =
+          fw.type === "nftables"
+            ? buildNftRuleCommand(op, spec)
+            : buildIptablesRuleCommand(op, spec);
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+        });
+        return {
+          success: result.code === 0,
+          output: result.stdout || result.stderr,
+          backend: fw.type,
+        };
+      },
+    ),
+  );
+
+  app.post(
+    "/host-metrics/managers/firewall/:id/persist",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "firewall_persist",
+      async (client, host) => {
+        const platform = await detectPlatform(client);
+        // Best-effort persistence across common tools.
+        const cmd =
+          "(command -v netfilter-persistent >/dev/null 2>&1 && netfilter-persistent save) || " +
+          "(command -v service >/dev/null 2>&1 && service iptables save) || " +
+          "(command -v nft >/dev/null 2>&1 && nft list ruleset > /etc/nftables.conf) || true";
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+        });
+        return {
+          success: result.code === 0,
+          output: result.stdout || result.stderr,
+          pkg: platform.pkg,
+        };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/health.ts

@@ -0,0 +1,249 @@
+import type { Express } from "express";
+import type { Client } from "ssh2";
+import type { AuthenticatedRequest } from "../../../../../src/types/index.js";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { createCurrentHostHealthRepository } from "../../../../../src/backend/database/repositories/factory.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import { shellSingleQuote } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { isValidPort } from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import type { ManagerRoutesDeps } from "./types.js";
+import { notifyAutomationHealthCheck } from "../automation-bridge.js";
+
+export interface HealthCheck {
+  id: string;
+  name: string;
+  type: "tcp" | "http";
+  target: string;
+  port?: number;
+  path?: string;
+}
+
+export interface HealthResult {
+  checkId: string;
+  ok: boolean;
+  latencyMs: number | null;
+  detail: string;
+}
+
+const TARGET_RE = /^[A-Za-z0-9.\-_:]+$/;
+const PATH_RE = /^\/[A-Za-z0-9._~!$&'()*+,;=:@/%-]*$/;
+
+export function isValidHealthCheck(c: unknown): c is HealthCheck {
+  if (!c || typeof c !== "object") return false;
+  const o = c as Record<string, unknown>;
+  if (typeof o.id !== "string" || !o.id) return false;
+  if (typeof o.name !== "string") return false;
+  if (o.type !== "tcp" && o.type !== "http") return false;
+  if (typeof o.target !== "string" || !TARGET_RE.test(o.target)) return false;
+  if (o.type === "tcp" && !isValidPort(o.port)) return false;
+  if (
+    o.path !== undefined &&
+    (typeof o.path !== "string" || !PATH_RE.test(o.path))
+  )
+    return false;
+  return true;
+}
+
+/** Build a command that runs the check from the host and prints "ok latency". */
+export function buildHealthCheckCommand(check: HealthCheck): string {
+  if (check.type === "tcp") {
+    const host = shellSingleQuote(check.target);
+    const port = check.port;
+    // Prefer bash /dev/tcp; time it with date in ms.
+    return `start=$(date +%s%3N); if timeout 3 bash -c '</dev/tcp/'${host}'/'${port} 2>/dev/null; then echo "ok $(( $(date +%s%3N) - start ))"; else echo "fail $(( $(date +%s%3N) - start ))"; fi`;
+  }
+  // http
+  const scheme = check.target.includes("://") ? "" : "http://";
+  const url = shellSingleQuote(`${scheme}${check.target}${check.path ?? ""}`);
+  return `curl -s -o /dev/null -m 5 -w '%{http_code} %{time_total}' ${url} || echo '000 0'`;
+}
+
+export function parseHealthResult(
+  check: HealthCheck,
+  output: string,
+): HealthResult {
+  const line = output.trim().split("\n").pop() ?? "";
+  if (check.type === "tcp") {
+    const [status, ms] = line.split(/\s+/);
+    return {
+      checkId: check.id,
+      ok: status === "ok",
+      latencyMs: Number(ms) || null,
+      detail: status === "ok" ? "open" : "closed/timeout",
+    };
+  }
+  const m = line.match(/^(\d{3})\s+([\d.]+)/);
+  if (!m)
+    return { checkId: check.id, ok: false, latencyMs: null, detail: line };
+  const code = Number(m[1]);
+  return {
+    checkId: check.id,
+    ok: code >= 200 && code < 400,
+    latencyMs: Math.round(Number(m[2]) * 1000),
+    detail: `HTTP ${code}`,
+  };
+}
+
+async function runChecks(
+  client: Client,
+  checks: HealthCheck[],
+): Promise<HealthResult[]> {
+  return Promise.all(
+    checks.map(async (check) => {
+      try {
+        const { stdout } = await execCommand(
+          client,
+          buildHealthCheckCommand(check),
+          8000,
+        );
+        return parseHealthResult(check, stdout);
+      } catch {
+        return {
+          checkId: check.id,
+          ok: false,
+          latencyMs: null,
+          detail: "error",
+        };
+      }
+    }),
+  );
+}
+
+const HISTORY_KEEP = 500;
+
+function recordHistory(
+  userId: string,
+  hostId: number,
+  results: HealthResult[],
+): Promise<void> {
+  return createCurrentHostHealthRepository()
+    .recordHistory(userId, hostId, results, HISTORY_KEEP)
+    .then(() => undefined);
+}
+
+async function loadChecks(
+  userId: string,
+  hostId: number,
+): Promise<HealthCheck[]> {
+  const row = await createCurrentHostHealthRepository().findChecksByUserAndHost(
+    userId,
+    hostId,
+  );
+  if (!row?.checks) return [];
+  try {
+    const parsed = JSON.parse(row.checks);
+    return Array.isArray(parsed) ? parsed.filter(isValidHealthCheck) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function registerHealthRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/health/:id",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "health_get",
+      async (client, host, req) => {
+        const userId = (req as AuthenticatedRequest).userId;
+        const checks = await loadChecks(userId, host.id);
+        const results = checks.length ? await runChecks(client, checks) : [];
+        if (results.length) {
+          await recordHistory(userId, host.id, results);
+          for (const r of results) {
+            notifyAutomationHealthCheck(
+              host.id,
+              userId,
+              r.checkId,
+              r.ok,
+              r.detail ?? undefined,
+            );
+          }
+        }
+
+        const history = (
+          await createCurrentHostHealthRepository().listHistory(
+            userId,
+            host.id,
+            200,
+          )
+        ).map((row) => ({
+          checkId: row.checkId,
+          ts: row.ts,
+          ok: row.ok,
+          latencyMs: row.latencyMs,
+          detail: row.detail,
+        }));
+        return { checks, results, history };
+      },
+    ),
+  );
+
+  app.post(
+    "/host-metrics/managers/health/:id/config",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "health_config",
+      async (_client, host, req) => {
+        const userId = (req as AuthenticatedRequest).userId;
+        const { checks, intervalSeconds } = req.body as {
+          checks?: unknown;
+          intervalSeconds?: number;
+        };
+        if (!Array.isArray(checks) || !checks.every(isValidHealthCheck)) {
+          throw new ManagerInputError("Invalid checks");
+        }
+        const interval =
+          typeof intervalSeconds === "number" &&
+          intervalSeconds >= 30 &&
+          intervalSeconds <= 86400
+            ? Math.round(intervalSeconds)
+            : 300;
+        const now = new Date().toISOString();
+        await createCurrentHostHealthRepository().upsertChecks(
+          userId,
+          host.id,
+          JSON.stringify(checks),
+          interval,
+          now,
+        );
+        return { success: true };
+      },
+    ),
+  );
+
+  app.post(
+    "/host-metrics/managers/health/:id/run",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "health_run",
+      async (client, host, req) => {
+        const userId = (req as AuthenticatedRequest).userId;
+        const checks = await loadChecks(userId, host.id);
+        const results = await runChecks(client, checks);
+        if (results.length) {
+          await recordHistory(userId, host.id, results);
+          for (const r of results) {
+            notifyAutomationHealthCheck(
+              host.id,
+              userId,
+              r.checkId,
+              r.ok,
+              r.detail ?? undefined,
+            );
+          }
+        }
+        return { results };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/index.ts

@@ -0,0 +1,65 @@
+import type { Express } from "express";
+import { detectPlatform } from "../../../../../src/backend/hosts/metrics-shared/platform.js";
+import { managerHandler } from "./route-helpers.js";
+import type { ManagerRoutesDeps } from "./types.js";
+import { registerServiceRoutes } from "./services.js";
+import { registerProcessRoutes } from "./processes.js";
+import { registerSimpleReadRoutes } from "./simple-reads.js";
+import { registerCronRoutes } from "./cron.js";
+import { registerPackageRoutes } from "./packages.js";
+import { registerSslRoutes } from "./ssl.js";
+import { registerFirewallRoutes } from "./firewall.js";
+import { registerUserRoutes } from "./users.js";
+import { registerHealthRoutes } from "./health.js";
+import { registerLogRoutes } from "./logs.js";
+import { registerWireGuardRoutes } from "./wireguard.js";
+import { registerTailscaleRoutes } from "./tailscale.js";
+
+/**
+ * Registers every Host Metrics manager route under the `/host-metrics/managers`
+ * prefix on the stats app. All routes are on-demand (not polled).
+ */
+export function registerManagerRoutes(
+  app: Express,
+  deps: ManagerRoutesDeps,
+): void {
+  const { validateHostId, runOnHost } = deps;
+
+  /**
+   * @openapi
+   * /host-metrics/platform/{id}:
+   *   get:
+   *     summary: Detect available management tooling on a host
+   *     tags:
+   *       - Host Metrics
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: integer
+   *     responses:
+   *       200:
+   *         description: Platform capabilities (systemd, package manager, certbot, docker).
+   */
+  app.get(
+    "/host-metrics/platform/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "platform_detect", (client) =>
+      detectPlatform(client),
+    ),
+  );
+
+  registerServiceRoutes(app, deps);
+  registerProcessRoutes(app, deps);
+  registerSimpleReadRoutes(app, deps);
+  registerCronRoutes(app, deps);
+  registerPackageRoutes(app, deps);
+  registerSslRoutes(app, deps);
+  registerFirewallRoutes(app, deps);
+  registerUserRoutes(app, deps);
+  registerHealthRoutes(app, deps);
+  registerLogRoutes(app, deps);
+  registerWireGuardRoutes(app, deps);
+  registerTailscaleRoutes(app, deps);
+}

plugins/host-metrics/src/backend/managers/logs.ts

@@ -0,0 +1,97 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import {
+  execElevated,
+  shellSingleQuote,
+} from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import {
+  isAllowedPath,
+  isValidSystemdUnit,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+/** Directories from which arbitrary log files may be tailed. */
+export const LOG_PATH_ALLOWLIST = ["/var/log"];
+
+const COMMON_LOGS = [
+  "/var/log/syslog",
+  "/var/log/messages",
+  "/var/log/auth.log",
+  "/var/log/secure",
+  "/var/log/kern.log",
+  "/var/log/dpkg.log",
+  "/var/log/nginx/access.log",
+  "/var/log/nginx/error.log",
+];
+
+const LIST_LOGS_CMD = `ls -1 ${LOG_PATH_ALLOWLIST.map(shellSingleQuote).join(" ")} 2>/dev/null`;
+
+export function clampLines(n: unknown): number {
+  const v = typeof n === "string" ? Number(n) : n;
+  if (typeof v !== "number" || !Number.isFinite(v)) return 200;
+  return Math.min(2000, Math.max(1, Math.round(v)));
+}
+
+export function buildTailCommand(path: string, lines: number): string {
+  // Keep stderr intact so execElevated can detect a permission error and
+  // escalate; suppressing it (2>/dev/null) would hide the denial and return an
+  // empty log with no chance to retry under sudo.
+  return `tail -n ${lines} ${shellSingleQuote(path)}`;
+}
+
+export function buildJournalCommand(unit: string, lines: number): string {
+  return `journalctl -u ${shellSingleQuote(unit)} -n ${lines} --no-pager`;
+}
+
+export function registerLogRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/logs/:id/files",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "logs_list", async (client) => {
+      const { stdout } = await execCommand(client, LIST_LOGS_CMD, 10000);
+      const found = stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((name) => `/var/log/${name}`);
+      return { common: COMMON_LOGS, files: found };
+    }),
+  );
+
+  app.get(
+    "/host-metrics/managers/logs/:id",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "logs_tail",
+      async (client, host, req) => {
+        const path = req.query.path as string | undefined;
+        const unit = req.query.unit as string | undefined;
+        const lines = clampLines(req.query.lines);
+
+        let cmd: string;
+        if (unit) {
+          if (!isValidSystemdUnit(unit))
+            throw new ManagerInputError("Invalid unit");
+          cmd = buildJournalCommand(unit, lines);
+        } else if (path) {
+          if (!isAllowedPath(path, LOG_PATH_ALLOWLIST)) {
+            throw new ManagerInputError("Path not allowed");
+          }
+          cmd = buildTailCommand(path, lines);
+        } else {
+          throw new ManagerInputError("Provide a path or unit");
+        }
+
+        // Try unprivileged; many logs need root (auth.log, etc.).
+        const result = await execElevated(client, cmd, host.sudoPassword);
+        return { content: result.stdout, lines };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/packages.ts

@@ -0,0 +1,71 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import { isValidPackageName } from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import { detectPlatform } from "../../../../../src/backend/hosts/metrics-shared/platform.js";
+import {
+  buildListUpgradableCommand,
+  buildPackageActionCommand,
+  parseUpgradable,
+  type PackageAction,
+} from "../../../../../src/backend/hosts/metrics-shared/package-commands.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export function registerPackageRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/packages/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "packages_list", async (client) => {
+      const platform = await detectPlatform(client);
+      const cmd = buildListUpgradableCommand(platform.pkg);
+      if (!cmd) return { pkg: platform.pkg, upgradable: [] };
+      const { stdout } = await execCommand(client, cmd, 60000);
+      return {
+        pkg: platform.pkg,
+        upgradable: parseUpgradable(platform.pkg, stdout),
+      };
+    }),
+  );
+
+  app.post(
+    "/host-metrics/managers/packages/:id/action",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "packages_action",
+      async (client, host, req) => {
+        const { action, pkg: name } = req.body as {
+          action?: PackageAction;
+          pkg?: string;
+        };
+        if (
+          action !== "upgrade-all" &&
+          action !== "install" &&
+          action !== "upgrade"
+        ) {
+          throw new ManagerInputError("Invalid action");
+        }
+        if (action !== "upgrade-all" && !isValidPackageName(name)) {
+          throw new ManagerInputError("Invalid package name");
+        }
+        const platform = await detectPlatform(client);
+        const cmd = buildPackageActionCommand(platform.pkg, action, name);
+        if (!cmd) throw new ManagerInputError("No supported package manager");
+        // Package operations can be slow; allow up to 10 minutes.
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+          timeoutMs: 600000,
+        });
+        return {
+          success: result.code === 0,
+          output: (result.stdout || result.stderr).slice(-8000),
+        };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/processes.ts

@@ -0,0 +1,134 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import {
+  isValidPid,
+  isValidSignal,
+  type Signal,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export interface ProcessRow {
+  pid: number;
+  ppid: number;
+  user: string;
+  cpu: number;
+  mem: number;
+  rss: number;
+  stat: string;
+  command: string;
+  args: string;
+}
+
+const LIST_PROCESSES_CMD =
+  "ps -eo pid,ppid,user:20,pcpu,pmem,rss,stat,comm,args --sort=-pcpu --no-headers 2>/dev/null | head -n 300";
+
+/** Parse `ps -eo pid,ppid,user,pcpu,pmem,rss,stat,comm,args` output. */
+export function parseProcessList(output: string): ProcessRow[] {
+  const rows: ProcessRow[] = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = line.match(
+      /^(\d+)\s+(\d+)\s+(\S+)\s+([\d.]+)\s+([\d.]+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.*)$/,
+    );
+    if (!m) continue;
+    rows.push({
+      pid: Number(m[1]),
+      ppid: Number(m[2]),
+      user: m[3],
+      cpu: Number(m[4]),
+      mem: Number(m[5]),
+      rss: Number(m[6]),
+      stat: m[7],
+      command: m[8],
+      args: m[9],
+    });
+  }
+  return rows;
+}
+
+export function buildKillCommand(pid: number, signal: Signal): string {
+  return `kill -${signal} ${pid}`;
+}
+
+export function registerProcessRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  /**
+   * @openapi
+   * /host-metrics/managers/processes/{id}:
+   *   get:
+   *     summary: List processes (rich, sortable, filterable client-side)
+   *     tags: [Host Metrics]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: integer }
+   *     responses:
+   *       200: { description: Process list. }
+   */
+  app.get(
+    "/host-metrics/managers/processes/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "processes_list", async (client) => {
+      const { stdout } = await execCommand(client, LIST_PROCESSES_CMD, 20000);
+      return { processes: parseProcessList(stdout) };
+    }),
+  );
+
+  /**
+   * @openapi
+   * /host-metrics/managers/processes/{id}/signal:
+   *   post:
+   *     summary: Send a signal to a process (TERM/KILL/HUP/INT)
+   *     tags: [Host Metrics]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: integer }
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               pid: { type: integer }
+   *               signal: { type: string }
+   *     responses:
+   *       200: { description: Signal result. }
+   *       400: { description: Invalid pid or signal. }
+   *       403: { description: Elevation required or denied. }
+   */
+  app.post(
+    "/host-metrics/managers/processes/:id/signal",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "processes_signal",
+      async (client, host, req) => {
+        const { pid, signal } = req.body as {
+          pid?: number;
+          signal?: string;
+        };
+        if (!isValidPid(pid)) throw new ManagerInputError("Invalid pid");
+        if (!isValidSignal(signal))
+          throw new ManagerInputError("Invalid signal");
+        const cmd = buildKillCommand(Number(pid), signal);
+        // Try unprivileged first; elevate only if the process isn't owned.
+        const result = await execElevated(client, cmd, host.sudoPassword);
+        return {
+          success: result.code === 0,
+          output: result.stdout || result.stderr,
+          usedSudo: result.usedSudo,
+        };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/route-helpers.ts

@@ -0,0 +1,62 @@
+import { getErrorMessage } from "../../../../../src/backend/utils/error-message.js";
+import type { Request, Response } from "express";
+import type { Client } from "ssh2";
+import type { AuthenticatedRequest } from "../../../../../src/types/index.js";
+import { statsLogger } from "../../../../../src/backend/utils/logger.js";
+import { ElevationError } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import type { ManagerHost, RunOnHost } from "./types.js";
+import type { HostAction } from "../../../../../src/backend/utils/permission-manager.js";
+
+export class AccessDeniedError extends Error {
+  constructor(message = "No access to this host") {
+    super(message);
+    this.name = "AccessDeniedError";
+  }
+}
+
+export class ManagerInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ManagerInputError";
+  }
+}
+
+/**
+ * Wrap a manager handler: parses hostId, runs `fn` on a pooled connection at the
+ * given access level, and maps known errors to clean HTTP responses.
+ */
+export function managerHandler(
+  runOnHost: RunOnHost,
+  level: HostAction,
+  operation: string,
+  fn: (client: Client, host: ManagerHost, req: Request) => Promise<unknown>,
+) {
+  return async (req: Request, res: Response) => {
+    const userId = (req as AuthenticatedRequest).userId;
+    const hostId = parseInt(String(req.params.id), 10);
+    try {
+      const result = await runOnHost(hostId, userId, level, (client, host) =>
+        fn(client, host, req),
+      );
+      return res.json(result);
+    } catch (error) {
+      if (error instanceof ManagerInputError) {
+        return res.status(400).json({ error: error.message });
+      }
+      if (error instanceof AccessDeniedError) {
+        return res.status(403).json({ error: error.message });
+      }
+      if (error instanceof ElevationError) {
+        return res.status(403).json({ error: error.message, code: error.code });
+      }
+      statsLogger.error(`Manager operation failed: ${operation}`, {
+        operation,
+        hostId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return res.status(500).json({
+        error: getErrorMessage(error, "Operation failed"),
+      });
+    }
+  };
+}

plugins/host-metrics/src/backend/managers/services.ts

@@ -0,0 +1,135 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import {
+  isValidSystemdUnit,
+  isValidServiceAction,
+  type ServiceAction,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export interface SystemdService {
+  unit: string;
+  load: string;
+  active: string;
+  sub: string;
+  description: string;
+}
+
+const LIST_SERVICES_CMD =
+  "systemctl list-units --type=service --all --no-legend --no-pager --plain 2>/dev/null";
+
+/** Parse `systemctl list-units --plain` output into structured rows. */
+export function parseServiceList(output: string): SystemdService[] {
+  const services: SystemdService[] = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Columns: UNIT LOAD ACTIVE SUB DESCRIPTION (description may contain spaces)
+    const parts = line.split(/\s+/);
+    if (parts.length < 4) continue;
+    const [unit, load, active, sub, ...rest] = parts;
+    if (!unit.endsWith(".service")) continue;
+    services.push({
+      unit,
+      load,
+      active,
+      sub,
+      description: rest.join(" "),
+    });
+  }
+  return services;
+}
+
+export function buildServiceActionCommand(
+  unit: string,
+  action: ServiceAction,
+): string {
+  return `systemctl ${action} ${unit}`;
+}
+
+export function registerServiceRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  /**
+   * @openapi
+   * /host-metrics/managers/services/{id}:
+   *   get:
+   *     summary: List systemd services
+   *     tags: [Host Metrics]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: integer }
+   *     responses:
+   *       200: { description: List of services. }
+   */
+  app.get(
+    "/host-metrics/managers/services/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "services_list", async (client) => {
+      const { stdout } = await execCommand(client, LIST_SERVICES_CMD, 20000);
+      return { services: parseServiceList(stdout) };
+    }),
+  );
+
+  /**
+   * @openapi
+   * /host-metrics/managers/services/{id}/action:
+   *   post:
+   *     summary: Start/stop/restart/enable/disable a systemd service
+   *     tags: [Host Metrics]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: integer }
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               unit: { type: string }
+   *               action: { type: string }
+   *     responses:
+   *       200: { description: Action result. }
+   *       400: { description: Invalid unit or action. }
+   *       403: { description: Elevation required or denied. }
+   */
+  app.post(
+    "/host-metrics/managers/services/:id/action",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "services_action",
+      async (client, host, req) => {
+        const { unit, action } = req.body as {
+          unit?: string;
+          action?: string;
+        };
+        if (!isValidSystemdUnit(unit)) {
+          throw new ManagerInputError("Invalid unit name");
+        }
+        if (!isValidServiceAction(action)) {
+          throw new ManagerInputError("Invalid action");
+        }
+        const result = await execElevated(
+          client,
+          buildServiceActionCommand(unit, action),
+          host.sudoPassword,
+          { forceSudo: true, timeoutMs: 30000 },
+        );
+        return {
+          success: result.code === 0,
+          output: result.stdout || result.stderr,
+        };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/simple-reads.ts

@@ -0,0 +1,138 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { managerHandler } from "./route-helpers.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+// ─── Top by memory ──────────────────────────────────────────────────────────
+
+export interface MemProcessRow {
+  pid: number;
+  user: string;
+  mem: number;
+  rss: number;
+  command: string;
+}
+
+const TOP_MEM_CMD =
+  "ps -eo pid,user:20,pmem,rss,comm --sort=-pmem --no-headers 2>/dev/null | head -n 20";
+
+export function parseTopMemory(output: string): MemProcessRow[] {
+  const rows: MemProcessRow[] = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = line.match(/^(\d+)\s+(\S+)\s+([\d.]+)\s+(\d+)\s+(.*)$/);
+    if (!m) continue;
+    rows.push({
+      pid: Number(m[1]),
+      user: m[2],
+      mem: Number(m[3]),
+      rss: Number(m[4]),
+      command: m[5],
+    });
+  }
+  return rows;
+}
+
+// ─── Systemd timers ─────────────────────────────────────────────────────────
+
+export interface TimerRow {
+  next: string;
+  left: string;
+  last: string;
+  unit: string;
+  activates: string;
+}
+
+const TIMERS_CMD =
+  "systemctl list-timers --all --no-legend --no-pager 2>/dev/null";
+
+export function parseTimers(output: string): TimerRow[] {
+  const rows: TimerRow[] = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("NEXT")) continue;
+    // NEXT(3) LEFT(2) LAST(3) PASSED(2) UNIT ACTIVATES  -> columns vary; grab
+    // the trailing UNIT + ACTIVATES which always end the line.
+    const parts = line.split(/\s+/);
+    if (parts.length < 2) continue;
+    const activates = parts[parts.length - 1];
+    const unit = parts[parts.length - 2];
+    if (!unit.endsWith(".timer")) continue;
+    rows.push({
+      next: parts.slice(0, 3).join(" "),
+      left: "",
+      last: "",
+      unit,
+      activates,
+    });
+  }
+  return rows;
+}
+
+// ─── Disk breakdown (per-mount) ─────────────────────────────────────────────
+
+export interface MountUsage {
+  filesystem: string;
+  sizeKb: number;
+  usedKb: number;
+  availKb: number;
+  usePct: number;
+  mount: string;
+}
+
+const DF_CMD = "df -Pk 2>/dev/null | tail -n +2";
+
+export function parseDfMounts(output: string): MountUsage[] {
+  const mounts: MountUsage[] = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = line.match(/^(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)%\s+(.+)$/);
+    if (!m) continue;
+    const fs = m[1];
+    // Skip pseudo/virtual filesystems that clutter the view.
+    if (/^(tmpfs|devtmpfs|overlay|udev|none|shm)$/.test(fs)) continue;
+    mounts.push({
+      filesystem: fs,
+      sizeKb: Number(m[2]),
+      usedKb: Number(m[3]),
+      availKb: Number(m[4]),
+      usePct: Number(m[5]),
+      mount: m[6],
+    });
+  }
+  return mounts;
+}
+
+export function registerSimpleReadRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/top-memory/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "top_memory", async (client) => {
+      const { stdout } = await execCommand(client, TOP_MEM_CMD, 15000);
+      return { processes: parseTopMemory(stdout) };
+    }),
+  );
+
+  app.get(
+    "/host-metrics/managers/timers/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "systemd_timers", async (client) => {
+      const { stdout } = await execCommand(client, TIMERS_CMD, 15000);
+      return { timers: parseTimers(stdout) };
+    }),
+  );
+
+  app.get(
+    "/host-metrics/managers/disk-breakdown/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "disk_breakdown", async (client) => {
+      const { stdout } = await execCommand(client, DF_CMD, 15000);
+      return { mounts: parseDfMounts(stdout) };
+    }),
+  );
+}

plugins/host-metrics/src/backend/managers/ssl.ts

@@ -0,0 +1,320 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import {
+  execElevated,
+  shellSingleQuote,
+} from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import {
+  isValidDomain,
+  isValidDnsProvider,
+  isAllowedPath,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import { detectPlatform } from "../../../../../src/backend/hosts/metrics-shared/platform.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export type AcmeClient = "certbot" | "acme.sh";
+export type ChallengeType = "http-standalone" | "http-webroot" | "dns";
+
+export interface CertInfo {
+  client: AcmeClient | "other";
+  name: string;
+  domains: string[];
+  expiry: string | null;
+  path?: string;
+}
+
+const CERTBOT_LIST_CMD = "certbot certificates 2>/dev/null";
+const ACMESH_BIN = '"$(command -v acme.sh || echo "$HOME/.acme.sh/acme.sh")"';
+const ACMESH_LIST_CMD = `${ACMESH_BIN} --list 2>/dev/null`;
+
+/** Parse `certbot certificates` output. */
+export function parseCertbotCertificates(output: string): CertInfo[] {
+  const certs: CertInfo[] = [];
+  let current: CertInfo | null = null;
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    const nameM = line.match(/^Certificate Name:\s+(.+)$/);
+    if (nameM) {
+      if (current) certs.push(current);
+      current = {
+        client: "certbot",
+        name: nameM[1],
+        domains: [],
+        expiry: null,
+      };
+      continue;
+    }
+    if (!current) continue;
+    const domM = line.match(/^Domains:\s+(.+)$/);
+    if (domM) current.domains = domM[1].split(/\s+/).filter(Boolean);
+    const expM = line.match(/^Expiry Date:\s+(\S+\s+\S+)/);
+    if (expM) current.expiry = expM[1];
+    const pathM = line.match(/^Certificate Path:\s+(.+)$/);
+    if (pathM) current.path = pathM[1];
+  }
+  if (current) certs.push(current);
+  return certs;
+}
+
+/** Parse `acme.sh --list` (tab/space separated columns with a header). */
+export function parseAcmeShList(output: string): CertInfo[] {
+  const certs: CertInfo[] = [];
+  const lines = output.split("\n").filter((l) => l.trim());
+  if (lines.length < 2) return certs;
+  for (const line of lines.slice(1)) {
+    const cols = line
+      .split(/\s{2,}|\t/)
+      .map((c) => c.trim())
+      .filter(Boolean);
+    if (cols.length < 1) continue;
+    certs.push({
+      client: "acme.sh",
+      name: cols[0],
+      domains: [cols[0]],
+      expiry: cols[cols.length - 1] || null,
+    });
+  }
+  return certs;
+}
+
+/**
+ * A certbot cert name or acme.sh primary domain. Allows letters, digits, dots,
+ * hyphens, underscores and the wildcard `*` (acme.sh), but no shell metachars.
+ */
+const CERT_NAME_RE = /^[A-Za-z0-9._*-]+$/;
+export function isValidCertName(name: unknown): name is string {
+  return typeof name === "string" && name.length > 0 && CERT_NAME_RE.test(name);
+}
+
+export interface IssueRequest {
+  client: AcmeClient;
+  domains: string[];
+  challenge: ChallengeType;
+  webroot?: string;
+  dnsProvider?: string;
+}
+
+/**
+ * Build the certificate issuance command for the chosen client/challenge.
+ * DNS-01 provider credentials are expected to already be present in the
+ * environment / provider config file; we never put secrets in argv.
+ */
+export function buildIssueCommand(req: IssueRequest): string {
+  const domains = req.domains;
+  if (req.client === "certbot") {
+    const dFlags = domains.map((d) => `-d ${shellSingleQuote(d)}`).join(" ");
+    if (req.challenge === "dns") {
+      return `certbot certonly --non-interactive --agree-tos --dns-${req.dnsProvider} ${dFlags}`;
+    }
+    if (req.challenge === "http-webroot") {
+      return `certbot certonly --non-interactive --agree-tos --webroot -w ${shellSingleQuote(
+        req.webroot as string,
+      )} ${dFlags}`;
+    }
+    return `certbot certonly --non-interactive --agree-tos --standalone ${dFlags}`;
+  }
+  // acme.sh
+  const dFlags = domains.map((d) => `-d ${shellSingleQuote(d)}`).join(" ");
+  if (req.challenge === "dns") {
+    return `${ACMESH_BIN} --issue --dns dns_${req.dnsProvider} ${dFlags}`;
+  }
+  if (req.challenge === "http-webroot") {
+    return `${ACMESH_BIN} --issue -w ${shellSingleQuote(
+      req.webroot as string,
+    )} ${dFlags}`;
+  }
+  return `${ACMESH_BIN} --issue --standalone ${dFlags}`;
+}
+
+export function buildRenewCommand(client: AcmeClient, dryRun: boolean): string {
+  if (client === "certbot") {
+    return `certbot renew${dryRun ? " --dry-run" : ""}`;
+  }
+  return `${ACMESH_BIN} --renew-all${dryRun ? " --staging" : ""}`;
+}
+
+/**
+ * Revoke (and remove) a certificate. certbot revokes by its certificate name and
+ * deletes the lineage afterwards; acme.sh revokes by primary domain then removes
+ * it from management. `name` is the certbot cert name or the acme.sh domain.
+ */
+export function buildRevokeCommand(client: AcmeClient, name: string): string {
+  if (client === "certbot") {
+    return `certbot revoke --non-interactive --cert-name ${shellSingleQuote(
+      name,
+    )} --delete-after-revoke`;
+  }
+  const d = shellSingleQuote(name);
+  return `${ACMESH_BIN} --revoke -d ${d} && ${ACMESH_BIN} --remove -d ${d}`;
+}
+
+export function registerSslRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/ssl/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "ssl_list", async (client, host) => {
+      const platform = await detectPlatform(client);
+      const certs: CertInfo[] = [];
+      if (platform.hasCertbot) {
+        const r = await execElevated(
+          client,
+          CERTBOT_LIST_CMD,
+          host.sudoPassword,
+        ).catch(() => null);
+        if (r) certs.push(...parseCertbotCertificates(r.stdout));
+      }
+      if (platform.hasAcmeSh) {
+        const { stdout } = await execCommand(
+          client,
+          ACMESH_LIST_CMD,
+          15000,
+        ).catch(() => ({ stdout: "" }) as { stdout: string });
+        certs.push(...parseAcmeShList(stdout));
+      }
+      return {
+        clients: {
+          certbot: platform.hasCertbot,
+          acmeSh: platform.hasAcmeSh,
+        },
+        certs,
+      };
+    }),
+  );
+
+  app.post(
+    "/host-metrics/managers/ssl/:id/issue",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "ssl_issue",
+      async (client, host, req) => {
+        const body = req.body as Partial<IssueRequest>;
+        if (body.client !== "certbot" && body.client !== "acme.sh") {
+          throw new ManagerInputError("Invalid ACME client");
+        }
+        if (!Array.isArray(body.domains) || body.domains.length === 0) {
+          throw new ManagerInputError("At least one domain is required");
+        }
+        for (const d of body.domains) {
+          if (!isValidDomain(d))
+            throw new ManagerInputError(`Invalid domain: ${d}`);
+        }
+        const challenge = body.challenge;
+        if (
+          challenge !== "http-standalone" &&
+          challenge !== "http-webroot" &&
+          challenge !== "dns"
+        ) {
+          throw new ManagerInputError("Invalid challenge type");
+        }
+        if (challenge === "dns" && !isValidDnsProvider(body.dnsProvider)) {
+          throw new ManagerInputError("Invalid DNS provider");
+        }
+        if (
+          challenge === "http-webroot" &&
+          !isAllowedPath(body.webroot, ["/var/www", "/srv", "/usr/share/nginx"])
+        ) {
+          throw new ManagerInputError("Invalid or disallowed webroot path");
+        }
+        const cmd = buildIssueCommand(body as IssueRequest);
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+          timeoutMs: 300000,
+        });
+        return {
+          success: result.code === 0,
+          output: (result.stdout || result.stderr).slice(-8000),
+        };
+      },
+    ),
+  );
+
+  app.post(
+    "/host-metrics/managers/ssl/:id/renew",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "ssl_renew",
+      async (client, host, req) => {
+        const { client: acmeClient, dryRun } = req.body as {
+          client?: AcmeClient;
+          dryRun?: boolean;
+        };
+        if (acmeClient !== "certbot" && acmeClient !== "acme.sh") {
+          throw new ManagerInputError("Invalid ACME client");
+        }
+        const cmd = buildRenewCommand(acmeClient, !!dryRun);
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+          timeoutMs: 300000,
+        });
+        return {
+          success: result.code === 0,
+          output: (result.stdout || result.stderr).slice(-8000),
+        };
+      },
+    ),
+  );
+
+  /**
+   * @openapi
+   * /host-metrics/managers/ssl/{id}/revoke:
+   *   post:
+   *     summary: Revoke and remove an issued certificate (certbot or acme.sh)
+   *     tags: [Host Metrics]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: integer }
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               client: { type: string, enum: [certbot, acme.sh] }
+   *               name: { type: string, description: certbot cert name or acme.sh domain }
+   *     responses:
+   *       200: { description: Revoke result. }
+   *       400: { description: Invalid client or certificate name. }
+   *       403: { description: Elevation required or denied. }
+   */
+  app.post(
+    "/host-metrics/managers/ssl/:id/revoke",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "ssl_revoke",
+      async (client, host, req) => {
+        const { client: acmeClient, name } = req.body as {
+          client?: AcmeClient;
+          name?: string;
+        };
+        if (acmeClient !== "certbot" && acmeClient !== "acme.sh") {
+          throw new ManagerInputError("Invalid ACME client");
+        }
+        if (!isValidCertName(name)) {
+          throw new ManagerInputError("Invalid certificate name");
+        }
+        const cmd = buildRevokeCommand(acmeClient, name);
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+          timeoutMs: 120000,
+        });
+        return {
+          success: result.code === 0,
+          output: (result.stdout || result.stderr).slice(-8000),
+        };
+      },
+    ),
+  );
+}

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

@@ -0,0 +1,177 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import type { ManagerRoutesDeps } from "./types.js";
+import { isValidTailscaleAction } from "../../../../../src/backend/hosts/metrics-shared/validation.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;
+
+  // Strip the installation probe line to get the raw JSON
+  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,
+    };
+  }
+}
+
+export function registerTailscaleRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  /**
+   * @openapi
+   * /host-metrics/managers/tailscale/{id}:
+   *   get:
+   *     summary: Get Tailscale status and IPs
+   *     tags:
+   *       - Host Metrics
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: integer
+   *     responses:
+   *       200:
+   *         description: Tailscale installation status, running state, IPs, and peer count.
+   */
+  app.get(
+    "/host-metrics/managers/tailscale/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "tailscale_read", async (client) => {
+      const { stdout } = await execCommand(client, PROBE_CMD, 15000);
+      return parseTailscaleData(stdout);
+    }),
+  );
+
+  /**
+   * @openapi
+   * /host-metrics/managers/tailscale/{id}/action:
+   *   post:
+   *     summary: Connect or disconnect Tailscale
+   *     tags:
+   *       - Host Metrics
+   *     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.
+   */
+  app.post(
+    "/host-metrics/managers/tailscale/:id/action",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "tailscale_action",
+      async (client, host, req) => {
+        const { action } = req.body as { action: unknown };
+        if (!isValidTailscaleAction(action)) {
+          throw new ManagerInputError("Invalid action, must be 'up' or 'down'");
+        }
+        const result = await execElevated(
+          client,
+          `tailscale ${action}`,
+          host.sudoPassword,
+          { forceSudo: false, timeoutMs: 30000 },
+        );
+        return {
+          success: result.code === 0,
+          output: (result.stdout + result.stderr).trim(),
+        };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/types.ts

@@ -0,0 +1,28 @@
+import type { Client } from "ssh2";
+import type { RequestHandler } from "express";
+import type { HostAction } from "../../../../../src/backend/utils/permission-manager.js";
+
+/** Minimal host shape managers need (includes the decrypted sudo password). */
+export interface ManagerHost {
+  id: number;
+  userId: string;
+  sudoPassword?: string;
+  enableDocker?: boolean;
+}
+
+/**
+ * Runs `fn` against a pooled SSH connection for the host, after verifying the
+ * user has at least `level` access. Resolves the host (with sudoPassword) so
+ * managers can elevate. Rejects with an access error if not permitted.
+ */
+export type RunOnHost = <T>(
+  hostId: number,
+  userId: string,
+  level: HostAction,
+  fn: (client: Client, host: ManagerHost) => Promise<T>,
+) => Promise<T>;
+
+export interface ManagerRoutesDeps {
+  validateHostId: RequestHandler;
+  runOnHost: RunOnHost;
+}

plugins/host-metrics/src/backend/managers/users.ts

@@ -0,0 +1,154 @@
+import type { Express } from "express";
+import { execCommand } from "../../../../../src/backend/hosts/metrics-shared/common-utils.js";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import {
+  isValidUsername,
+  isValidGroupName,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+import type { ManagerRoutesDeps } from "./types.js";
+
+export interface SystemUser {
+  name: string;
+  uid: number;
+  gid: number;
+  home: string;
+  shell: string;
+}
+
+export interface SystemGroup {
+  name: string;
+  gid: number;
+  members: string[];
+}
+
+// Human users only (uid >= 1000, excluding nobody at 65534).
+const READ_USERS_CMD = "getent passwd 2>/dev/null";
+const READ_GROUPS_CMD = "getent group 2>/dev/null";
+const READ_SUDOERS_CMD = "getent group sudo wheel 2>/dev/null";
+
+export function parsePasswd(output: string): SystemUser[] {
+  const users: SystemUser[] = [];
+  for (const line of output.split("\n")) {
+    const parts = line.split(":");
+    if (parts.length < 7) continue;
+    const uid = Number(parts[2]);
+    if (!Number.isFinite(uid)) continue;
+    if (uid < 1000 || uid === 65534) continue;
+    users.push({
+      name: parts[0],
+      uid,
+      gid: Number(parts[3]),
+      home: parts[5],
+      shell: parts[6],
+    });
+  }
+  return users;
+}
+
+export function parseGroups(output: string): SystemGroup[] {
+  const groups: SystemGroup[] = [];
+  for (const line of output.split("\n")) {
+    const parts = line.split(":");
+    if (parts.length < 4) continue;
+    groups.push({
+      name: parts[0],
+      gid: Number(parts[2]),
+      members: parts[3].split(",").filter(Boolean),
+    });
+  }
+  return groups;
+}
+
+export function parseSudoers(output: string): string[] {
+  const members = new Set<string>();
+  for (const line of output.split("\n")) {
+    const parts = line.split(":");
+    if (parts.length < 4) continue;
+    parts[3]
+      .split(",")
+      .filter(Boolean)
+      .forEach((m) => members.add(m));
+  }
+  return [...members];
+}
+
+export type UserAction = "create" | "delete" | "addToGroup" | "removeFromGroup";
+
+export function registerUserRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  app.get(
+    "/host-metrics/managers/users/:id",
+    validateHostId,
+    managerHandler(runOnHost, "connect", "users_list", async (client) => {
+      const [passwd, groups, sudoers] = await Promise.all([
+        execCommand(client, READ_USERS_CMD, 15000),
+        execCommand(client, READ_GROUPS_CMD, 15000),
+        execCommand(client, READ_SUDOERS_CMD, 15000),
+      ]);
+      return {
+        users: parsePasswd(passwd.stdout),
+        groups: parseGroups(groups.stdout),
+        sudoers: parseSudoers(sudoers.stdout),
+      };
+    }),
+  );
+
+  app.post(
+    "/host-metrics/managers/users/:id/action",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "users_action",
+      async (client, host, req) => {
+        const { action, username, group } = req.body as {
+          action?: UserAction;
+          username?: string;
+          group?: string;
+        };
+        if (!isValidUsername(username))
+          throw new ManagerInputError("Invalid username");
+
+        // Never modify/delete the user we're connected as, or root.
+        const who = (await execCommand(client, "id -un", 8000)).stdout.trim();
+        if (username === who || username === "root") {
+          throw new ManagerInputError(
+            "Refusing to modify the connected user or root",
+          );
+        }
+
+        let cmd: string;
+        switch (action) {
+          case "create":
+            cmd = `useradd -m ${username}`;
+            break;
+          case "delete":
+            cmd = `userdel -r ${username}`;
+            break;
+          case "addToGroup":
+          case "removeFromGroup":
+            if (!isValidGroupName(group))
+              throw new ManagerInputError("Invalid group");
+            cmd =
+              action === "addToGroup"
+                ? `usermod -aG ${group} ${username}`
+                : `gpasswd -d ${username} ${group}`;
+            break;
+          default:
+            throw new ManagerInputError("Invalid action");
+        }
+
+        const result = await execElevated(client, cmd, host.sudoPassword, {
+          forceSudo: true,
+        });
+        return {
+          success: result.code === 0,
+          output: result.stdout || result.stderr,
+        };
+      },
+    ),
+  );
+}

plugins/host-metrics/src/backend/managers/wireguard.ts

@@ -0,0 +1,222 @@
+import type { Express } from "express";
+import { execElevated } from "../../../../../src/backend/hosts/metrics-shared/exec-elevated.js";
+import { managerHandler, ManagerInputError } from "./route-helpers.js";
+import type { ManagerRoutesDeps } from "./types.js";
+import {
+  isValidWireGuardInterface,
+  isValidWireGuardAction,
+} from "../../../../../src/backend/hosts/metrics-shared/validation.js";
+
+export interface WireGuardPeer {
+  publicKey: string;
+  endpoint: string | null;
+  allowedIPs: string[];
+  latestHandshake: number | null;
+  rxBytes: number;
+  txBytes: number;
+}
+
+export interface WireGuardInterface {
+  name: string;
+  publicKey: string | null;
+  listenPort: number | null;
+  up: boolean;
+  peers: WireGuardPeer[];
+}
+
+export interface WireGuardData {
+  installed: boolean;
+  interfaces: WireGuardInterface[];
+}
+
+const PROBE_CMD = [
+  "command -v wg >/dev/null 2>&1 && echo wg_installed=1 || echo wg_installed=0",
+  "ip link show type wireguard 2>/dev/null",
+  "echo __DUMP__",
+  "wg show all dump 2>/dev/null",
+].join("; ");
+
+export function parseWireGuardData(output: string): WireGuardData {
+  if (output.includes("wg_installed=0")) {
+    return { installed: false, interfaces: [] };
+  }
+
+  const dumpIdx = output.indexOf("__DUMP__");
+  const ipLinkPart = dumpIdx >= 0 ? output.slice(0, dumpIdx) : "";
+  const dumpPart =
+    dumpIdx >= 0 ? output.slice(dumpIdx + "__DUMP__".length) : "";
+
+  // Collect up interface names from `ip link show type wireguard`
+  const upSet = new Set<string>();
+  for (const line of ipLinkPart.split("\n")) {
+    const m = line.match(/^\d+:\s+([A-Za-z0-9_-]+):/);
+    if (m) upSet.add(m[1]);
+  }
+
+  const ifaceMap = new Map<string, WireGuardInterface>();
+
+  for (const raw of dumpPart.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const cols = line.split("\t");
+
+    if (cols.length === 5) {
+      // Interface row: iface private_key public_key listen_port fwmark
+      const [name, , publicKey, listenPortStr] = cols;
+      if (!name) continue;
+      ifaceMap.set(name, {
+        name,
+        publicKey: publicKey && publicKey !== "(none)" ? publicKey : null,
+        listenPort:
+          listenPortStr && listenPortStr !== "(none)"
+            ? Number(listenPortStr)
+            : null,
+        up: upSet.has(name),
+        peers: [],
+      });
+    } else if (cols.length === 9) {
+      // Peer row: iface public_key preshared_key endpoint allowed_ips latest_handshake rx_bytes tx_bytes persistent_keepalive
+      const [
+        name,
+        publicKey,
+        ,
+        endpoint,
+        allowedIPsStr,
+        handshakeStr,
+        rxStr,
+        txStr,
+      ] = cols;
+      if (!name) continue;
+
+      if (!ifaceMap.has(name)) {
+        ifaceMap.set(name, {
+          name,
+          publicKey: null,
+          listenPort: null,
+          up: upSet.has(name),
+          peers: [],
+        });
+      }
+
+      const handshake = Number(handshakeStr);
+      ifaceMap.get(name)!.peers.push({
+        publicKey: publicKey ?? "",
+        endpoint: endpoint && endpoint !== "(none)" ? endpoint : null,
+        allowedIPs:
+          allowedIPsStr && allowedIPsStr !== "(none)"
+            ? allowedIPsStr.split(",").map((s) => s.trim())
+            : [],
+        latestHandshake: handshake > 0 ? handshake : null,
+        rxBytes: Number(rxStr) || 0,
+        txBytes: Number(txStr) || 0,
+      });
+    }
+  }
+
+  return { installed: true, interfaces: Array.from(ifaceMap.values()) };
+}
+
+export function registerWireGuardRoutes(
+  app: Express,
+  { validateHostId, runOnHost }: ManagerRoutesDeps,
+): void {
+  /**
+   * @openapi
+   * /host-metrics/managers/wireguard/{id}:
+   *   get:
+   *     summary: Get WireGuard interfaces and peers
+   *     tags:
+   *       - Host Metrics
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: integer
+   *     responses:
+   *       200:
+   *         description: WireGuard installation status, interfaces, and peer details.
+   */
+  app.get(
+    "/host-metrics/managers/wireguard/:id",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "wireguard_read",
+      async (client, host) => {
+        const result = await execElevated(
+          client,
+          PROBE_CMD,
+          host.sudoPassword,
+          {
+            forceSudo: false,
+            timeoutMs: 15000,
+          },
+        );
+        return parseWireGuardData(result.stdout);
+      },
+    ),
+  );
+
+  /**
+   * @openapi
+   * /host-metrics/managers/wireguard/{id}/action:
+   *   post:
+   *     summary: Bring a WireGuard interface up or down
+   *     tags:
+   *       - Host Metrics
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: integer
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               interface:
+   *                 type: string
+   *               action:
+   *                 type: string
+   *                 enum: [up, down]
+   *     responses:
+   *       200:
+   *         description: Action result.
+   */
+  app.post(
+    "/host-metrics/managers/wireguard/:id/action",
+    validateHostId,
+    managerHandler(
+      runOnHost,
+      "connect",
+      "wireguard_action",
+      async (client, host, req) => {
+        const { interface: iface, action } = req.body as {
+          interface: unknown;
+          action: unknown;
+        };
+        if (!isValidWireGuardInterface(iface)) {
+          throw new ManagerInputError("Invalid WireGuard interface name");
+        }
+        if (!isValidWireGuardAction(action)) {
+          throw new ManagerInputError("Invalid action, must be 'up' or 'down'");
+        }
+        const result = await execElevated(
+          client,
+          `wg-quick ${action} ${iface}`,
+          host.sudoPassword,
+          { forceSudo: true, timeoutMs: 30000 },
+        );
+        return {
+          success: result.code === 0,
+          output: (result.stdout + result.stderr).trim(),
+        };
+      },
+    ),
+  );
+}