refactor(tests): move backend tests into src/backend/tests mirror tree

Backend *.test.ts files (and the test-support harness) no longer sit next
to source files; they live under src/backend/tests/ mirroring the source
layout. Imports rewritten accordingly; CLAUDE.md convention updated.

src/backend/tests/hosts/credential-username.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  pickResolvedUsername,
+  pickResolvedPassword,
+  expandOidcUsername,
+} from "../../hosts/credential-username.js";
+
+describe("pickResolvedUsername", () => {
+  it("keeps the host username when one is set, even with a credential username", () => {
+    expect(pickResolvedUsername("admin", "root", false)).toBe("admin");
+  });
+
+  it("falls back to the credential username when the host has none", () => {
+    expect(pickResolvedUsername("", "root", false)).toBe("root");
+    expect(pickResolvedUsername(undefined, "root", false)).toBe("root");
+    expect(pickResolvedUsername("   ", "root", false)).toBe("root");
+  });
+
+  it("treats whitespace-only host usernames as empty", () => {
+    expect(pickResolvedUsername("  ", "deploy", false)).toBe("deploy");
+  });
+
+  it("forces the host username when overrideCredentialUsername is set", () => {
+    expect(pickResolvedUsername("admin", "root", true)).toBe("admin");
+    expect(pickResolvedUsername("", "root", true)).toBeUndefined();
+  });
+
+  it("returns undefined when neither username is usable", () => {
+    expect(pickResolvedUsername("", "", false)).toBeUndefined();
+    expect(pickResolvedUsername(undefined, undefined, false)).toBeUndefined();
+  });
+});
+
+describe("pickResolvedPassword", () => {
+  it("keeps the host-specific password ahead of the credential password", () => {
+    expect(pickResolvedPassword("host-pass", "credential-pass")).toBe(
+      "host-pass",
+    );
+  });
+
+  it("falls back to the credential password when the host has none", () => {
+    expect(pickResolvedPassword("", "credential-pass")).toBe("credential-pass");
+    expect(pickResolvedPassword(undefined, "credential-pass")).toBe(
+      "credential-pass",
+    );
+  });
+
+  it("treats whitespace-only passwords as empty", () => {
+    expect(pickResolvedPassword("   ", "credential-pass")).toBe(
+      "credential-pass",
+    );
+  });
+});
+
+describe("expandOidcUsername", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it("returns the username unchanged when it has no placeholder", async () => {
+    expect(await expandOidcUsername("alice", "user-1")).toBe("alice");
+    expect(await expandOidcUsername(undefined, "user-1")).toBeUndefined();
+  });
+
+  it("expands the placeholder with the user's OIDC identifier", async () => {
+    vi.doMock("../../database/repositories/factory.js", () => ({
+      createCurrentUserRepository: () => ({
+        findById: async () => ({ oidcIdentifier: "jdoe" }),
+      }),
+    }));
+
+    const { expandOidcUsername: expand } =
+      await import("../../hosts/credential-username.js");
+    expect(await expand("$oidc.preferred_username", "user-1")).toBe("jdoe");
+  });
+
+  it("leaves the placeholder as-is when the user has no OIDC identifier", async () => {
+    vi.doMock("../../database/repositories/factory.js", () => ({
+      createCurrentUserRepository: () => ({
+        findById: async () => ({ oidcIdentifier: null }),
+      }),
+    }));
+
+    const { expandOidcUsername: expand } =
+      await import("../../hosts/credential-username.js");
+    expect(await expand("$oidc.preferred_username", "user-1")).toBe(
+      "$oidc.preferred_username",
+    );
+  });
+
+  it("returns the username unchanged when the DB lookup throws", async () => {
+    vi.doMock("../../database/repositories/factory.js", () => ({
+      createCurrentUserRepository: () => {
+        throw new Error("DB unavailable");
+      },
+    }));
+
+    const { expandOidcUsername: expand } =
+      await import("../../hosts/credential-username.js");
+    expect(await expand("$oidc.preferred_username", "user-1")).toBe(
+      "$oidc.preferred_username",
+    );
+  });
+});

src/backend/tests/hosts/file-manager-operation-commands.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { buildDeleteCommand } from "../../hosts/file-manager-operation-commands.js";
+
+describe("buildDeleteCommand", () => {
+  it("builds a PowerShell 5.1 compatible delete command for Windows files", () => {
+    const command = buildDeleteCommand(
+      "/C:/Users/Administrator/test.txt",
+      false,
+    );
+
+    expect(command.command).toBe(
+      "Remove-Item -LiteralPath 'C:\\Users\\Administrator\\test.txt' -Force -ErrorAction Stop",
+    );
+    expect(command.commandWithSuccess).toBe(
+      `${command.command}; if ($?) { Write-Output "SUCCESS" }`,
+    );
+    expect(command.commandWithSuccess).not.toContain("&&");
+  });
+
+  it("adds recursive deletion for Windows directories", () => {
+    const command = buildDeleteCommand("C:/Temp/Folder", true);
+
+    expect(command.command).toBe(
+      "Remove-Item -LiteralPath 'C:\\Temp\\Folder' -Recurse -Force -ErrorAction Stop",
+    );
+  });
+
+  it("escapes single quotes in Windows literal paths", () => {
+    const command = buildDeleteCommand("/C:/Temp/O'Brien.txt", false);
+
+    expect(command.command).toBe(
+      "Remove-Item -LiteralPath 'C:\\Temp\\O''Brien.txt' -Force -ErrorAction Stop",
+    );
+  });
+
+  it("keeps POSIX delete commands using shell success chaining", () => {
+    const command = buildDeleteCommand("/tmp/O'Brien.txt", false);
+
+    expect(command.command).toBe("rm -f '/tmp/O'\"'\"'Brien.txt'");
+    expect(command.commandWithSuccess).toBe(
+      `${command.command} && echo "SUCCESS"`,
+    );
+  });
+});

src/backend/tests/hosts/file-manager-utils.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from "vitest";
+import {
+  isExecutableFile,
+  modeToPermissions,
+  formatMtime,
+  getMimeType,
+  detectBinary,
+  parseLsDateToTimestamp,
+} from "../../hosts/file-manager-utils.js";
+
+describe("isExecutableFile", () => {
+  it("flags scripts with execute permission", () => {
+    expect(isExecutableFile("-rwxr-xr-x", "deploy.sh")).toBe(true);
+    expect(isExecutableFile("-rwxr-xr-x", "run.py")).toBe(true);
+  });
+
+  it("flags known executable extensions with execute permission", () => {
+    expect(isExecutableFile("-rwxr-xr-x", "tool.bin")).toBe(true);
+    expect(isExecutableFile("-rwxr-xr-x", "app.exe")).toBe(true);
+  });
+
+  it("flags extensionless files with execute permission", () => {
+    expect(isExecutableFile("-rwxr-xr-x", "myprogram")).toBe(true);
+  });
+
+  it("does not flag files without execute permission", () => {
+    expect(isExecutableFile("-rw-r--r--", "deploy.sh")).toBe(false);
+    expect(isExecutableFile("-rw-r--r--", "myprogram")).toBe(false);
+  });
+
+  it("does not flag non-script data files even when executable", () => {
+    expect(isExecutableFile("-rwxr-xr-x", "notes.txt")).toBe(false);
+  });
+});
+
+describe("modeToPermissions", () => {
+  it("renders a regular file with rwxr-xr-x", () => {
+    expect(modeToPermissions(0o100755)).toBe("-rwxr-xr-x");
+  });
+
+  it("renders a directory prefix", () => {
+    expect(modeToPermissions(0o040755)).toBe("drwxr-xr-x");
+  });
+
+  it("renders a symlink prefix", () => {
+    expect(modeToPermissions(0o120777)).toBe("lrwxrwxrwx");
+  });
+
+  it("renders a read-only file", () => {
+    expect(modeToPermissions(0o100444)).toBe("-r--r--r--");
+  });
+
+  it("renders no permissions", () => {
+    expect(modeToPermissions(0o100000)).toBe("----------");
+  });
+});
+
+describe("formatMtime", () => {
+  it("uses HH:MM format for recent timestamps", () => {
+    // Within the last 6 months relative to now.
+    const recent = Math.floor(Date.now() / 1000) - 60 * 60 * 24 * 5;
+    const result = formatMtime(recent);
+    expect(result).toMatch(/^[A-Z][a-z]{2} +\d{1,2} \d{2}:\d{2}$/);
+  });
+
+  it("uses the year for old timestamps", () => {
+    // ~2 years ago is comfortably outside the 6-month window.
+    const old = Math.floor(Date.now() / 1000) - 60 * 60 * 24 * 365 * 2;
+    const result = formatMtime(old);
+    expect(result).toMatch(/^[A-Z][a-z]{2} +\d{1,2} +\d{4}$/);
+  });
+});
+
+describe("getMimeType", () => {
+  it("maps known extensions", () => {
+    expect(getMimeType("readme.txt")).toBe("text/plain");
+    expect(getMimeType("data.json")).toBe("application/json");
+    expect(getMimeType("photo.JPEG")).toBe("image/jpeg");
+    expect(getMimeType("archive.zip")).toBe("application/zip");
+  });
+
+  it("falls back to octet-stream for unknown or missing extensions", () => {
+    expect(getMimeType("mystery.xyz")).toBe("application/octet-stream");
+    expect(getMimeType("noextension")).toBe("application/octet-stream");
+  });
+});
+
+describe("parseLsDateToTimestamp", () => {
+  it("parses a year-format date string", () => {
+    const ts = parseLsDateToTimestamp("Dec 12  2025");
+    const d = new Date(ts * 1000);
+    expect(d.getFullYear()).toBe(2025);
+    expect(d.getMonth()).toBe(11);
+    expect(d.getDate()).toBe(12);
+  });
+
+  it("parses a time-format date string for a recent file", () => {
+    const now = new Date();
+    const month = [
+      "Jan",
+      "Feb",
+      "Mar",
+      "Apr",
+      "May",
+      "Jun",
+      "Jul",
+      "Aug",
+      "Sep",
+      "Oct",
+      "Nov",
+      "Dec",
+    ][now.getMonth()];
+    const day = now.getDate();
+    const ts = parseLsDateToTimestamp(`${month} ${day} 10:30`);
+    const d = new Date(ts * 1000);
+    expect(d.getHours()).toBe(10);
+    expect(d.getMinutes()).toBe(30);
+  });
+
+  it("returns 0 for an empty or invalid string", () => {
+    expect(parseLsDateToTimestamp("")).toBe(0);
+    expect(parseLsDateToTimestamp("Xyz 5 12:00")).toBe(0);
+  });
+
+  it("produces ascending order for older vs newer dates", () => {
+    const older = parseLsDateToTimestamp("Jan  1  2020");
+    const newer = parseLsDateToTimestamp("Dec 31  2024");
+    expect(older).toBeLessThan(newer);
+  });
+});
+
+describe("detectBinary", () => {
+  it("returns false for empty buffers", () => {
+    expect(detectBinary(Buffer.from([]))).toBe(false);
+  });
+
+  it("returns false for plain UTF-8 text", () => {
+    expect(detectBinary(Buffer.from("hello world\nsecond line\t tab"))).toBe(
+      false,
+    );
+  });
+
+  it("returns true when null bytes are present", () => {
+    expect(detectBinary(Buffer.from([0x48, 0x00, 0x49, 0x00]))).toBe(true);
+  });
+
+  it("allows common whitespace control characters", () => {
+    expect(detectBinary(Buffer.from("line1\r\nline2\tend"))).toBe(false);
+  });
+});

src/backend/tests/hosts/guacamole/token-service.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("../../../utils/logger.js", () => ({
+  guacLogger: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+const { GuacamoleTokenService } =
+  await import("../../../hosts/guacamole/token-service.js");
+
+describe("GuacamoleTokenService", () => {
+  const tokenService = GuacamoleTokenService.getInstance();
+
+  it("disables RDP pre-authentication when no credentials are configured", () => {
+    const token = tokenService.createRdpToken("windows.example.test", "", "");
+    const decrypted = tokenService.decryptToken(token);
+
+    expect(decrypted?.connection.settings).toMatchObject({
+      hostname: "windows.example.test",
+      port: 3389,
+      "ignore-cert": true,
+      "disable-auth": true,
+    });
+    expect(decrypted?.connection.settings.username).toBeUndefined();
+    expect(decrypted?.connection.settings.password).toBeUndefined();
+  });
+
+  it("keeps normal RDP credential authentication unchanged", () => {
+    const token = tokenService.createRdpToken(
+      "windows.example.test",
+      "Administrator",
+      "secret",
+    );
+    const decrypted = tokenService.decryptToken(token);
+
+    expect(decrypted?.connection.settings).toMatchObject({
+      hostname: "windows.example.test",
+      username: "Administrator",
+      password: "secret",
+      port: 3389,
+    });
+    expect(decrypted?.connection.settings["disable-auth"]).toBeUndefined();
+  });
+
+  it("preserves recording metadata outside guacd connection settings", () => {
+    const recording = {
+      hostId: 42,
+      userId: "user-1",
+      protocol: "vnc" as const,
+      path: "recording.guac",
+      startedAt: "2026-07-14T00:00:00.000Z",
+    };
+    const token = tokenService.createVncToken(
+      "vnc.example.test",
+      "user",
+      "secret",
+      {},
+      recording,
+    );
+
+    expect(tokenService.decryptToken(token)?.recording).toEqual(recording);
+  });
+});

src/backend/tests/hosts/host-metrics-helpers.test.ts

@@ -0,0 +1,124 @@
+import type { Client } from "ssh2";
+import { describe, it, expect, vi } from "vitest";
+import {
+  supportsMetrics,
+  isTcpPingEnabled,
+  tcpPingThroughJumpHost,
+} from "../../hosts/host-metrics-helpers.js";
+import { createConnectionLog } from "../../hosts/connection-log.js";
+
+describe("supportsMetrics", () => {
+  it("supports plain ssh hosts", () => {
+    expect(
+      supportsMetrics({ connectionType: "ssh", authType: "password" }),
+    ).toBe(true);
+  });
+
+  it("defaults missing connectionType to ssh", () => {
+    expect(supportsMetrics({ authType: "key" })).toBe(true);
+  });
+
+  it("rejects non-ssh connection types", () => {
+    expect(supportsMetrics({ connectionType: "rdp" })).toBe(false);
+    expect(supportsMetrics({ connectionType: "vnc" })).toBe(false);
+    expect(supportsMetrics({ connectionType: "telnet" })).toBe(false);
+  });
+
+  it("rejects ssh hosts that cannot run shell commands", () => {
+    expect(supportsMetrics({ connectionType: "ssh", authType: "none" })).toBe(
+      false,
+    );
+    expect(supportsMetrics({ connectionType: "ssh", authType: "opkssh" })).toBe(
+      false,
+    );
+  });
+});
+
+describe("isTcpPingEnabled", () => {
+  it("is enabled when status checks are on and tcp ping is not disabled", () => {
+    expect(
+      isTcpPingEnabled({ statusCheckEnabled: true, disableTcpPing: false }),
+    ).toBe(true);
+    expect(isTcpPingEnabled({ statusCheckEnabled: true })).toBe(true);
+  });
+
+  it("is disabled when status checks are off", () => {
+    expect(isTcpPingEnabled({ statusCheckEnabled: false })).toBe(false);
+  });
+
+  it("is disabled when tcp ping is explicitly disabled", () => {
+    expect(
+      isTcpPingEnabled({ statusCheckEnabled: true, disableTcpPing: true }),
+    ).toBe(false);
+  });
+});
+
+describe("createConnectionLog", () => {
+  it("builds a log entry without id/timestamp", () => {
+    const entry = createConnectionLog("info", "connection", "Connecting", {
+      hostId: 1,
+    });
+    expect(entry).toEqual({
+      type: "info",
+      stage: "connection",
+      message: "Connecting",
+      details: { hostId: 1 },
+    });
+    expect("id" in entry).toBe(false);
+    expect("timestamp" in entry).toBe(false);
+  });
+});
+
+describe("tcpPingThroughJumpHost", () => {
+  it("reports the final destination online when forwarding succeeds", async () => {
+    const stream = { destroy: vi.fn() };
+    const jumpClient = {
+      end: vi.fn(),
+      forwardOut: vi.fn((_src, _srcPort, host, port, callback) => {
+        expect(host).toBe("private.example");
+        expect(port).toBe(22);
+        callback(undefined, stream);
+      }),
+    } as unknown as Pick<Client, "forwardOut" | "end">;
+
+    await expect(
+      tcpPingThroughJumpHost(jumpClient, "private.example", 22),
+    ).resolves.toBe(true);
+    expect(stream.destroy).toHaveBeenCalledOnce();
+    expect(jumpClient.end).toHaveBeenCalledOnce();
+  });
+
+  it("reports the final destination offline when forwarding fails", async () => {
+    const jumpClient = {
+      end: vi.fn(),
+      forwardOut: vi.fn((_src, _srcPort, _host, _port, callback) => {
+        callback(new Error("Connection refused"));
+      }),
+    } as unknown as Pick<Client, "forwardOut" | "end">;
+
+    await expect(
+      tcpPingThroughJumpHost(jumpClient, "private.example", 22),
+    ).resolves.toBe(false);
+    expect(jumpClient.end).toHaveBeenCalledOnce();
+  });
+
+  it("reports the final destination offline when forwarding times out", async () => {
+    vi.useFakeTimers();
+    const jumpClient = {
+      end: vi.fn(),
+      forwardOut: vi.fn(),
+    } as unknown as Pick<Client, "forwardOut" | "end">;
+
+    const result = tcpPingThroughJumpHost(
+      jumpClient,
+      "private.example",
+      22,
+      5000,
+    );
+    await vi.advanceTimersByTimeAsync(5000);
+
+    await expect(result).resolves.toBe(false);
+    expect(jumpClient.end).toHaveBeenCalledOnce();
+    vi.useRealTimers();
+  });
+});

src/backend/tests/hosts/host-metrics-preferences.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import {
+  deriveEnabledWidgets,
+  defaultLayoutFromWidgets,
+  isMetricCardId,
+  isManagerCardId,
+  METRIC_CARD_IDS,
+} from "../../../types/host-metrics.js";
+
+describe("deriveEnabledWidgets", () => {
+  it("returns only metric ids, in canonical order, deduped", () => {
+    const slots = [
+      { id: "firewall" },
+      { id: "cpu" },
+      { id: "cpu" },
+      { id: "memory" },
+    ];
+    expect(deriveEnabledWidgets(slots)).toEqual(["cpu", "memory", "firewall"]);
+  });
+
+  it("excludes manager card ids (mobile contract: never leak managers)", () => {
+    const slots = [
+      { id: "cpu" },
+      { id: "service_manager" },
+      { id: "log_viewer" },
+      { id: "disk" },
+    ];
+    const out = deriveEnabledWidgets(slots);
+    expect(out).toEqual(["cpu", "disk"]);
+    for (const id of out) expect(isMetricCardId(id)).toBe(true);
+  });
+
+  it("output is always a subset of the 10 known WidgetTypes", () => {
+    const slots = METRIC_CARD_IDS.map((id) => ({ id })).concat([
+      { id: "user_manager" } as { id: (typeof METRIC_CARD_IDS)[number] },
+      { id: "bogus" } as { id: (typeof METRIC_CARD_IDS)[number] },
+    ]);
+    const out = deriveEnabledWidgets(slots);
+    expect(out).toEqual(METRIC_CARD_IDS);
+    expect(out.length).toBe(METRIC_CARD_IDS.length);
+  });
+
+  it("empty slots -> empty widgets", () => {
+    expect(deriveEnabledWidgets([])).toEqual([]);
+  });
+});
+
+describe("defaultLayoutFromWidgets", () => {
+  it("builds slots in canonical order with dense ordering", () => {
+    const layout = defaultLayoutFromWidgets(["disk", "cpu", "memory"]);
+    expect(layout.slots.map((s) => s.id)).toEqual(["cpu", "memory", "disk"]);
+    expect(layout.slots.map((s) => s.order)).toEqual([0, 1, 2]);
+    expect(layout.columns).toBe(3);
+  });
+
+  it("ignores unknown widget ids", () => {
+    const layout = defaultLayoutFromWidgets(["cpu", "nope", "service_manager"]);
+    expect(layout.slots.map((s) => s.id)).toEqual(["cpu"]);
+  });
+
+  it("assigns valid colSpans (1..3)", () => {
+    const layout = defaultLayoutFromWidgets([...METRIC_CARD_IDS]);
+    for (const s of layout.slots) {
+      expect([1, 2, 3]).toContain(s.colSpan);
+    }
+  });
+
+  it("round-trips: deriveEnabledWidgets(defaultLayout) === input order", () => {
+    const layout = defaultLayoutFromWidgets(["ports", "cpu", "firewall"]);
+    expect(deriveEnabledWidgets(layout.slots)).toEqual([
+      "cpu",
+      "ports",
+      "firewall",
+    ]);
+  });
+});
+
+describe("card id guards", () => {
+  it("classifies metric vs manager ids", () => {
+    expect(isMetricCardId("cpu")).toBe(true);
+    expect(isMetricCardId("service_manager")).toBe(false);
+    expect(isManagerCardId("service_manager")).toBe(true);
+    expect(isManagerCardId("cpu")).toBe(false);
+  });
+});

src/backend/tests/hosts/host-metrics-state.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  ConcurrentLimiter,
+  HostPollCache,
+} from "../../hosts/host-metrics-state.js";
+
+describe("ConcurrentLimiter", () => {
+  it("never exceeds max concurrent runners", async () => {
+    const limiter = new ConcurrentLimiter(2);
+    let peak = 0;
+    let current = 0;
+
+    const job = async () => {
+      current += 1;
+      peak = Math.max(peak, current);
+      await new Promise((r) => setTimeout(r, 30));
+      current -= 1;
+    };
+
+    await Promise.all([
+      limiter.run(job),
+      limiter.run(job),
+      limiter.run(job),
+      limiter.run(job),
+    ]);
+
+    expect(peak).toBeLessThanOrEqual(2);
+    expect(limiter.activeCount).toBe(0);
+    expect(limiter.pendingCount).toBe(0);
+  });
+
+  it("runs waiters in FIFO order after a slot frees", async () => {
+    const limiter = new ConcurrentLimiter(1);
+    const order: number[] = [];
+
+    const first = limiter.run(async () => {
+      order.push(1);
+      await new Promise((r) => setTimeout(r, 20));
+    });
+    const second = limiter.run(async () => {
+      order.push(2);
+    });
+    const third = limiter.run(async () => {
+      order.push(3);
+    });
+
+    await Promise.all([first, second, third]);
+    expect(order).toEqual([1, 2, 3]);
+  });
+
+  it("rejects invalid maxConcurrent", () => {
+    expect(() => new ConcurrentLimiter(0)).toThrow(/maxConcurrent/);
+  });
+});
+
+describe("HostPollCache", () => {
+  it("returns cached host within TTL for the same user", () => {
+    const cache = new HostPollCache<{ id: number; name: string }>(60_000);
+    cache.set(1, "user-a", { id: 1, name: "alpha" });
+    expect(cache.get(1, "user-a")).toEqual({ id: 1, name: "alpha" });
+    expect(cache.get(1, "user-b")).toBeNull();
+  });
+
+  it("expires entries after TTL", () => {
+    vi.useFakeTimers();
+    const cache = new HostPollCache<{ id: number }>(1_000);
+    cache.set(7, "u", { id: 7 });
+    expect(cache.get(7, "u")).toEqual({ id: 7 });
+    vi.advanceTimersByTime(1_001);
+    expect(cache.get(7, "u")).toBeNull();
+    vi.useRealTimers();
+  });
+
+  it("invalidate drops a host or the whole cache", () => {
+    const cache = new HostPollCache<{ id: number }>(60_000);
+    cache.set(1, "u", { id: 1 });
+    cache.set(2, "u", { id: 2 });
+    cache.invalidate(1);
+    expect(cache.get(1, "u")).toBeNull();
+    expect(cache.get(2, "u")).toEqual({ id: 2 });
+    cache.invalidate();
+    expect(cache.get(2, "u")).toBeNull();
+  });
+});

src/backend/tests/hosts/managers/exec-elevated.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const execCommand = vi.fn();
+vi.mock("../../../hosts/widgets/common-utils.js", () => ({
+  execCommand: (...args: unknown[]) => execCommand(...args),
+}));
+
+import {
+  execElevated,
+  ElevationError,
+} from "../../../hosts/managers/exec-elevated.js";
+import type { Client } from "ssh2";
+
+const fakeClient = {} as Client;
+
+function result(stdout: string, stderr = "", code: number | null = 0) {
+  return { stdout, stderr, code };
+}
+
+beforeEach(() => {
+  execCommand.mockReset();
+});
+
+describe("execElevated (no force)", () => {
+  it("returns the direct result when the command succeeds unprivileged", async () => {
+    execCommand.mockResolvedValueOnce(result("hello", "", 0));
+    const r = await execElevated(fakeClient, "echo hello", "pw");
+    expect(r.usedSudo).toBe(false);
+    expect(r.stdout).toBe("hello");
+    expect(execCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT escalate when stdout merely contains scary words", async () => {
+    // A non-zero exit whose OUTPUT contains 'permission denied' but stderr does
+    // not should be surfaced as-is, never retried under sudo.
+    execCommand.mockResolvedValueOnce(
+      result("log line: permission denied for user foo", "", 1),
+    );
+    const r = await execElevated(fakeClient, "grep denied /tmp/app.log", "pw");
+    expect(r.usedSudo).toBe(false);
+    expect(execCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it("escalates when stderr indicates a permission problem", async () => {
+    execCommand
+      .mockResolvedValueOnce(result("", "Permission denied", 1))
+      .mockResolvedValueOnce(result("__TX_SUDO_OK__\nelevated output", "", 0));
+    const r = await execElevated(fakeClient, "cat /etc/shadow", "pw");
+    expect(r.usedSudo).toBe(true);
+    expect(r.stdout).toBe("elevated output");
+    expect(execCommand).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws SUDO_REQUIRED when elevation is needed but no password is set", async () => {
+    execCommand.mockResolvedValueOnce(result("", "Permission denied", 1));
+    await expect(
+      execElevated(fakeClient, "cat /etc/shadow", undefined),
+    ).rejects.toMatchObject({ code: "SUDO_REQUIRED" });
+  });
+});
+
+describe("execElevated (forced)", () => {
+  it("strips the success marker from stdout", async () => {
+    execCommand.mockResolvedValueOnce(
+      result("__TX_SUDO_OK__\nthe real output\n", "", 0),
+    );
+    const r = await execElevated(fakeClient, "id", "pw", { forceSudo: true });
+    expect(r.stdout).toBe("the real output\n");
+    expect(r.usedSudo).toBe(true);
+  });
+
+  it("does NOT throw when command output contains 'incorrect password' but sudo authenticated", async () => {
+    execCommand.mockResolvedValueOnce(
+      result(
+        "__TX_SUDO_OK__\nUser entered an incorrect password earlier",
+        "",
+        0,
+      ),
+    );
+    const r = await execElevated(fakeClient, "tail /var/log/auth.log", "pw", {
+      forceSudo: true,
+    });
+    expect(r.usedSudo).toBe(true);
+    expect(r.stdout).toContain("incorrect password");
+  });
+
+  it("throws SUDO_FAILED on a real wrong-password (no marker, sudo stderr)", async () => {
+    execCommand.mockResolvedValueOnce(
+      result("", "sudo: 1 incorrect password attempt", 1),
+    );
+    await expect(
+      execElevated(fakeClient, "id", "wrong", { forceSudo: true }),
+    ).rejects.toMatchObject({ code: "SUDO_FAILED" });
+  });
+
+  it("throws NOT_SUDOER when the user is not in sudoers", async () => {
+    execCommand.mockResolvedValueOnce(
+      result("", "deploy is not in the sudoers file.", 1),
+    );
+    await expect(
+      execElevated(fakeClient, "id", "pw", { forceSudo: true }),
+    ).rejects.toMatchObject({ code: "NOT_SUDOER" });
+  });
+
+  it("throws SUDO_REQUIRED when forced without a password", async () => {
+    await expect(
+      execElevated(fakeClient, "id", undefined, { forceSudo: true }),
+    ).rejects.toBeInstanceOf(ElevationError);
+    expect(execCommand).not.toHaveBeenCalled();
+  });
+});

src/backend/tests/hosts/managers/managers.test.ts

@@ -0,0 +1,434 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildSudoCommand,
+  shellSingleQuote,
+} from "../../../hosts/managers/exec-elevated.js";
+import { parsePlatformProbe } from "../../../hosts/managers/platform.js";
+import {
+  isValidSystemdUnit,
+  isValidPid,
+  isValidPort,
+  isValidPackageName,
+  isValidUsername,
+  isValidDomain,
+  isValidDnsProvider,
+  isValidSignal,
+  isValidServiceAction,
+  isAllowedPath,
+} from "../../../hosts/managers/validation.js";
+import {
+  parseServiceList,
+  buildServiceActionCommand,
+} from "../../../hosts/managers/services.js";
+import {
+  parseProcessList,
+  buildKillCommand,
+} from "../../../hosts/managers/processes.js";
+import {
+  parseDfMounts,
+  parseTopMemory,
+} from "../../../hosts/managers/simple-reads.js";
+import {
+  parseCrontab,
+  serializeCrontab,
+  isValidCronSchedule,
+  buildApplyCrontabCommand,
+} from "../../../hosts/managers/cron.js";
+import {
+  buildPackageActionCommand,
+  parseUpgradable,
+  buildListUpgradableCommand,
+} from "../../../hosts/managers/packages.js";
+import {
+  buildIssueCommand,
+  buildRenewCommand,
+  buildRevokeCommand,
+  isValidCertName,
+  parseCertbotCertificates,
+} from "../../../hosts/managers/ssl.js";
+import {
+  buildIptablesRuleCommand,
+  buildNftRuleCommand,
+} from "../../../hosts/managers/firewall.js";
+import { parsePasswd, parseSudoers } from "../../../hosts/managers/users.js";
+import {
+  buildHealthCheckCommand,
+  parseHealthResult,
+} from "../../../hosts/managers/health.js";
+import { buildTailCommand, clampLines } from "../../../hosts/managers/logs.js";
+
+describe("exec-elevated", () => {
+  it("single-quotes and escapes for the shell", () => {
+    expect(shellSingleQuote("abc")).toBe("'abc'");
+    expect(shellSingleQuote("a'b")).toBe(`'a'"'"'b'`);
+  });
+  it("builds the sudo -S pipeline wrapping the command in sh -c with a success marker", () => {
+    expect(buildSudoCommand("systemctl restart nginx", "pw")).toBe(
+      `echo 'pw' | sudo -S -p '' sh -c 'echo __TX_SUDO_OK__; systemctl restart nginx'`,
+    );
+  });
+  it("does not merge stderr into stdout (no 2>&1)", () => {
+    expect(buildSudoCommand("id", "pw")).not.toContain("2>&1");
+  });
+  it("escapes a password containing a quote", () => {
+    expect(buildSudoCommand("id", "p'w")).toContain(`echo 'p'"'"'w'`);
+  });
+});
+
+describe("platform probe parsing", () => {
+  it("parses capabilities and prefers dnf over yum", () => {
+    const out = [
+      "systemd=1",
+      "apt=0",
+      "dnf=1",
+      "yum=1",
+      "pacman=0",
+      "certbot=1",
+      "acmesh=0",
+      "docker=1",
+      "os=Fedora Linux 40",
+    ].join("\n");
+    const p = parsePlatformProbe(out);
+    expect(p.hasSystemd).toBe(true);
+    expect(p.pkg).toBe("dnf");
+    expect(p.hasCertbot).toBe(true);
+    expect(p.hasAcmeSh).toBe(false);
+    expect(p.hasDocker).toBe(true);
+    expect(p.osPrettyName).toBe("Fedora Linux 40");
+  });
+  it("picks apt when present", () => {
+    expect(parsePlatformProbe("apt=1\ndnf=1").pkg).toBe("apt");
+  });
+});
+
+describe("validation (injection defense)", () => {
+  it("systemd units", () => {
+    expect(isValidSystemdUnit("nginx.service")).toBe(true);
+    expect(isValidSystemdUnit("ssh.socket")).toBe(true);
+    expect(isValidSystemdUnit("nginx.service; rm -rf /")).toBe(false);
+    expect(isValidSystemdUnit("nginx")).toBe(false);
+  });
+  it("pids", () => {
+    expect(isValidPid(123)).toBe(true);
+    expect(isValidPid("123")).toBe(true);
+    expect(isValidPid(0)).toBe(false);
+    expect(isValidPid("1; reboot")).toBe(false);
+    expect(isValidPid(-5)).toBe(false);
+  });
+  it("ports", () => {
+    expect(isValidPort(443)).toBe(true);
+    expect(isValidPort(0)).toBe(false);
+    expect(isValidPort(70000)).toBe(false);
+  });
+  it("package names", () => {
+    expect(isValidPackageName("nginx")).toBe(true);
+    expect(isValidPackageName("lib-foo.bar+1")).toBe(true);
+    expect(isValidPackageName("nginx && curl evil")).toBe(false);
+    expect(isValidPackageName("-rf")).toBe(false);
+  });
+  it("usernames and domains", () => {
+    expect(isValidUsername("deploy")).toBe(true);
+    expect(isValidUsername("root; rm")).toBe(false);
+    expect(isValidDomain("example.com")).toBe(true);
+    expect(isValidDomain("*.example.com")).toBe(true);
+    expect(isValidDomain("ex ample.com")).toBe(false);
+    expect(isValidDomain("a;b.com")).toBe(false);
+  });
+  it("dns providers, signals, service actions", () => {
+    expect(isValidDnsProvider("cloudflare")).toBe(true);
+    expect(isValidDnsProvider("cf; rm")).toBe(false);
+    expect(isValidSignal("KILL")).toBe(true);
+    expect(isValidSignal("BOOM")).toBe(false);
+    expect(isValidServiceAction("restart")).toBe(true);
+    expect(isValidServiceAction("destroy")).toBe(false);
+  });
+  it("path allowlist rejects traversal and out-of-allowlist", () => {
+    expect(isAllowedPath("/var/log/syslog", ["/var/log"])).toBe(true);
+    expect(isAllowedPath("/var/log/../../etc/passwd", ["/var/log"])).toBe(
+      false,
+    );
+    expect(isAllowedPath("/etc/passwd", ["/var/log"])).toBe(false);
+    expect(isAllowedPath("relative/path", ["/var/log"])).toBe(false);
+  });
+});
+
+describe("services", () => {
+  it("parses list-units --plain", () => {
+    const out =
+      "nginx.service loaded active running A high performance web server\n" +
+      "ssh.service loaded active running OpenBSD Secure Shell server\n" +
+      "cron.service loaded inactive dead Regular background program";
+    const rows = parseServiceList(out);
+    expect(rows).toHaveLength(3);
+    expect(rows[0]).toMatchObject({ unit: "nginx.service", active: "active" });
+    expect(rows[2].active).toBe("inactive");
+  });
+  it("builds action command", () => {
+    expect(buildServiceActionCommand("nginx.service", "restart")).toBe(
+      "systemctl restart nginx.service",
+    );
+  });
+});
+
+describe("processes", () => {
+  it("parses ps output", () => {
+    const out =
+      "1234 1 root 12.5 3.2 45000 S /usr/bin/node node server.js\n" +
+      "5678 1234 deploy 0.0 1.1 12000 Sl bash -bash";
+    const rows = parseProcessList(out);
+    expect(rows[0]).toMatchObject({
+      pid: 1234,
+      user: "root",
+      cpu: 12.5,
+      command: "/usr/bin/node",
+    });
+    expect(rows[1].pid).toBe(5678);
+  });
+  it("builds kill command", () => {
+    expect(buildKillCommand(42, "TERM")).toBe("kill -TERM 42");
+  });
+});
+
+describe("simple reads", () => {
+  it("parses df -Pk and skips tmpfs", () => {
+    const out =
+      "/dev/sda1 100000 40000 60000 40% /\n" +
+      "tmpfs 8000 0 8000 0% /dev/shm\n" +
+      "/dev/sdb1 200000 100000 100000 50% /data";
+    const mounts = parseDfMounts(out);
+    expect(mounts).toHaveLength(2);
+    expect(mounts[0].mount).toBe("/");
+    expect(mounts[1].usePct).toBe(50);
+  });
+  it("parses top by memory", () => {
+    const rows = parseTopMemory("1234 root 5.5 50000 node");
+    expect(rows[0]).toMatchObject({ pid: 1234, mem: 5.5, command: "node" });
+  });
+});
+
+describe("cron", () => {
+  it("parses enabled and toggled entries", () => {
+    const out = "0 2 * * * /backup.sh\n# 30 4 * * * /old.sh\nPATH=/usr/bin";
+    const entries = parseCrontab(out);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toMatchObject({ enabled: true, schedule: "0 2 * * *" });
+    expect(entries[1].enabled).toBe(false);
+  });
+  it("validates schedules", () => {
+    expect(isValidCronSchedule("0 2 * * *")).toBe(true);
+    expect(isValidCronSchedule("@daily")).toBe(true);
+    expect(isValidCronSchedule("not a schedule")).toBe(false);
+  });
+  it("serializes (commenting disabled entries) and round-trips", () => {
+    const body = serializeCrontab([
+      { raw: "", enabled: true, schedule: "0 2 * * *", command: "/a.sh" },
+      { raw: "", enabled: false, schedule: "@daily", command: "/b.sh" },
+    ]);
+    expect(body).toBe("0 2 * * * /a.sh\n# @daily /b.sh\n");
+    const reparsed = parseCrontab(body);
+    expect(reparsed[0].enabled).toBe(true);
+    expect(reparsed[1].enabled).toBe(false);
+  });
+  it("builds apply command piping into crontab -", () => {
+    expect(buildApplyCrontabCommand("x\n")).toBe(
+      `printf '%s' 'x\n' | crontab -`,
+    );
+  });
+});
+
+describe("packages", () => {
+  it("builds per-distro commands", () => {
+    expect(buildPackageActionCommand("apt", "install", "nginx")).toContain(
+      "apt-get -y install nginx",
+    );
+    expect(buildPackageActionCommand("pacman", "upgrade-all")).toBe(
+      "pacman -Syu --noconfirm",
+    );
+    expect(buildPackageActionCommand(null, "install", "x")).toBeNull();
+  });
+  it("lists per distro", () => {
+    expect(buildListUpgradableCommand("apt")).toContain(
+      "apt list --upgradable",
+    );
+    expect(buildListUpgradableCommand(null)).toBeNull();
+  });
+  it("parses apt upgradable", () => {
+    const out =
+      "nginx/focal-updates 1.18.0-2 amd64 [upgradable from: 1.18.0-1]";
+    const pkgs = parseUpgradable("apt", out);
+    expect(pkgs[0]).toMatchObject({
+      name: "nginx",
+      newVersion: "1.18.0-2",
+      currentVersion: "1.18.0-1",
+    });
+  });
+  it("parses pacman upgradable", () => {
+    const pkgs = parseUpgradable("pacman", "linux 6.1 -> 6.2");
+    expect(pkgs[0]).toMatchObject({ name: "linux", newVersion: "6.2" });
+  });
+});
+
+describe("ssl (dual client)", () => {
+  it("builds certbot issue for http + dns", () => {
+    expect(
+      buildIssueCommand({
+        client: "certbot",
+        domains: ["a.com"],
+        challenge: "http-standalone",
+      }),
+    ).toContain(
+      "certbot certonly --non-interactive --agree-tos --standalone -d 'a.com'",
+    );
+    expect(
+      buildIssueCommand({
+        client: "certbot",
+        domains: ["a.com"],
+        challenge: "dns",
+        dnsProvider: "cloudflare",
+      }),
+    ).toContain("--dns-cloudflare");
+  });
+  it("builds acme.sh issue", () => {
+    const cmd = buildIssueCommand({
+      client: "acme.sh",
+      domains: ["a.com", "b.com"],
+      challenge: "dns",
+      dnsProvider: "cf",
+    });
+    expect(cmd).toContain("--issue --dns dns_cf");
+    expect(cmd).toContain("-d 'a.com'");
+    expect(cmd).toContain("-d 'b.com'");
+  });
+  it("builds renew per client", () => {
+    expect(buildRenewCommand("certbot", true)).toBe("certbot renew --dry-run");
+    expect(buildRenewCommand("acme.sh", false)).toContain("--renew-all");
+  });
+  it("builds revoke per client", () => {
+    expect(buildRevokeCommand("certbot", "example.com")).toBe(
+      "certbot revoke --non-interactive --cert-name 'example.com' --delete-after-revoke",
+    );
+    const acme = buildRevokeCommand("acme.sh", "example.com");
+    expect(acme).toContain("--revoke -d 'example.com'");
+    expect(acme).toContain("--remove -d 'example.com'");
+  });
+  it("validates certificate names (rejects shell metachars)", () => {
+    expect(isValidCertName("example.com")).toBe(true);
+    expect(isValidCertName("example.com-0001")).toBe(true);
+    expect(isValidCertName("*.example.com")).toBe(true);
+    expect(isValidCertName("a.com; rm -rf /")).toBe(false);
+    expect(isValidCertName("")).toBe(false);
+    expect(isValidCertName(undefined)).toBe(false);
+  });
+  it("parses certbot certificates", () => {
+    const out = [
+      "Found the following certs:",
+      "  Certificate Name: example.com",
+      "    Domains: example.com www.example.com",
+      "    Expiry Date: 2026-09-01 12:00:00+00:00 (VALID: 80 days)",
+      "    Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem",
+    ].join("\n");
+    const certs = parseCertbotCertificates(out);
+    expect(certs[0]).toMatchObject({
+      name: "example.com",
+      client: "certbot",
+    });
+    expect(certs[0].domains).toContain("www.example.com");
+  });
+});
+
+describe("firewall", () => {
+  it("builds iptables add/delete on INPUT only", () => {
+    expect(
+      buildIptablesRuleCommand("add", {
+        protocol: "tcp",
+        port: 443,
+        target: "ACCEPT",
+      }),
+    ).toBe("iptables -A INPUT -p tcp --dport 443 -j ACCEPT");
+    expect(
+      buildIptablesRuleCommand("delete", {
+        protocol: "udp",
+        port: 53,
+        target: "DROP",
+      }),
+    ).toBe("iptables -D INPUT -p udp --dport 53 -j DROP");
+  });
+  it("builds nft rules", () => {
+    expect(
+      buildNftRuleCommand("add", {
+        protocol: "tcp",
+        port: 22,
+        target: "ACCEPT",
+      }),
+    ).toContain("add rule inet filter input tcp dport 22 accept");
+  });
+});
+
+describe("users", () => {
+  it("parses passwd for human users only", () => {
+    const out =
+      "root:x:0:0:root:/root:/bin/bash\n" +
+      "deploy:x:1000:1000:Deploy:/home/deploy:/bin/bash\n" +
+      "nobody:x:65534:65534:nobody:/:/usr/sbin/nologin";
+    const users = parsePasswd(out);
+    expect(users).toHaveLength(1);
+    expect(users[0].name).toBe("deploy");
+  });
+  it("parses sudoers membership", () => {
+    const out = "sudo:x:27:deploy,alice\nwheel:x:10:bob";
+    expect(parseSudoers(out).sort()).toEqual(["alice", "bob", "deploy"]);
+  });
+});
+
+describe("health checks", () => {
+  it("builds tcp and http commands", () => {
+    const tcp = buildHealthCheckCommand({
+      id: "1",
+      name: "ssh",
+      type: "tcp",
+      target: "localhost",
+      port: 22,
+    });
+    expect(tcp).toContain("/dev/tcp/");
+    const http = buildHealthCheckCommand({
+      id: "2",
+      name: "web",
+      type: "http",
+      target: "example.com",
+      path: "/health",
+    });
+    expect(http).toContain("curl -s -o /dev/null");
+    expect(http).toContain("http://example.com/health");
+  });
+  it("parses tcp and http results", () => {
+    const tcp = parseHealthResult(
+      { id: "1", name: "ssh", type: "tcp", target: "h", port: 22 },
+      "ok 12",
+    );
+    expect(tcp).toMatchObject({ ok: true, latencyMs: 12 });
+    const http = parseHealthResult(
+      { id: "2", name: "web", type: "http", target: "h" },
+      "200 0.045",
+    );
+    expect(http).toMatchObject({ ok: true, latencyMs: 45 });
+    const bad = parseHealthResult(
+      { id: "3", name: "web", type: "http", target: "h" },
+      "500 0.01",
+    );
+    expect(bad.ok).toBe(false);
+  });
+});
+
+describe("logs", () => {
+  it("clamps line counts", () => {
+    expect(clampLines(50)).toBe(50);
+    expect(clampLines(99999)).toBe(2000);
+    expect(clampLines("abc")).toBe(200);
+    expect(clampLines(0)).toBe(1);
+  });
+  it("builds a quoted tail command without suppressing stderr", () => {
+    expect(buildTailCommand("/var/log/syslog", 100)).toBe(
+      "tail -n 100 '/var/log/syslog'",
+    );
+  });
+});

src/backend/tests/hosts/ssh-dns.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  isRetriableDnsError,
+  resolveHostForSshConnect,
+  resolveSshConnectConfigHost,
+  shouldResolveBeforeSshConnect,
+} from "../../hosts/ssh-dns.js";
+
+describe("SSH DNS resolution", () => {
+  it("retries transient EAI_AGAIN errors before returning an address", async () => {
+    const lookup = vi
+      .fn()
+      .mockRejectedValueOnce(
+        Object.assign(new Error("try again"), { code: "EAI_AGAIN" }),
+      )
+      .mockResolvedValueOnce({ address: "10.0.0.5", family: 4 });
+    const wait = vi.fn().mockResolvedValue(undefined);
+
+    await expect(
+      resolveHostForSshConnect("alp", lookup, [10], wait),
+    ).resolves.toEqual({
+      host: "10.0.0.5",
+      resolvedAddress: "10.0.0.5",
+      attempts: 2,
+    });
+    expect(wait).toHaveBeenCalledWith(10);
+  });
+
+  it("does not retry permanent DNS failures", async () => {
+    const error = Object.assign(new Error("not found"), { code: "ENOTFOUND" });
+    const lookup = vi.fn().mockRejectedValue(error);
+    const wait = vi.fn().mockResolvedValue(undefined);
+
+    await expect(
+      resolveHostForSshConnect("missing", lookup, [10], wait),
+    ).rejects.toBe(error);
+    expect(wait).not.toHaveBeenCalled();
+  });
+
+  it("skips DNS lookup for literal IP addresses", async () => {
+    const lookup = vi.fn();
+
+    await expect(
+      resolveHostForSshConnect("192.0.2.1", lookup),
+    ).resolves.toEqual({
+      host: "192.0.2.1",
+      attempts: 0,
+    });
+    expect(lookup).not.toHaveBeenCalled();
+  });
+
+  it("detects retryable DNS errors by code or message", () => {
+    expect(isRetriableDnsError({ code: "EAI_AGAIN" })).toBe(true);
+    expect(isRetriableDnsError(new Error("getaddrinfo EAI_AGAIN alp"))).toBe(
+      true,
+    );
+    expect(isRetriableDnsError({ code: "ENOTFOUND" })).toBe(false);
+  });
+
+  it("only pre-resolves hostnames", () => {
+    expect(shouldResolveBeforeSshConnect("alp")).toBe(true);
+    expect(shouldResolveBeforeSshConnect("127.0.0.1")).toBe(false);
+    expect(shouldResolveBeforeSshConnect("[2001:db8::1]")).toBe(false);
+  });
+
+  it("updates SSH connect config hosts in place", async () => {
+    const lookup = vi
+      .fn()
+      .mockResolvedValue({ address: "10.0.0.6", family: 4 });
+    const config = { host: "alp", port: 22 };
+
+    await expect(resolveSshConnectConfigHost(config, lookup)).resolves.toEqual({
+      host: "10.0.0.6",
+      port: 22,
+      originalHost: "alp",
+      resolvedHost: "10.0.0.6",
+    });
+  });
+});

src/backend/tests/hosts/terminal-agent-auth.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const mockAccess = vi.fn();
+
+vi.mock("fs/promises", () => ({
+  access: mockAccess,
+}));
+
+import { resolveAgentSocket } from "../../hosts/terminal-auth-helpers.js";
+
+describe("resolveAgentSocket", () => {
+  const originalEnv = process.env.SSH_AUTH_SOCK;
+  const originalPlatform = process.platform;
+
+  beforeEach(() => {
+    mockAccess.mockReset();
+    delete process.env.SSH_AUTH_SOCK;
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.SSH_AUTH_SOCK = originalEnv;
+    } else {
+      delete process.env.SSH_AUTH_SOCK;
+    }
+    Object.defineProperty(process, "platform", { value: originalPlatform });
+  });
+
+  it("uses explicit socket path from terminalConfig over SSH_AUTH_SOCK", async () => {
+    Object.defineProperty(process, "platform", { value: "linux" });
+    process.env.SSH_AUTH_SOCK = "/tmp/ssh-env/agent.123";
+    mockAccess.mockResolvedValue(undefined);
+
+    const result = await resolveAgentSocket({
+      agentSocketPath: "/run/user/1000/gnupg/S.gpg-agent.ssh",
+    });
+
+    expect(result).toEqual({
+      socketPath: "/run/user/1000/gnupg/S.gpg-agent.ssh",
+    });
+    expect(mockAccess).toHaveBeenCalledWith(
+      "/run/user/1000/gnupg/S.gpg-agent.ssh",
+    );
+  });
+
+  it("falls back to SSH_AUTH_SOCK when no explicit path is provided", async () => {
+    Object.defineProperty(process, "platform", { value: "linux" });
+    process.env.SSH_AUTH_SOCK = "/tmp/ssh-XXXX/agent.456";
+    mockAccess.mockResolvedValue(undefined);
+
+    const result = await resolveAgentSocket({});
+
+    expect(result).toEqual({ socketPath: "/tmp/ssh-XXXX/agent.456" });
+  });
+
+  it("falls back to SSH_AUTH_SOCK when agentSocketPath is empty string", async () => {
+    Object.defineProperty(process, "platform", { value: "linux" });
+    process.env.SSH_AUTH_SOCK = "/tmp/ssh-XXXX/agent.789";
+    mockAccess.mockResolvedValue(undefined);
+
+    const result = await resolveAgentSocket({ agentSocketPath: "  " });
+
+    expect(result).toEqual({ socketPath: "/tmp/ssh-XXXX/agent.789" });
+  });
+
+  it("returns error when neither SSH_AUTH_SOCK nor explicit path is set", async () => {
+    const result = await resolveAgentSocket({});
+
+    expect(result).toHaveProperty("error");
+    expect((result as { error: string }).error).toContain("SSH_AUTH_SOCK");
+  });
+
+  it("returns error when terminalConfig is undefined and SSH_AUTH_SOCK is not set", async () => {
+    const result = await resolveAgentSocket(undefined);
+
+    expect(result).toHaveProperty("error");
+  });
+
+  it("returns error on non-Windows when socket file is missing", async () => {
+    Object.defineProperty(process, "platform", { value: "linux" });
+    process.env.SSH_AUTH_SOCK = "/tmp/missing-agent.sock";
+    mockAccess.mockRejectedValue(new Error("ENOENT"));
+
+    const result = await resolveAgentSocket({});
+
+    expect(result).toHaveProperty("error");
+    expect((result as { error: string }).error).toContain(
+      "/tmp/missing-agent.sock",
+    );
+  });
+
+  it("skips file existence check on Windows", async () => {
+    Object.defineProperty(process, "platform", { value: "win32" });
+    process.env.SSH_AUTH_SOCK = "\\\\.\\pipe\\openssh-ssh-agent";
+
+    const result = await resolveAgentSocket({});
+
+    expect(result).toEqual({
+      socketPath: "\\\\.\\pipe\\openssh-ssh-agent",
+    });
+    expect(mockAccess).not.toHaveBeenCalled();
+  });
+});

src/backend/tests/hosts/terminal-port-knocking.test.ts

@@ -0,0 +1,57 @@
+import { EventEmitter } from "events";
+import { describe, expect, it, vi } from "vitest";
+import { performPortKnocking } from "../../hosts/terminal-auth-helpers.js";
+
+class FakeTcpSocket extends EventEmitter {
+  readonly connect = vi.fn();
+  readonly destroy = vi.fn();
+}
+
+describe("performPortKnocking", () => {
+  it("continues through TCP knock errors", async () => {
+    const first = new FakeTcpSocket();
+    const second = new FakeTcpSocket();
+    const wait = vi.fn().mockResolvedValue(undefined);
+
+    const knocking = performPortKnocking(
+      "192.0.2.10",
+      [
+        { port: 1111, protocol: "tcp", delay: 10 },
+        { port: 2222, protocol: "tcp", delay: 0 },
+      ],
+      {
+        createTcpSocket: vi
+          .fn()
+          .mockReturnValueOnce(first)
+          .mockReturnValueOnce(second),
+        wait,
+      },
+    );
+
+    first.emit("error", new Error("closed"));
+    await Promise.resolve();
+    second.emit("connect");
+    await knocking;
+
+    expect(first.connect).toHaveBeenCalledWith(1111, "192.0.2.10");
+    expect(second.connect).toHaveBeenCalledWith(2222, "192.0.2.10");
+    expect(first.destroy).toHaveBeenCalled();
+    expect(second.destroy).toHaveBeenCalled();
+    expect(wait).toHaveBeenCalledWith(10);
+  });
+
+  it("times out TCP knocks that are silently dropped", async () => {
+    const socket = new FakeTcpSocket();
+    const wait = vi.fn().mockResolvedValue(undefined);
+
+    await performPortKnocking("192.0.2.10", [{ port: 1111, delay: 0 }], {
+      createTcpSocket: () => socket as never,
+      tcpTimeoutMs: 1,
+      wait,
+    });
+
+    expect(socket.connect).toHaveBeenCalledWith(1111, "192.0.2.10");
+    expect(socket.destroy).toHaveBeenCalled();
+    expect(wait).not.toHaveBeenCalled();
+  });
+});

src/backend/tests/hosts/terminal-session-manager.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Stub all external imports before loading the module under test
+const mockCreate = vi.fn().mockResolvedValue({ id: 1 });
+const mockUpdateEnded = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("../../database/db/index.js", () => ({
+  getDb: () => ({}),
+}));
+
+vi.mock("../../database/repositories/factory.js", () => ({
+  createCurrentSessionRecordingRepository: () => ({
+    create: mockCreate,
+    updateEnded: mockUpdateEnded,
+  }),
+}));
+
+vi.mock("../../utils/logger.js", () => ({
+  sshLogger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+// Mock individual fs.promises methods via a stub object
+const mockMkdir = vi.fn().mockResolvedValue(undefined);
+const mockWriteFile = vi.fn().mockResolvedValue(undefined);
+const mockAppendFile = vi.fn().mockResolvedValue(undefined);
+const mockUnlink = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("fs", () => ({
+  default: {
+    promises: {
+      mkdir: mockMkdir,
+      writeFile: mockWriteFile,
+      appendFile: mockAppendFile,
+      readFile: vi.fn(),
+      unlink: mockUnlink,
+    },
+  },
+  promises: {
+    mkdir: mockMkdir,
+    writeFile: mockWriteFile,
+    appendFile: mockAppendFile,
+    readFile: vi.fn(),
+    unlink: mockUnlink,
+  },
+}));
+
+const { sessionManager } =
+  await import("../../hosts/terminal-session-manager.js");
+
+describe("TerminalSessionManager - session logging", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Re-apply resolved values after clearAllMocks
+    mockMkdir.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+    mockCreate.mockResolvedValue({ id: 1 });
+    mockUpdateEnded.mockResolvedValue(undefined);
+  });
+
+  it("createSession stores sessionLoggingEnabled=true by default", () => {
+    const id = sessionManager.createSession("u1", 1, "host", 80, 24);
+    const session = sessionManager.getSession(id);
+    expect(session?.sessionLoggingEnabled).toBe(true);
+    sessionManager.destroySession(id);
+  });
+
+  it("createSession stores sessionLoggingEnabled=false when passed", () => {
+    const id = sessionManager.createSession(
+      "u1",
+      1,
+      "host",
+      80,
+      24,
+      undefined,
+      false,
+    );
+    const session = sessionManager.getSession(id);
+    expect(session?.sessionLoggingEnabled).toBe(false);
+    sessionManager.destroySession(id);
+  });
+
+  it("does not write log file when sessionLoggingEnabled=false", async () => {
+    const id = sessionManager.createSession(
+      "u1",
+      1,
+      "host",
+      80,
+      24,
+      undefined,
+      false,
+    );
+    sessionManager.bufferOutput(id, "some output");
+    sessionManager.destroySession(id);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it("writes log file and inserts DB row when sessionLoggingEnabled=true", async () => {
+    const id = sessionManager.createSession(
+      "u1",
+      1,
+      "host",
+      80,
+      24,
+      undefined,
+      true,
+    );
+    sessionManager.bufferOutput(id, "terminal output data");
+    sessionManager.destroySession(id);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(mockWriteFile).toHaveBeenCalledOnce();
+    expect(mockCreate).toHaveBeenCalledOnce();
+  });
+
+  it("does not write log file when buffer is empty", async () => {
+    const id = sessionManager.createSession(
+      "u1",
+      1,
+      "host",
+      80,
+      24,
+      undefined,
+      true,
+    );
+    sessionManager.destroySession(id);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it("bufferOutput trims old data when exceeding 512KB", () => {
+    const id = sessionManager.createSession(
+      "u1",
+      1,
+      "host",
+      80,
+      24,
+      undefined,
+      false,
+    );
+    const chunk = "x".repeat(300 * 1024);
+    sessionManager.bufferOutput(id, chunk);
+    sessionManager.bufferOutput(id, chunk);
+    const session = sessionManager.getSession(id);
+    expect(session!.outputBufferBytes).toBeLessThanOrEqual(512 * 1024);
+    sessionManager.destroySession(id);
+  });
+});

src/backend/tests/hosts/tmux-helper.test.ts

@@ -0,0 +1,56 @@
+import { EventEmitter } from "node:events";
+import type { Client } from "ssh2";
+import { describe, expect, it } from "vitest";
+import {
+  detectTmux,
+  tmuxCommand,
+  withTmuxPath,
+} from "../../hosts/tmux-helper.js";
+
+describe("tmux command path handling", () => {
+  it("adds common non-login shell tmux paths", () => {
+    const command = withTmuxPath("command -v tmux");
+
+    expect(command).toMatch(/^\/bin\/sh -c '/);
+    expect(command).toContain("/opt/homebrew/bin");
+    expect(command).toContain("/usr/local/bin");
+    expect(command).toContain("/opt/bin");
+    expect(command).toContain("/usr/pkg/bin");
+    expect(command).toContain(":$PATH; export PATH; command -v tmux");
+  });
+
+  it("wraps tmux invocations with the same path", () => {
+    expect(tmuxCommand("list-sessions")).toMatch(
+      /^\/bin\/sh -c 'PATH=.*:\$PATH; export PATH; tmux list-sessions'$/,
+    );
+  });
+
+  it("detects suffixed tmux versions without parsing the version number", async () => {
+    const commands: string[] = [];
+    const conn = {
+      exec(command: string, callback: (error: null, stream: never) => void) {
+        commands.push(command);
+        const stream = new EventEmitter() as EventEmitter & {
+          stderr: EventEmitter;
+        };
+        stream.stderr = new EventEmitter();
+        callback(null, stream as never);
+
+        queueMicrotask(() => {
+          if (commands.length === 1) {
+            stream.emit("data", Buffer.from("tmux 3.7b\n"));
+            stream.emit("close", 0);
+            return;
+          }
+          stream.emit("close", 1);
+        });
+      },
+    } as unknown as Client;
+
+    await expect(detectTmux(conn)).resolves.toEqual({
+      available: true,
+      sessions: [],
+    });
+    expect(commands[0]).toContain("tmux -V");
+  });
+});

src/backend/tests/hosts/tmux-monitor-helpers.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect } from "vitest";
+import {
+  SEP,
+  parseSessions,
+  parseWindows,
+  parsePanes,
+  parsePsOutput,
+  parseGpuOutput,
+  buildPaneMetrics,
+  attachPanesToWindows,
+  shellEscape,
+} from "../../hosts/tmux-monitor-helpers.js";
+
+function join(...fields: (string | number)[]): string {
+  return fields.join(SEP);
+}
+
+describe("parseSessions", () => {
+  it("parses tmux list-sessions output", () => {
+    const output = [
+      join("training", 1760000000, 1760001000, 1),
+      join("lab|with|pipes", 1760000500, 1760002000, 0),
+    ].join("\n");
+
+    const sessions = parseSessions(output);
+    expect(sessions).toHaveLength(2);
+    expect(sessions[0]).toEqual({
+      name: "training",
+      created: 1760000000,
+      lastActivity: 1760001000,
+      attachedClients: 1,
+    });
+    // Session names containing "|" survive because SEP is a multi-char token
+    expect(sessions[1].name).toBe("lab|with|pipes");
+    expect(sessions[1].attachedClients).toBe(0);
+  });
+
+  it("returns empty array for empty output", () => {
+    expect(parseSessions("")).toEqual([]);
+  });
+});
+
+describe("parseWindows", () => {
+  it("groups windows by session", () => {
+    const output = [
+      join("training", 0, 1, "vim"),
+      join("training", 1, 0, "logs"),
+      join("api", 0, 1, "server"),
+    ].join("\n");
+
+    const windows = parseWindows(output);
+    expect(windows.get("training")).toHaveLength(2);
+    expect(windows.get("training")![0]).toMatchObject({
+      index: 0,
+      name: "vim",
+      active: true,
+    });
+    expect(windows.get("api")![0].name).toBe("server");
+  });
+});
+
+describe("parsePanes", () => {
+  it("parses full pane lines including free-text fields", () => {
+    const output = join(
+      "training",
+      0,
+      "%3",
+      1,
+      12345,
+      1,
+      120,
+      40,
+      "python",
+      "/home/user/my|dir",
+      "gpu01: train.py",
+    );
+
+    const panes = parsePanes(output);
+    expect(panes).toHaveLength(1);
+    expect(panes[0]).toEqual({
+      sessionName: "training",
+      windowIndex: 0,
+      id: "%3",
+      index: 1,
+      pid: 12345,
+      active: true,
+      width: 120,
+      height: 40,
+      command: "python",
+      path: "/home/user/my|dir",
+      title: "gpu01: train.py",
+    });
+  });
+});
+
+describe("parsePsOutput", () => {
+  it("parses ps -eo pid,ppid,pcpu,pmem,rss,comm output", () => {
+    const output = [
+      "    1     0  0.0  0.1  1234 systemd",
+      "12345     1  2.5  1.0 50000 bash",
+      "12400 12345 95.3 12.5 800000 python3",
+      "garbage line",
+    ].join("\n");
+
+    const procs = parsePsOutput(output);
+    expect(procs).toHaveLength(3);
+    expect(procs[2]).toEqual({
+      pid: 12400,
+      ppid: 12345,
+      cpu: 95.3,
+      mem: 12.5,
+      rss: 800000,
+      comm: "python3",
+    });
+  });
+});
+
+describe("parseGpuOutput", () => {
+  it("parses nvidia-smi csv output and sums per pid", () => {
+    const output = ["12400, 8000", "12400, 2000", "99999, 512"].join("\n");
+    const gpu = parseGpuOutput(output);
+    expect(gpu.get(12400)).toBe(10000);
+    expect(gpu.get(99999)).toBe(512);
+  });
+
+  it("handles empty output (no GPU)", () => {
+    expect(parseGpuOutput("").size).toBe(0);
+  });
+});
+
+describe("buildPaneMetrics", () => {
+  const panes = parsePanes(
+    [
+      join("training", 0, "%1", 0, 100, 1, 80, 24, "bash", "/", "t"),
+      join("idle", 0, "%2", 0, 200, 1, 80, 24, "bash", "/", "t"),
+    ].join("\n"),
+  );
+
+  const processes = parsePsOutput(
+    [
+      // pane %1: bash(100) -> python3(110) -> worker(111)
+      "  100     1  0.1  0.1  4000 bash",
+      "  110   100 90.0 10.0 700000 python3",
+      "  111   110  9.5  2.0 100000 dataloader",
+      // pane %2: bash(200) only
+      "  200     1  0.0  0.1  4000 bash",
+      // unrelated process
+      "  300     1 50.0  5.0 200000 chrome",
+    ].join("\n"),
+  );
+
+  it("aggregates descendant trees per pane", () => {
+    const metrics = buildPaneMetrics(panes, processes, new Map());
+    const m1 = metrics.find((m) => m.paneId === "%1")!;
+    expect(m1.processCount).toBe(3);
+    expect(m1.cpuPercent).toBeCloseTo(99.6, 1);
+    expect(m1.memRssKb).toBe(804000);
+    expect(m1.topCommand).toBe("python3");
+
+    const m2 = metrics.find((m) => m.paneId === "%2")!;
+    expect(m2.processCount).toBe(1);
+    expect(m2.cpuPercent).toBe(0);
+    // Unrelated process is never attributed
+    expect(m2.memRssKb).toBe(4000);
+  });
+
+  it("attributes GPU memory through the process tree", () => {
+    const gpu = new Map([
+      [110, 8000],
+      [300, 4000],
+    ]);
+    const metrics = buildPaneMetrics(panes, processes, gpu);
+    expect(metrics.find((m) => m.paneId === "%1")!.gpuMemMb).toBe(8000);
+    expect(metrics.find((m) => m.paneId === "%2")!.gpuMemMb).toBe(0);
+  });
+
+  it("handles a pane whose pid is missing from ps output", () => {
+    const orphan = parsePanes(
+      join("gone", 0, "%9", 0, 99999, 0, 80, 24, "bash", "/", "t"),
+    );
+    const metrics = buildPaneMetrics(orphan, processes, new Map());
+    expect(metrics[0].processCount).toBe(0);
+    expect(metrics[0].cpuPercent).toBe(0);
+    expect(metrics[0].topCommand).toBeNull();
+  });
+
+  it("does not loop on cyclic ppid data", () => {
+    const cyclic = parsePsOutput(
+      ["  100   101 1.0 0.1 1000 a", "  101   100 1.0 0.1 1000 b"].join("\n"),
+    );
+    const pane = parsePanes(
+      join("s", 0, "%1", 0, 100, 1, 80, 24, "a", "/", "t"),
+    );
+    const metrics = buildPaneMetrics(pane, cyclic, new Map());
+    expect(metrics[0].processCount).toBe(2);
+  });
+});
+
+describe("attachPanesToWindows", () => {
+  it("places panes into their windows", () => {
+    const windows = parseWindows(
+      [join("s1", 0, 1, "main"), join("s1", 1, 0, "logs")].join("\n"),
+    );
+    const panes = parsePanes(
+      [
+        join("s1", 0, "%1", 0, 100, 1, 80, 24, "bash", "/", "t"),
+        join("s1", 1, "%2", 0, 200, 0, 80, 24, "tail", "/", "t"),
+        join("unknown", 5, "%3", 0, 300, 0, 80, 24, "bash", "/", "t"),
+      ].join("\n"),
+    );
+
+    attachPanesToWindows(windows, panes);
+    expect(windows.get("s1")![0].panes).toHaveLength(1);
+    expect(windows.get("s1")![0].panes[0].id).toBe("%1");
+    expect(windows.get("s1")![1].panes[0].id).toBe("%2");
+  });
+});
+
+describe("shellEscape", () => {
+  it("wraps in single quotes and escapes embedded quotes", () => {
+    expect(shellEscape("simple")).toBe("'simple'");
+    expect(shellEscape("it's")).toBe("'it'\\''s'");
+    expect(shellEscape("$(rm -rf /)")).toBe("'$(rm -rf /)'");
+  });
+});

src/backend/tests/hosts/vault-signer-core.test.ts

@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeAll, afterEach, vi } from "vitest";
+import { execFileSync } from "child_process";
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import os from "os";
+import path from "path";
+import ssh2Pkg from "ssh2";
+import {
+  generateEphemeralKeyPair,
+  parseCertValidBefore,
+  startVaultOidc,
+  completeVaultOidc,
+  signWithVault,
+  type VaultProfileConfig,
+} from "../../hosts/vault-signer-core.js";
+
+const { utils: ssh2Utils } = ssh2Pkg;
+
+describe("generateEphemeralKeyPair", () => {
+  for (const keyType of [
+    "ssh-ed25519",
+    "ecdsa-sha2-nistp256",
+    "ssh-rsa",
+  ] as const) {
+    it(`generates a parseable ${keyType} keypair`, () => {
+      const pair = generateEphemeralKeyPair(keyType);
+      expect(pair.privateKey).toContain("BEGIN OPENSSH PRIVATE KEY");
+      expect(pair.publicKey.split(/\s+/)[0]).toBe(keyType);
+
+      // Both halves must be parseable by the same library that signs/connects.
+      const priv = ssh2Utils.parseKey(pair.privateKey);
+      expect(priv instanceof Error).toBe(false);
+      const pub = ssh2Utils.parseKey(pair.publicKey);
+      expect(pub instanceof Error).toBe(false);
+    });
+  }
+
+  it("defaults to ed25519 for unknown key types", () => {
+    const pair = generateEphemeralKeyPair("nonsense");
+    expect(pair.publicKey.startsWith("ssh-ed25519")).toBe(true);
+  });
+});
+
+describe("parseCertValidBefore", () => {
+  let cert = "";
+  let signedAt = 0;
+  let haveSshKeygen = true;
+
+  beforeAll(() => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "vault-cert-test-"));
+    try {
+      execFileSync("ssh-keygen", [
+        "-t",
+        "ed25519",
+        "-f",
+        `${dir}/ca`,
+        "-N",
+        "",
+        "-q",
+      ]);
+      execFileSync("ssh-keygen", [
+        "-t",
+        "ed25519",
+        "-f",
+        `${dir}/user`,
+        "-N",
+        "",
+        "-q",
+      ]);
+      signedAt = Math.floor(Date.now() / 1000);
+      execFileSync("ssh-keygen", [
+        "-s",
+        `${dir}/ca`,
+        "-I",
+        "test-id",
+        "-n",
+        "root",
+        "-V",
+        "+60m",
+        `${dir}/user.pub`,
+      ]);
+      cert = readFileSync(`${dir}/user-cert.pub`, "utf8").trim();
+    } catch {
+      haveSshKeygen = false;
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("reads valid_before from a real ssh-keygen certificate", () => {
+    if (!haveSshKeygen) {
+      console.warn("ssh-keygen unavailable; skipping real-cert parse test");
+      return;
+    }
+    const validBefore = parseCertValidBefore(cert);
+    // -V +60m => valid_before is roughly signedAt + 3600 (start rounds to minute)
+    expect(validBefore).toBeGreaterThan(signedAt + 3300);
+    expect(validBefore).toBeLessThan(signedAt + 3900);
+  });
+
+  it("returns 0 for malformed input", () => {
+    expect(parseCertValidBefore("")).toBe(0);
+    expect(parseCertValidBefore("not-a-cert")).toBe(0);
+    expect(parseCertValidBefore("ssh-ed25519 AAAAnotbase64!!")).toBe(0);
+  });
+});
+
+describe("Vault HTTP flow (mocked fetch)", () => {
+  const profile: VaultProfileConfig = {
+    id: 1,
+    vaultAddr: "https://vault.example.com:8200/",
+    vaultNamespace: "team-a",
+    oidcMount: "oidc",
+    oidcRole: "developer",
+    sshMount: "ssh-client-signer",
+    sshRole: "my-role",
+    validPrincipals: "root,deploy",
+    keyType: "ssh-ed25519",
+  };
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(
+    impl: (
+      url: string,
+      init: RequestInit,
+    ) => { status?: number; body: unknown },
+  ) {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string, init: RequestInit) => {
+        calls.push({ url, init });
+        const { status = 200, body } = impl(url, init);
+        return {
+          ok: status >= 200 && status < 300,
+          status,
+          text: async () => JSON.stringify(body),
+        } as Response;
+      }),
+    );
+    return calls;
+  }
+
+  it("startVaultOidc posts auth_url and extracts state", async () => {
+    const calls = mockFetch(() => ({
+      body: {
+        data: {
+          auth_url:
+            "https://idp.example.com/authorize?client_id=x&state=ST-abc123&nonce=n",
+        },
+      },
+    }));
+
+    const result = await startVaultOidc(
+      profile,
+      "https://termix/vault/oidc/callback",
+    );
+
+    expect(result.state).toBe("ST-abc123");
+    expect(result.clientNonce).toMatch(/^[0-9a-f]{40}$/);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe(
+      "https://vault.example.com:8200/v1/auth/oidc/oidc/auth_url",
+    );
+    expect(calls[0].init.method).toBe("POST");
+    const headers = calls[0].init.headers as Record<string, string>;
+    expect(headers["X-Vault-Namespace"]).toBe("team-a");
+    const body = JSON.parse(calls[0].init.body as string);
+    expect(body).toMatchObject({
+      role: "developer",
+      redirect_uri: "https://termix/vault/oidc/callback",
+    });
+    expect(body.client_nonce).toBe(result.clientNonce);
+  });
+
+  it("completeVaultOidc returns the client token", async () => {
+    const calls = mockFetch(() => ({
+      body: { auth: { client_token: "hvs.TESTTOKEN" } },
+    }));
+
+    const token = await completeVaultOidc(profile, {
+      state: "ST-abc123",
+      code: "auth-code",
+      clientNonce: "nonce123",
+    });
+
+    expect(token).toBe("hvs.TESTTOKEN");
+    const url = new URL(calls[0].url);
+    expect(url.pathname).toBe("/v1/auth/oidc/oidc/callback");
+    expect(url.searchParams.get("state")).toBe("ST-abc123");
+    expect(url.searchParams.get("code")).toBe("auth-code");
+    expect(url.searchParams.get("client_nonce")).toBe("nonce123");
+    expect(calls[0].init.method).toBe("GET");
+  });
+
+  it("signWithVault posts the public key and returns signed_key", async () => {
+    const calls = mockFetch(() => ({
+      body: {
+        data: { signed_key: "ssh-ed25519-cert-v01@openssh.com AAAAcert" },
+      },
+    }));
+
+    const cert = await signWithVault(
+      profile,
+      "hvs.TESTTOKEN",
+      "ssh-ed25519 AAAApub comment",
+    );
+
+    expect(cert).toBe("ssh-ed25519-cert-v01@openssh.com AAAAcert");
+    expect(calls[0].url).toBe(
+      "https://vault.example.com:8200/v1/ssh-client-signer/sign/my-role",
+    );
+    const headers = calls[0].init.headers as Record<string, string>;
+    expect(headers["X-Vault-Token"]).toBe("hvs.TESTTOKEN");
+    expect(headers["X-Vault-Namespace"]).toBe("team-a");
+    const body = JSON.parse(calls[0].init.body as string);
+    expect(body).toMatchObject({
+      public_key: "ssh-ed25519 AAAApub comment",
+      cert_type: "user",
+      valid_principals: "root,deploy",
+    });
+  });
+
+  it("surfaces Vault error messages", async () => {
+    mockFetch(() => ({
+      status: 400,
+      body: { errors: ["role not found", "permission denied"] },
+    }));
+
+    await expect(
+      signWithVault(profile, "tok", "ssh-ed25519 AAAA"),
+    ).rejects.toThrow(/role not found; permission denied/);
+  });
+});
+
+// Live integration against a real Vault (e.g. `vault server -dev` in Docker).
+// Runs only when VAULT_ADDR + VAULT_TOKEN are set and the SSH signer mount
+// (VAULT_SSH_MOUNT/VAULT_SSH_ROLE) has been configured by the test harness.
+describe("Vault live signing", () => {
+  const addr = process.env.VAULT_ADDR;
+  const token = process.env.VAULT_TOKEN;
+  const run = !!addr && !!token;
+
+  it.skipIf(!run)("signs an ephemeral key against a real Vault", async () => {
+    const profile: VaultProfileConfig = {
+      id: 99,
+      vaultAddr: addr!,
+      sshMount: process.env.VAULT_SSH_MOUNT || "ssh-client-signer",
+      sshRole: process.env.VAULT_SSH_ROLE || "my-role",
+      validPrincipals: "root",
+      keyType: "ssh-ed25519",
+    };
+
+    const pair = generateEphemeralKeyPair(profile.keyType);
+    const before = Math.floor(Date.now() / 1000);
+    const cert = await signWithVault(profile, token!, pair.publicKey);
+
+    expect(cert).toMatch(/-cert-v01@openssh\.com /);
+    // The signed cert must parse with the same library used to connect.
+    const parsed = ssh2Utils.parseKey(cert);
+    expect(parsed instanceof Error).toBe(false);
+
+    const validBefore = parseCertValidBefore(cert);
+    expect(validBefore).toBeGreaterThan(before);
+  });
+});

src/backend/tests/hosts/widgets/common-utils.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { toFixedNum, kibToGiB } from "../../../hosts/widgets/common-utils.js";
+
+describe("toFixedNum", () => {
+  it("rounds to the requested digit count", () => {
+    expect(toFixedNum(3.14159, 2)).toBe(3.14);
+    expect(toFixedNum(3.14159, 0)).toBe(3);
+    expect(toFixedNum(2.5, 0)).toBe(3);
+  });
+
+  it("defaults to 2 digits", () => {
+    expect(toFixedNum(1.23456)).toBe(1.23);
+  });
+
+  it("returns null for non-finite or non-number input", () => {
+    expect(toFixedNum(null)).toBeNull();
+    expect(toFixedNum(undefined)).toBeNull();
+    expect(toFixedNum(NaN)).toBeNull();
+    expect(toFixedNum(Infinity)).toBeNull();
+  });
+});
+
+describe("kibToGiB", () => {
+  it("converts kibibytes to gibibytes", () => {
+    expect(kibToGiB(1024 * 1024)).toBe(1);
+    expect(kibToGiB(0)).toBe(0);
+    expect(kibToGiB(2 * 1024 * 1024)).toBe(2);
+  });
+});

src/backend/tests/hosts/widgets/cpu-collector.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { parseCpuLine } from "../../../hosts/widgets/cpu-collector.js";
+
+describe("parseCpuLine", () => {
+  it("parses a standard /proc/stat cpu line", () => {
+    // user nice system idle iowait irq softirq
+    const result = parseCpuLine("cpu  100 0 50 800 30 0 20");
+    expect(result).toBeDefined();
+    // idle = idle(800) + iowait(30)
+    expect(result?.idle).toBe(830);
+    // total = sum of all fields
+    expect(result?.total).toBe(100 + 0 + 50 + 800 + 30 + 0 + 20);
+  });
+
+  it("tolerates leading/trailing whitespace", () => {
+    const result = parseCpuLine("  cpu 1 2 3 4  ");
+    expect(result?.total).toBe(10);
+    expect(result?.idle).toBe(4);
+  });
+
+  it("returns undefined for non-cpu lines", () => {
+    expect(parseCpuLine("cpu0 1 2 3 4")).toBeUndefined();
+    expect(parseCpuLine("intr 12345")).toBeUndefined();
+  });
+
+  it("returns undefined when there are fewer than 4 numeric fields", () => {
+    expect(parseCpuLine("cpu 1 2 3")).toBeUndefined();
+  });
+});

src/backend/tests/hosts/widgets/temperature-collector.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseSensorsOutput,
+  parseSysfsThermalOutput,
+} from "../../../hosts/widgets/temperature-collector.js";
+
+describe("temperature collectors", () => {
+  it("parses sysfs thermal zone output", () => {
+    const result = parseSysfsThermalOutput(
+      "x86_pkg_temp\t51000\nacpitz\t42\nbad\tnope\n",
+    );
+
+    expect(result).toEqual([
+      { label: "x86_pkg_temp", celsius: 51 },
+      { label: "acpitz", celsius: 42 },
+    ]);
+  });
+
+  it("parses lm-sensors temperature lines", () => {
+    const result = parseSensorsOutput(`
+coretemp-isa-0000
+Adapter: ISA adapter
+Package id 0:  +52.0°C  (high = +80.0°C, crit = +100.0°C)
+Core 0:        +48.5°C
+fan1:          1200 RPM
+`);
+
+    expect(result).toEqual([
+      { label: "Package id 0", celsius: 52 },
+      { label: "Core 0", celsius: 48.5 },
+    ]);
+  });
+});