feat: move network topology into a first-party plugin

src/backend/database/database.ts

@@ -18,7 +18,7 @@ import sessionLogRoutes from "./routes/session-log-routes.js";
 import guacamoleDispatch from "./routes/guacamole-dispatch.js";
 import sessionSharingRoutes from "../hosts/session-sharing/routes.js";
 import collabRoutes from "../hosts/collab/routes.js";
-import networkTopologyRoutes from "./routes/network-topology.js";
+import networkTopologyDispatch from "./routes/network-topology-dispatch.js";
 import rbacRoutes from "./routes/rbac.js";
 import openTabsRoutes from "./routes/open-tabs.js";
 import userPreferencesRoutes from "./routes/user-preferences.js";
@@ -1761,7 +1761,7 @@ app.use("/session_logs", sessionLogRoutes);
 app.use("/guacamole", guacamoleDispatch);
 app.use("/session-sharing", sessionSharingRoutes);
 app.use("/collab", collabRoutes);
-app.use("/network-topology", networkTopologyRoutes);
+app.use("/network-topology", networkTopologyDispatch);
 app.use("/rbac", rbacRoutes);
 app.use("/open-tabs", openTabsRoutes);
 app.use("/user-preferences", userPreferencesRoutes);

src/backend/database/routes/network-topology-dispatch.ts

@@ -0,0 +1,47 @@
+// Mounted at /network-topology. Network Topology ships as a first-party
+// in-process plugin (plugins/network-topology) rather than a route file
+// imported directly here, so this module exists to keep /network-topology/*
+// working at its original path without handing the plugin a reference to the
+// shared app instance. The plugin runtime registers its router via
+// registerNetworkTopologyRouter when it activates, and clears it on
+// deactivate, so a disabled plugin falls back to the 404 below.
+//
+// Unlike /plugin-api, this dispatcher applies no auth of its own: it forwards
+// to exactly one first-party router (the Network Topology plugin's own), and
+// every route in that router already applies authenticateJWT itself, the same
+// as every other router mounted alongside it here (/users, /host, /snippets,
+// ...). /plugin-api gates at the mount point because it forwards to arbitrary
+// third-party plugin code that cannot be assumed to gate itself; that
+// reasoning does not apply to a single first-party router that already does.
+
+import type { Request, Response, NextFunction, Router } from "express";
+import { databaseLogger } from "../../utils/logger.js";
+
+let activeRouter: Router | null = null;
+
+export function registerNetworkTopologyRouter(router: Router): void {
+  activeRouter = router;
+  databaseLogger.info("Registered Network Topology plugin router", {
+    operation: "network_topology_dispatch_register",
+  });
+}
+
+export function unregisterNetworkTopologyRouter(): void {
+  if (!activeRouter) return;
+  activeRouter = null;
+  databaseLogger.info("Unregistered Network Topology plugin router", {
+    operation: "network_topology_dispatch_register",
+  });
+}
+
+export default function networkTopologyDispatch(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  if (!activeRouter) {
+    res.status(404).json({ error: "Network Topology is not available" });
+    return;
+  }
+  activeRouter(req, res, next);
+}

src/backend/database/routes/network-topology.ts

@@ -1,177 +0,0 @@
-import express from "express";
-import { AuthManager } from "../../utils/auth-manager.js";
-import type { AuthenticatedRequest } from "../../../types/index.js";
-import { databaseLogger } from "../../utils/logger.js";
-import { createCurrentNetworkTopologyRepository } from "../repositories/factory.js";
-
-const router = express.Router();
-const authManager = AuthManager.getInstance();
-const authenticateJWT = authManager.createAuthMiddleware();
-
-/**
- * @openapi
- * /network-topology:
- *   get:
- *     summary: Get network topology for authenticated user
- *     description: Retrieves the saved network topology graph (nodes and edges) for the current user. Returns null if no topology exists.
- *     tags:
- *       - Network Topology
- *     security:
- *       - bearerAuth: []
- *     responses:
- *       200:
- *         description: Network topology retrieved successfully
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               nullable: true
- *               properties:
- *                 nodes:
- *                   type: array
- *                   description: Array of graph nodes (hosts and groups)
- *                   items:
- *                     type: object
- *                     properties:
- *                       data:
- *                         type: object
- *                         description: Node data including id, label, type, etc.
- *                       position:
- *                         type: object
- *                         description: Node position coordinates
- *                         properties:
- *                           x:
- *                             type: number
- *                           y:
- *                             type: number
- *                 edges:
- *                   type: array
- *                   description: Array of graph edges (connections)
- *                   items:
- *                     type: object
- *                     properties:
- *                       data:
- *                         type: object
- *                         description: Edge data including source and target node ids
- *       401:
- *         description: User not authenticated
- *       500:
- *         description: Server error
- */
-router.get(
-  "/",
-  authenticateJWT,
-  async (req: express.Request, res: express.Response) => {
-    try {
-      const userId = (req as AuthenticatedRequest).userId;
-      if (!userId) {
-        return res.status(401).json({ error: "User not authenticated" });
-      }
-
-      const record =
-        await createCurrentNetworkTopologyRepository().findByUserId(userId);
-
-      if (record) {
-        const topologyStr = record.topology;
-        const topology = topologyStr ? JSON.parse(topologyStr) : null;
-        return res.json(topology);
-      } else {
-        return res.json(null);
-      }
-    } catch (error) {
-      databaseLogger.error("Failed to fetch network topology", error, {
-        operation: "network_topology_fetch",
-        userId: (req as AuthenticatedRequest).userId,
-      });
-      return res.status(500).json({
-        error: "Failed to fetch network topology",
-        details: (error as Error).message,
-      });
-    }
-  },
-);
-
-/**
- * @openapi
- * /network-topology:
- *   post:
- *     summary: Save network topology for authenticated user
- *     description: Saves or updates the network topology graph. Uses upsert logic - creates new record if none exists, updates existing record otherwise.
- *     tags:
- *       - Network Topology
- *     security:
- *       - bearerAuth: []
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required:
- *               - topology
- *             properties:
- *               topology:
- *                 type: object
- *                 description: Network topology data containing nodes and edges
- *                 properties:
- *                   nodes:
- *                     type: array
- *                     description: Array of graph nodes (hosts and groups)
- *                   edges:
- *                     type: array
- *                     description: Array of graph edges (connections)
- *     responses:
- *       200:
- *         description: Topology saved successfully
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 success:
- *                   type: boolean
- *       400:
- *         description: Invalid topology data
- *       401:
- *         description: User not authenticated
- *       500:
- *         description: Server error
- */
-router.post(
-  "/",
-  authenticateJWT,
-  async (req: express.Request, res: express.Response) => {
-    try {
-      const userId = (req as AuthenticatedRequest).userId;
-      if (!userId) {
-        return res.status(401).json({ error: "User not authenticated" });
-      }
-
-      const { topology } = req.body;
-      if (!topology) {
-        return res.status(400).json({ error: "Topology data is required" });
-      }
-
-      const topologyStr =
-        typeof topology === "string" ? topology : JSON.stringify(topology);
-
-      await createCurrentNetworkTopologyRepository().upsertForUser(
-        userId,
-        topologyStr,
-      );
-
-      return res.json({ success: true });
-    } catch (error) {
-      databaseLogger.error("Failed to save network topology", error, {
-        operation: "network_topology_save",
-        userId: (req as AuthenticatedRequest).userId,
-      });
-      return res.status(500).json({
-        error: "Failed to save network topology",
-        details: (error as Error).message,
-      });
-    }
-  },
-);
-
-export default router;

src/backend/plugins/first-party.ts

@@ -83,6 +83,15 @@
  * direct repository access plus subscription to the cross-plugin event bus
  * (host metrics, status and health-check events) that the worker's read-only
  * ctx.hosts and single-postMessage-reply ctx.http.route cannot support.
+ *
+ * network-topology is here for a different reason than the rest of this
+ * list: its two routes are plain per-user JSON CRUD against a single
+ * repository, and would fit the worker ctx fine on their own. It stays
+ * in-process to keep its existing /network-topology URL and its existing
+ * dedicated table (network_topology, keyed by userId) rather than moving
+ * onto /plugin-api/network-topology/* and the generic key-value
+ * ctx.storage the worker tier would require -- a URL and storage-model
+ * change, not a capability gap.
  */
 export const FIRST_PARTY_PLUGIN_IDS: ReadonlySet<string> = new Set([
   "ssh-terminal",
@@ -93,6 +102,7 @@ export const FIRST_PARTY_PLUGIN_IDS: ReadonlySet<string> = new Set([
   "remote-desktop",
   "fleets",
   "automations",
+  "network-topology",
 ]);
 
 export const TRANSPORT_OWNER_CAPABILITY = "process:transport-owner";

src/backend/starter.ts

@@ -295,15 +295,16 @@ async function provisionLocalDesktopUserIfNeeded(): Promise<void> {
     // ssh-terminal, docker and host-metrics plugins start their own servers,
     // so disabling any of them stops its WS/HTTP server. See
     // plugins/ssh-terminal, plugins/docker and plugins/host-metrics.
-    // AI, Proxmox, Remote Desktop, Fleets and Automations are also absent for
-    // the same reason: each plugin registers its router with its own
-    // dispatcher in database.ts on activate (/ai, /proxmox, /guacamole,
-    // /fleets, /automations), so disabling any of them makes its routes 404
-    // instead of leaving a dead import here. Automations' scheduler (due
-    // schedules, dwell rechecks, docker-event polling, history pruning) also
-    // starts from its own activate() rather than here. See plugins/ai,
-    // plugins/proxmox, plugins/remote-desktop, plugins/fleets and
-    // plugins/automations.
+    // AI, Proxmox, Remote Desktop, Fleets, Automations and Network Topology
+    // are also absent for the same reason: each plugin registers its router
+    // with its own dispatcher in database.ts on activate (/ai, /proxmox,
+    // /guacamole, /fleets, /automations, /network-topology), so disabling
+    // any of them makes its routes 404 instead of leaving a dead import
+    // here. Automations' scheduler (due schedules, dwell rechecks,
+    // docker-event polling, history pruning) also starts from its own
+    // activate() rather than here. See plugins/ai, plugins/proxmox,
+    // plugins/remote-desktop, plugins/fleets, plugins/automations and
+    // plugins/network-topology.
     await import("./hosts/tunnel/index.js");
     await import("./hosts/file-manager/index.js");
     await import("./hosts/tmux/index.js");

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

@@ -324,3 +324,53 @@ describe("bundled automations plugin", () => {
     expect(source).toMatch(/export async function deactivate/);
   });
 });
+
+describe("bundled network-topology plugin", () => {
+  it("ships a directory with a manifest and both entry points", () => {
+    const dir = path.join(getBundledPluginsDir(), "network-topology");
+
+    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("network-topology"),
+    );
+
+    expect(errors).toEqual([]);
+    expect(manifest?.id).toBe("network-topology");
+    expect(manifest?.category).toBe("Infrastructure");
+  });
+
+  it("declares the transport-owner capability and qualifies for the tier", () => {
+    const { manifest } = parseManifest(readBundledManifest("network-topology"));
+
+    expect(manifest?.permissions).toContain(TRANSPORT_OWNER_CAPABILITY);
+    expect(isFirstParty("network-topology")).toBe(true);
+    expect(runsInProcess("network-topology", manifest!.permissions)).toBe(true);
+  });
+
+  it("contributes the network_graph tab the shell registers", () => {
+    const { manifest } = parseManifest(readBundledManifest("network-topology"));
+    const tab = manifest?.contributes?.tabs?.[0];
+
+    // The shell keys tab content off this id, so it has to stay "network_graph".
+    expect(tab?.id).toBe("network_graph");
+    expect(tab?.openFrom).toContain("rail");
+  });
+
+  it("exports activate and deactivate from its backend entry", () => {
+    const entry = path.join(
+      getBundledPluginsDir(),
+      "network-topology",
+      "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,20 +39,21 @@ function manifest(overrides: Record<string, unknown> = {}) {
 }
 
 describe("first-party allowlist", () => {
-  it("contains only ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets and automations", () => {
+  it("contains only ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets, automations and network-topology", () => {
     expect([...FIRST_PARTY_PLUGIN_IDS].sort()).toEqual([
       "ai",
       "automations",
       "docker",
       "fleets",
       "host-metrics",
+      "network-topology",
       "proxmox",
       "remote-desktop",
       "ssh-terminal",
     ]);
   });
 
-  it("recognises ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets and automations and nothing else", () => {
+  it("recognises ssh-terminal, docker, host-metrics, ai, proxmox, remote-desktop, fleets, automations and network-topology and nothing else", () => {
     expect(isFirstParty("ssh-terminal")).toBe(true);
     expect(isFirstParty("docker")).toBe(true);
     expect(isFirstParty("host-metrics")).toBe(true);
@@ -61,6 +62,7 @@ describe("first-party allowlist", () => {
     expect(isFirstParty("remote-desktop")).toBe(true);
     expect(isFirstParty("fleets")).toBe(true);
     expect(isFirstParty("automations")).toBe(true);
+    expect(isFirstParty("network-topology")).toBe(true);
     expect(isFirstParty("ssh-terminal-pro")).toBe(false);
     expect(isFirstParty("community-plugin")).toBe(false);
     expect(isFirstParty("")).toBe(false);
@@ -85,6 +87,9 @@ describe("runsInProcess", () => {
     expect(runsInProcess("automations", [TRANSPORT_OWNER_CAPABILITY])).toBe(
       true,
     );
+    expect(
+      runsInProcess("network-topology", [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.
@@ -96,6 +101,7 @@ describe("runsInProcess", () => {
     expect(runsInProcess("remote-desktop", ["hosts.read"])).toBe(false);
     expect(runsInProcess("fleets", ["hosts.read"])).toBe(false);
     expect(runsInProcess("automations", ["hosts.read"])).toBe(false);
+    expect(runsInProcess("network-topology", ["hosts.read"])).toBe(false);
 
     // Asking for it but not on the list.
     expect(
@@ -199,6 +205,18 @@ describe("manifest gate on the reserved capability", () => {
     expect(parsed?.id).toBe("automations");
   });
 
+  it("allows it for network-topology", () => {
+    const { manifest: parsed, errors } = parseManifest(
+      manifest({
+        id: "network-topology",
+        permissions: [TRANSPORT_OWNER_CAPABILITY],
+      }),
+    );
+
+    expect(errors).toEqual([]);
+    expect(parsed?.id).toBe("network-topology");
+  });
+
   it("still accepts an ordinary manifest that never mentions it", () => {
     const { manifest: parsed, errors } = parseManifest(
       manifest({ permissions: ["hosts.read"] }),

src/backend/tests/plugins/network-topology/routes.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { Request, Response, Router } from "express";
+
+const state = vi.hoisted(() => ({
+  currentUserId: "user-1" as string | undefined,
+  records: new Map<string, { userId: string; topology: string | null }>(),
+}));
+
+vi.mock("../../../database/db/index.js", () => ({ db: {} }));
+
+vi.mock("../../../utils/logger.js", () => ({
+  databaseLogger: {
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+vi.mock("../../../utils/auth-manager.js", () => ({
+  AuthManager: {
+    getInstance: () => ({
+      createAuthMiddleware:
+        () =>
+        (req: Record<string, unknown>, _res: unknown, next: () => void) => {
+          req.userId = state.currentUserId;
+          next();
+        },
+    }),
+  },
+}));
+
+vi.mock("../../../database/repositories/factory.js", () => ({
+  createCurrentNetworkTopologyRepository: () => ({
+    findByUserId: async (userId: string) => state.records.get(userId) ?? null,
+    upsertForUser: async (userId: string, topology: string) => {
+      state.records.set(userId, { userId, topology });
+    },
+  }),
+}));
+
+vi.mock("../../../database/routes/network-topology-dispatch.js", () => ({
+  registerNetworkTopologyRouter: vi.fn(),
+  unregisterNetworkTopologyRouter: vi.fn(),
+}));
+
+const { router } =
+  await import("../../../../../plugins/network-topology/backend/routes.js");
+
+function findLayer(method: string, path: string) {
+  const stack = (router as unknown as Router).stack as Array<{
+    route?: {
+      path: string;
+      methods: Record<string, boolean>;
+      stack: Array<{ handle: (req: Request, res: Response) => unknown }>;
+    };
+  }>;
+  const layer = stack.find(
+    (l) => l.route?.path === path && l.route?.methods[method],
+  );
+  if (!layer?.route) throw new Error(`No route for ${method} ${path}`);
+  return layer.route.stack[layer.route.stack.length - 1].handle;
+}
+
+function makeReqRes(overrides: { body?: Record<string, unknown> }) {
+  const req = {
+    userId: state.currentUserId,
+    body: overrides.body ?? {},
+    headers: {},
+  } as unknown as Request;
+
+  const res = {
+    statusCode: 200,
+    jsonBody: null as unknown,
+    status(code: number) {
+      (this as unknown as { statusCode: number }).statusCode = code;
+      return this;
+    },
+    json(payload: unknown) {
+      (this as unknown as { jsonBody: unknown }).jsonBody = payload;
+      return this;
+    },
+  } as unknown as Response & { statusCode: number; jsonBody: unknown };
+
+  return { req, res };
+}
+
+async function invoke(
+  method: string,
+  path: string,
+  overrides: { body?: Record<string, unknown> } = {},
+) {
+  const handler = findLayer(method, path);
+  const { req, res } = makeReqRes(overrides);
+  await handler(req, res);
+  return res as unknown as {
+    statusCode: number;
+    jsonBody: Record<string, unknown> | null;
+  };
+}
+
+beforeEach(() => {
+  state.currentUserId = "user-1";
+  state.records = new Map();
+});
+
+describe("GET /network-topology", () => {
+  it("returns null when the user has no saved topology", async () => {
+    const res = await invoke("get", "/");
+    expect(res.jsonBody).toBeNull();
+  });
+
+  it("returns the parsed topology when one exists", async () => {
+    state.records.set("user-1", {
+      userId: "user-1",
+      topology: JSON.stringify({ nodes: [{ id: "host-1" }], edges: [] }),
+    });
+
+    const res = await invoke("get", "/");
+    expect(res.jsonBody).toEqual({ nodes: [{ id: "host-1" }], edges: [] });
+  });
+
+  it("rejects an unauthenticated request", async () => {
+    state.currentUserId = undefined;
+    const res = await invoke("get", "/");
+    expect(res.statusCode).toBe(401);
+  });
+});
+
+describe("POST /network-topology", () => {
+  it("saves the topology and returns success", async () => {
+    const res = await invoke("post", "/", {
+      body: { topology: { nodes: [], edges: [] } },
+    });
+
+    expect(res.jsonBody).toEqual({ success: true });
+    expect(state.records.get("user-1")?.topology).toBe(
+      JSON.stringify({ nodes: [], edges: [] }),
+    );
+  });
+
+  it("rejects a request with no topology", async () => {
+    const res = await invoke("post", "/", { body: {} });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("rejects an unauthenticated request", async () => {
+    state.currentUserId = undefined;
+    const res = await invoke("post", "/", { body: { topology: {} } });
+    expect(res.statusCode).toBe(401);
+  });
+});