bunqueue-dashboard 0.0.35 → 0.0.37

package/agent/flow/validation.ts

@@ -0,0 +1,230 @@
+import type { FlowJobTarget, FlowMutationOperation } from './types';
+import { readLimitedJsonBody } from '../server/jsonBody';
+
+const MAX_PROGRESS_JSON_BYTES = 65_536;
+const MAX_PROGRESS_DEPTH = 32;
+const MAX_PROGRESS_VALUES = 10_000;
+const UNSAFE_JSON_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+const MAX_FLOW_BODY_BYTES = 1024 * 1024;
+
+export interface FlowProgressWireValue {
+  progress: number;
+  message?: string;
+}
+
+export function validateFlowTarget(target: FlowJobTarget): void {
+  if (!target.id || target.id.length > 1024) {
+    throw new Error('Flow job id must contain 1–1024 characters');
+  }
+  if (!target.queueName || target.queueName.length > 256) {
+    throw new Error('Flow queue name must contain 1–256 characters');
+  }
+}
+
+export function validateParentIds(value: unknown): asserts value is string[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 1_000) {
+    throw new Error('Flow parent IDs must contain between 1 and 1000 entries');
+  }
+  for (const id of value) {
+    if (typeof id !== 'string' || id.length < 1 || id.length > 1024) {
+      throw new Error('Each Flow parent ID must contain 1–1024 characters');
+    }
+  }
+}
+
+export function validateMutationPayload(
+  operation: FlowMutationOperation,
+  payload: Record<string, unknown>
+): void {
+  const keys: Partial<Record<FlowMutationOperation, readonly string[]>> = {
+    updateData: ['data'],
+    updateProgress: ['progress', 'message'],
+    log: ['message'],
+    changeDelay: ['delay'],
+    changePriority: ['priority', 'lifo'],
+    clearLogs: ['keepLogs'],
+  };
+  const allowed = keys[operation] ?? [];
+  const unknown = Object.keys(payload).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new Error(`Unknown Flow ${operation} option: ${unknown[0]}`);
+  if (operation === 'updateData' && !Object.hasOwn(payload, 'data')) {
+    throw new Error('Flow updateData requires data');
+  }
+  if (operation === 'updateProgress') validateProgress(payload);
+  if (
+    operation === 'log' &&
+    (typeof payload.message !== 'string' || payload.message.length > 65_536)
+  ) {
+    throw new Error('Flow log message must be a string of at most 65536 characters');
+  }
+  if (operation === 'changeDelay') {
+    boundedInteger(payload.delay, 'delay', 10 * 365 * 24 * 60 * 60 * 1_000);
+  }
+  if (operation === 'changePriority') {
+    boundedInteger(payload.priority, 'priority', 2_147_483_647);
+    if (payload.lifo !== undefined && typeof payload.lifo !== 'boolean') {
+      throw new Error('Flow lifo must be boolean');
+    }
+  }
+  if (operation === 'clearLogs' && payload.keepLogs !== undefined) {
+    boundedInteger(payload.keepLogs, 'keepLogs', 1_000_000);
+  }
+}
+
+export function asFlowRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Flow request must be an object');
+  }
+  return value as Record<string, unknown>;
+}
+
+export function assertExactFlowKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string
+): void {
+  const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`Unknown Flow ${label} option: ${unknown}`);
+}
+
+export async function readFlowJsonBody(request: Request): Promise<unknown> {
+  return readLimitedJsonBody(request, {
+    scope: 'Flow',
+    maxBytes: MAX_FLOW_BODY_BYTES,
+    limitLabel: '1 MiB',
+    invalidContentLengthMessage: 'Flow Content-Length must be an integer',
+  });
+}
+
+export function assertNoFlowBody(request: Request): void {
+  const declared = request.headers.get('content-length');
+  if (request.body !== null || (declared !== null && declared !== '0')) {
+    throw new Error('This Flow operation does not accept a request body');
+  }
+}
+
+export function assertFlowBodySize(value: unknown): void {
+  if (JSON.stringify(value).length > MAX_FLOW_BODY_BYTES) {
+    throw new Error('Flow request exceeds 1 MiB');
+  }
+}
+
+export function normalizeFlowProgressPayload(
+  payload: Record<string, unknown>
+): FlowProgressWireValue {
+  const value = payload.progress;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value < 0 || value > 100) {
+      throw new Error('Flow progress must be a number from 0 to 100 or a JSON object');
+    }
+    const message = optionalProgressMessage(payload.message);
+    return message === undefined ? { progress: value } : { progress: value, message };
+  }
+  if (!isPlainRecord(value)) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      throw new Error('Flow progress object must use only plain JSON objects and arrays');
+    }
+    throw new Error('Flow progress must be a number from 0 to 100 or a JSON object');
+  }
+  if (payload.message !== undefined) {
+    throw new Error('Flow progress message is only supported with numeric progress');
+  }
+  validateJsonValue(value, new WeakSet(), { count: 0 }, 0);
+  const message = JSON.stringify(value);
+  if (new TextEncoder().encode(message).byteLength > MAX_PROGRESS_JSON_BYTES) {
+    throw new Error(`Flow progress object must encode to at most ${MAX_PROGRESS_JSON_BYTES} bytes`);
+  }
+  return { progress: 0, message };
+}
+
+function validateProgress(payload: Record<string, unknown>): void {
+  normalizeFlowProgressPayload(payload);
+}
+
+function optionalProgressMessage(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== 'string' ||
+    new TextEncoder().encode(value).byteLength > MAX_PROGRESS_JSON_BYTES
+  ) {
+    throw new Error('Flow progress message must be a string of at most 65536 bytes');
+  }
+  return value;
+}
+
+function validateJsonValue(
+  value: unknown,
+  ancestors: WeakSet<object>,
+  budget: { count: number },
+  depth: number
+): void {
+  budget.count += 1;
+  if (budget.count > MAX_PROGRESS_VALUES) {
+    throw new Error(`Flow progress object may contain at most ${MAX_PROGRESS_VALUES} values`);
+  }
+  if (depth > MAX_PROGRESS_DEPTH) {
+    throw new Error(`Flow progress object may be at most ${MAX_PROGRESS_DEPTH} levels deep`);
+  }
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('Flow progress object must contain valid JSON');
+    return;
+  }
+  if (typeof value !== 'object') throw new Error('Flow progress object must contain valid JSON');
+  if (ancestors.has(value)) throw new Error('Flow progress object must not contain cycles');
+  if (!Array.isArray(value) && !isPlainRecord(value)) {
+    throw new Error('Flow progress object must use only plain JSON objects and arrays');
+  }
+  if (Array.isArray(value) && Object.getPrototypeOf(value) !== Array.prototype) {
+    throw new Error('Flow progress object must use only plain JSON objects and arrays');
+  }
+  ancestors.add(value);
+  validateJsonProperties(value, ancestors, budget, depth);
+  ancestors.delete(value);
+}
+
+function validateJsonProperties(
+  value: object,
+  ancestors: WeakSet<object>,
+  budget: { count: number },
+  depth: number
+): void {
+  if (Array.isArray(value)) validateJsonArrayShape(value);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (Array.isArray(value) && key === 'length') continue;
+    if (typeof key !== 'string' || UNSAFE_JSON_KEYS.has(key)) {
+      throw new Error('Flow progress object contains an unsafe property name');
+    }
+    const descriptor = descriptors[key];
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) {
+      throw new Error('Flow progress object must contain plain enumerable JSON values');
+    }
+    validateJsonValue(descriptor.value, ancestors, budget, depth + 1);
+  }
+}
+
+function validateJsonArrayShape(value: unknown[]): void {
+  if (value.length > MAX_PROGRESS_VALUES) {
+    throw new Error(`Flow progress object may contain at most ${MAX_PROGRESS_VALUES} values`);
+  }
+  const keys = Object.keys(value);
+  if (
+    keys.length !== value.length ||
+    keys.some((key, index) => key !== String(index) || !Object.hasOwn(value, index))
+  ) {
+    throw new Error('Flow progress object must contain dense arrays without extra properties');
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function boundedInteger(value: unknown, label: string, maximum: number): void {
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > maximum) {
+    throw new Error(`Flow ${label} must be an integer from 0 to ${maximum}`);
+  }
+}

package/agent/index.ts

@@ -9,11 +9,18 @@
  *
  * Run:  bun run agent/index.ts        (default port 6800)
  * Env:  AGENT_PORT, AGENT_ALLOWED_ORIGINS, AGENT_TOKEN,
- *       BUNQUEUE_START_CMD, HTTP_PORT, TCP_PORT, BUNQUEUE_DATA_PATH
+ *       BUNQUEUE_START_CMD, BUNQUEUE_MANAGED, BUNQUEUE_URL, BUNQUEUE_TOKEN,
+ *       HTTP_PORT, TCP_PORT, BUNQUEUE_DATA_PATH
  */
 import { logger } from './logger';
 import { ProcessManager } from './manager';
-import { createFetchHandler, resolveAllowedHosts, resolveAllowedOrigins } from './server';
+import {
+  createFetchHandler,
+  resolveAllowedHosts,
+  resolveAllowedOrigins,
+  resolveServerControlTarget,
+} from './server';
+import { installAgentShutdown } from './shutdown';
 
 const mgr = new ProcessManager();
 const PORT = Number(process.env.AGENT_PORT) || 6800;
@@ -24,32 +31,26 @@ const allowedOrigins = resolveAllowedOrigins();
 // GETs. Extend via AGENT_ALLOWED_HOSTS when fronted by a proxy on another host.
 const allowedHosts = resolveAllowedHosts();
 const token = process.env.AGENT_TOKEN || undefined;
+const controlTarget = resolveServerControlTarget(process.env);
 
-const handle = createFetchHandler(mgr, { allowedOrigins, allowedHosts, token });
+const handle = createFetchHandler(mgr, { allowedOrigins, allowedHosts, token, controlTarget });
+const stopAccepting: Array<() => unknown | Promise<unknown>> = [];
+installAgentShutdown(handle, { stopAccepting });
 
-Bun.serve({
+const server = Bun.serve({
   port: PORT,
   hostname: '127.0.0.1',
   fetch: handle,
 });
-
-// Stop the managed server before exiting — without this, Ctrl-C / SIGTERM on
-// the agent orphans the spawned bunqueue child (it reparents to PID 1 and keeps
-// holding the ports and the SQLite db, so the next start fails EADDRINUSE).
-let shuttingDown = false;
-const shutdown = (signal: string) => {
-  if (shuttingDown) return;
-  shuttingDown = true;
-  logger.info({ signal }, 'signal received, stopping managed server');
-  // shutdown() (not stop()) latches the manager closed first: a plain stop()
-  // racing an in-flight restart() returns successfully *because* restart's
-  // start() already spawned a replacement — which process.exit() would orphan.
-  void mgr.shutdown().finally(() => process.exit(0));
-};
-process.on('SIGINT', () => shutdown('SIGINT'));
-process.on('SIGTERM', () => shutdown('SIGTERM'));
+stopAccepting.push(() => server.stop());
 
 logger.info(
-  { url: `http://127.0.0.1:${PORT}/control`, allowedOrigins, allowedHosts, tokenAuth: Boolean(token) },
+  {
+    url: `http://127.0.0.1:${PORT}/control`,
+    allowedOrigins,
+    allowedHosts,
+    tokenAuth: Boolean(token),
+    serverManagement: controlTarget.mode,
+  },
   'bunqueue dashboard control agent ready'
 );

package/agent/logger.ts

@@ -42,29 +42,133 @@ const isTTY = !!process.stdout.isTTY;
 
 const pad2 = (n: number): string => String(n).padStart(2, '0');
 const clock = (d: Date): string => `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+const RESERVED_FIELDS = new Set(['level', 'time', 'msg', 'toJSON', 'logSerializationError']);
+const UNSAFE_FIELDS = '[Unsafe log fields omitted]';
+const UNSERIALIZABLE_FIELDS = '[Unserializable log fields]';
 
-function write(level: LogLevel, a?: unknown, b?: unknown): void {
-  if (LEVELS[level] < threshold) return;
+function json(value: unknown): string | null {
+  const seen = new WeakSet<object>();
+  try {
+    return (
+      JSON.stringify(value, (_key, current: unknown) => {
+        if (typeof current === 'bigint') return current.toString();
+        if (typeof current === 'symbol') return `[${String(current)}]`;
+        if (typeof current === 'function') return `[Function ${current.name || 'anonymous'}]`;
+        if (typeof current === 'object' && current !== null) {
+          if (seen.has(current)) return '[Circular]';
+          seen.add(current);
+        }
+        return current;
+      }) ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+function safeText(value: unknown): string {
+  if (typeof value === 'string') return value;
+  try {
+    return value === undefined ? '' : String(value);
+  } catch {
+    return '[Unprintable log message]';
+  }
+}
+
+function safeFields(value: unknown): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if ((typeof value !== 'object' || value === null) && typeof value !== 'function') {
+    return { value };
+  }
+  const fields: Record<string, unknown> = Object.create(null);
+  let unsafe = false;
+  let keys: PropertyKey[];
+  try {
+    keys = Reflect.ownKeys(value);
+  } catch {
+    return { logSerializationError: UNSERIALIZABLE_FIELDS };
+  }
+  for (const key of keys) {
+    if (typeof key !== 'string') continue;
+    if (RESERVED_FIELDS.has(key)) {
+      unsafe = true;
+      continue;
+    }
+    let descriptor: PropertyDescriptor | undefined;
+    try {
+      descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+    } catch {
+      return { logSerializationError: UNSERIALIZABLE_FIELDS };
+    }
+    if (!descriptor?.enumerable) continue;
+    if ('value' in descriptor) fields[key] = descriptor.value;
+    else {
+      fields[key] = '[Accessor log field omitted]';
+      unsafe = true;
+    }
+  }
+  if (unsafe) fields.logSerializationError = UNSAFE_FIELDS;
+  return fields;
+}
+
+function logLine(level: LogLevel, obj: unknown, msg: unknown): string {
+  const time = Date.now();
+  const record: Record<string, unknown> = Object.create(null);
+  record.level = LEVELS[level];
+  record.time = time;
+  const fields = safeFields(obj);
+  if (fields) {
+    for (const [key, value] of Object.entries(fields)) record[key] = value;
+  }
+  record.msg = safeText(msg);
+  const line = json(record);
+  if (line) return line;
+  return JSON.stringify({
+    level: LEVELS[level],
+    time,
+    logSerializationError: UNSERIALIZABLE_FIELDS,
+    msg: safeText(msg),
+  });
+}
+
+function logArguments(a?: unknown, b?: unknown): { obj: unknown; msg: unknown } {
   // pino signature: (mergeObject, message) or just (message). An Error as the
   // first arg gets its message/stack lifted explicitly — Error props are
   // non-enumerable, so a plain spread would silently log `{}`.
-  const [obj, msg] =
-    typeof a === 'string'
-      ? [undefined, a]
-      : a instanceof Error
-        ? [{ err: { message: a.message, stack: a.stack } }, b as string | undefined]
-        : [a as Record<string, unknown> | undefined, b as string | undefined];
+  let obj: unknown;
+  let msg: unknown;
+  if (typeof a === 'string') {
+    msg = a;
+  } else {
+    msg = b;
+    try {
+      obj =
+        a instanceof Error
+          ? { err: { name: a.name, message: a.message, stack: a.stack } }
+          : (a as Record<string, unknown> | undefined);
+    } catch {
+      obj = { err: '[Uninspectable log argument]' };
+    }
+  }
+  return { obj, msg };
+}
 
-  if (isTTY) {
-    const fields = obj && Object.keys(obj).length ? ` ${DIM}${JSON.stringify(obj)}${RESET}` : '';
-    console.log(
-      `${DIM}${clock(new Date())}${RESET} ${COLORS[level]}${level.toUpperCase().padEnd(5)}${RESET} ${msg ?? ''}${fields}`
-    );
-    return;
+export function formatLogEntry(level: LogLevel, a?: unknown, b?: unknown, tty = isTTY): string {
+  const { obj, msg } = logArguments(a, b);
+  if (tty) {
+    const fieldsObject = safeFields(obj);
+    const serialized = fieldsObject
+      ? (json(fieldsObject) ?? JSON.stringify({ logSerializationError: UNSERIALIZABLE_FIELDS }))
+      : null;
+    const fields = serialized && serialized !== '{}' ? ` ${DIM}${serialized}${RESET}` : '';
+    return `${DIM}${clock(new Date())}${RESET} ${COLORS[level]}${level.toUpperCase().padEnd(5)}${RESET} ${safeText(msg)}${fields}`;
   }
-  console.log(
-    JSON.stringify({ level: LEVELS[level], time: Date.now(), ...(obj ?? {}), msg: msg ?? '' })
-  );
+  return logLine(level, obj, msg);
+}
+
+function write(level: LogLevel, a?: unknown, b?: unknown): void {
+  if (LEVELS[level] < threshold) return;
+  console.log(formatLogEntry(level, a, b));
 }
 
 export const logger = {

package/agent/managedTarget.ts

@@ -0,0 +1,82 @@
+import type { ServerConfig } from './manager';
+
+const MANAGED_PROXY_PATH_PATTERN = /^\/(?:[A-Za-z0-9._~-]+\/)*api$/;
+
+export interface ManagedTargetPolicy {
+  /** Exact browser-visible proxy alias accepted in addition to legacy `/api`. */
+  proxyPath: string;
+  /** Local upstream represented by the alias; it still passes the anti-SSRF gate. */
+  proxyUrl?: string;
+}
+
+/** Validate the one browser-visible proxy path that aliases the local managed server. */
+export function resolveManagedProxyPath(value: string | undefined): string {
+  const path = value?.trim() || '/api';
+  if (
+    !MANAGED_PROXY_PATH_PATTERN.test(path) ||
+    path.split('/').some((segment) => segment === '.' || segment === '..')
+  ) {
+    throw new Error('Managed proxy path must be /api or a safe root-relative path ending in /api');
+  }
+  return path;
+}
+
+/** Resolve the alias once without cloning a request or touching its body stream. */
+export function resolveManagedTargetPolicy(
+  proxyPath: string | undefined,
+  proxyUrl?: string
+): ManagedTargetPolicy {
+  return {
+    proxyPath: resolveManagedProxyPath(proxyPath),
+    proxyUrl: proxyUrl?.trim() || undefined,
+  };
+}
+
+/** Refuse agent-side SDK operations for a server the agent does not manage. */
+export function assertManagedTarget(
+  query: URLSearchParams,
+  config: ServerConfig,
+  policy: ManagedTargetPolicy | string =
+    process.env.BUNQUEUE_URL?.trim() || 'http://localhost:6790'
+): void {
+  const target = query.get('target');
+  if (!target) throw new Error('Managed Bunqueue target is required');
+  const proxyPath =
+    typeof policy === 'string' ? '/api' : resolveManagedProxyPath(policy.proxyPath);
+  const proxyTarget =
+    (typeof policy === 'string' ? policy : policy.proxyUrl?.trim()) ||
+    process.env.BUNQUEUE_URL?.trim() ||
+    'http://localhost:6790';
+  if (target === '/api' || target === proxyPath) {
+    assertLocalTarget(proxyTarget, config, 'Dashboard /api proxy');
+    return;
+  }
+  assertLocalTarget(target, config, 'Managed target');
+}
+
+/** Resolve the exact AUTH_TOKENS value inherited by the managed child. */
+export function managedAuthToken(config: ServerConfig): string | undefined {
+  const configured = Object.hasOwn(config.extraEnv, 'AUTH_TOKENS')
+    ? config.extraEnv.AUTH_TOKENS
+    : process.env.AUTH_TOKENS;
+  return configured
+    ?.split(',')
+    .map((token) => token.trim())
+    .find(Boolean);
+}
+
+function assertLocalTarget(target: string, config: ServerConfig, label: string): void {
+  let url: URL;
+  try {
+    url = new URL(target);
+  } catch {
+    throw new Error(`${label} must be an absolute local HTTP URL`);
+  }
+  const local = ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+  if (!local || port !== config.httpPort || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+    throw new Error(
+      `${label} ${target} does not match the agent-managed Bunqueue server on port ${config.httpPort}`
+    );
+  }
+}

package/agent/manager/config.ts

@@ -0,0 +1,84 @@
+import type { ServerConfig } from './types';
+
+const CONFIG_KEYS = new Set<keyof ServerConfig>([
+  'command',
+  'httpPort',
+  'tcpPort',
+  'dataPath',
+  'extraEnv',
+]);
+
+export function defaultConfig(): ServerConfig {
+  return {
+    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.8.59 start',
+    httpPort: Number(process.env.HTTP_PORT) || 6790,
+    tcpPort: Number(process.env.TCP_PORT) || 6789,
+    dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',
+    extraEnv: {},
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function validatePort(name: 'httpPort' | 'tcpPort', value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65_535) {
+    throw new Error(`${name} must be an integer between 1 and 65535`);
+  }
+  return value;
+}
+
+/** Validate an untrusted PUT /control/config body before merging any field. */
+export function validateConfigPatch(value: unknown): Partial<ServerConfig> {
+  if (!isRecord(value)) throw new Error('Config must be an object');
+  for (const key of Object.keys(value)) {
+    if (!CONFIG_KEYS.has(key as keyof ServerConfig)) {
+      throw new Error(`Unknown config key: ${key}`);
+    }
+  }
+
+  const patch: Partial<ServerConfig> = {};
+  if (Object.hasOwn(value, 'command')) {
+    if (typeof value.command !== 'string' || value.command.trim() === '') {
+      throw new Error('command must be a non-empty string');
+    }
+    patch.command = value.command;
+  }
+  if (Object.hasOwn(value, 'httpPort')) {
+    patch.httpPort = validatePort('httpPort', value.httpPort);
+  }
+  if (Object.hasOwn(value, 'tcpPort')) {
+    patch.tcpPort = validatePort('tcpPort', value.tcpPort);
+  }
+  if (Object.hasOwn(value, 'dataPath')) {
+    if (typeof value.dataPath !== 'string') throw new Error('dataPath must be a string');
+    patch.dataPath = value.dataPath;
+  }
+  if (Object.hasOwn(value, 'extraEnv')) {
+    if (!isRecord(value.extraEnv)) {
+      throw new Error('extraEnv must be an object containing only string values');
+    }
+    const entries = Object.entries(value.extraEnv);
+    for (const [key, entry] of entries) {
+      if (typeof entry !== 'string') throw new Error(`extraEnv.${key} must be a string`);
+    }
+    patch.extraEnv = Object.fromEntries(entries) as Record<string, string>;
+  }
+  return patch;
+}
+
+export function validateServerConfig(value: unknown): ServerConfig {
+  if (!isRecord(value)) throw new Error('Config must be an object');
+  const config = validateConfigPatch(value);
+  for (const key of CONFIG_KEYS) {
+    if (!Object.hasOwn(value, key)) throw new Error(`Missing config key: ${key}`);
+  }
+  return config as ServerConfig;
+}
+
+export function copyConfig(config: ServerConfig): ServerConfig {
+  return { ...config, extraEnv: { ...config.extraEnv } };
+}