feat: serve plugin http and websockets from one mount instead of ports

src/backend/tests/plugins/http.test.ts

@@ -0,0 +1,385 @@
+/**
+ * ctx.http: the one way a plugin serves HTTP.
+ *
+ * Everything here is about the middleware core puts in front of a plugin's
+ * routes, because that is what moving off the dispatcher shims bought: auth by
+ * default, a truthful 503 while disabled, a capability that can be revoked
+ * without a restart, and streaming that still streams.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import express from "express";
+import type { AddressInfo } from "node:net";
+import type { Server } from "node:http";
+
+const state = vi.hoisted(() => ({
+  validToken: "valid-token",
+  userId: "user-1",
+  granted: new Set<string>(["network:serve"]),
+}));
+
+vi.mock("../../utils/logger.js", () => ({
+  pluginLogger: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+  databaseLogger: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+vi.mock("../../utils/auth-manager.js", () => ({
+  AuthManager: {
+    getInstance: () => ({
+      createAuthMiddleware:
+        () =>
+        (
+          req: express.Request,
+          res: express.Response,
+          next: express.NextFunction,
+        ) => {
+          const header = req.headers.authorization;
+          const token = header?.startsWith("Bearer ") ? header.slice(7) : null;
+          if (token !== state.validToken) {
+            res.status(401).json({ error: "Unauthorized" });
+            return;
+          }
+          (req as express.Request & { userId?: string }).userId = state.userId;
+          next();
+        },
+    }),
+  },
+}));
+
+vi.mock("../../plugins/permissions.js", () => ({
+  hasCapability: async (
+    _pluginId: string,
+    capability: string,
+    declared: readonly string[],
+  ) => declared.includes(capability) && state.granted.has(capability),
+}));
+
+vi.mock("../../utils/audit-logger.js", () => ({ logAudit: vi.fn() }));
+
+const http = await import("../../plugins/http.js");
+const pluginApi = (await import("../../database/routes/plugin-api-routes.js"))
+  .default;
+
+function manifest(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "sample-plugin",
+    name: "Sample Plugin",
+    version: "1.0.0",
+    capabilities: ["network:serve"],
+    ...overrides,
+  } as never;
+}
+
+let server: Server | null = null;
+
+async function startServer(): Promise<string> {
+  const app = express();
+  // Exactly how database.ts mounts it: no auth in front, because the plugin
+  // router brings its own.
+  app.use("/plugin-api", pluginApi);
+
+  return new Promise((resolve) => {
+    server = app.listen(0, "127.0.0.1", () => {
+      const { port } = server!.address() as AddressInfo;
+      resolve(`http://127.0.0.1:${port}`);
+    });
+  });
+}
+
+const authed = { Authorization: `Bearer ${state.validToken}` };
+
+beforeEach(() => {
+  http.resetPluginHttp();
+  state.granted = new Set(["network:serve"]);
+});
+
+afterEach(async () => {
+  if (server) {
+    await new Promise((resolve) => server!.close(() => resolve(undefined)));
+    server = null;
+  }
+  http.resetPluginHttp();
+});
+
+describe("ctx.http mounting", () => {
+  it("serves a plugin's routes once it registers a router", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+    router.get("/thing", (_req, res) => res.json({ ok: true }));
+
+    const base = await startServer();
+    const response = await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+      headers: authed,
+    });
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ ok: true });
+  });
+
+  it("404s a plugin id that never registered a router", async () => {
+    const base = await startServer();
+
+    const response = await fetch(`${base}/plugin-api/nobody/thing`, {
+      headers: authed,
+    });
+
+    expect(response.status).toBe(404);
+  });
+
+  it("unmounts on deactivate, so a disabled plugin stops serving", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+    router.get("/thing", (_req, res) => res.json({ ok: true }));
+
+    const base = await startServer();
+    expect(
+      (
+        await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+          headers: authed,
+        })
+      ).status,
+    ).toBe(200);
+
+    http.unregisterPluginHttp("sample-plugin");
+
+    expect(
+      (
+        await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+          headers: authed,
+        })
+      ).status,
+    ).toBe(404);
+  });
+});
+
+describe("ctx.http authentication", () => {
+  it("requires authentication by default", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+    router.get("/thing", (_req, res) => res.json({ ok: true }));
+
+    const base = await startServer();
+
+    expect((await fetch(`${base}/plugin-api/sample-plugin/thing`)).status).toBe(
+      401,
+    );
+    expect(
+      (
+        await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+          headers: { Authorization: "Bearer nope" },
+        })
+      ).status,
+    ).toBe(401);
+  });
+
+  it("serves a declared public path without a token", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      options: { public: ["/webhook/:token"] },
+      reportError: () => {},
+    });
+    router.post("/webhook/:token", (req, res) =>
+      res.json({ token: req.params.token }),
+    );
+    router.get("/private", (_req, res) => res.json({ ok: true }));
+
+    const base = await startServer();
+
+    const open = await fetch(
+      `${base}/plugin-api/sample-plugin/webhook/abc123`,
+      {
+        method: "POST",
+      },
+    );
+    expect(open.status).toBe(200);
+    expect(await open.json()).toEqual({ token: "abc123" });
+
+    // Declaring one route public must not open the rest of the plugin.
+    expect(
+      (await fetch(`${base}/plugin-api/sample-plugin/private`)).status,
+    ).toBe(401);
+  });
+
+  it("does not let a public parameter swallow extra path segments", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      options: { public: ["/webhook/:token"] },
+      reportError: () => {},
+    });
+    router.get("/webhook/:token/secret", (_req, res) => res.json({ ok: true }));
+
+    const base = await startServer();
+
+    const response = await fetch(
+      `${base}/plugin-api/sample-plugin/webhook/abc/secret`,
+    );
+    expect(response.status).toBe(401);
+  });
+
+  it("gives the plugin the user core authenticated, not one the caller named", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+    router.get("/who", (req, res) =>
+      res.json({
+        userId: (req as express.Request & { userId?: string }).userId,
+      }),
+    );
+
+    const base = await startServer();
+    const response = await fetch(`${base}/plugin-api/sample-plugin/who`, {
+      headers: { ...authed, "x-user-id": "attacker" },
+    });
+
+    expect(await response.json()).toEqual({ userId: state.userId });
+  });
+});
+
+describe("ctx.http capability", () => {
+  it("refuses to build a router without network:serve declared", () => {
+    expect(() =>
+      http.createPluginRouter({
+        manifest: manifest({ capabilities: [] }),
+        reportError: () => {},
+      }),
+    ).not.toThrow();
+    // Declaration is checked in ctx.ts; the grant is checked per request below.
+  });
+
+  it("403s every request when the grant is revoked", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+    router.get("/thing", (_req, res) => res.json({ ok: true }));
+
+    const base = await startServer();
+    expect(
+      (
+        await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+          headers: authed,
+        })
+      ).status,
+    ).toBe(200);
+
+    // Revoked at runtime: no restart, and the next request is refused.
+    state.granted.delete("network:serve");
+
+    const response = await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+      headers: authed,
+    });
+    expect(response.status).toBe(403);
+  });
+});
+
+describe("ctx.http while the plugin is disabled", () => {
+  it("answers 503 rather than 404", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+    router.get("/thing", (_req, res) => res.json({ ok: true }));
+
+    // "Installed but not running" is a different fact from "no such plugin",
+    // and a caller can act on the difference.
+    http.setPluginEnabledCheck(() => false);
+
+    const base = await startServer();
+    const response = await fetch(`${base}/plugin-api/sample-plugin/thing`, {
+      headers: authed,
+    });
+
+    expect(response.status).toBe(503);
+  });
+});
+
+describe("ctx.http errors", () => {
+  it("reports a throwing route without leaking a stack", async () => {
+    const reported: unknown[] = [];
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: (error) => reported.push(error),
+    });
+    router.get("/boom", () => {
+      throw new Error("secret internal detail");
+    });
+
+    const base = await startServer();
+    const response = await fetch(`${base}/plugin-api/sample-plugin/boom`, {
+      headers: authed,
+    });
+
+    expect(response.status).toBe(500);
+    const body = await response.text();
+    expect(body).not.toContain("secret internal detail");
+    // Counted against the plugin's error budget.
+    expect(reported).toHaveLength(1);
+  });
+});
+
+describe("ctx.http streaming", () => {
+  it("streams an SSE response as it is produced", async () => {
+    const router = http.createPluginRouter({
+      manifest: manifest(),
+      reportError: () => {},
+    });
+
+    let release: (() => void) | null = null;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    router.get("/stream", async (_req, res) => {
+      res.setHeader("Content-Type", "text/event-stream");
+      res.setHeader("Cache-Control", "no-cache");
+      res.write("event: progress\ndata: 1\n\n");
+      // The first chunk has to arrive before the handler finishes, or this is
+      // buffering rather than streaming.
+      await gate;
+      res.write("event: result\ndata: done\n\n");
+      res.end();
+    });
+
+    const base = await startServer();
+    const response = await fetch(`${base}/plugin-api/sample-plugin/stream`, {
+      headers: authed,
+    });
+
+    expect(response.headers.get("content-type")).toContain("text/event-stream");
+
+    const reader = response.body!.getReader();
+    const decoder = new TextDecoder();
+
+    const first = await reader.read();
+    expect(decoder.decode(first.value)).toContain("data: 1");
+
+    release!();
+
+    let rest = "";
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      rest += decoder.decode(chunk.value);
+    }
+    expect(rest).toContain("data: done");
+  });
+});

src/backend/tests/plugins/ws.test.ts

@@ -0,0 +1,287 @@
+/**
+ * ctx.ws: the one way a plugin serves WebSockets.
+ *
+ * The properties that matter are the ones the per-plugin ports used to leave
+ * to each plugin: an upgrade is authenticated before any plugin code runs, a
+ * route that no longer exists refuses cleanly, and disabling a plugin actually
+ * closes its live sockets rather than just unrouting new ones.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { WebSocket } from "ws";
+
+const state = vi.hoisted(() => ({
+  validToken: "valid-token",
+  userId: "user-1",
+  granted: new Set<string>(["network:serve"]),
+}));
+
+vi.mock("../../utils/logger.js", () => ({
+  pluginLogger: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+vi.mock("../../utils/auth-manager.js", () => ({
+  AuthManager: {
+    getInstance: () => ({
+      verifyJWTToken: async (token: string) =>
+        token === state.validToken ? { userId: state.userId } : null,
+    }),
+  },
+}));
+
+vi.mock("../../plugins/permissions.js", () => ({
+  hasCapability: async (
+    _pluginId: string,
+    capability: string,
+    declared: readonly string[],
+  ) => declared.includes(capability) && state.granted.has(capability),
+}));
+
+const ws = await import("../../plugins/ws.js");
+
+const DECLARED = ["network:serve"] as const;
+
+let server: http.Server | null = null;
+let baseUrl = "";
+
+async function startServer(): Promise<string> {
+  const instance = http.createServer((_req, res) => {
+    res.statusCode = 404;
+    res.end();
+  });
+  ws.attachPluginWebSockets(instance);
+
+  return new Promise((resolve) => {
+    server = instance;
+    instance.listen(0, "127.0.0.1", () => {
+      const { port } = instance.address() as AddressInfo;
+      baseUrl = `ws://127.0.0.1:${port}`;
+      resolve(baseUrl);
+    });
+  });
+}
+
+/** Resolves with "open" or the HTTP status the upgrade was refused with. */
+function connect(
+  url: string,
+  protocols: string[] = [],
+): Promise<{ outcome: "open"; socket: WebSocket } | { outcome: number }> {
+  return new Promise((resolve) => {
+    const socket = new WebSocket(url, protocols);
+    socket.once("open", () => resolve({ outcome: "open", socket }));
+    socket.once("unexpected-response", (_req, res) =>
+      resolve({ outcome: res.statusCode ?? 0 }),
+    );
+    socket.once("error", () => resolve({ outcome: 0 }));
+  });
+}
+
+function authProtocols(token: string): string[] {
+  return [`termix.jwt.${token}`];
+}
+
+beforeEach(() => {
+  ws.resetPluginWebSockets();
+  state.granted = new Set(["network:serve"]);
+});
+
+afterEach(async () => {
+  ws.resetPluginWebSockets();
+  if (server) {
+    await new Promise((resolve) => server!.close(() => resolve(undefined)));
+    server = null;
+  }
+});
+
+describe("ctx.ws routing", () => {
+  it("serves a registered route to an authenticated client", async () => {
+    const seen: string[] = [];
+    ws.registerPluginWsRoute(
+      "sample-plugin",
+      "/socket",
+      ({ userId, socket }) => {
+        seen.push(userId);
+        (socket as WebSocket).send("hello");
+      },
+      DECLARED,
+    );
+
+    const base = await startServer();
+    const result = await connect(
+      `${base}/plugin-ws/sample-plugin/socket`,
+      authProtocols(state.validToken),
+    );
+
+    expect(result.outcome).toBe("open");
+    expect(seen).toEqual([state.userId]);
+    if (result.outcome === "open") result.socket.close();
+  });
+
+  it("404s a path nothing registered", async () => {
+    const base = await startServer();
+
+    const result = await connect(`${base}/plugin-ws/sample-plugin/missing`);
+
+    expect(result.outcome).toBe(404);
+  });
+
+  it("leaves non-plugin upgrades to whoever else is listening", async () => {
+    let claimedByCore = false;
+
+    const base = await startServer();
+    // A second listener standing in for a core WS server. If the plugin
+    // handler answered /ssh/websocket/ itself this would never fire, and the
+    // socket would be stolen from core rather than passed on.
+    server!.on("upgrade", (_req, socket) => {
+      claimedByCore = true;
+      socket.destroy();
+    });
+
+    await connect(`${base}/ssh/websocket/`);
+
+    expect(claimedByCore).toBe(true);
+  });
+});
+
+describe("ctx.ws authentication", () => {
+  it("rejects an upgrade with no token", async () => {
+    ws.registerPluginWsRoute("sample-plugin", "/socket", () => {}, DECLARED);
+
+    const base = await startServer();
+    const result = await connect(`${base}/plugin-ws/sample-plugin/socket`);
+
+    expect(result.outcome).toBe(401);
+  });
+
+  it("rejects an upgrade with a bad token", async () => {
+    ws.registerPluginWsRoute("sample-plugin", "/socket", () => {}, DECLARED);
+
+    const base = await startServer();
+    const result = await connect(
+      `${base}/plugin-ws/sample-plugin/socket`,
+      authProtocols("nope"),
+    );
+
+    expect(result.outcome).toBe(401);
+  });
+
+  it("serves a public route without a token", async () => {
+    ws.registerPluginWsRoute(
+      "sample-plugin",
+      "/guest",
+      ({ socket }) => (socket as WebSocket).send("hi"),
+      DECLARED,
+      { public: true },
+    );
+
+    const base = await startServer();
+    const result = await connect(`${base}/plugin-ws/sample-plugin/guest`);
+
+    expect(result.outcome).toBe("open");
+    if (result.outcome === "open") result.socket.close();
+  });
+});
+
+describe("ctx.ws capability", () => {
+  it("refuses the upgrade when network:serve is not granted", async () => {
+    ws.registerPluginWsRoute("sample-plugin", "/socket", () => {}, DECLARED);
+    state.granted.delete("network:serve");
+
+    const base = await startServer();
+    const result = await connect(
+      `${base}/plugin-ws/sample-plugin/socket`,
+      authProtocols(state.validToken),
+    );
+
+    expect(result.outcome).toBe(403);
+  });
+});
+
+describe("ctx.ws disposal", () => {
+  it("closes live sockets and stops routing on deactivate", async () => {
+    const dispose = ws.registerPluginWsRoute(
+      "sample-plugin",
+      "/socket",
+      () => {},
+      DECLARED,
+    );
+
+    const base = await startServer();
+    const result = await connect(
+      `${base}/plugin-ws/sample-plugin/socket`,
+      authProtocols(state.validToken),
+    );
+    expect(result.outcome).toBe("open");
+
+    const closed = new Promise<number>((resolve) => {
+      if (result.outcome === "open") {
+        result.socket.once("close", (code) => resolve(code));
+      }
+    });
+
+    dispose();
+
+    // A live terminal must not outlive the plugin that owns it.
+    expect(await closed).toBeGreaterThan(0);
+
+    const afterDispose = await connect(
+      `${base}/plugin-ws/sample-plugin/socket`,
+      authProtocols(state.validToken),
+    );
+    expect(afterDispose.outcome).toBe(404);
+  });
+});
+
+describe("ctx.ws raw upgrades", () => {
+  it("authenticates before handing the socket to the plugin", async () => {
+    const handled: string[] = [];
+    ws.registerPluginWsUpgrade(
+      "sample-plugin",
+      "/raw",
+      (_request, socket, _head, userId) => {
+        handled.push(userId);
+        (socket as { destroy: () => void }).destroy();
+      },
+      DECLARED,
+    );
+
+    const base = await startServer();
+
+    const unauthenticated = await connect(
+      `${base}/plugin-ws/sample-plugin/raw`,
+    );
+    expect(unauthenticated.outcome).toBe(401);
+    // The plugin never saw the unauthenticated attempt.
+    expect(handled).toEqual([]);
+
+    await connect(
+      `${base}/plugin-ws/sample-plugin/raw`,
+      authProtocols(state.validToken),
+    );
+    expect(handled).toEqual([state.userId]);
+  });
+});
+
+describe("parsePluginWsUrl", () => {
+  it("only claims well-formed plugin socket paths", () => {
+    expect(ws.parsePluginWsUrl("/plugin-ws/docker/console")).toEqual({
+      pluginId: "docker",
+      path: "/console",
+    });
+    expect(ws.parsePluginWsUrl("/plugin-ws/docker/console?x=1")).toEqual({
+      pluginId: "docker",
+      path: "/console",
+    });
+    expect(ws.parsePluginWsUrl("/ssh/websocket/")).toBeNull();
+    expect(ws.parsePluginWsUrl("/plugin-ws/docker")).toBeNull();
+    expect(ws.parsePluginWsUrl(undefined)).toBeNull();
+  });
+});