Fail fast on invalid stackflow-node boolean env config

Author: warmidris

README.md

@@ -281,6 +281,9 @@ exposure. Use a public bind only with hardened ingress controls.
 invalid values.
 `STACKFLOW_NODE_MAX_RECENT_EVENTS` is clamped to at least `1` so event pruning
 cannot be disabled accidentally via negative values.
+Boolean env vars accept `true/false`, `1/0`, `yes/no`, and `on/off`
+(case-insensitive); invalid boolean text now fails fast to prevent silent
+misconfiguration.
 Observer ingress controls:
 
 - `STACKFLOW_NODE_OBSERVER_LOCALHOST_ONLY` defaults to `true` and restricts

server/src/config.ts

@@ -72,7 +72,7 @@ function parsePrincipalCsv(value: unknown): string[] {
   return [...new Set(principals)];
 }
 
-function parseBoolean(value: unknown, fallback: boolean): boolean {
+function parseBoolean(value: unknown, fallback: boolean, key: string): boolean {
   if (value === undefined || value === null || value === '') {
     return fallback;
   }
@@ -85,7 +85,7 @@ function parseBoolean(value: unknown, fallback: boolean): boolean {
     return false;
   }
 
-  return fallback;
+  throw new Error(`${key} must be a boolean (true/false, 1/0, yes/no, on/off)`);
 }
 
 function normalizeBaseUrl(input: string): string {
@@ -172,7 +172,11 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): StackflowNodeC
     port: parsePort(env.STACKFLOW_NODE_PORT),
     dbFile,
     maxRecentEvents: parseMaxRecentEvents(env.STACKFLOW_NODE_MAX_RECENT_EVENTS),
-    logRawEvents: parseBoolean(env.STACKFLOW_NODE_LOG_RAW_EVENTS, false),
+    logRawEvents: parseBoolean(
+      env.STACKFLOW_NODE_LOG_RAW_EVENTS,
+      false,
+      'STACKFLOW_NODE_LOG_RAW_EVENTS',
+    ),
     watchedContracts: parseCsv(env.STACKFLOW_CONTRACTS),
     watchedPrincipals: parsePrincipalCsv(env.STACKFLOW_NODE_PRINCIPALS),
     stacksNetwork: parseNetwork(env.STACKS_NETWORK),
@@ -207,6 +211,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): StackflowNodeC
     disputeOnlyBeneficial: parseBoolean(
       env.STACKFLOW_NODE_DISPUTE_ONLY_BENEFICIAL,
       false,
+      'STACKFLOW_NODE_DISPUTE_ONLY_BENEFICIAL',
     ),
     peerWriteRateLimitPerMinute: Math.max(
       0,
@@ -218,22 +223,30 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): StackflowNodeC
     trustProxy: parseBoolean(
       env.STACKFLOW_NODE_TRUST_PROXY,
       DEFAULT_TRUST_PROXY,
+      'STACKFLOW_NODE_TRUST_PROXY',
     ),
     observerLocalhostOnly: parseBoolean(
       env.STACKFLOW_NODE_OBSERVER_LOCALHOST_ONLY,
       DEFAULT_OBSERVER_LOCALHOST_ONLY,
+      'STACKFLOW_NODE_OBSERVER_LOCALHOST_ONLY',
     ),
     observerAllowedIps: parseCsv(env.STACKFLOW_NODE_OBSERVER_ALLOWED_IPS),
     adminReadToken: env.STACKFLOW_NODE_ADMIN_READ_TOKEN?.trim() || null,
     adminReadLocalhostOnly: parseBoolean(
       env.STACKFLOW_NODE_ADMIN_READ_LOCALHOST_ONLY,
       DEFAULT_ADMIN_READ_LOCALHOST_ONLY,
+      'STACKFLOW_NODE_ADMIN_READ_LOCALHOST_ONLY',
     ),
     redactSensitiveReadData: parseBoolean(
       env.STACKFLOW_NODE_REDACT_SENSITIVE_READ_DATA,
       DEFAULT_REDACT_SENSITIVE_READ_DATA,
+      'STACKFLOW_NODE_REDACT_SENSITIVE_READ_DATA',
+    ),
+    forwardingEnabled: parseBoolean(
+      env.STACKFLOW_NODE_FORWARDING_ENABLED,
+      false,
+      'STACKFLOW_NODE_FORWARDING_ENABLED',
     ),
-    forwardingEnabled: parseBoolean(env.STACKFLOW_NODE_FORWARDING_ENABLED, false),
     forwardingMinFee: Math.max(
       0,
       parseInteger(env.STACKFLOW_NODE_FORWARDING_MIN_FEE, 0),
@@ -248,6 +261,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): StackflowNodeC
     forwardingAllowPrivateDestinations: parseBoolean(
       env.STACKFLOW_NODE_FORWARDING_ALLOW_PRIVATE_DESTINATIONS,
       false,
+      'STACKFLOW_NODE_FORWARDING_ALLOW_PRIVATE_DESTINATIONS',
     ),
     forwardingAllowedBaseUrls: parseCsv(
       env.STACKFLOW_NODE_FORWARDING_ALLOWED_BASE_URLS,

tests/stackflow-node-config.test.ts

@@ -67,6 +67,22 @@ describe('stackflow-node config parsing', () => {
     expect(config.forwardingRevealRetryMaxAttempts).toBe(1);
   });
 
+  it('parses boolean aliases and rejects invalid boolean text', () => {
+    const config = loadConfig({
+      STACKFLOW_NODE_FORWARDING_ENABLED: 'YeS',
+      STACKFLOW_NODE_TRUST_PROXY: '0',
+    });
+
+    expect(config.forwardingEnabled).toBe(true);
+    expect(config.trustProxy).toBe(false);
+
+    expect(() =>
+      loadConfig({
+        STACKFLOW_NODE_FORWARDING_ENABLED: 'maybe',
+      }),
+    ).toThrow(/STACKFLOW_NODE_FORWARDING_ENABLED must be a boolean/);
+  });
+
   it('rejects stackflow-node ports outside the TCP range', () => {
     expect(() =>
       loadConfig({