feat(env): hard-fail at startup when NODE_ENV=production + DB_PASSWORD empty (#119)

A missing DB_PASSWORD in production is operator error: the pod
starts, /healthz reports degraded (db: down), and load balancers
that key off http-200 from /healthz risk routing traffic to a
broken process anyway. Better to refuse to start so systemd/k8s
catch the misconfiguration before traffic flips.

Behavior:

- NODE_ENV unset / development / test → warn + keep going. Matches
  the existing scaffolding/test ergonomics (the test suite itself
  runs with empty DB_PASSWORD).
- NODE_ENV=production with empty DB_PASSWORD → log to stderr and
  `process.exit(1)`. systemd: unit fails. k8s: pod CrashLoopBackoff.
  Either way, traffic doesn't reach the broken process.

Tests
- New `tests/unit/env-validation.test.js` spawns child processes
  in each of the four matrix slots (env unset / dev / prod-empty /
  prod-set) and asserts exit code + stderr substring.
- Full suite: 484 pass / 9 skip (was 480/9 — +4 new cases).

Co-authored-by: Aaron K. Clark <akclark@thenetwerk.net>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

app/config/env.js

@@ -22,6 +22,23 @@ const env = {
 };
 
 if (!env.password) {
+    // In development, an empty password is normal (running tests
+    // without a live DB, scaffolding a fresh repo, etc.) — warn and
+    // keep going.
+    //
+    // In production, an empty password means the operator forgot to
+    // wire credentials. We hard-fail here rather than at first DB
+    // query so the misconfiguration surfaces during process startup
+    // (where systemd/k8s catch it and won't flip traffic), not after
+    // the load balancer has already sent the pod 200/health checks.
+    if (process.env.NODE_ENV === 'production') {
+        console.error(
+            '[env] DB_PASSWORD is empty and NODE_ENV=production. ' +
+            'Refusing to start. Set DB_PASSWORD via your process manager, ' +
+            'container orchestrator, or shell.'
+        );
+        process.exit(1);
+    }
     console.warn(
         '[env] DB_PASSWORD is empty. Set it in .env (development) or via your ' +
         'environment (production). Connections will likely fail without it.'

tests/unit/env-validation.test.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Aaron K. Clark
+//
+// Tests for `app/config/env.js` empty-password handling. The dev
+// case warns and lets the process keep going (useful for tests +
+// scaffolding); the prod case hard-fails so systemd/k8s catch the
+// misconfiguration before traffic flips.
+
+import { describe, test, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const ENV_MODULE = resolve(__dirname, '../../app/config/env.js');
+
+function run(env) {
+    return spawnSync(process.execPath, ['-e', `require(${JSON.stringify(ENV_MODULE)})`], {
+        // Force the child to ignore the parent's DB_PASSWORD so we
+        // can test the empty-password path in isolation.
+        env: { PATH: process.env.PATH || '', ...env },
+        encoding: 'utf8',
+    });
+}
+
+describe('env validation: empty DB_PASSWORD', () => {
+    test('NODE_ENV unset → warn + exit 0 (dev/test ergonomics)', () => {
+        const r = run({});
+        expect(r.status).toBe(0);
+        expect(r.stderr).toMatch(/DB_PASSWORD is empty/i);
+        expect(r.stderr).not.toMatch(/Refusing to start/i);
+    });
+
+    test('NODE_ENV=development → warn + exit 0', () => {
+        const r = run({ NODE_ENV: 'development' });
+        expect(r.status).toBe(0);
+        expect(r.stderr).toMatch(/DB_PASSWORD is empty/i);
+    });
+
+    test('NODE_ENV=production → hard-fail with exit 1', () => {
+        const r = run({ NODE_ENV: 'production' });
+        expect(r.status).toBe(1);
+        expect(r.stderr).toMatch(/NODE_ENV=production/);
+        expect(r.stderr).toMatch(/Refusing to start/i);
+    });
+
+    test('NODE_ENV=production + DB_PASSWORD set → no warning, exit 0', () => {
+        const r = run({ NODE_ENV: 'production', DB_PASSWORD: 'real-password' });
+        expect(r.status).toBe(0);
+        expect(r.stderr).not.toMatch(/DB_PASSWORD/);
+    });
+});