@mingxy/cerebro 1.20.4 → 1.20.6

package/src/web-server.test.ts

@@ -0,0 +1,740 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+// ── Hoisted mock functions ───────────────────────────────────────────
+
+const {
+  mockExistsSync,
+  mockStat,
+  mockReadFile,
+  mockLogInfo,
+  mockLogWarn,
+  mockLogError,
+} = vi.hoisted(() => ({
+  mockExistsSync: vi.fn(),
+  mockStat: vi.fn(),
+  mockReadFile: vi.fn(),
+  mockLogInfo: vi.fn(),
+  mockLogWarn: vi.fn(),
+  mockLogError: vi.fn(),
+}));
+
+// ── Mocks ────────────────────────────────────────────────────────────
+
+let capturedHandler: (req: IncomingMessage, res: ServerResponse) => void;
+
+const mockServerInstance = {
+  on: vi.fn(),
+  listen: vi.fn(),
+  close: vi.fn(),
+  unref: vi.fn(),
+};
+
+vi.mock("node:http", () => ({
+  createServer: vi.fn().mockImplementation((handler) => {
+    capturedHandler = handler;
+    return mockServerInstance;
+  }),
+}));
+
+vi.mock("node:fs", () => ({
+  existsSync: mockExistsSync,
+  stat: mockStat,
+  readFile: mockReadFile,
+}));
+
+vi.mock("./logger.js", () => ({
+  logInfo: mockLogInfo,
+  logWarn: mockLogWarn,
+  logError: mockLogError,
+}));
+
+// ── Imports (post-mock) ──────────────────────────────────────────────
+
+import * as http from "node:http";
+import { startWebServer, stopWebServer } from "./web-server.js";
+import type { WebServerHandle } from "./web-server.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+const mockedCreateServer = vi.mocked(http.createServer);
+
+function makeReq(url: string, method = "GET"): IncomingMessage {
+  return { url, method } as IncomingMessage;
+}
+
+function makeRes(): ServerResponse & {
+  _status: number;
+  _headers: Record<string, string>;
+  _body: string;
+  _ended: boolean;
+} {
+  return {
+    _status: 0,
+    _headers: {},
+    _body: "",
+    _ended: false,
+    writeHead(status: number, headers?: Record<string, string>) {
+      this._status = status;
+      if (headers) Object.assign(this._headers, headers);
+      return this;
+    },
+    end(data?: unknown) {
+      if (data !== undefined) this._body = typeof data === "string" ? data : String(data);
+      this._ended = true;
+      return this;
+    },
+  } as any;
+}
+
+function resetMockServer() {
+  mockServerInstance.on.mockReturnThis();
+  mockServerInstance.listen.mockImplementation((_p: number, _h: string, cb: () => void) => cb());
+  mockServerInstance.close.mockImplementation((cb: () => void) => cb());
+  mockServerInstance.unref.mockReturnThis();
+}
+
+function defaultFsMocks() {
+  mockExistsSync.mockImplementation((p: unknown) => {
+    const s = String(p);
+    return s.includes("web") || s.includes("index.html");
+  });
+  mockStat.mockImplementation((_p: unknown, cb: Function) => {
+    cb(null, { isFile: () => true, size: 100 });
+  });
+  mockReadFile.mockImplementation((_p: unknown, cb: Function) => {
+    cb(null, Buffer.from("file content"));
+  });
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe("web-server", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    resetMockServer();
+    defaultFsMocks();
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  // ── Server startup ────────────────────────────────────────────────
+
+  describe("server startup", () => {
+    it("returns null when web directory does not exist", async () => {
+      mockExistsSync.mockReturnValue(false);
+
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      expect(handle).toBeNull();
+      expect(mockLogWarn).toHaveBeenCalledWith(
+        "web-server: web directory not found, skipping",
+        expect.objectContaining({ webDir: expect.any(String) }),
+      );
+    });
+
+    it("returns null when index.html does not exist", async () => {
+      mockExistsSync.mockImplementation((p: unknown) => {
+        const s = String(p);
+        return s.includes("web") && !s.includes("index.html");
+      });
+
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      expect(handle).toBeNull();
+      expect(mockLogWarn).toHaveBeenCalledWith(
+        "web-server: index.html not found, skipping",
+        expect.objectContaining({ webDir: expect.any(String) }),
+      );
+    });
+
+    it("creates server and returns handle on success", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      expect(handle).not.toBeNull();
+      expect(mockedCreateServer).toHaveBeenCalled();
+      expect(mockLogInfo).toHaveBeenCalledWith(
+        "web-server: server started",
+        expect.objectContaining({ port: 5212 }),
+      );
+
+      await stopWebServer(handle!);
+    });
+
+    it("uses config.port when provided", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080", port: 9999 });
+
+      const addr = handle!.address();
+      expect(addr).toEqual({ port: 9999, family: "IPv4", address: "127.0.0.1" });
+
+      await stopWebServer(handle!);
+    });
+  });
+
+  // ── HTTP handler ──────────────────────────────────────────────────
+
+  describe("HTTP handler", () => {
+    async function getHandle(): Promise<WebServerHandle> {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+      expect(handle).not.toBeNull();
+      return handle!;
+    }
+
+    it("returns health check JSON at /health", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/health");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).toBe(200);
+      expect(res._headers["Content-Type"]).toBe("application/json");
+      expect(res._headers["X-Content-Type-Options"]).toBe("nosniff");
+      const body = JSON.parse(res._body);
+      expect(body).toEqual({ status: "ok", service: "cerebro", port: 5212 });
+
+      await stopWebServer(handle);
+    });
+
+    it("returns health check at /health/ (trailing slash)", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/health/");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).toBe(200);
+      expect(JSON.parse(res._body).service).toBe("cerebro");
+
+      await stopWebServer(handle);
+    });
+
+    it("returns 405 for POST method", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/some/path", "POST");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).toBe(405);
+      expect(res._headers["X-Content-Type-Options"]).toBe("nosniff");
+      expect(res._body).toBe("Method Not Allowed");
+
+      await stopWebServer(handle);
+    });
+
+    it("returns 405 for DELETE method", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/some/path", "DELETE");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).toBe(405);
+      expect(res._body).toBe("Method Not Allowed");
+
+      await stopWebServer(handle);
+    });
+
+    it("returns 405 for PUT method", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/some/path", "PUT");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).toBe(405);
+
+      await stopWebServer(handle);
+    });
+
+    it("allows HEAD method", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/style.css", "HEAD");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).not.toBe(405);
+
+      await stopWebServer(handle);
+    });
+
+    it("allows GET method", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/app.js", "GET");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+
+      expect(res._status).not.toBe(405);
+
+      await stopWebServer(handle);
+    });
+  });
+
+  // ── Static file serving ───────────────────────────────────────────
+
+  describe("static file serving", () => {
+    async function getHandle(): Promise<WebServerHandle> {
+      return (await startWebServer({ apiUrl: "http://localhost:8080" }))!;
+    }
+
+    it("serves JS with correct content type", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/app.js");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+      expect(res._headers["Content-Type"]).toContain("application/javascript");
+
+      await stopWebServer(handle);
+    });
+
+    it("serves CSS with correct content type", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/style.css");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+      expect(res._headers["Content-Type"]).toContain("text/css");
+
+      await stopWebServer(handle);
+    });
+
+    it("serves SVG with correct content type", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/icon.svg");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+      expect(res._headers["Content-Type"]).toBe("image/svg+xml");
+
+      await stopWebServer(handle);
+    });
+
+    it("serves JSON with correct content type", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/data.json");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+      expect(res._headers["Content-Type"]).toContain("application/json");
+
+      await stopWebServer(handle);
+    });
+
+    it("falls back to application/octet-stream for unknown extensions", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/data.xyz");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+      expect(res._headers["Content-Type"]).toBe("application/octet-stream");
+
+      await stopWebServer(handle);
+    });
+
+    it("falls back to index.html for unknown paths (SPA)", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/unknown-route");
+      const res = makeRes();
+
+      let statCallCount = 0;
+      mockStat.mockImplementation((_p: unknown, cb: Function) => {
+        statCallCount++;
+        if (statCallCount === 1) {
+          cb(new Error("ENOENT"), undefined);
+        } else {
+          cb(null, { isFile: () => true, size: 500 });
+        }
+      });
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+
+      await stopWebServer(handle);
+    });
+
+    it("returns 404 when index.html is missing for SPA fallback", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/unknown-route");
+      const res = makeRes();
+
+      mockStat.mockImplementation((_p: unknown, cb: Function) => {
+        cb(new Error("ENOENT"), undefined);
+      });
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(404);
+      expect(res._body).toBe("Not Found");
+
+      await stopWebServer(handle);
+    });
+  });
+
+  // ── Cache headers ─────────────────────────────────────────────────
+
+  describe("cache headers", () => {
+    async function getHandle(): Promise<WebServerHandle> {
+      return (await startWebServer({ apiUrl: "http://localhost:8080" }))!;
+    }
+
+    it("sets no-cache for HTML files", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/index.html");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._headers["Cache-Control"]).toBe("no-cache, no-store, must-revalidate");
+
+      await stopWebServer(handle);
+    });
+
+    it("sets long cache for JS files", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/app.js");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._headers["Cache-Control"]).toBe("public, max-age=86400");
+
+      await stopWebServer(handle);
+    });
+
+    it("sets long cache for CSS files", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/style.css");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._headers["Cache-Control"]).toBe("public, max-age=86400");
+
+      await stopWebServer(handle);
+    });
+  });
+
+  // ── COMMON_HEADERS (X-Content-Type-Options) ───────────────────────
+
+  describe("COMMON_HEADERS", () => {
+    async function getHandle(): Promise<WebServerHandle> {
+      return (await startWebServer({ apiUrl: "http://localhost:8080" }))!;
+    }
+
+    it("includes X-Content-Type-Options: nosniff on health endpoint", async () => {
+      const handle = await getHandle();
+      const res = makeRes();
+
+      capturedHandler(makeReq("/health"), res);
+
+      expect(res._headers["X-Content-Type-Options"]).toBe("nosniff");
+
+      await stopWebServer(handle);
+    });
+
+    it("includes X-Content-Type-Options: nosniff on 405", async () => {
+      const handle = await getHandle();
+      const res = makeRes();
+
+      capturedHandler(makeReq("/x", "POST"), res);
+
+      expect(res._headers["X-Content-Type-Options"]).toBe("nosniff");
+
+      await stopWebServer(handle);
+    });
+
+    it("includes X-Content-Type-Options: nosniff on 404", async () => {
+      const handle = await getHandle();
+      const res = makeRes();
+
+      mockStat.mockImplementation((_p: unknown, cb: Function) => {
+        cb(new Error("ENOENT"), undefined);
+      });
+
+      capturedHandler(makeReq("/missing-route"), res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._headers["X-Content-Type-Options"]).toBe("nosniff");
+
+      await stopWebServer(handle);
+    });
+  });
+
+  // ── XSS prevention in HTML ────────────────────────────────────────
+
+  describe("XSS prevention", () => {
+    async function getHandle(apiUrl = "http://localhost:8080"): Promise<WebServerHandle> {
+      return (await startWebServer({ apiUrl }))!;
+    }
+
+    it("replaces __OMEM_API_URL__ with JSON.stringify for safety", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/index.html");
+      const res = makeRes();
+
+      mockReadFile.mockImplementation((_p: unknown, cb: Function) => {
+        cb(null, Buffer.from(
+          '<html><script>window.__OMEM_API_URL__ = "__OMEM_API_URL__";</script></html>',
+        ));
+      });
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+      // Placeholder replaced with JSON.stringify value
+      expect(res._body).toContain('"http://localhost:8080"');
+      // Raw placeholder should be gone
+      expect(res._body).not.toMatch(/window\.__OMEM_API_URL__\s*=\s*["']__OMEM_API_URL__["']/);
+
+      await stopWebServer(handle);
+    });
+
+    it("escapes quotes in malicious apiUrl via JSON.stringify", async () => {
+      const maliciousUrl = 'http://evil.com"; alert(1) //';
+      const handle = await getHandle(maliciousUrl);
+      const req = makeReq("/index.html");
+      const res = makeRes();
+
+      mockReadFile.mockImplementation((_p: unknown, cb: Function) => {
+        cb(null, Buffer.from(
+          '<script>window.__OMEM_API_URL__ = "__OMEM_API_URL__";</script>',
+        ));
+      });
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      // JSON.stringify wraps the value in quotes and escapes internal quotes
+      expect(res._body).not.toMatch(/window\.__OMEM_API_URL__\s*=\s*["']__OMEM_API_URL__["']/);
+
+      await stopWebServer(handle);
+    });
+
+    it("does not modify non-HTML files", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/data.json");
+      const res = makeRes();
+
+      mockReadFile.mockImplementation((_p: unknown, cb: Function) => {
+        cb(null, Buffer.from('{"url": "__OMEM_API_URL__"}'));
+      });
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      // Non-HTML should not be modified
+      expect(res._body).toBe('{"url": "__OMEM_API_URL__"}');
+
+      await stopWebServer(handle);
+    });
+  });
+
+  // ── File read error ───────────────────────────────────────────────
+
+  describe("file read error", () => {
+    async function getHandle(): Promise<WebServerHandle> {
+      return (await startWebServer({ apiUrl: "http://localhost:8080" }))!;
+    }
+
+    it("returns 500 when file read fails", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/broken.css");
+      const res = makeRes();
+
+      mockReadFile.mockImplementation((_p: unknown, cb: Function) => {
+        cb(new Error("read error"), undefined);
+      });
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(500);
+      expect(res._body).toBe("Internal Server Error");
+      expect(res._headers["X-Content-Type-Options"]).toBe("nosniff");
+
+      await stopWebServer(handle);
+    });
+  });
+
+  // ── Port configuration ────────────────────────────────────────────
+
+  describe("port configuration", () => {
+    it("uses config.port when provided", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080", port: 9999 });
+
+      const req = makeReq("/health");
+      const res = makeRes();
+      capturedHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.port).toBe(9999);
+
+      await stopWebServer(handle!);
+    });
+
+    it("uses default port 5212 when no port specified", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      const req = makeReq("/health");
+      const res = makeRes();
+      capturedHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.port).toBe(5212);
+
+      await stopWebServer(handle!);
+    });
+  });
+
+  // ── WebServerHandle ───────────────────────────────────────────────
+
+  describe("WebServerHandle", () => {
+    it("address() returns correct info", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080", port: 9999 });
+
+      const addr = handle!.address();
+      expect(addr).toEqual({ port: 9999, family: "IPv4", address: "127.0.0.1" });
+
+      await stopWebServer(handle!);
+    });
+
+    it("isOwner() returns true when server was started by us", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      expect(handle!.isOwner()).toBe(true);
+
+      await stopWebServer(handle!);
+    });
+
+    it("stop() closes the server", async () => {
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      await stopWebServer(handle!);
+
+      expect(mockServerInstance.close).toHaveBeenCalled();
+    });
+  });
+
+  // ── Takeover mechanism ────────────────────────────────────────────
+
+  describe("takeover mechanism", () => {
+    it("starts takeover watch when existing server is healthy", async () => {
+      const mockedFetch = vi.mocked(fetch);
+      mockedFetch.mockResolvedValue({ ok: true, text: () => Promise.resolve("cerebro") } as any);
+
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      expect(mockLogInfo).toHaveBeenCalledWith(
+        "web-server: reusing existing server",
+        expect.objectContaining({ port: 5212 }),
+      );
+      // We didn't create the server, so isOwner should be false
+      expect(handle!.isOwner()).toBe(false);
+
+      await stopWebServer(handle!);
+    });
+
+    it("starts takeover when port is busy (EADDRINUSE)", async () => {
+      const mockedFetch = vi.mocked(fetch);
+      mockedFetch.mockRejectedValue(new Error("ECONNREFUSED"));
+
+      mockServerInstance.on.mockImplementation((event: string, handler: Function) => {
+        if (event === "error") {
+          handler(Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" }));
+        }
+        return mockServerInstance;
+      });
+
+      const handle = await startWebServer({ apiUrl: "http://localhost:8080" });
+
+      expect(mockLogInfo).toHaveBeenCalledWith(
+        "web-server: port busy, starting takeover watch",
+        expect.objectContaining({ port: 5212 }),
+      );
+
+      await stopWebServer(handle!);
+    });
+  });
+
+  // ── Path traversal defense ────────────────────────────────────────
+  // NOTE: new URL() normalizes ../ segments, so ../../../etc/passwd
+  // becomes /etc/passwd which resolves to webDir/etc/passwd — safely
+  // inside the web directory. resolveSafe is defense-in-depth.
+
+  describe("path traversal defense", () => {
+    async function getHandle(): Promise<WebServerHandle> {
+      return (await startWebServer({ apiUrl: "http://localhost:8080" }))!;
+    }
+
+    it("URL normalization prevents ../ traversal (served as safe path)", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/../../../etc/passwd");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      // URL normalizes ../ → result is within webDir, served as 200
+      expect(res._status).toBe(200);
+
+      await stopWebServer(handle);
+    });
+
+    it("allows normal file paths", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/assets/app.js");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+
+      await stopWebServer(handle);
+    });
+
+    it("allows root path / (served as index.html)", async () => {
+      const handle = await getHandle();
+      const req = makeReq("/");
+      const res = makeRes();
+
+      capturedHandler(req, res);
+      await vi.waitFor(() => res._ended);
+
+      expect(res._status).toBe(200);
+
+      await stopWebServer(handle);
+    });
+  });
+});