feat: overhaul config loading

app/routes/auth/oidc-callback.ts

@@ -3,7 +3,7 @@ import { count, eq } from 'drizzle-orm';
 import { createCookie, type LoaderFunctionArgs, redirect } from 'react-router';
 import { ulid } from 'ulidx';
 import type { LoadContext } from '~/server';
-import { HeadplaneConfig } from '~/server/config/schema';
+import { HeadplaneConfig } from '~/server/config/config-schema';
 import { users } from '~/server/db/schema';
 import { Roles } from '~/server/web/roles';
 import { FlowUser, finishAuthFlow, formatError } from '~/utils/oidc';

app/server/config/config-schema.ts

@@ -0,0 +1,177 @@
+import { type } from 'arktype';
+import DockerIntegration from './integration/docker';
+import KubernetesIntegration from './integration/kubernetes';
+import ProcIntegration from './integration/proc';
+import { deprecatedField } from './utils';
+
+export const pathSupportedKeys = [
+	'server.cookie_secret',
+	'oidc.client_secret',
+	'oidc.headscale_api_key',
+	'integration.agent.pre_authkey',
+] as const;
+
+const serverConfig = type({
+	host: 'string.ip = "127.0.0.1"',
+	port: 'number.integer = 3000',
+	data_path: 'string.lower = "/var/lib/headplane/"',
+
+	cookie_secret: '(32 <= string <= 32)',
+	cookie_secure: 'boolean = true',
+	cookie_domain: 'string.lower?',
+	cookie_max_age: 'number.integer = 86400',
+});
+
+const partialServerConfig = type({
+	host: 'string.ip?',
+	port: 'number.integer?',
+	data_path: 'string.lower?',
+
+	cookie_secret: '(32 <= string <= 32)?',
+	cookie_secure: 'boolean?',
+	cookie_domain: 'string.lower?',
+	cookie_max_age: 'number.integer?',
+});
+
+const headscaleConfig = type({
+	url: type('string.url').pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v)),
+	public_url: type('string.url')
+		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
+		.optional(),
+	config_path: 'string.lower?',
+	config_strict: 'boolean = true',
+	dns_records_path: 'string.lower?',
+	tls_cert_path: 'string.lower?',
+});
+
+const partialHeadscaleConfig = type({
+	url: type('string.url')
+		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
+		.optional(),
+	public_url: type('string.url')
+		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
+		.optional(),
+	config_path: 'string.lower?',
+	config_strict: 'boolean?',
+	dns_records_path: 'string.lower?',
+	tls_cert_path: 'string.lower?',
+});
+
+const oidcConfig = type({
+	issuer: 'string.url',
+	client_id: 'string',
+	client_secret: 'string',
+	headscale_api_key: 'string',
+	redirect_uri: 'string.url?',
+	disable_api_key_login: 'boolean = false',
+	scope: 'string = "openid email profile"',
+	extra_params: 'Record<string, string>?',
+	profile_picture_source: '"oidc" | "gravatar" = "oidc"',
+
+	authorization_endpoint: 'string.url?',
+	token_endpoint: 'string.url?',
+	userinfo_endpoint: 'string.url?',
+
+	// Old/deprecated options
+	user_storage_file: 'string.lower = "/var/lib/headplane/users.json"',
+	strict_validation: type('unknown').narrow(deprecatedField()).optional(),
+	token_endpoint_auth_method: type('unknown')
+		.narrow(deprecatedField())
+		.optional(),
+});
+
+const partialOidcConfig = type({
+	issuer: 'string.url?',
+	client_id: 'string?',
+	client_secret: 'string?',
+	headscale_api_key: 'string?',
+	redirect_uri: 'string.url?',
+	disable_api_key_login: 'boolean?',
+	scope: 'string?',
+	extra_params: 'Record<string, string>?',
+	profile_picture_source: '"oidc" | "gravatar"?',
+
+	authorization_endpoint: 'string.url?',
+	token_endpoint: 'string.url?',
+	userinfo_endpoint: 'string.url?',
+
+	// Old/deprecated options
+	user_storage_file: 'string.lower?',
+	strict_validation: type('unknown').narrow(deprecatedField()).optional(),
+	token_endpoint_auth_method: type('unknown')
+		.narrow(deprecatedField())
+		.optional(),
+});
+
+const agentConfig = type({
+	enabled: 'boolean',
+	host_name: 'string = "headplane-agent"',
+	pre_authkey: 'string',
+	cache_ttl: 'number.integer = 180000',
+	cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
+	executable_path: 'string = "/usr/libexec/headplane/agent"',
+	work_dir: 'string = "/var/lib/headplane/agent"',
+});
+
+const partialAgentConfig = type({
+	enabled: 'boolean?',
+	host_name: 'string?',
+	pre_authkey: 'string?',
+	cache_ttl: 'number.integer?',
+	cache_path: 'string?',
+	executable_path: 'string?',
+	work_dir: 'string?',
+});
+
+const integrationConfig = type({
+	docker: DockerIntegration.configSchema.full,
+	kubernetes: KubernetesIntegration.configSchema.full,
+	proc: ProcIntegration.configSchema.full,
+	agent: agentConfig.optional(),
+}).partial();
+
+export const partialIntegrationConfig = type({
+	docker: DockerIntegration.configSchema.partial,
+	kubernetes: KubernetesIntegration.configSchema.partial,
+	proc: ProcIntegration.configSchema.partial,
+	agent: partialAgentConfig.optional(),
+}).partial();
+
+export const headplaneConfig = type({
+	debug: 'boolean = false',
+	server: serverConfig,
+	headscale: headscaleConfig,
+	oidc: oidcConfig.optional(),
+	integration: integrationConfig.optional(),
+}).onDeepUndeclaredKey('delete');
+
+export const partialHeadplaneConfig = type({
+	debug: 'boolean?',
+	server: partialServerConfig.optional(),
+	headscale: partialHeadscaleConfig.optional(),
+	oidc: partialOidcConfig.optional(),
+	integration: partialIntegrationConfig.optional(),
+});
+
+export type HeadplaneConfig = typeof headplaneConfig.infer;
+export type PartialHeadplaneConfig = typeof partialHeadplaneConfig.infer;
+
+type DotNotationToObjects<
+	T extends string,
+	V,
+> = T extends `${infer K}.${infer Rest}`
+	? { [P in K]?: DotNotationToObjects<Rest, V> }
+	: { [P in `${T}_path`]?: V };
+
+type ObjectDeepMerge<T> = T extends object
+	? {
+			[K in keyof T]: T[K] extends object ? ObjectDeepMerge<T[K]> : T[K];
+		}
+	: T;
+
+type ConfigWithPathKeys = ObjectDeepMerge<
+	DotNotationToObjects<(typeof pathSupportedKeys)[number], string | undefined>
+>;
+
+export type PartialHeadplaneConfigWithPaths = PartialHeadplaneConfig &
+	ConfigWithPathKeys;

app/server/config/env.ts

@@ -1,76 +0,0 @@
-import { exit } from 'node:process';
-import { type } from 'arktype';
-import log from '~/utils/log';
-
-// Custom type for boolean environment variables, allowing for values like
-// 1, true, yes, and on to count as a truthy value.
-const booleanEnv = type('string | undefined').pipe((v) => {
-	return ['1', 'true', 'yes', 'on'].includes(v?.toLowerCase() ?? '');
-});
-
-export const envVariables = {
-	debugLog: 'HEADPLANE_DEBUG_LOG',
-	envOverrides: 'HEADPLANE_LOAD_ENV_OVERRIDES',
-	configPath: 'HEADPLANE_CONFIG_PATH',
-} as const;
-
-export function configureLogger(env: string | undefined) {
-	const result = booleanEnv(env);
-	if (result instanceof type.errors) {
-		log.error(
-			'config',
-			'HEADPLANE_DEBUG_LOG value is invalid: %s',
-			result.summary,
-		);
-		log.info('config', 'Using a default value: false');
-		log.debug = () => {}; // Disable debug logging if the value is invalid
-		log.debugEnabled = false;
-		return;
-	}
-
-	if (result === false) {
-		log.debug = () => {}; // Disable debug logging if the value is false
-		log.debugEnabled = false;
-		return;
-	}
-
-	log.debug('config', 'Debug logging has been enabled');
-	log.debug('config', 'It is recommended this be disabled in production');
-}
-
-export interface EnvOverrides {
-	loadEnv: boolean;
-	path: string;
-}
-
-export function configureConfig(overrides: {
-	loadEnv: string | undefined;
-	path: string | undefined;
-}): EnvOverrides {
-	const loadResult = booleanEnv(overrides.loadEnv);
-	if (loadResult instanceof type.errors) {
-		log.error(
-			'config',
-			'HEADPLANE_LOAD_ENV_OVERRIDES value is invalid: %s',
-			loadResult.summary,
-		);
-
-		exit(1);
-	}
-
-	const pathResult = type('string | undefined')(overrides.path);
-	if (pathResult instanceof type.errors) {
-		log.error(
-			'config',
-			'HEADPLANE_CONFIG_PATH value is invalid: %s',
-			pathResult.summary,
-		);
-
-		exit(1);
-	}
-
-	return {
-		loadEnv: loadResult,
-		path: pathResult ?? '/etc/headplane/config.yaml',
-	};
-}

app/server/config/error.ts

@@ -0,0 +1,74 @@
+interface ErrorCodes {
+	CONFLICTING_SECRET_PATH_FIELD: {
+		fieldName: string;
+	};
+
+	INVALID_REQUIRED_FIELDS: {
+		messages: string[];
+	};
+
+	MISSING_INTERPOLATION_VARIABLE: {
+		pathKey: string;
+		variableName: string;
+	};
+
+	MISSING_SECRET_FILE: {
+		pathKey: string;
+		filePath: string;
+	};
+}
+
+const translationsWithVars: {
+	[K in keyof ErrorCodes]: (vars: ErrorCodes[K]) => string;
+} = {
+	CONFLICTING_SECRET_PATH_FIELD: ({ fieldName }) =>
+		`Both "${fieldName}" and "${fieldName}_path" are set; please provide only one of these fields.`,
+	INVALID_REQUIRED_FIELDS: ({ messages }) =>
+		`The configuration is missing required fields or has invalid values:\n- ${messages.join('\n- ')}`,
+	MISSING_INTERPOLATION_VARIABLE: ({ pathKey, variableName }) =>
+		`Could not resolve environment variable "${variableName}" for configuration key "${pathKey}".`,
+
+	MISSING_SECRET_FILE: ({ pathKey, filePath }) =>
+		`The secret file specified in "${pathKey}" could not be accessed at path "${filePath}". Please ensure the file exists and is readable.`,
+} as const;
+
+/**
+ * Custom error class for configuration-related errors.
+ */
+export class ConfigError extends Error {
+	/**
+	 * The error code representing the type of configuration error.
+	 */
+	code: keyof ErrorCodes;
+
+	/**
+	 * Creates a new ConfigError instance.
+	 *
+	 * @param code The error code
+	 * @param vars The variables to interpolate into the error message
+	 */
+	constructor(code: keyof ErrorCodes, vars: unknown) {
+		super(
+			translationsWithVars[code](
+				vars as (typeof translationsWithVars)[typeof code] extends (
+					vars: infer U,
+				) => string
+					? U
+					: never,
+			),
+		);
+		this.code = code;
+		this.name = 'ConfigError';
+	}
+
+	/**
+	 * Factory method to create a ConfigError instance.
+	 *
+	 * @param code The error code
+	 * @param vars The variables to interpolate into the error message
+	 * @returns A new ConfigError instance
+	 */
+	static from<K extends keyof ErrorCodes>(code: K, vars: ErrorCodes[K]) {
+		return new ConfigError(code, vars);
+	}
+}

app/server/config/integration/docker.ts

@@ -1,9 +1,9 @@
 import { access, constants } from 'node:fs/promises';
 import { setTimeout } from 'node:timers/promises';
+import { type } from 'arktype';
 import { Client } from 'undici';
 import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 import log from '~/utils/log';
-import type { HeadplaneConfig } from '../schema';
 import { Integration } from './abstract';
 
 interface DockerContainer {
@@ -11,8 +11,25 @@ interface DockerContainer {
 	Names: string[];
 }
 
-type T = NonNullable<HeadplaneConfig['integration']>['docker'];
-export default class DockerIntegration extends Integration<T> {
+const configSchema = {
+	full: type({
+		enabled: 'boolean',
+		container_name: 'string?',
+		container_label: 'string = "me.tale.headplane.target=headscale"',
+		socket: 'string = "unix:///var/run/docker.sock"',
+	}),
+
+	partial: type({
+		enabled: 'boolean?',
+		container_name: 'string?',
+		container_label: 'string?',
+		socket: 'string?',
+	}).partial(),
+};
+
+export default class DockerIntegration extends Integration<
+	typeof configSchema.full.infer
+> {
 	private maxAttempts = 10;
 	private client: Client | undefined;
 	private containerId: string | undefined;
@@ -21,6 +38,10 @@ export default class DockerIntegration extends Integration<T> {
 		return 'Docker';
 	}
 
+	static get configSchema() {
+		return configSchema;
+	}
+
 	async getContainerName(label: string, value: string): Promise<string> {
 		if (!this.client) {
 			throw new Error('Docker client is not initialized');
@@ -60,7 +81,7 @@ export default class DockerIntegration extends Integration<T> {
 		// Basic configuration check, the name overrides the container_label
 		// selector because of legacy support.
 		const { container_name, container_label } = this.context;
-		if (container_name.length === 0 && container_label.length === 0) {
+		if (container_name?.length === 0 && container_label.length === 0) {
 			log.error(
 				'config',
 				'Missing a Docker `container_name` or `container_label`',
@@ -127,7 +148,7 @@ export default class DockerIntegration extends Integration<T> {
 
 		const qp = new URLSearchParams({
 			filters: JSON.stringify(
-				container_name.length > 0
+				container_name != null && container_name.length > 0
 					? { name: [container_name] }
 					: { label: [container_label] },
 			),
@@ -151,7 +172,7 @@ export default class DockerIntegration extends Integration<T> {
 
 		const data = (await res.body.json()) as DockerContainer[];
 		if (data.length > 1) {
-			if (container_name.length > 0) {
+			if (container_name != null && container_name.length > 0) {
 				log.error(
 					'config',
 					`Found multiple containers with name ${container_name}`,
@@ -167,7 +188,7 @@ export default class DockerIntegration extends Integration<T> {
 		}
 
 		if (data.length === 0) {
-			if (container_name.length > 0) {
+			if (container_name != null && container_name.length > 0) {
 				log.error(
 					'config',
 					`No container found with the name ${container_name}`,

app/server/config/integration/index.ts

@@ -1,5 +1,5 @@
-import { HeadplaneConfig } from '~/server/config/schema';
 import log from '~/utils/log';
+import type { HeadplaneConfig } from '../config-schema';
 import dockerIntegration from './docker';
 import kubernetesIntegration from './kubernetes';
 import procIntegration from './proc';
@@ -47,16 +47,16 @@ function getIntegration(integration: HeadplaneConfig['integration']) {
 
 	if (docker?.enabled) {
 		log.info('config', 'Using Docker integration');
-		return new dockerIntegration(integration?.docker);
+		return new dockerIntegration(integration!.docker!);
 	}
 
 	if (k8s?.enabled) {
 		log.info('config', 'Using Kubernetes integration');
-		return new kubernetesIntegration(integration?.kubernetes);
+		return new kubernetesIntegration(integration!.kubernetes!);
 	}
 
 	if (proc?.enabled) {
 		log.info('config', 'Using Proc integration');
-		return new procIntegration(integration?.proc);
+		return new procIntegration(integration!.proc!);
 	}
 }

app/server/config/integration/kubernetes.ts

@@ -4,9 +4,9 @@ import { join, resolve } from 'node:path';
 import { kill } from 'node:process';
 import { setTimeout } from 'node:timers/promises';
 import { CoreV1Api, KubeConfig } from '@kubernetes/client-node';
+import { type } from 'arktype';
 import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 import log from '~/utils/log';
-import type { HeadplaneConfig } from '../schema';
 import { Integration } from './abstract';
 
 // https://github.com/kubernetes-client/javascript/blob/055b83c6504dfd1b2a2d081efd974163c6cbb808/src/config.ts#L40
@@ -15,8 +15,23 @@ const svcCaPath = `${svcRoot}/ca.crt`;
 const svcTokenPath = `${svcRoot}/token`;
 const svcNamespacePath = `${svcRoot}/namespace`;
 
-type T = NonNullable<HeadplaneConfig['integration']>['kubernetes'];
-export default class KubernetesIntegration extends Integration<T> {
+const configSchema = {
+	full: type({
+		enabled: 'boolean',
+		pod_name: 'string',
+		validate_manifest: 'boolean = true',
+	}),
+
+	partial: type({
+		enabled: 'boolean?',
+		pod_name: 'string?',
+		validate_manifest: 'boolean?',
+	}).partial(),
+};
+
+export default class KubernetesIntegration extends Integration<
+	typeof configSchema.full.infer
+> {
 	private pid: number | undefined;
 	private maxAttempts = 10;
 
@@ -24,6 +39,10 @@ export default class KubernetesIntegration extends Integration<T> {
 		return 'Kubernetes (k8s)';
 	}
 
+	static get configSchema() {
+		return configSchema;
+	}
+
 	async isAvailable() {
 		if (platform() !== 'linux') {
 			log.error('config', 'Kubernetes is only available on Linux');

app/server/config/integration/proc.ts

@@ -3,13 +3,25 @@ import { platform } from 'node:os';
 import { join, resolve } from 'node:path';
 import { kill } from 'node:process';
 import { setTimeout } from 'node:timers/promises';
+import { type } from 'arktype';
 import type { RuntimeApiClient } from '~/server/headscale/api/endpoints';
 import log from '~/utils/log';
-import type { HeadplaneConfig } from '../schema';
+import type { HeadplaneConfig } from '../config-schema';
 import { Integration } from './abstract';
 
-type T = NonNullable<HeadplaneConfig['integration']>['proc'];
-export default class ProcIntegration extends Integration<T> {
+const configSchema = {
+	full: type({
+		enabled: 'boolean',
+	}),
+
+	partial: type({
+		enabled: 'boolean?',
+	}).partial(),
+};
+
+export default class ProcIntegration extends Integration<
+	typeof configSchema.full.infer
+> {
 	private pid: number | undefined;
 	private maxAttempts = 10;
 
@@ -17,6 +29,10 @@ export default class ProcIntegration extends Integration<T> {
 		return 'Native Linux (/proc)';
 	}
 
+	static get configSchema() {
+		return configSchema;
+	}
+
 	async isAvailable() {
 		if (platform() !== 'linux') {
 			log.error('config', '/proc is only available on Linux');

app/server/config/load.ts

@@ -0,0 +1,267 @@
+import { access, constants, readFile } from 'node:fs/promises';
+import { type } from 'arktype';
+import { load } from 'js-yaml';
+import log from '~/utils/log';
+import {
+	headplaneConfig,
+	PartialHeadplaneConfig,
+	partialHeadplaneConfig,
+	pathSupportedKeys,
+} from './config-schema';
+import { ConfigError } from './error';
+
+/**
+ * Main entrypoint that attempts to load and merge configuration from both
+ * a YAML config file (if available) and environment variables. Importantly,
+ * the environment variables will override any values set in the config file.
+ *
+ * The function also supports loading secret values from file paths for
+ * specific configuration keys (e.g., certificates, private keys) by checking
+ * for corresponding `_path` suffixed environment variables or config file
+ * entries.
+ *
+ * @param configPathOverride Used for testing to override the config file path
+ * @returns @ref{HeadplaneConfig} The fully validated configuration
+ * @throws {Error} If there are validation errors in the final configuration
+ */
+export async function loadConfig(configPathOverride?: string) {
+	const configPath =
+		configPathOverride != null
+			? configPathOverride
+			: process.env.HEADPLANE_CONFIG_PATH != null
+				? String(process.env.HEADPLANE_CONFIG_PATH)
+				: '/etc/headplane/config.yaml';
+
+	const fileConfig = await loadConfigFile(configPath);
+	const envConfig = await loadConfigEnv();
+
+	const combinedConfig = deepMerge(fileConfig, envConfig);
+	await loadConfigKeyPaths(combinedConfig);
+
+	const finalConfig = headplaneConfig(combinedConfig);
+	if (finalConfig instanceof type.errors) {
+		throw ConfigError.from('INVALID_REQUIRED_FIELDS', {
+			messages: finalConfig.map((e) => e.toString()),
+		});
+	}
+
+	return finalConfig;
+}
+
+/**
+ * Attempts to load configuration from a YAML file at the specified path.
+ * If the file is not accessible, it returns undefined.
+ *
+ * @param path The file path to load the configuration from
+ * @returns A partial configuration object or undefined
+ * @throws {Error} If there are validation errors in the loaded configuration
+ */
+export async function loadConfigFile(path: string) {
+	try {
+		await access(path, constants.R_OK);
+	} catch {
+		log.info('config', 'Could not access config file at path: %s', path);
+		return;
+	}
+
+	const rawBuffer = await readFile(path, 'utf8');
+	const rawConfig = load(rawBuffer);
+	const config = partialHeadplaneConfig(rawConfig);
+	if (config instanceof type.errors) {
+		throw ConfigError.from('INVALID_REQUIRED_FIELDS', {
+			messages: config.map((e) => e.toString()),
+		});
+	}
+
+	return config;
+}
+
+/**
+ * Loads configuration overrides from environment variables prefixed with
+ * `HEADPLANE_`. Nested configuration keys can be represented using double
+ * underscores (`__`). For example, `HEADPLANE_SERVER__PORT=8080` would set
+ * the `server.port` configuration key to `8080`.
+ *
+ * @returns A partial configuration object or undefined
+ * @throws {Error} If there are validation errors in the loaded configuration
+ */
+export async function loadConfigEnv() {
+	if (process.env.HEADPLANE_LOAD_ENV_OVERRIDES != null) {
+		log.warn(
+			'config',
+			'HEADPLANE_LOAD_ENV_OVERRIDES is deprecated and will be removed in future versions',
+		);
+		log.warn(
+			'config',
+			'Environment variables are always loaded and `.env` files are no longer supported',
+		);
+	}
+
+	const rawConfig: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(process.env)) {
+		if (value == null || !key.startsWith('HEADPLANE_')) {
+			continue;
+		}
+
+		const parsedValue = parseEnvValue(value);
+		const configKey = key.slice('HEADPLANE_'.length).toLowerCase();
+		deepSet(rawConfig, configKey.split('__'), parsedValue);
+	}
+
+	const config = partialHeadplaneConfig(rawConfig);
+	if (config instanceof type.errors) {
+		throw ConfigError.from('INVALID_REQUIRED_FIELDS', {
+			messages: config.map((e) => e.toString()),
+		});
+	}
+
+	return Object.keys(config).length > 0 ? config : undefined;
+}
+
+/**
+ * Deeply merges multiple objects together. Later objects in the arguments
+ * list will override properties of earlier objects.
+ *
+ * @param objects The objects to merge
+ * @returns The merged object
+ */
+function deepMerge<T>(...objects: (T | undefined)[]): T {
+	const result: { [key: string]: unknown } = {};
+	for (const obj of objects.filter((o) => o != null)) {
+		for (const [key, value] of Object.entries(
+			obj as {
+				[key: string]: unknown;
+			},
+		)) {
+			if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+				if (
+					result[key] == null ||
+					typeof result[key] !== 'object' ||
+					Array.isArray(result[key])
+				) {
+					result[key] = {};
+				}
+				result[key] = deepMerge(result[key], value);
+			} else {
+				result[key] = value;
+			}
+		}
+	}
+
+	return result as T;
+}
+
+/**
+ * Sets a value deeply within an object based on the provided path.
+ *
+ * @param obj The object to set the value in
+ * @param path An array of keys representing the path to set
+ * @param value The value to set at the specified path
+ */
+function deepSet(
+	obj: { [key: string]: unknown },
+	path: string[],
+	value: unknown,
+): void {
+	let current = obj;
+	for (let i = 0; i < path.length - 1; i++) {
+		const key = path[i];
+		if (current[key] == null || typeof current[key] !== 'object') {
+			current[key] = {};
+		}
+
+		current = current[key] as { [key: string]: unknown };
+	}
+
+	current[path[path.length - 1]] = value;
+}
+
+/**
+ * Parses an environment variable string value into an appropriate type.
+ * Supports booleans, null, undefined, and numbers. Falls back to string.
+ *
+ * @param value The environment variable string value
+ * @returns The parsed value
+ */
+function parseEnvValue(value: string): unknown {
+	const v = value.trim().toLowerCase();
+	if (v === 'true') return true;
+	if (v === 'false') return false;
+	if (v === 'null') return null;
+	if (v === 'undefined') return undefined;
+
+	if (/^-?\d+(\.\d+)?$/.test(v)) {
+		const num = Number(v);
+		if (!Number.isNaN(num)) return num;
+	}
+
+	return value;
+}
+
+/**
+ * For configuration keys that support loading from file paths (e.g.,
+ * certificates, private keys), this function checks for corresponding
+ * `_path` suffixed keys and loads the file content if the main key is
+ * not already set.
+ *
+ * @param partial The partial configuration object to update
+ */
+export async function loadConfigKeyPaths(partial: PartialHeadplaneConfig) {
+	for (const key of pathSupportedKeys) {
+		const pathKey = `${key}_path`;
+		const pathValue = deepGet(partial, pathKey.split('.'));
+		const existing = deepGet(partial, key.split('.'));
+
+		if (pathValue == null || typeof pathValue !== 'string') {
+			continue;
+		}
+
+		if (existing != null) {
+			throw ConfigError.from('CONFLICTING_SECRET_PATH_FIELD', {
+				fieldName: key,
+			});
+		}
+
+		const realPath = pathValue.replace(/\$\{([^}]+)\}/g, (_, variableName) => {
+			const value = process.env[variableName];
+			if (value === undefined) {
+				throw ConfigError.from('MISSING_INTERPOLATION_VARIABLE', {
+					pathKey: `${key}_path`,
+					variableName: variableName,
+				});
+			}
+
+			return value;
+		});
+
+		try {
+			const fileContent = await readFile(realPath, 'utf8');
+			deepSet(partial, key.split('.'), fileContent.trim().normalize());
+		} catch {
+			throw ConfigError.from('MISSING_SECRET_FILE', {
+				pathKey: `${key}_path`,
+				filePath: realPath,
+			});
+		}
+	}
+}
+
+/**
+ * Deeply retrieves a value from an object based on the provided path.
+ *
+ * @param obj The object to retrieve the value from
+ * @param path An array of keys representing the path to retrieve
+ * @returns The value at the specified path or undefined if not found
+ */
+function deepGet(obj: { [key: string]: unknown }, path: string[]): unknown {
+	let current = obj;
+	for (const segment of path) {
+		if (current == null || typeof current !== 'object') {
+			return undefined;
+		}
+
+		current = current[segment] as { [key: string]: unknown };
+	}
+
+	return current;
+}

app/server/config/loader.ts

@@ -1,303 +0,0 @@
-import { access, constants, readFile } from 'node:fs/promises';
-import { env } from 'node:process';
-import { type } from 'arktype';
-import { configDotenv } from 'dotenv';
-import { parseDocument } from 'yaml';
-import log from '~/utils/log';
-import { EnvOverrides, envVariables } from './env';
-import {
-	HeadplaneConfig,
-	headplaneConfig,
-	partialHeadplaneConfig,
-} from './schema';
-
-// Custom error for config issues
-export class ConfigError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = 'ConfigError';
-	}
-}
-
-/**
- * Interpolate environment variables in a string
- * Replaces ${VAR_NAME} patterns with the actual environment variable values
- */
-export function interpolateEnvVars(str: string): string {
-	return str.replace(/\$\{([^}]+)\}/g, (_, varName) => {
-		const value = env[varName];
-		if (value === undefined) {
-			throw new ConfigError(`Environment variable "${varName}" not found`);
-		}
-		return value;
-	});
-}
-
-// loadConfig is a has a lifetime of the entire application and is
-// used to load the configuration for Headplane. It is called once.
-//
-// TODO: Potential for file watching on the configuration
-// But this may not be necessary as a use-case anyways
-export async function loadConfig({ loadEnv, path }: EnvOverrides) {
-	log.debug('config', 'Loading configuration file: %s', path);
-	await validateConfigPath(path);
-
-	const data = await loadConfigFile(path);
-	if (!data) {
-		throw new ConfigError('Failed to load configuration file');
-	}
-
-	let config = validateConfig({ ...data, debug: log.debugEnabled });
-
-	if (!loadEnv) {
-		log.debug('config', 'Environment variable overrides are disabled');
-		log.debug('config', 'This also disables the loading of a .env file');
-		const moddedConfig = await loadSecretsFromFiles(config);
-		log.debug('config', 'Loaded file-based secrets');
-		return moddedConfig;
-	}
-
-	log.info('config', 'Loading a .env file (if available)');
-	configDotenv({ override: true, quiet: true });
-	const merged = coalesceEnv(config);
-	if (merged) config = merged;
-	if (config.headscale && typeof config.headscale.config_path === 'string') {
-		config.headscale.config_path = interpolateEnvVars(
-			config.headscale.config_path,
-		);
-	}
-
-	const moddedConfig = await loadSecretsFromFiles(config);
-	log.debug('config', 'Loaded file-based secrets');
-
-	return moddedConfig;
-}
-
-/**
- * Recursively walks the config object; for any key in the whitelist of secret path keys,
- * reads that file and assigns its contents to the corresponding key
- * without the suffix, then removes the "_path" property.
- */
-const SECRET_PATH_KEYS = [
-	'pre_authkey_path',
-	'client_secret_path',
-	'headscale_api_key_path',
-	'cookie_secret_path',
-] as const;
-
-// For fast set hashing lookups, but we still need the array for typings
-const SECRET_PATH_KEY_SET = new Set<string>(SECRET_PATH_KEYS);
-
-type SecretPathKey = (typeof SECRET_PATH_KEYS)[number];
-type StripPath<S extends string> = S extends `${infer T}_path` ? T : never;
-type KeysToPromote<T> = Extract<keyof T & string, SecretPathKey>;
-type MappedKeys<T> = StripPath<KeysToPromote<T>>;
-
-type NonNullablized<T> = Omit<T, KeysToPromote<T> | MappedKeys<T>> & {
-	[K in MappedKeys<T>]-?: string;
-};
-
-type NestedNonNullablized<T> = T extends readonly (infer U)[]
-	? readonly NestedNonNullablized<U>[]
-	: T extends (infer U)[]
-		? NestedNonNullablized<U>[]
-		: T extends object
-			? {
-					[K in keyof NonNullablized<T>]: NestedNonNullablized<
-						NonNullablized<T>[K]
-					>;
-				}
-			: T;
-
-async function loadSecretsFromFiles<T extends object>(
-	obj: T,
-): Promise<NestedNonNullablized<T>> {
-	// Work with a Record so we can mutate/delete properties
-	const record = obj as Record<string, unknown>;
-
-	for (const key of Object.keys(record)) {
-		const val = record[key];
-
-		if (val && typeof val === 'object') {
-			// recurse into nested objects
-			record[key] = await loadSecretsFromFiles(val);
-			continue;
-		}
-
-		if (SECRET_PATH_KEY_SET.has(key) && typeof val === 'string') {
-			try {
-				const path = interpolateEnvVars(val);
-				const content = await readFile(path, 'utf8');
-				const secretKey = key.slice(0, -5); // drop '_path'
-				record[secretKey] = content.trim();
-				delete record[key];
-				log.debug('config', 'Loaded secret from %s → %s', val, secretKey);
-			} catch (err) {
-				if (err instanceof ConfigError) throw err;
-				log.error('config', 'Failed to read secret file %s: %s', val, err);
-				throw new ConfigError(`Failed to read secret file ${val}: ${err}`);
-			}
-		}
-	}
-
-	// Cast back to the original T so callers keep their precise type
-	return record as NestedNonNullablized<T>;
-}
-
-async function validateConfigPath(path: string) {
-	try {
-		await access(path, constants.F_OK | constants.R_OK);
-		log.info('config', 'Found a valid configuration file at %s', path);
-		return true;
-	} catch (error) {
-		log.error('config', 'Unable to read a configuration file at %s', path);
-		log.error('config', '%s', error);
-		throw new ConfigError(
-			`Unable to read configuration file at ${path}: ${error}`,
-		);
-	}
-}
-
-async function loadConfigFile(path: string): Promise<unknown> {
-	log.debug('config', 'Reading configuration file at %s', path);
-	try {
-		const data = await readFile(path, 'utf8');
-		const configYaml = parseDocument(data);
-		if (configYaml.errors.length > 0) {
-			log.error('config', 'Cannot parse configuration file at %s', path);
-			for (const error of configYaml.errors) {
-				log.error('config', ` - ${error.toString()}`);
-			}
-
-			throw new ConfigError(`Cannot parse configuration file at ${path}`);
-		}
-
-		if (configYaml.warnings.length > 0) {
-			log.warn(
-				'config',
-				'Warnings while parsing configuration file at %s',
-				path,
-			);
-			for (const warning of configYaml.warnings) {
-				log.warn('config', ` - ${warning.toString()}`);
-			}
-		}
-
-		return configYaml.toJSON() as unknown;
-	} catch (e) {
-		log.error('config', 'Error reading configuration file at %s', path);
-		log.error('config', '%s', e);
-		throw new ConfigError(`Error reading configuration file at ${path}: ${e}`);
-	}
-}
-
-export function validateConfig(config: unknown) {
-	log.debug('config', 'Validating Headplane configuration');
-	const result = headplaneConfig(config);
-	if (result instanceof type.errors) {
-		const errorMessages = [];
-		for (const [number, error] of result.entries()) {
-			const errorMsg = error.toString();
-			log.error('config', ` - (${number}): ${errorMsg}`);
-			errorMessages.push(errorMsg);
-		}
-		throw new ConfigError(errorMessages.join('\n'));
-	}
-	return result;
-}
-
-function coalesceEnv(config: HeadplaneConfig) {
-	const envConfig: Record<string, unknown> = {};
-	const rootKeys: string[] = Object.values(envVariables);
-
-	// Typescript is still insanely stupid at nullish filtering
-	const vars = Object.entries(env).filter(([key, value]) => {
-		if (!value) {
-			return false;
-		}
-
-		if (!key.startsWith('HEADPLANE_')) {
-			return false;
-		}
-
-		// Filter out the rootEnv configurations
-		if (rootKeys.includes(key)) {
-			return false;
-		}
-
-		return true;
-	}) as [string, string][];
-
-	log.debug('config', 'Coalescing %s environment variables', vars.length);
-	for (const [key, value] of vars) {
-		const configPath = key.replace('HEADPLANE_', '').toLowerCase().split('__');
-		log.debug(
-			'config',
-			` - ${key}=${new Array(value.length).fill('*').join('')}`,
-		);
-
-		let current = envConfig;
-		while (configPath.length > 1) {
-			const path = configPath.shift() as string;
-			if (!(path in current)) {
-				current[path] = {};
-			}
-
-			current = current[path] as Record<string, unknown>;
-		}
-
-		current[configPath[0]] = value;
-	}
-
-	const toMerge = coalesceConfig(envConfig);
-	if (!toMerge) {
-		return;
-	}
-
-	// Deep merge the environment variables into the configuration
-	// This will overwrite any existing values in the configuration
-	return deepMerge(config, toMerge);
-}
-
-export function coalesceConfig(config: unknown) {
-	log.debug('config', 'Revalidating config after coalescing variables');
-	const out = partialHeadplaneConfig(config);
-	if (out instanceof type.errors) {
-		log.error('config', 'Error parsing variables:');
-		for (const [number, error] of out.entries()) {
-			log.error('config', ` - (${number}): ${error.toString()}`);
-		}
-
-		return;
-	}
-
-	return out;
-}
-
-type DeepPartial<T> =
-	| {
-			[P in keyof T]?: DeepPartial<T[P]>;
-	  }
-	| undefined;
-
-function deepMerge<T>(target: T, source: DeepPartial<T>): T {
-	if (typeof target !== 'object' || typeof source !== 'object')
-		return source as T;
-	const result = { ...target } as T;
-
-	for (const key in source) {
-		const val = source[key];
-		if (val === undefined || val === null) {
-			continue;
-		}
-
-		if (typeof val === 'object') {
-			result[key] = deepMerge(result[key], val);
-			continue;
-		}
-
-		result[key] = val;
-	}
-
-	return result;
-}

app/server/config/schema.ts

@@ -1,227 +0,0 @@
-import { type } from 'arktype';
-
-const stringToBool = type('string | boolean').pipe((v) => {
-	if (typeof v === 'string') {
-		if (v === '1' || v === 'true' || v === 'yes') {
-			return true;
-		}
-
-		if (v === '0' || v === 'false' || v === 'no') {
-			return false;
-		}
-
-		throw new Error(`Invalid string value for boolean: ${v}`);
-	}
-
-	return Boolean(v);
-});
-
-const serverConfig = type({
-	host: 'string.ip',
-	port: type('string | number.integer').pipe((v) => Number(v)),
-	data_path: 'string = "/var/lib/headplane/"',
-	cookie_secret: '(32 <= string <= 32)?',
-	cookie_secret_path: 'string?',
-	cookie_secure: stringToBool,
-	cookie_domain: 'string?',
-	cookie_max_age: 'number.integer = 86400',
-})
-	.narrow((obj: Record<string, unknown>, ctx: any) => {
-		const hasVal = obj.cookie_secret != null && `${obj.cookie_secret}` !== '';
-		const hasPath =
-			obj.cookie_secret_path != null && obj.cookie_secret_path !== '';
-		if (hasVal && hasPath)
-			return ctx.reject(
-				`Only one of "cookie_secret" or "cookie_secret_path" may be set.`,
-			);
-		if (!hasVal && !hasPath)
-			return ctx.reject(
-				`Either "cookie_secret" or "cookie_secret_path" must be provided for cookie_secret.`,
-			);
-		return true;
-	})
-	.onDeepUndeclaredKey('reject');
-
-const partialServerConfig = type({
-	host: 'string.ip?',
-	port: type('string | number.integer')
-		.pipe((v) => Number(v))
-		.optional(),
-	data_path: 'string = "/var/lib/headplane/"',
-	cookie_secret: '32 <= string <= 32?',
-	cookie_secret_path: 'string?',
-	cookie_secure: stringToBool.optional(),
-	cookie_domain: 'string?',
-	cookie_max_age: 'number.integer?',
-});
-
-const oidcConfig = type({
-	issuer: 'string.url',
-	client_id: 'string',
-	client_secret: 'string?',
-	client_secret_path: 'string?',
-	token_endpoint_auth_method:
-		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"',
-	redirect_uri: 'string.url?',
-	user_storage_file: 'string = "/var/lib/headplane/users.json"',
-	disable_api_key_login: stringToBool,
-	headscale_api_key: 'string?',
-	headscale_api_key_path: 'string?',
-	profile_picture_source: '"oidc" | "gravatar" = "oidc"',
-	strict_validation: stringToBool.default(true),
-	scope: 'string = "openid email profile"',
-	extra_params: 'Record<string, string>?',
-	authorization_endpoint: 'string.url?',
-	token_endpoint: 'string.url?',
-	userinfo_endpoint: 'string.url?',
-})
-	.narrow((obj: Record<string, unknown>, ctx: any) => {
-		const hasVal =
-			obj.headscale_api_key != null && `${obj.headscale_api_key}` !== '';
-		const hasPath =
-			obj.headscale_api_key_path != null && obj.headscale_api_key_path !== '';
-		if (hasVal && hasPath)
-			return ctx.reject(
-				`Only one of "headscale_api_key" or "headscale_api_key_path" may be set.`,
-			);
-		if (!hasVal && !hasPath)
-			return ctx.reject(
-				`Either "headscale_api_key" or "headscale_api_key_path" must be provided.`,
-			);
-		return true;
-	})
-	.onDeepUndeclaredKey('reject');
-
-const partialOidcConfig = type({
-	issuer: 'string.url?',
-	client_id: 'string?',
-	client_secret: 'string?',
-	client_secret_path: 'string?',
-	token_endpoint_auth_method:
-		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"?',
-	redirect_uri: 'string.url?',
-	user_storage_file: 'string?',
-	disable_api_key_login: stringToBool.optional(),
-	headscale_api_key: 'string?',
-	headscale_api_key_path: 'string?',
-	profile_picture_source: '("oidc" | "gravatar")?',
-	strict_validation: stringToBool.default(true),
-	scope: 'string?',
-	extra_params: 'Record<string, string>?',
-	authorization_endpoint: 'string.url?',
-	token_endpoint: 'string.url?',
-	userinfo_endpoint: 'string.url?',
-});
-
-const headscaleConfig = type({
-	url: type('string.url').pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v)),
-	tls_cert_path: 'string?',
-	public_url: 'string.url?',
-	config_path: 'string?',
-	config_strict: stringToBool,
-	dns_records_path: 'string?',
-}).onDeepUndeclaredKey('reject');
-
-const partialHeadscaleConfig = type({
-	url: type('string.url')
-		.pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v))
-		.optional(),
-	tls_cert_path: 'string?',
-	public_url: 'string.url?',
-	config_path: 'string?',
-	config_strict: stringToBool.optional(),
-	dns_records_path: 'string?',
-});
-
-const agentConfig = type({
-	enabled: stringToBool.default(false),
-	host_name: 'string = "headplane-agent"',
-	pre_authkey: 'string?',
-	pre_authkey_path: 'string?',
-	cache_ttl: 'number.integer = 180000',
-	cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
-	executable_path: 'string = "/usr/libexec/headplane/agent"',
-	work_dir: 'string = "/var/lib/headplane/agent"',
-})
-	.narrow((obj: Record<string, unknown>, ctx: any) => {
-		const hasVal = obj.pre_authkey != null && `${obj.pre_authkey}` !== '';
-		const hasPath = obj.pre_authkey_path != null && obj.pre_authkey_path !== '';
-		if (hasVal && hasPath)
-			return ctx.reject(
-				`Only one of "pre_authkey" or "pre_authkey_path" may be set.`,
-			);
-		if (!hasVal && !hasPath)
-			return ctx.reject(
-				`Either "pre_authkey" or "pre_authkey_path" must be provided.`,
-			);
-		return true;
-	})
-	.onDeepUndeclaredKey('reject');
-
-const partialAgentConfig = type({
-	enabled: stringToBool.default(false),
-	host_name: 'string = "headplane-agent"',
-	pre_authkey: 'string?',
-	pre_authkey_path: 'string?',
-	cache_ttl: 'number.integer = 180000',
-	cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
-	executable_path: 'string = "/usr/libexec/headplane/agent"',
-	work_dir: 'string = "/var/lib/headplane/agent"',
-});
-
-const dockerConfig = type({
-	enabled: stringToBool,
-	container_name: 'string = ""',
-	container_label: 'string = "me.tale.headplane.target=headscale"',
-	socket: 'string = "unix:///var/run/docker.sock"',
-});
-
-const partialDockerConfig = type({
-	enabled: stringToBool,
-	container_name: 'string | undefined',
-	container_label: 'string | undefined',
-	socket: 'string | undefined',
-}).partial();
-
-const kubernetesConfig = type({
-	enabled: stringToBool,
-	pod_name: 'string',
-	validate_manifest: stringToBool,
-});
-
-const procConfig = type({
-	enabled: stringToBool,
-});
-
-const integrationConfig = type({
-	'docker?': dockerConfig,
-	'kubernetes?': kubernetesConfig,
-	'proc?': procConfig,
-	'agent?': agentConfig,
-});
-
-const partialIntegrationConfig = type({
-	'docker?': partialDockerConfig,
-	'kubernetes?': kubernetesConfig.partial(),
-	'proc?': procConfig.partial(),
-	'agent?': partialAgentConfig,
-}).partial();
-
-export const headplaneConfig = type({
-	debug: stringToBool,
-	server: serverConfig,
-	'oidc?': oidcConfig,
-	'integration?': integrationConfig,
-	headscale: headscaleConfig,
-}).onDeepUndeclaredKey('delete');
-
-export const partialHeadplaneConfig = type({
-	debug: stringToBool,
-	server: partialServerConfig,
-	'oidc?': partialOidcConfig,
-	'integration?': partialIntegrationConfig,
-	headscale: partialHeadscaleConfig,
-}).partial();
-
-export type HeadplaneConfig = typeof headplaneConfig.infer;
-export type PartialHeadplaneConfig = typeof partialHeadplaneConfig.infer;

app/server/config/utils.ts

@@ -0,0 +1,9 @@
+import type { Traversal } from 'arktype';
+import log from '~/utils/log';
+
+export function deprecatedField() {
+	return (_: unknown, ctx: Traversal) => {
+		log.warn('config', `${ctx.propString} is deprecated and has no effect.`);
+		return true;
+	};
+}

app/server/hp-agent.ts

@@ -7,7 +7,7 @@ import { inArray } from 'drizzle-orm';
 import { LibSQLDatabase } from 'drizzle-orm/libsql/driver-core';
 import { HostInfo } from '~/types';
 import log from '~/utils/log';
-import { HeadplaneConfig } from './config/schema';
+import { HeadplaneConfig } from './config/config-schema';
 import { hostInfo } from './db/schema';
 
 export async function createHeadplaneAgent(

app/server/index.ts

@@ -1,10 +1,9 @@
 import { join } from 'node:path';
-import { env, versions } from 'node:process';
+import { versions } from 'node:process';
 import { createHonoServer } from 'react-router-hono-server/node';
 import log from '~/utils/log';
-import { configureConfig, configureLogger, envVariables } from './config/env';
 import { loadIntegration } from './config/integration';
-import { loadConfig } from './config/loader';
+import { loadConfig } from './config/load';
 import { createDbClient } from './db/client.server';
 import { createHeadscaleInterface } from './headscale/api';
 import { loadHeadscaleConfig } from './headscale/config-loader';
@@ -21,13 +20,7 @@ declare global {
 // This module contains a side-effect because everything running here
 // exists for the lifetime of the process, making it appropriate.
 log.info('server', 'Running Node.js %s', versions.node);
-configureLogger(env[envVariables.debugLog]);
-const config = await loadConfig(
-	configureConfig({
-		loadEnv: env[envVariables.envOverrides],
-		path: env[envVariables.configPath],
-	}),
-);
+const config = await loadConfig();
 
 const db = await createDbClient(join(config.server.data_path, 'hp_persist.db'));
 const agents = await createHeadplaneAgent(

app/utils/log.ts

@@ -14,10 +14,11 @@ export interface Logger
 	debugEnabled: boolean;
 }
 
+const logLevels = getLogLevels();
 export default {
-	debugEnabled: true,
+	debugEnabled: logLevels.includes('debug'),
 	...Object.fromEntries(
-		levels.map((level) => [
+		logLevels.map((level) => [
 			level,
 			(category: Category, message: string, ...args: unknown[]) => {
 				const date = new Date().toISOString();
@@ -29,3 +30,18 @@ export default {
 		]),
 	),
 } as Logger;
+
+function getLogLevels() {
+	const debugLog = process.env.HEADPLANE_DEBUG_LOG;
+	if (debugLog == null) {
+		return ['info', 'warn', 'error'];
+	}
+
+	const normalized = debugLog.trim().toLowerCase();
+	const truthyValues = ['1', 'true', 'yes', 'on'];
+	if (!truthyValues.includes(normalized)) {
+		return ['info', 'warn', 'error'];
+	}
+
+	return ['info', 'warn', 'error', 'debug'];
+}