feat: validate environment variables at startup with a typed config

Author: rubenhensen

package-lock.json

@@ -56,7 +56,8 @@
 		"@privacybydesign/yivi-web": "^1.0.1",
 		"pino": "^10.3.1",
 		"sass": "^1.100.0",
-		"svelte-i18n": "^4.0.1"
+		"svelte-i18n": "^4.0.1",
+		"zod": "^4.4.3"
 	},
 	"overrides": {
 		"@sveltejs/kit": {

package.json

@@ -1,5 +1,5 @@
 import { dev } from '$app/environment';
-import { env } from '$env/dynamic/private';
+import { config } from '$lib/server/config';
 
 export type FeatureFlag =
 	| 'pricingPage'
@@ -30,17 +30,17 @@ export const FLAG_LABELS: Record<FeatureFlag, string> = {
 
 /** Flags from environment variables (immutable, set at startup). */
 const envFlags: Record<FeatureFlag, boolean> = {
-	pricingPage: env.FF_PRICING_PAGE === 'true',
-	registration: env.FF_REGISTRATION === 'true',
-	portalApiKeys: env.FF_PORTAL_API_KEYS === 'true',
-	portalOrgInfo: env.FF_PORTAL_ORG_INFO === 'true',
-	portalEmailLog: env.FF_PORTAL_EMAIL_LOG === 'true',
-	portalDns: env.FF_PORTAL_DNS === 'true',
-	portalMembers: env.FF_PORTAL_MEMBERS === 'true',
-	adminPanel: env.FF_ADMIN_PANEL === 'true',
-	adminOrgStatus: env.FF_ADMIN_ORG_STATUS === 'true',
-	adminAuditLog: env.FF_ADMIN_AUDIT_LOG === 'true',
-	adminImpersonation: env.FF_ADMIN_IMPERSONATION === 'true'
+	pricingPage: config.FF_PRICING_PAGE,
+	registration: config.FF_REGISTRATION,
+	portalApiKeys: config.FF_PORTAL_API_KEYS,
+	portalOrgInfo: config.FF_PORTAL_ORG_INFO,
+	portalEmailLog: config.FF_PORTAL_EMAIL_LOG,
+	portalDns: config.FF_PORTAL_DNS,
+	portalMembers: config.FF_PORTAL_MEMBERS,
+	adminPanel: config.FF_ADMIN_PANEL,
+	adminOrgStatus: config.FF_ADMIN_ORG_STATUS,
+	adminAuditLog: config.FF_ADMIN_AUDIT_LOG,
+	adminImpersonation: config.FF_ADMIN_IMPERSONATION
 };
 
 /** Runtime overrides — only used in dev mode. */

src/lib/feature-flags.ts

@@ -1,8 +1,8 @@
-import { env } from '$env/dynamic/private';
+import { config } from '$lib/server/config';
 
-export const YIVI_SERVER_URL = env.YIVI_SERVER_URL ?? 'http://localhost:8088';
-export const YIVI_SERVER_TOKEN = env.YIVI_SERVER_TOKEN ?? '';
-const USE_DEMO_ATTRS = env.YIVI_DEMO_ATTRIBUTES === 'true';
+export const YIVI_SERVER_URL = config.YIVI_SERVER_URL;
+export const YIVI_SERVER_TOKEN = config.YIVI_SERVER_TOKEN;
+const USE_DEMO_ATTRS = config.YIVI_DEMO_ATTRIBUTES;
 
 // Production attributes (pbdf scheme)
 const PROD_ATTR = {

src/lib/server/auth/yivi.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { env } from '$env/dynamic/private';
+
+// Env booleans are strings; match the app's existing `=== 'true'` semantics
+// exactly (only the literal "true" is truthy; unset → false).
+const boolFromEnv = z.preprocess((v) => v === 'true', z.boolean());
+
+// Single source of truth for the server's environment configuration. Validated
+// once at startup so a missing/mistyped var fails fast with a clear message,
+// rather than surfacing at the first use of each value.
+export const configSchema = z.object({
+	DATABASE_URL: z.string().min(1),
+
+	// Yivi / IRMA. Injected via docker-compose / k8s in real environments.
+	YIVI_SERVER_URL: z.string().min(1).default('http://localhost:8088'),
+	YIVI_SERVER_TOKEN: z.string().default(''),
+	YIVI_DEMO_ATTRIBUTES: boolFromEnv,
+
+	// Feature flags (FF_*).
+	FF_PRICING_PAGE: boolFromEnv,
+	FF_REGISTRATION: boolFromEnv,
+	FF_PORTAL_API_KEYS: boolFromEnv,
+	FF_PORTAL_ORG_INFO: boolFromEnv,
+	FF_PORTAL_EMAIL_LOG: boolFromEnv,
+	FF_PORTAL_DNS: boolFromEnv,
+	FF_PORTAL_MEMBERS: boolFromEnv,
+	FF_ADMIN_PANEL: boolFromEnv,
+	FF_ADMIN_ORG_STATUS: boolFromEnv,
+	FF_ADMIN_AUDIT_LOG: boolFromEnv,
+	FF_ADMIN_IMPERSONATION: boolFromEnv
+});
+
+export type Config = z.infer<typeof configSchema>;
+
+function loadConfig(): Config {
+	const parsed = configSchema.safeParse(env);
+	if (!parsed.success) {
+		const issues = parsed.error.issues
+			.map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
+			.join('\n');
+		throw new Error(`Invalid environment configuration:\n${issues}`);
+	}
+	return parsed.data;
+}
+
+export const config = loadConfig();

src/lib/server/config.ts

@@ -2,19 +2,19 @@ import { drizzle } from 'drizzle-orm/postgres-js';
 import postgres from 'postgres';
 import * as schema from './schema';
 import { env } from '$env/dynamic/private';
-
-if (!env.DATABASE_URL) throw new Error('DATABASE_URL is not set');
+import { config } from '$lib/server/config';
 
 // Parse a positive-integer env var, falling back to a default when unset/invalid.
 export function intFromEnv(value: string | undefined, fallback: number): number {
 	const parsed = Number(value);
 	return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
 
-// Explicit pool sizing + timeouts. postgres.js otherwise leaves connect/idle
-// timeouts effectively unbounded, and `max` should be sized against Postgres
-// `max_connections` across replicas — so make it tunable via env.
-const client = postgres(env.DATABASE_URL, {
+// DATABASE_URL is validated in config (fails fast at startup if unset). Pool
+// sizing/timeouts stay tunable here via env. postgres.js otherwise leaves
+// connect/idle timeouts effectively unbounded, and `max` should be sized
+// against Postgres `max_connections` across replicas.
+const client = postgres(config.DATABASE_URL, {
 	max: intFromEnv(env.DB_POOL_MAX, 10),
 	idle_timeout: intFromEnv(env.DB_IDLE_TIMEOUT, 20), // seconds
 	connect_timeout: intFromEnv(env.DB_CONNECT_TIMEOUT, 10), // seconds

src/lib/server/db/index.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// Importing the config module runs validation against the real env at load time;
+// give it a valid DATABASE_URL so the import doesn't throw, then exercise the
+// schema directly with explicit inputs.
+vi.mock('$env/dynamic/private', () => ({
+	env: { DATABASE_URL: 'postgres://user:pass@localhost:5432/db' }
+}));
+
+import { configSchema } from '$lib/server/config';
+
+describe('configSchema', () => {
+	it('applies sensible defaults for a minimal valid env', () => {
+		const c = configSchema.parse({ DATABASE_URL: 'postgres://x' });
+		expect(c.YIVI_SERVER_URL).toBe('http://localhost:8088');
+		expect(c.YIVI_SERVER_TOKEN).toBe('');
+		expect(c.YIVI_DEMO_ATTRIBUTES).toBe(false);
+		expect(c.FF_ADMIN_PANEL).toBe(false);
+	});
+
+	it('coerces only the exact string "true" to boolean true', () => {
+		const c = configSchema.parse({
+			DATABASE_URL: 'postgres://x',
+			YIVI_DEMO_ATTRIBUTES: 'true',
+			FF_ADMIN_PANEL: 'true',
+			FF_REGISTRATION: 'false',
+			FF_PORTAL_DNS: 'TRUE'
+		});
+		expect(c.YIVI_DEMO_ATTRIBUTES).toBe(true);
+		expect(c.FF_ADMIN_PANEL).toBe(true);
+		expect(c.FF_REGISTRATION).toBe(false);
+		expect(c.FF_PORTAL_DNS).toBe(false); // case-sensitive, matches legacy behaviour
+	});
+
+	it('rejects a missing or empty DATABASE_URL', () => {
+		expect(configSchema.safeParse({}).success).toBe(false);
+		expect(configSchema.safeParse({ DATABASE_URL: '' }).success).toBe(false);
+	});
+});