feat: move web endpoint into a first-party plugin

src/backend/tests/plugins/bundled-plugin.test.ts

@@ -415,3 +415,54 @@ describe("bundled workspaces plugin", () => {
     expect(source).toMatch(/export async function deactivate/);
   });
 });
+
+describe("bundled web-endpoint plugin", () => {
+  it("ships a directory with a manifest and both entry points", () => {
+    const dir = path.join(getBundledPluginsDir(), "web-endpoint");
+
+    expect(fs.existsSync(path.join(dir, "manifest.json"))).toBe(true);
+    expect(fs.existsSync(path.join(dir, "backend", "index.mjs"))).toBe(true);
+    expect(fs.existsSync(path.join(dir, "frontend", "index.mjs"))).toBe(true);
+  });
+
+  it("has a manifest that passes the real validator", () => {
+    const { manifest, errors } = parseManifest(
+      readBundledManifest("web-endpoint"),
+    );
+
+    expect(errors).toEqual([]);
+    expect(manifest?.id).toBe("web-endpoint");
+    expect(manifest?.category).toBe("Networking");
+  });
+
+  it("declares the transport-owner capability and qualifies for the tier", () => {
+    const { manifest } = parseManifest(readBundledManifest("web-endpoint"));
+
+    expect(manifest?.permissions).toContain(TRANSPORT_OWNER_CAPABILITY);
+    expect(isFirstParty("web-endpoint")).toBe(true);
+    expect(runsInProcess("web-endpoint", manifest!.permissions)).toBe(true);
+  });
+
+  // The column this points at stays on core's ssh_data table, so a typo here
+  // would silently detach the host-editor checkbox from its storage.
+  it("contributes the enableWebUi host capability", () => {
+    const { manifest } = parseManifest(readBundledManifest("web-endpoint"));
+
+    expect(manifest?.contributes?.hostCapability).toMatchObject({
+      key: "enableWebUi",
+    });
+  });
+
+  it("exports activate and deactivate from its backend entry", () => {
+    const entry = path.join(
+      getBundledPluginsDir(),
+      "web-endpoint",
+      "backend",
+      "index.mjs",
+    );
+    const source = fs.readFileSync(entry, "utf8");
+
+    expect(source).toMatch(/export async function activate/);
+    expect(source).toMatch(/export async function deactivate/);
+  });
+});

src/backend/tests/plugins/first-party.test.ts

@@ -39,7 +39,7 @@ function manifest(overrides: Record<string, unknown> = {}) {
 }
 
 describe("first-party allowlist", () => {
-  it("contains only ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets, automations, network-topology, tailscale and workspaces", () => {
+  it("contains only ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets, automations, network-topology, tailscale, workspaces and web-endpoint", () => {
     expect([...FIRST_PARTY_PLUGIN_IDS].sort()).toEqual([
       "ai",
       "automations",
@@ -51,11 +51,12 @@ describe("first-party allowlist", () => {
       "remote-desktop",
       "ssh-terminal",
       "tailscale",
+      "web-endpoint",
       "workspaces",
     ]);
   });
 
-  it("recognises ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets, automations, network-topology, tailscale and workspaces and nothing else", () => {
+  it("recognises ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets, automations, network-topology, tailscale, workspaces and web-endpoint and nothing else", () => {
     expect(isFirstParty("ssh-terminal")).toBe(true);
     expect(isFirstParty("docker")).toBe(true);
     expect(isFirstParty("host-metrics")).toBe(true);
@@ -67,6 +68,7 @@ describe("first-party allowlist", () => {
     expect(isFirstParty("network-topology")).toBe(true);
     expect(isFirstParty("tailscale")).toBe(true);
     expect(isFirstParty("workspaces")).toBe(true);
+    expect(isFirstParty("web-endpoint")).toBe(true);
     expect(isFirstParty("ssh-terminal-pro")).toBe(false);
     expect(isFirstParty("community-plugin")).toBe(false);
     expect(isFirstParty("")).toBe(false);
@@ -98,6 +100,9 @@ describe("runsInProcess", () => {
     expect(runsInProcess("workspaces", [TRANSPORT_OWNER_CAPABILITY])).toBe(
       true,
     );
+    expect(runsInProcess("web-endpoint", [TRANSPORT_OWNER_CAPABILITY])).toBe(
+      true,
+    );
 
     // On the list but not asking for it: stays in a worker, so the manifest
     // remains an honest description of what the plugin does.
@@ -112,6 +117,7 @@ describe("runsInProcess", () => {
     expect(runsInProcess("network-topology", ["hosts.read"])).toBe(false);
     expect(runsInProcess("tailscale", ["hosts.read"])).toBe(false);
     expect(runsInProcess("workspaces", ["hosts.read"])).toBe(false);
+    expect(runsInProcess("web-endpoint", ["hosts.read"])).toBe(false);
 
     // Asking for it but not on the list.
     expect(
@@ -251,6 +257,18 @@ describe("manifest gate on the reserved capability", () => {
     expect(parsed?.id).toBe("workspaces");
   });
 
+  it("allows it for web-endpoint", () => {
+    const { manifest: parsed, errors } = parseManifest(
+      manifest({
+        id: "web-endpoint",
+        permissions: [TRANSPORT_OWNER_CAPABILITY],
+      }),
+    );
+
+    expect(errors).toEqual([]);
+    expect(parsed?.id).toBe("web-endpoint");
+  });
+
   it("still accepts an ordinary manifest that never mentions it", () => {
     const { manifest: parsed, errors } = parseManifest(
       manifest({ permissions: ["hosts.read"] }),

src/backend/tests/plugins/web-endpoint/routes.test.ts

@@ -0,0 +1,350 @@
+import type express from "express";
+import { readFile } from "node:fs/promises";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const resolveHostById = vi.hoisted(() => vi.fn());
+vi.mock("../../../hosts/host-resolver.js", () => ({ resolveHostById }));
+
+const manager = vi.hoisted(() => ({
+  activeTunnelRuntimes: new Map<string, unknown>(),
+  connectionStatus: new Map<string, unknown>(),
+  tunnelConnecting: new Set<string>(),
+  connectSSHTunnel: vi.fn(),
+  cleanupTunnelResources: vi.fn(async () => undefined),
+}));
+vi.mock("../../../hosts/tunnel/manager.js", () => manager);
+
+const forwardOut = vi.hoisted(() => vi.fn(async () => ({ end: vi.fn() })));
+vi.mock("../../../hosts/tunnel/ssh-primitives.js", () => ({ forwardOut }));
+
+vi.mock("../../../utils/auth-manager.js", () => ({
+  AuthManager: { getInstance: () => ({ createAuthMiddleware: () => vi.fn() }) },
+}));
+
+function response() {
+  const res = {
+    statusCode: 0,
+    body: undefined as unknown,
+    status(code: number) {
+      this.statusCode = code;
+      return this;
+    },
+    json(payload: unknown) {
+      this.body = payload;
+      return this;
+    },
+  };
+  return res as unknown as express.Response & {
+    statusCode: number;
+    body: { port?: number; error?: string };
+  };
+}
+
+function request(body: unknown, userId: string | undefined = "u1") {
+  return { body, userId } as unknown as express.Request;
+}
+
+const endpoint = (overrides: Record<string, unknown> = {}) => ({
+  id: "e1",
+  label: "Proxmox",
+  scheme: "http",
+  port: 8006,
+  path: "/",
+  access: "tunnel",
+  render: "embedded",
+  ...overrides,
+});
+
+function host(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 7,
+    userId: "u1",
+    ip: "10.0.0.5",
+    port: 22,
+    username: "root",
+    authType: "password",
+    password: "pw",
+    enableWebUi: true,
+    webUiConfig: JSON.stringify({ endpoints: [endpoint()] }),
+    ...overrides,
+  };
+}
+
+/** Makes connectSSHTunnel behave like a successful open. */
+function tunnelConnectsOn(port: number) {
+  manager.connectSSHTunnel.mockImplementation(
+    async (config: { name: string }) => {
+      manager.activeTunnelRuntimes.set(config.name, {
+        bindPort: port,
+        sourceClient: {},
+        close: vi.fn(),
+      });
+    },
+  );
+}
+
+beforeEach(() => {
+  manager.activeTunnelRuntimes.clear();
+  manager.connectionStatus.clear();
+  manager.tunnelConnecting.clear();
+  manager.connectSSHTunnel.mockReset();
+  manager.cleanupTunnelResources.mockClear();
+  forwardOut.mockClear();
+  forwardOut.mockResolvedValue({ end: vi.fn() });
+  resolveHostById.mockReset();
+  resolveHostById.mockResolvedValue(host());
+});
+
+afterEach(() => {
+  vi.resetModules();
+});
+
+describe("POST /tunnel/web-endpoint/open", () => {
+  it("refuses a host the user cannot resolve, without opening anything", async () => {
+    resolveHostById.mockResolvedValue(null);
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const res = response();
+    await handleWebEndpointOpen(request({ hostId: 7, endpointId: "e1" }), res);
+
+    expect(res.statusCode).toBe(403);
+    expect(manager.connectSSHTunnel).not.toHaveBeenCalled();
+  });
+
+  it("refuses when the feature is disabled even though the config still lists the endpoint", async () => {
+    // Reachable via a bulk update that sends only { webUiConfig } while the
+    // stored enable_web_ui is still 0. The UI reads as off in that state.
+    resolveHostById.mockResolvedValue(host({ enableWebUi: false }));
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const res = response();
+    await handleWebEndpointOpen(request({ hostId: 7, endpointId: "e1" }), res);
+
+    expect(res.statusCode).toBe(400);
+    expect(manager.connectSSHTunnel).not.toHaveBeenCalled();
+  });
+
+  it("refuses an endpoint id that matches nothing", async () => {
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const res = response();
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "nope" }),
+      res,
+    );
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("returns the real bound port", async () => {
+    tunnelConnectsOn(41234);
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const res = response();
+    await handleWebEndpointOpen(request({ hostId: 7, endpointId: "e1" }), res);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.port).toBe(41234);
+  });
+
+  it("selects the local-forward path via endpointHost, not targetHost", async () => {
+    // connectSSHTunnel routes on isSingleHostTunnel, which keys on
+    // endpointHost === "127.0.0.1". Setting only targetHost would silently
+    // select a different strategy and the forward would never bind locally.
+    tunnelConnectsOn(41234);
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "e1" }),
+      response(),
+    );
+
+    const config = manager.connectSSHTunnel.mock.calls[0][0];
+    expect(config.endpointHost).toBe("127.0.0.1");
+    expect(config.mode).toBe("local");
+    expect(config.endpointPort).toBe(8006);
+    // Carries the source SSH identity -- connectSSHTunnel builds its client
+    // from these, and reads sourceUserId specifically.
+    expect(config.sourceIP).toBe("10.0.0.5");
+    expect(config.sourceUserId).toBe("u1");
+  });
+
+  it("binds loopback by default and the endpoint's choice when given", async () => {
+    tunnelConnectsOn(41234);
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "e1" }),
+      response(),
+    );
+    expect(manager.connectSSHTunnel.mock.calls[0][0].bindHost).toBe(
+      "127.0.0.1",
+    );
+
+    manager.activeTunnelRuntimes.clear();
+    resolveHostById.mockResolvedValue(
+      host({
+        webUiConfig: JSON.stringify({
+          endpoints: [endpoint({ bindHost: "0.0.0.0", localPort: 38080 })],
+        }),
+      }),
+    );
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "e1" }),
+      response(),
+    );
+    const config = manager.connectSSHTunnel.mock.calls[1][0];
+    expect(config.bindHost).toBe("0.0.0.0");
+    expect(config.sourcePort).toBe(38080);
+  });
+
+  it("reuses a live tunnel instead of opening a second one", async () => {
+    tunnelConnectsOn(41234);
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const first = response();
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "e1" }),
+      first,
+    );
+    const second = response();
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "e1" }),
+      second,
+    );
+
+    expect(second.body.port).toBe(41234);
+    expect(manager.connectSSHTunnel).toHaveBeenCalledTimes(1);
+  });
+
+  it("reopens when the endpoint's target changed under a live tunnel", async () => {
+    tunnelConnectsOn(41234);
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    await handleWebEndpointOpen(
+      request({ hostId: 7, endpointId: "e1" }),
+      response(),
+    );
+
+    // Same id, different port: the live forward now points at the wrong place.
+    resolveHostById.mockResolvedValue(
+      host({
+        webUiConfig: JSON.stringify({ endpoints: [endpoint({ port: 9000 })] }),
+      }),
+    );
+    tunnelConnectsOn(51234);
+    const res = response();
+    await handleWebEndpointOpen(request({ hostId: 7, endpointId: "e1" }), res);
+
+    expect(manager.cleanupTunnelResources).toHaveBeenCalledWith(
+      "web:7:e1",
+      true,
+    );
+    expect(res.body.port).toBe(51234);
+  });
+
+  it("reports the target port being closed rather than returning a dead 200", async () => {
+    // The likeliest real error: the listener binds fine, but nothing is
+    // serving on the endpoint's port. Without the probe this returns 200 and
+    // the user gets a blank frame with no message.
+    tunnelConnectsOn(41234);
+    forwardOut.mockRejectedValue(
+      new Error("Channel open failure: connect failed"),
+    );
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const res = response();
+    await handleWebEndpointOpen(request({ hostId: 7, endpointId: "e1" }), res);
+
+    expect(res.statusCode).toBe(502);
+    expect(String(res.body.error)).toMatch(/connect failed/);
+    // Nothing half-built is left registered.
+    expect(manager.cleanupTunnelResources).toHaveBeenCalledWith(
+      "web:7:e1",
+      true,
+    );
+  });
+
+  it("surfaces a connection failure reported only over the status map", async () => {
+    // connectSSHTunnel never rejects and resolves before the SSH handshake, so
+    // without waitForTunnelSettled this path would read as success.
+    manager.connectSSHTunnel.mockImplementation(
+      async (config: { name: string }) => {
+        manager.connectionStatus.set(config.name, {
+          connected: false,
+          reason: "All authentication methods failed",
+        });
+      },
+    );
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const res = response();
+    await handleWebEndpointOpen(request({ hostId: 7, endpointId: "e1" }), res);
+
+    expect(res.statusCode).toBe(502);
+    expect(String(res.body.error)).toMatch(/authentication methods failed/);
+  });
+
+  it("rejects a malformed request before touching the database", async () => {
+    const { handleWebEndpointOpen } =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    for (const body of [
+      {},
+      { hostId: "7", endpointId: "e1" },
+      { hostId: 0, endpointId: "e1" },
+    ]) {
+      const res = response();
+      await handleWebEndpointOpen(request(body), res);
+      expect(res.statusCode).toBe(400);
+    }
+    expect(resolveHostById).not.toHaveBeenCalled();
+  });
+});
+
+/**
+ * The client resolves "/tunnel/web-endpoint/open" against a baseURL that
+ * already ends in /ssh, and nginx proxies /ssh through with the path intact --
+ * so the server must serve the FULL "/ssh/tunnel/web-endpoint/open" path.
+ * Serving the unprefixed form 404s every call, and no handler unit test
+ * notices because they call the handler directly.
+ *
+ * This was caught only by opening a real tunnel against a deployed build.
+ *
+ * Since the plugin migration that path is composed of two halves: the mount
+ * point in src/backend/hosts/tunnel/index.ts and the route on the plugin's own
+ * router. Either half drifting breaks the URL, so both are asserted here.
+ */
+describe("route registration", () => {
+  it("registers /open on the router the dispatcher forwards to", async () => {
+    const routes =
+      await import("../../../../../plugins/web-endpoint/backend/routes.js");
+    const dispatch =
+      await import("../../../hosts/tunnel/web-endpoint-dispatch.js");
+    const registered: unknown[] = [];
+    vi.spyOn(dispatch, "registerWebEndpointRouter").mockImplementation(
+      (router) => {
+        registered.push(router);
+      },
+    );
+
+    routes.startWebEndpointService();
+
+    expect(registered).toHaveLength(1);
+    const paths = (
+      routes.router as unknown as {
+        stack: Array<{ route?: { path: string; methods: { post?: boolean } } }>;
+      }
+    ).stack
+      .filter((layer) => layer.route?.methods.post)
+      .map((layer) => layer.route?.path);
+    expect(paths).toContain("/open");
+  });
+
+  it("is mounted so the full client path resolves", async () => {
+    const source = await readFile(
+      new URL("../../../hosts/tunnel/index.ts", import.meta.url),
+      "utf8",
+    );
+
+    expect(source).toContain('app.use("/ssh/tunnel/web-endpoint"');
+  });
+});