shadow-claw 1.24.0 → 1.25.0

package/src/server/peer.ts

@@ -1,4 +1,5 @@
 import http from "node:http";
+import https from "node:https";
 import { ExpressPeerServer } from "peer";
 import type { Express } from "express";
 
@@ -10,10 +11,13 @@ import type { Express } from "express";
  * We mount the middleware at "/" and set internal path to "/" so routes land
  * at /peerjs/* as expected.
  *
- * @param httpServer - The underlying http.Server (needed for WebSocket upgrade).
+ * @param httpServer - The underlying http.Server or https.Server (needed for WebSocket upgrade).
  * @param app - The Express app to mount the PeerJS REST routes on.
  */
-export function attachPeerServer(httpServer: http.Server, app: Express): void {
+export function attachPeerServer(
+  httpServer: http.Server | https.Server,
+  app: Express,
+): void {
   const peerServer = ExpressPeerServer(httpServer, {
     path: "/",
     allow_discovery: false,

package/src/server/routes/backup.test.ts

@@ -121,6 +121,20 @@ describe("backup routes", () => {
     expect(res.data.backups).toBeDefined();
   });
 
+  it("allows GitHub Pages origin requests without explicit token header", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/api/backup/list",
+      headers: {
+        host: `127.0.0.1:${port}`,
+        origin: "https://xt-ml.github.io",
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.data.backups).toBeDefined();
+  });
+
   it("uploads a file and verifies on disk", async () => {
     const res = await makeHttpRequest({
       port,

package/src/server/routes/backup.ts

@@ -20,6 +20,8 @@ import {
 export interface BackupRoutesOptions {
   backupsDir: string;
   token?: string;
+  allowedOrigins?: Set<string>;
+  corsMode?: "localhost" | "private" | "all";
 }
 
 function isSafeRelativePath(relPath: string): boolean {
@@ -37,39 +39,66 @@ function isSafeRelativePath(relPath: string): boolean {
   return true;
 }
 
-function isSameOriginBrowser(req: Request): boolean {
+function isSameOriginBrowser(
+  req: Request,
+  options?: BackupRoutesOptions,
+): boolean {
   const host = req.headers.host || "127.0.0.1";
   const origin = req.headers.origin;
   const referer = req.headers.referer;
 
-  if (origin) {
+  const isTrustedUrl = (urlStr: string): boolean => {
     try {
-      const originUrl = new URL(origin);
-      if (originUrl.host === host) {
+      const parsed = new URL(urlStr);
+      if (parsed.host === host) {
         return true;
       }
+
+      const hostname = parsed.hostname.toLowerCase();
       if (
-        originUrl.hostname === "127.0.0.1" ||
-        originUrl.hostname === "localhost"
+        hostname === "127.0.0.1" ||
+        hostname === "localhost" ||
+        hostname === "::1" ||
+        hostname === "[::1]"
       ) {
         return true;
       }
-    } catch (_) {}
-  }
 
-  if (referer) {
-    try {
-      const refererUrl = new URL(referer);
-      if (refererUrl.host === host) {
+      if (
+        hostname === "github.com" ||
+        hostname.endsWith(".github.io") ||
+        hostname.endsWith(".pages.dev")
+      ) {
+        return true;
+      }
+
+      if (options?.corsMode === "all") {
+        return true;
+      }
+
+      if (
+        options?.allowedOrigins &&
+        options.allowedOrigins.has(parsed.origin)
+      ) {
         return true;
       }
+
       if (
-        refererUrl.hostname === "127.0.0.1" ||
-        refererUrl.hostname === "localhost"
+        options?.corsMode === "private" &&
+        /^(127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(hostname)
       ) {
         return true;
       }
     } catch (_) {}
+    return false;
+  };
+
+  if (origin && isTrustedUrl(origin)) {
+    return true;
+  }
+
+  if (referer && isTrustedUrl(referer)) {
+    return true;
   }
 
   const secFetchSite = req.headers["sec-fetch-site"];
@@ -103,7 +132,7 @@ export function registerBackupRoutes(
 
     const isAuthValid = providedToken
       ? providedToken === token
-      : isSameOriginBrowser(req);
+      : isSameOriginBrowser(req, options);
 
     if (!isAuthValid) {
       res.status(401).json({ error: "Unauthorized: Invalid control token" });

package/src/server/server.test.ts

@@ -147,3 +147,121 @@ describe("src/server/server.ts proxy simulation", () => {
     expect(headers.authorization).toBe("Bearer server-key");
   });
 });
+
+describe("startServer HTTP / HTTPS selection", () => {
+  let httpMock: any;
+  let httpsMock: any;
+  let appMock: any;
+  let tlsMock: any;
+  let tcpPortUsedMock: any;
+  let controlPlaneMock: any;
+
+  beforeEach(() => {
+    jest.resetModules();
+
+    const fakeServer = {
+      listen: jest.fn((_port: number, _host: string, cb: any) => {
+        if (cb) cb();
+        return fakeServer;
+      }),
+    };
+
+    httpMock = {
+      createServer: jest.fn(() => fakeServer),
+    };
+
+    httpsMock = {
+      createServer: jest.fn(() => fakeServer),
+    };
+
+    appMock = {
+      createApp: jest.fn(() => ({
+        app: {},
+        scheduler: { start: jest.fn() },
+      })),
+    };
+
+    tlsMock = {
+      ensureTlsCredentials: jest.fn(() => ({
+        key: Buffer.from("fake-key"),
+        cert: Buffer.from("fake-cert"),
+      })),
+    };
+
+    tcpPortUsedMock = {
+      check: jest.fn(() => Promise.resolve(false)),
+    };
+
+    controlPlaneMock = {
+      createControlPlane: jest.fn(() => ({
+        getToken: jest.fn(() => "test-token"),
+      })),
+    };
+
+    jest.spyOn(console, "log").mockImplementation(() => {});
+
+    jest.unstable_mockModule("node:http", () => ({
+      default: httpMock,
+      ...httpMock,
+    }));
+    jest.unstable_mockModule("node:https", () => ({
+      default: httpsMock,
+      ...httpsMock,
+    }));
+    jest.unstable_mockModule("./app.js", () => appMock);
+    jest.unstable_mockModule("./tls.js", () => tlsMock);
+    jest.unstable_mockModule("tcp-port-used", () => ({
+      default: tcpPortUsedMock,
+      ...tcpPortUsedMock,
+    }));
+    jest.unstable_mockModule("./control-plane.js", () => controlPlaneMock);
+    jest.unstable_mockModule("./peer.js", () => ({
+      attachPeerServer: jest.fn(),
+    }));
+  });
+
+  it("creates http.Server when config.https is false", async () => {
+    const { startServer } = await import("./server.js");
+    await startServer({
+      port: 8888,
+      bindHost: "127.0.0.1",
+      corsMode: "localhost",
+      allowedOrigins: new Set(),
+      verbose: false,
+      peerjs: false,
+      rootPath: "/root",
+      databaseDir: "/db",
+      allowPrivateProxy: false,
+      https: false,
+      sslDir: "/ssl",
+    });
+
+    expect(httpMock.createServer).toHaveBeenCalledTimes(1);
+    expect(httpsMock.createServer).not.toHaveBeenCalled();
+    expect(tlsMock.ensureTlsCredentials).not.toHaveBeenCalled();
+  });
+
+  it("creates https.Server with TLS credentials when config.https is true", async () => {
+    const { startServer } = await import("./server.js");
+    await startServer({
+      port: 8888,
+      bindHost: "127.0.0.1",
+      corsMode: "localhost",
+      allowedOrigins: new Set(),
+      verbose: false,
+      peerjs: false,
+      rootPath: "/root",
+      databaseDir: "/db",
+      allowPrivateProxy: false,
+      https: true,
+      sslDir: "/ssl",
+    });
+
+    expect(tlsMock.ensureTlsCredentials).toHaveBeenCalledTimes(1);
+    expect(httpsMock.createServer).toHaveBeenCalledWith(
+      { key: Buffer.from("fake-key"), cert: Buffer.from("fake-cert") },
+      expect.anything(),
+    );
+    expect(httpMock.createServer).not.toHaveBeenCalled();
+  });
+});

package/src/server/server.ts

@@ -1,5 +1,6 @@
 import { exit } from "node:process";
 import http from "node:http";
+import https from "node:https";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import tcpPortUsed from "tcp-port-used";
@@ -10,10 +11,11 @@ import { attachPeerServer } from "./peer.js";
 import { createControlPlane } from "./control-plane.js";
 import { ServerPeer } from "./server-peer.js";
 import { parseConfig, ServerConfig } from "./config.js";
+import { ensureTlsCredentials } from "./tls.js";
 
 export async function startServer(
   customConfig?: ServerConfig,
-): Promise<http.Server> {
+): Promise<http.Server | https.Server> {
   const config = customConfig || parseConfig();
   const { app, scheduler } = createApp(config);
 
@@ -27,13 +29,17 @@ export async function startServer(
 
   scheduler.start();
 
-  const httpServer = http.createServer(app);
+  const httpServer: http.Server | https.Server = config.https
+    ? https.createServer(ensureTlsCredentials(config), app)
+    : http.createServer(app);
 
   const controlPlane = createControlPlane({
     httpServer,
     app,
     token: config.controlToken,
     verbose: config.verbose,
+    allowedOrigins: config.allowedOrigins,
+    corsMode: config.corsMode,
   });
 
   let serverPeer: ServerPeer | null = null;
@@ -47,9 +53,20 @@ export async function startServer(
     });
   }
 
-  return new Promise<http.Server>((resolve) => {
+  return new Promise<http.Server | https.Server>((resolve) => {
     httpServer.listen(config.port, config.bindHost, () => {
-      console.log(`Server running at http://${config.bindHost}:${config.port}`);
+      const protocol = config.https ? "https" : "http";
+      const wsProtocol = config.https ? "wss" : "ws";
+
+      console.log(
+        `Server running at ${protocol}://${config.bindHost}:${config.port}`,
+      );
+
+      if (config.https) {
+        const certLocation =
+          config.certPath || path.join(config.sslDir, "cert.pem");
+        console.log(`TLS enabled (cert: ${certLocation})`);
+      }
 
       if (config.bindHost === DEFAULT_DEV_IP) {
         console.log(
@@ -70,7 +87,7 @@ export async function startServer(
       }
 
       console.log(
-        `Control plane active at http://${config.bindHost}:${config.port}/api/control/events (SSE) and ws://${config.bindHost}:${config.port}/ws/control (WebSocket)`,
+        `Control plane active at ${protocol}://${config.bindHost}:${config.port}/api/control/events (SSE) and ${wsProtocol}://${config.bindHost}:${config.port}/ws/control (WebSocket)`,
       );
       console.log(`Control token: ${controlPlane.getToken()}`);
 

package/src/server/tls.test.ts

@@ -0,0 +1,266 @@
+import { jest } from "@jest/globals";
+import type { ServerConfig } from "./config.js";
+
+describe("tls credentials", () => {
+  let fsMock: any;
+  let childProcessMock: any;
+  let processMock: any;
+  let osMock: any;
+  let baseConfig: ServerConfig;
+
+  beforeEach(() => {
+    jest.resetModules();
+
+    fsMock = {
+      existsSync: jest.fn(),
+      readFileSync: jest.fn(),
+      mkdirSync: jest.fn(),
+    };
+
+    childProcessMock = {
+      execFileSync: jest.fn(),
+    };
+
+    processMock = {
+      exit: jest.fn(),
+    };
+
+    osMock = {
+      networkInterfaces: jest.fn(() => ({
+        eth0: [{ address: "192.168.1.50" }],
+      })),
+    };
+
+    baseConfig = {
+      port: 8888,
+      bindHost: "127.0.0.1",
+      corsMode: "localhost",
+      allowedOrigins: new Set(),
+      verbose: false,
+      peerjs: false,
+      rootPath: "/app/public",
+      databaseDir: "/app/database",
+      allowPrivateProxy: false,
+      https: true,
+      sslDir: "/app/.cache/tls",
+    };
+
+    jest.spyOn(console, "error").mockImplementation(() => {});
+    jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    jest.unstable_mockModule("node:fs", () => ({
+      default: fsMock,
+      ...fsMock,
+    }));
+    jest.unstable_mockModule("node:os", () => ({
+      default: osMock,
+      ...osMock,
+    }));
+    jest.unstable_mockModule("node:child_process", () => ({
+      default: childProcessMock,
+      ...childProcessMock,
+    }));
+    jest.unstable_mockModule("node:process", () => ({
+      exit: processMock.exit,
+      default: processMock,
+    }));
+  });
+
+  it("reads explicit cert and key files when both are provided and exist", async () => {
+    fsMock.existsSync.mockReturnValue(true);
+    fsMock.readFileSync.mockImplementation((file: string) =>
+      Buffer.from(`content of ${file}`),
+    );
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    const credentials = ensureTlsCredentials({
+      ...baseConfig,
+      certPath: "/custom/cert.pem",
+      keyPath: "/custom/key.pem",
+    });
+
+    expect(credentials.cert.toString()).toBe("content of /custom/cert.pem");
+    expect(credentials.key.toString()).toBe("content of /custom/key.pem");
+    expect(childProcessMock.execFileSync).not.toHaveBeenCalled();
+  });
+
+  it("exits when certPath is provided without keyPath", async () => {
+    const { ensureTlsCredentials } = await import("./tls.js");
+    ensureTlsCredentials({
+      ...baseConfig,
+      certPath: "/custom/cert.pem",
+      keyPath: undefined,
+    });
+
+    expect(processMock.exit).toHaveBeenCalledWith(1);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("provided without --key"),
+    );
+  });
+
+  it("exits when keyPath is provided without certPath", async () => {
+    const { ensureTlsCredentials } = await import("./tls.js");
+    ensureTlsCredentials({
+      ...baseConfig,
+      certPath: undefined,
+      keyPath: "/custom/key.pem",
+    });
+
+    expect(processMock.exit).toHaveBeenCalledWith(1);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("provided without --cert"),
+    );
+  });
+
+  it("exits when provided cert file does not exist", async () => {
+    fsMock.existsSync.mockImplementation(
+      (file: string) => file !== "/custom/cert.pem",
+    );
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    ensureTlsCredentials({
+      ...baseConfig,
+      certPath: "/custom/cert.pem",
+      keyPath: "/custom/key.pem",
+    });
+
+    expect(processMock.exit).toHaveBeenCalledWith(1);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("TLS certificate not found"),
+    );
+  });
+
+  it("exits when provided key file does not exist", async () => {
+    fsMock.existsSync.mockImplementation(
+      (file: string) => file !== "/custom/key.pem",
+    );
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    ensureTlsCredentials({
+      ...baseConfig,
+      certPath: "/custom/cert.pem",
+      keyPath: "/custom/key.pem",
+    });
+
+    expect(processMock.exit).toHaveBeenCalledWith(1);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("TLS private key not found"),
+    );
+  });
+
+  it("returns cached cert and key if already present in sslDir", async () => {
+    fsMock.existsSync.mockReturnValue(true);
+    fsMock.readFileSync.mockImplementation((file: string) =>
+      Buffer.from(`cached ${file}`),
+    );
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    const credentials = ensureTlsCredentials(baseConfig);
+
+    expect(credentials.cert.toString()).toBe("cached /app/.cache/tls/cert.pem");
+    expect(credentials.key.toString()).toBe("cached /app/.cache/tls/key.pem");
+    expect(childProcessMock.execFileSync).not.toHaveBeenCalled();
+  });
+
+  it("generates self-signed cert and key via openssl when not in sslDir", async () => {
+    fsMock.existsSync.mockReturnValue(false);
+    fsMock.readFileSync.mockImplementation((file: string) =>
+      Buffer.from(`generated ${file}`),
+    );
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    const credentials = ensureTlsCredentials(baseConfig);
+
+    expect(fsMock.mkdirSync).toHaveBeenCalledWith("/app/.cache/tls", {
+      recursive: true,
+    });
+    expect(childProcessMock.execFileSync).toHaveBeenCalledWith(
+      "openssl",
+      expect.arrayContaining([
+        "-addext",
+        expect.stringMatching(/subjectAltName=.*IP:192\.168\.1\.50/),
+      ]),
+      { stdio: "pipe" },
+    );
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Generated self-signed TLS certificate"),
+    );
+    expect(credentials.cert.toString()).toBe(
+      "generated /app/.cache/tls/cert.pem",
+    );
+    expect(credentials.key.toString()).toBe(
+      "generated /app/.cache/tls/key.pem",
+    );
+  });
+
+  it("resolves SAN entries including loopback, local interfaces, and bindHost", async () => {
+    const { resolveSanList } = await import("./tls.js");
+    const sans = resolveSanList("10.9.8.226");
+
+    expect(sans).toContain("DNS:localhost");
+    expect(sans).toContain("IP:127.0.0.1");
+    expect(sans).toContain("IP:::1");
+    expect(sans).toContain("IP:192.168.1.50");
+    expect(sans).toContain("IP:10.9.8.226");
+  });
+
+  it("resolves DNS hostname for bindHost if bindHost is a domain", async () => {
+    const { resolveSanList } = await import("./tls.js");
+    const sans = resolveSanList("my-laptop.local");
+
+    expect(sans).toContain("DNS:my-laptop.local");
+  });
+
+  it("falls back to standard openssl args when -addext fails", async () => {
+    fsMock.existsSync.mockReturnValue(false);
+    fsMock.readFileSync.mockImplementation((file: string) =>
+      Buffer.from(`generated ${file}`),
+    );
+
+    childProcessMock.execFileSync
+      .mockImplementationOnce(() => {
+        throw new Error("unknown option -addext");
+      })
+      .mockImplementationOnce(() => Buffer.from(""));
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    const credentials = ensureTlsCredentials(baseConfig);
+
+    expect(childProcessMock.execFileSync).toHaveBeenCalledTimes(2);
+    expect(credentials.cert.toString()).toBe(
+      "generated /app/.cache/tls/cert.pem",
+    );
+  });
+
+  it("handles ENOENT when OpenSSL binary is missing", async () => {
+    fsMock.existsSync.mockReturnValue(false);
+    const enoentError: any = new Error("spawnSync openssl ENOENT");
+    enoentError.code = "ENOENT";
+    childProcessMock.execFileSync.mockImplementation(() => {
+      throw enoentError;
+    });
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    ensureTlsCredentials(baseConfig);
+
+    expect(processMock.exit).toHaveBeenCalledWith(1);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("OpenSSL must be installed"),
+    );
+  });
+
+  it("handles generic openssl execution error", async () => {
+    fsMock.existsSync.mockReturnValue(false);
+    childProcessMock.execFileSync.mockImplementation(() => {
+      throw new Error("Command failed");
+    });
+
+    const { ensureTlsCredentials } = await import("./tls.js");
+    ensureTlsCredentials(baseConfig);
+
+    expect(processMock.exit).toHaveBeenCalledWith(1);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining("Error generating TLS certificate with OpenSSL"),
+    );
+  });
+});