shadow-claw 1.24.1 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadow-claw",
-  "version": "1.24.1",
+  "version": "1.25.0",
   "type": "module",
   "license": "AGPL-3.0",
   "description": "Browser-native personal AI assistant.",

package/src/core/utils/initControlPlane.ts

@@ -334,9 +334,11 @@ export async function executeClientControlCommand(
       }
 
       const { BackupController } = await import("../backup-controller.js");
+
       const backupCtrl = new BackupController({
         clientId,
         token: args.token,
+        serverBaseUrl: getControlPlaneServerUrl().httpUrl,
         fileEnumerator: () => collectFiles(groupDir),
         fileReader: (filePath) => readFile(filePath),
       });

package/src/server/config.test.ts

@@ -111,4 +111,53 @@ describe("config", () => {
 
     expect(config.rootPath).toContain("public");
   });
+
+  it("defaults https to false and provides default sslDir", async () => {
+    const { parseConfig } = await import("./config.js");
+    const config = parseConfig();
+
+    expect(config.https).toBe(false);
+    expect(config.certPath).toBeUndefined();
+    expect(config.keyPath).toBeUndefined();
+    expect(config.sslDir).toContain(".cache/tls");
+  });
+
+  it("parses HTTPS options from CLI flags", async () => {
+    commanderMock.Command().opts.mockReturnValue({
+      https: true,
+      cert: "/custom/cert.pem",
+      key: "/custom/key.pem",
+      sslDir: "/custom/ssl",
+      corsAllowOrigin: [],
+    });
+
+    const { parseConfig } = await import("./config.js");
+    const config = parseConfig();
+
+    expect(config.https).toBe(true);
+    expect(config.certPath).toBe("/custom/cert.pem");
+    expect(config.keyPath).toBe("/custom/key.pem");
+    expect(config.sslDir).toBe("/custom/ssl");
+  });
+
+  it("parses HTTPS options from environment variables", async () => {
+    processMock.env.SHADOWCLAW_HTTPS = "1";
+    processMock.env.SHADOWCLAW_TLS_CERT = "/env/cert.pem";
+    processMock.env.SHADOWCLAW_TLS_KEY = "/env/key.pem";
+    processMock.env.SHADOWCLAW_SSL_DIR = "env-ssl";
+
+    const { parseConfig } = await import("./config.js");
+    const config = parseConfig();
+
+    expect(config.https).toBe(true);
+    expect(config.certPath).toBe("/env/cert.pem");
+    expect(config.keyPath).toBe("/env/key.pem");
+    expect(config.sslDir).toBe(
+      (await import("node:path")).default.resolve(
+        config.rootPath,
+        "..",
+        "env-ssl",
+      ),
+    );
+  });
 });

package/src/server/config.ts

@@ -27,6 +27,10 @@ export interface ServerConfig {
    */
   controlToken?: string;
   allowPrivateProxy: boolean;
+  https: boolean;
+  certPath?: string;
+  keyPath?: string;
+  sslDir: string;
 }
 
 export function parseConfig(): ServerConfig {
@@ -67,6 +71,13 @@ export function parseConfig(): ServerConfig {
     .option(
       "--control-token <token>",
       "Secret token for control-plane authentication",
+    )
+    .option("--https", "Enable HTTPS dev server", false)
+    .option("--cert <path>", "Path to existing TLS certificate file")
+    .option("--key <path>", "Path to existing TLS private key file")
+    .option(
+      "--ssl-dir <path>",
+      "Directory for TLS certificate generation/storage",
     );
 
   program.parse();
@@ -178,6 +189,38 @@ export function parseConfig(): ServerConfig {
     ? options.controlToken.trim()
     : envControlToken || undefined;
 
+  // HTTPS & TLS logic
+  const https =
+    Boolean(options.https) ||
+    ["1", "true", "yes"].includes(
+      (env.SHADOWCLAW_HTTPS || "").toLowerCase().trim(),
+    );
+
+  const envCert = (env.SHADOWCLAW_TLS_CERT || env.SHADOWCLAW_CERT || "").trim();
+  const certPath = options.cert
+    ? path.resolve(options.cert)
+    : envCert
+      ? path.resolve(envCert)
+      : undefined;
+
+  const envKey = (env.SHADOWCLAW_TLS_KEY || env.SHADOWCLAW_KEY || "").trim();
+  const keyPath = options.key
+    ? path.resolve(options.key)
+    : envKey
+      ? path.resolve(envKey)
+      : undefined;
+
+  const envSslDir = (
+    env.SHADOWCLAW_SSL_DIR ||
+    env.SHADOWCLAW_TLS_DIR ||
+    ""
+  ).trim();
+  const sslDir = options.sslDir
+    ? path.resolve(options.sslDir)
+    : envSslDir
+      ? path.resolve(projectRoot, envSslDir)
+      : path.resolve(databaseDir, "..", ".cache", "tls");
+
   return {
     port,
     bindHost,
@@ -189,5 +232,9 @@ export function parseConfig(): ServerConfig {
     databaseDir,
     controlToken,
     allowPrivateProxy,
+    https,
+    certPath,
+    keyPath,
+    sslDir,
   };
 }

package/src/server/control-plane.ts

@@ -7,6 +7,7 @@
  */
 
 import http from "node:http";
+import https from "node:https";
 import { URL } from "node:url";
 import { WebSocketServer, WebSocket } from "ws";
 import type { Express, Request, Response, NextFunction } from "express";
@@ -29,7 +30,7 @@ import type {
 } from "./control-plane-types.js";
 
 export interface ControlPlaneOptions {
-  httpServer: http.Server;
+  httpServer: http.Server | https.Server;
   app?: Express;
   token?: string;
   heartbeatTimeoutMs?: number;

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/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,7 +29,9 @@ 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,
@@ -49,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(
@@ -72,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"),
+    );
+  });
+});