Fail fast when HTTPS is requested but certificates are missing (#1640)

- Add ServerConfigError and throw when cert files are missing
- Catch ServerConfigError in node-server.ts with a clean fatal log
- Fix docker-entrypoint.sh: add set -e, fix bracket syntax, fix duplicate check
- Fix csr.conf trailing space so sed substitution matches
- Add docker-entrypoint.sh integration tests
- Add config-pipeline integration tests (shell → dotenv → Zod → server config)
- Add ServerConfigError message content tests
- Add grep-safe .env output tests for process-environment.sh
- Add test for openssl failure propagation in setup-ssl
- Read real cert/csr config files in setup-ssl tests

Closes #1634

Author: kmcginnes

.gitignore

@@ -8,3 +8,6 @@
 
 # TypeScript build cache manifests
 *.tsbuildinfo
+
+# Local planning docs
+plans/

docker-entrypoint.sh

@@ -1,11 +1,18 @@
 #!/bin/sh
+set -e
 
 ./process-environment.sh
 
 CONFIGURATION_FOLDER_PATH=${CONFIGURATION_FOLDER_PATH:-"./packages/graph-explorer/"}
-PROXY_SERVER_HTTPS_CONNECTION_VALUE=$(grep -e 'PROXY_SERVER_HTTPS_CONNECTION' $CONFIGURATION_FOLDER_PATH/.env | cut -d "=" -f 2)
 
-if [ -n "$PROXY_SERVER_HTTPS_CONNECTION_VALUE" ] && [ "$PROXY_SERVER_HTTPS_CONNECTION_VALUE" == "true" ]; then
+if [ ! -f "$CONFIGURATION_FOLDER_PATH/.env" ]; then
+    echo "Expected .env file not found at $CONFIGURATION_FOLDER_PATH/.env" >&2
+    exit 1
+fi
+
+PROXY_SERVER_HTTPS_CONNECTION_VALUE=$(grep -e '^PROXY_SERVER_HTTPS_CONNECTION=' "$CONFIGURATION_FOLDER_PATH/.env" | cut -d "=" -f 2 || true)
+
+if [ -n "$PROXY_SERVER_HTTPS_CONNECTION_VALUE" ] && [ "$PROXY_SERVER_HTTPS_CONNECTION_VALUE" = "true" ]; then
     CERT_DIR=/graph-explorer/packages/graph-explorer-proxy-server/cert-info \
         HOST="$HOST" \
         ./setup-ssl.sh
@@ -14,4 +21,5 @@ else
 fi
 
 echo "Starting graph explorer..."
+# Stubbed in tests — update docker-entrypoint.test.ts if changing
 cd /graph-explorer/packages/graph-explorer-proxy-server && NODE_ENV=production node dist/node-server.js

packages/graph-explorer-proxy-server/cert-info/csr.conf

@@ -17,4 +17,4 @@ subjectAltName = @alt_names
 
 [ alt_names ]
 # Filled in by Dockerfile
-DNS.1 =
+DNS.1 = 

packages/graph-explorer-proxy-server/src/config-pipeline.test.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from "child_process";
+import dotenv from "dotenv";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+import { parseEnvironmentValues } from "./env.js";
+import { proxyServerRoot } from "./paths.js";
+import { resolveServerConfig, ServerConfigError } from "./server-config.js";
+
+const expectedKeyPath = path.join(proxyServerRoot, "cert-info/server.key");
+const expectedCertPath = path.join(proxyServerRoot, "cert-info/server.crt");
+
+const processEnvScriptPath = path.resolve(
+  import.meta.dirname,
+  "../../../process-environment.sh",
+);
+
+function runPipeline(
+  workDir: string,
+  env: Record<string, string> = {},
+  presetEnvVars: Record<string, string> = {},
+) {
+  const configFolder =
+    env.CONFIGURATION_FOLDER_PATH ?? "./packages/graph-explorer/";
+  const resolvedConfigFolder = path.resolve(workDir, configFolder);
+  fs.mkdirSync(resolvedConfigFolder, { recursive: true });
+
+  // Pre-seed .env with vars the shell script doesn't write
+  if (Object.keys(presetEnvVars).length > 0) {
+    const lines = Object.entries(presetEnvVars)
+      .map(([k, v]) => `${k}=${v}`)
+      .join("\n");
+    fs.writeFileSync(path.join(resolvedConfigFolder, ".env"), lines + "\n");
+  }
+
+  execFileSync("sh", [processEnvScriptPath], {
+    cwd: workDir,
+    env: { ...env, PATH: process.env.PATH },
+  });
+
+  const envFilePath = path.join(resolvedConfigFolder, ".env");
+  const envFileContent = fs.readFileSync(envFilePath, "utf-8");
+  const parsed = dotenv.parse(envFileContent);
+  return parseEnvironmentValues(parsed);
+}
+
+describe("config pipeline: shell → dotenv → Zod → server config", () => {
+  let workDir: string;
+
+  beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "ge-pipeline-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("HTTPS enabled by default flows through to server config", () => {
+    const env = runPipeline(workDir);
+    expect(env.PROXY_SERVER_HTTPS_CONNECTION).toBe(true);
+
+    vi.spyOn(fs, "existsSync").mockImplementation(
+      p => p === expectedKeyPath || p === expectedCertPath,
+    );
+    const config = resolveServerConfig(env);
+    expect(config.useHttps).toBe(true);
+    expect(config.port).toBe(443);
+  });
+
+  it("HTTPS disabled flows through to HTTP config", () => {
+    const env = runPipeline(workDir, {
+      PROXY_SERVER_HTTPS_CONNECTION: "false",
+    });
+
+    const config = resolveServerConfig(env);
+    expect(config.useHttps).toBe(false);
+    expect(config.port).toBe(80);
+  });
+
+  it("Neptune Notebook forces HTTPS off", () => {
+    const env = runPipeline(workDir, { NEPTUNE_NOTEBOOK: "true" });
+
+    const config = resolveServerConfig(env);
+    expect(config.useHttps).toBe(false);
+  });
+
+  it("HTTPS enabled but certs missing throws ServerConfigError", () => {
+    const env = runPipeline(workDir);
+    expect(env.PROXY_SERVER_HTTPS_CONNECTION).toBe(true);
+
+    expect(() => resolveServerConfig(env)).toThrow(ServerConfigError);
+  });
+
+  it("custom HTTP port flows through", () => {
+    const env = runPipeline(
+      workDir,
+      { PROXY_SERVER_HTTPS_CONNECTION: "false" },
+      { PROXY_SERVER_HTTP_PORT: "8080" },
+    );
+
+    const config = resolveServerConfig(env);
+    expect(config.port).toBe(8080);
+  });
+});

packages/graph-explorer-proxy-server/src/docker-entrypoint.test.ts

@@ -0,0 +1,194 @@
+import { execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const originalScriptPath = path.resolve(
+  import.meta.dirname,
+  "../../../docker-entrypoint.sh",
+);
+
+function setupWorkDir() {
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "ge-entrypoint-test-"));
+  const configDir = path.join(workDir, "packages", "graph-explorer");
+  fs.mkdirSync(configDir, { recursive: true });
+
+  // Create modified entrypoint with stubbed last line
+  const script = fs.readFileSync(originalScriptPath, "utf-8");
+  const serverStartLine =
+    "cd /graph-explorer/packages/graph-explorer-proxy-server && NODE_ENV=production node dist/node-server.js";
+  if (!script.includes(serverStartLine)) {
+    throw new Error(
+      "docker-entrypoint.sh no longer contains the expected server start line. Update the test stub.",
+    );
+  }
+  const modifiedScript = script.replace(
+    serverStartLine,
+    'echo "SERVER_STARTED"',
+  );
+  const scriptPath = path.join(workDir, "docker-entrypoint.sh");
+  fs.writeFileSync(scriptPath, modifiedScript, { mode: 0o755 });
+
+  // Default stubs
+  fs.writeFileSync(
+    path.join(workDir, "process-environment.sh"),
+    "#!/bin/sh\nexit 0\n",
+    { mode: 0o755 },
+  );
+  fs.writeFileSync(
+    path.join(workDir, "setup-ssl.sh"),
+    '#!/bin/sh\ntouch ./ssl-called\necho "$HOST" > ./host-value\n',
+    { mode: 0o755 },
+  );
+
+  return { workDir, configDir, scriptPath };
+}
+
+function writeEnv(configDir: string, content: string) {
+  fs.writeFileSync(path.join(configDir, ".env"), content);
+}
+
+function runScript(
+  workDir: string,
+  scriptPath: string,
+  env: Record<string, string> = {},
+): { exitCode: number; stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync("sh", [scriptPath], {
+      cwd: workDir,
+      env: { PATH: process.env.PATH, ...env },
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { exitCode: 0, stdout, stderr: "" };
+  } catch (error: unknown) {
+    const e = error as { status: number; stdout: string; stderr: string };
+    return {
+      exitCode: e.status,
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? "",
+    };
+  }
+}
+
+describe("docker-entrypoint.sh", () => {
+  let workDir: string;
+  let configDir: string;
+  let scriptPath: string;
+
+  beforeEach(() => {
+    ({ workDir, configDir, scriptPath } = setupWorkDir());
+  });
+
+  afterEach(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  it("fails when .env file is missing", () => {
+    // Don't write any .env file
+
+    const { exitCode, stderr } = runScript(workDir, scriptPath);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain(".env");
+  });
+
+  it("set -e propagates process-environment.sh failure", () => {
+    fs.writeFileSync(
+      path.join(workDir, "process-environment.sh"),
+      "#!/bin/sh\nexit 1\n",
+      { mode: 0o755 },
+    );
+
+    const { exitCode } = runScript(workDir, scriptPath);
+    expect(exitCode).not.toBe(0);
+  });
+
+  it("set -e propagates setup-ssl.sh failure", () => {
+    writeEnv(configDir, "PROXY_SERVER_HTTPS_CONNECTION=true\n");
+    fs.writeFileSync(
+      path.join(workDir, "setup-ssl.sh"),
+      "#!/bin/sh\nexit 1\n",
+      { mode: 0o755 },
+    );
+
+    const { exitCode, stdout } = runScript(workDir, scriptPath);
+    expect(exitCode).not.toBe(0);
+    expect(stdout).not.toContain("Starting graph explorer");
+  });
+
+  it("calls setup-ssl.sh when HTTPS is true", () => {
+    writeEnv(configDir, "PROXY_SERVER_HTTPS_CONNECTION=true\n");
+
+    const { exitCode } = runScript(workDir, scriptPath, {
+      HOST: "localhost",
+    });
+
+    expect(exitCode).toBe(0);
+    expect(fs.existsSync(path.join(workDir, "ssl-called"))).toBe(true);
+  });
+
+  it("skips setup-ssl.sh when HTTPS is false", () => {
+    writeEnv(configDir, "PROXY_SERVER_HTTPS_CONNECTION=false\n");
+
+    const { exitCode, stdout } = runScript(workDir, scriptPath);
+
+    expect(exitCode).toBe(0);
+    expect(fs.existsSync(path.join(workDir, "ssl-called"))).toBe(false);
+    expect(stdout).toContain("SSL disabled");
+  });
+
+  it("skips setup-ssl.sh when PROXY_SERVER_HTTPS_CONNECTION is absent", () => {
+    writeEnv(configDir, "LOG_LEVEL=info\n");
+
+    const { exitCode, stdout } = runScript(workDir, scriptPath);
+
+    expect(exitCode).toBe(0);
+    expect(fs.existsSync(path.join(workDir, "ssl-called"))).toBe(false);
+    expect(stdout).toContain("SSL disabled");
+  });
+
+  it("grep ignores commented-out lines", () => {
+    writeEnv(configDir, "# PROXY_SERVER_HTTPS_CONNECTION=true\n");
+
+    const { exitCode } = runScript(workDir, scriptPath);
+
+    expect(exitCode).toBe(0);
+    expect(fs.existsSync(path.join(workDir, "ssl-called"))).toBe(false);
+  });
+
+  it("grep ignores similarly-named variables", () => {
+    writeEnv(configDir, "GRAPH_EXP_PROXY_SERVER_HTTPS_CONNECTION=true\n");
+
+    const { exitCode } = runScript(workDir, scriptPath);
+
+    expect(exitCode).toBe(0);
+    expect(fs.existsSync(path.join(workDir, "ssl-called"))).toBe(false);
+  });
+
+  it("passes HOST to setup-ssl.sh", () => {
+    writeEnv(configDir, "PROXY_SERVER_HTTPS_CONNECTION=true\n");
+
+    runScript(workDir, scriptPath, { HOST: "my-test-host" });
+
+    const hostValue = fs
+      .readFileSync(path.join(workDir, "host-value"), "utf-8")
+      .trim();
+    expect(hostValue).toBe("my-test-host");
+  });
+
+  it("uses custom CONFIGURATION_FOLDER_PATH", () => {
+    const customDir = path.join(workDir, "custom-config");
+    fs.mkdirSync(customDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(customDir, ".env"),
+      "PROXY_SERVER_HTTPS_CONNECTION=false\n",
+    );
+
+    const { exitCode, stdout } = runScript(workDir, scriptPath, {
+      CONFIGURATION_FOLDER_PATH: customDir,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("SSL disabled");
+  });
+});

packages/graph-explorer-proxy-server/src/node-server.ts

@@ -6,7 +6,7 @@ import { parseEnvironmentValues } from "./env.js";
 import { handleError } from "./error-handler.js";
 import { createLogger } from "./logging.js";
 import { clientRoot, isDirectory } from "./paths.js";
-import { resolveServerConfig } from "./server-config.js";
+import { resolveServerConfig, ServerConfigError } from "./server-config.js";
 import { createServer } from "./server.js";
 
 // Load .env files into process.env before parsing
@@ -27,6 +27,17 @@ const env = parseEnvironmentValues(process.env);
 const logger = createLogger(env);
 logger.info("Parsed environment values: %o", env);
 
+let serverConfig;
+try {
+  serverConfig = resolveServerConfig(env);
+} catch (error) {
+  if (error instanceof ServerConfigError) {
+    logger.fatal(error.message);
+    process.exit(1);
+  }
+  throw error;
+}
+
 const {
   port,
   baseUrl,
@@ -35,7 +46,7 @@ const {
   staticFilesVirtualPath,
   staticFilesPath,
   useHttps,
-} = resolveServerConfig(env);
+} = serverConfig;
 
 const app = createApp({ configPath, staticFilesVirtualPath, staticFilesPath });