@harperfast/harper 5.2.0-beta.1 → 5.2.0-beta.2

package/resources/scheduler/scheduler.ts

@@ -0,0 +1,236 @@
+import { isAbsolute, join } from 'node:path';
+import { getWorkerIndex } from '../../server/threads/manageThreads.js';
+import { ClientError } from '../../utility/errors/hdbError.ts';
+import { convertToMS } from '../../utility/common_utils.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import { CronExpression, validateTimezone } from './CronExpression.ts';
+import {
+	registerComponentJobs,
+	safeErrorMessage,
+	startSchedulerEngine,
+	unregisterComponentJobs,
+	type JobRunContext,
+	type ScheduledJob,
+} from './engine.ts';
+
+const schedulerLogger = harperLogger.forComponent('scheduler');
+
+export class SchedulerConfigError extends ClientError {
+	constructor(message: string) {
+		super(message, 400);
+		this.name = 'SchedulerConfigError';
+	}
+}
+
+const MIN_INTERVAL_MS = 1000;
+// Generous for any real maintenance cadence while keeping fire-time
+// arithmetic comfortably inside Date range
+const MAX_INTERVAL_MS = 365 * 24 * 60 * 60 * 1000;
+const KNOWN_JOB_KEYS = new Set(['name', 'cron', 'interval', 'timezone', 'handler']);
+
+interface SchedulerJobConfig {
+	name?: unknown;
+	cron?: unknown;
+	interval?: unknown;
+	timezone?: unknown;
+	handler?: unknown;
+}
+
+/**
+ * Built-in `scheduler` plugin (issue #951): lets a component declare recurring
+ * jobs in its config and have core invoke a designated export on that
+ * schedule, exactly once per cluster (leader election and failover live in
+ * ./engine.ts).
+ *
+ * ```yaml
+ * scheduler:
+ *   jobs:
+ *     - name: daily-metrics-snapshot
+ *       cron: '0 2 * * *'
+ *       timezone: America/New_York   # optional; defaults to the server timezone
+ *       handler: ./jobs.ts#snapshotMetrics
+ *     - name: sync-exchange-rates
+ *       interval: 15m                # simple cadence instead of cron
+ *       handler: ./jobs.ts#syncExchangeRates
+ * ```
+ *
+ * The handler reference is `<module path>#<named export>` relative to the
+ * component directory (omit `#...` to use the module's default export). The
+ * handler is invoked with a {@link JobRunContext} and may return a promise.
+ *
+ * Handlers should be idempotent: leadership failover (the lease has no
+ * compare-and-set) and DST fall-back can occasionally deliver the same logical
+ * occurrence twice. Conversely, catch-up only makes up the single most recent
+ * missed occurrence of a cron job — a leader down for an extended outage does
+ * not backfill every occurrence it missed.
+ */
+export async function handleApplication(scope): Promise<void> {
+	// Validation runs UNCONDITIONALLY — on every worker and on deploy
+	// pre-flight validation loads, which land on an arbitrary worker. Gating
+	// validation behind worker 0 would let a bad config pass pre-flight
+	// nondeterministically and then fail cluster-wide at the next restart
+	// (review finding). Only ACTIVATION is gated below.
+	const config = scope.options.getAll() ?? {};
+	// null covers the common "all jobs commented out" edit, which YAML parses
+	// as `jobs: null` — that must degrade like an absent key, not fail the
+	// whole component load (audit finding)
+	if (config.jobs == null) {
+		schedulerLogger.warn?.(`Component ${scope.appName} has a scheduler block with no jobs`);
+		return;
+	}
+	if (!Array.isArray(config.jobs)) {
+		throw new SchedulerConfigError(`scheduler.jobs in component ${scope.appName} must be an array of job entries`);
+	}
+
+	const jobs: ScheduledJob[] = [];
+	const seenNames = new Set<string>();
+	for (const jobConfig of config.jobs as SchedulerJobConfig[]) {
+		const job = await buildJob(scope, jobConfig);
+		if (seenNames.has(job.name)) {
+			throw new SchedulerConfigError(`Duplicate scheduler job name "${job.name}" in component ${scope.appName}`);
+		}
+		seenNames.add(job.name);
+		jobs.push(job);
+	}
+
+	// Activation gates: one worker owns scheduling for the whole node
+	// (getWorkerIndex() === 0 is correct in every threading mode, including
+	// threads:0 where the main thread acts as worker 0), and a deploy
+	// pre-flight validation scope must never touch the live engine — it can
+	// share a running component's identity, so registering from it would
+	// displace the real component's jobs (review finding).
+	if (getWorkerIndex() !== 0) {
+		schedulerLogger.debug?.('Scheduler config validated; activation skipped on non-primary worker');
+		return;
+	}
+	if (scope.isTransientValidation) {
+		schedulerLogger.debug?.(`Scheduler config validated for ${scope.appName}; activation skipped for validation load`);
+		return;
+	}
+
+	registerComponentJobs(scope.appName, jobs);
+	// A closing scope (worker shutdown or redeploy) must take its timers with it
+	scope.on('close', () => unregisterComponentJobs(scope.appName));
+	// Scope only requests a restart on option CHANGES; deleting the whole
+	// scheduler: block emits 'remove', which nothing else consumes — without
+	// this, a dev-watch session keeps firing jobs whose config is gone
+	// (audit finding)
+	scope.options.on('remove', () => scope.requestRestart());
+	startSchedulerEngine();
+	schedulerLogger.trace?.(`Registered ${jobs.length} scheduled job(s) for component ${scope.appName}`);
+}
+
+async function buildJob(scope, jobConfig: SchedulerJobConfig): Promise<ScheduledJob> {
+	const componentName = scope.appName;
+	if (typeof jobConfig !== 'object' || jobConfig === null) {
+		throw new SchedulerConfigError(`Each scheduler.jobs entry in component ${componentName} must be an object`);
+	}
+	const { name, cron, interval, timezone, handler } = jobConfig;
+	// The schema declares additionalProperties: false but is IDE-only; without
+	// this runtime check a misspelled OPTIONAL key (timeZone:, timzone:) is
+	// silently dropped and the job runs with different behavior — e.g. a cron
+	// evaluated in the server timezone instead of the intended one
+	// (audit finding)
+	const unknownKeys = Object.keys(jobConfig).filter((key) => !KNOWN_JOB_KEYS.has(key));
+	if (unknownKeys.length > 0) {
+		throw new SchedulerConfigError(
+			`Scheduler job entry in component ${componentName} has unrecognized key(s): ${unknownKeys.join(', ')} (allowed: name, cron, interval, timezone, handler)`
+		);
+	}
+	if (typeof name !== 'string' || name.length === 0) {
+		throw new SchedulerConfigError(`Every scheduler job in component ${componentName} needs a non-empty string name`);
+	}
+	if ((cron === undefined) === (interval === undefined)) {
+		throw new SchedulerConfigError(
+			`Scheduler job "${name}" in component ${componentName} must declare exactly one of "cron" or "interval"`
+		);
+	}
+	if (typeof handler !== 'string' || handler.length === 0) {
+		throw new SchedulerConfigError(
+			`Scheduler job "${name}" in component ${componentName} needs a handler like "./jobs.ts#myExport"`
+		);
+	}
+
+	const job: ScheduledJob = {
+		name,
+		componentName,
+		handler: await resolveHandler(scope, name, handler),
+	};
+	if (cron !== undefined) {
+		if (typeof cron !== 'string') {
+			throw new SchedulerConfigError(`Scheduler job "${name}" in component ${componentName}: "cron" must be a string`);
+		}
+		job.cron = new CronExpression(cron);
+		if (timezone !== undefined) {
+			if (typeof timezone !== 'string') {
+				throw new SchedulerConfigError(
+					`Scheduler job "${name}" in component ${componentName}: "timezone" must be an IANA timezone string`
+				);
+			}
+			job.timezone = validateTimezone(timezone);
+		}
+	} else {
+		if (timezone !== undefined) {
+			throw new SchedulerConfigError(
+				`Scheduler job "${name}" in component ${componentName}: "timezone" only applies to cron schedules`
+			);
+		}
+		// convertToMS silently treats any unrecognized unit as seconds (e.g.
+		// '500ms' would become 500 seconds); restrict to the documented forms
+		if (typeof interval === 'string' && !/^\d+(\.\d+)?[smhd]?$/.test(interval.trim())) {
+			throw new SchedulerConfigError(
+				`Scheduler job "${name}" in component ${componentName}: interval "${interval}" is not a supported duration — use a number of seconds or a value like 90s, 5m, 1h, 1d`
+			);
+		}
+		const intervalMs = convertToMS(typeof interval === 'string' ? interval.trim() : interval);
+		// Both bounds matter: values that overflow Date arithmetic (YAML .inf,
+		// 1e309, or absurdly large finite numbers) would otherwise produce an
+		// Invalid Date downstream, whose NaN delay Node's setTimeout coerces to
+		// ~1ms — turning a "practically never" interval into a hot loop
+		// (review finding)
+		if (!Number.isFinite(intervalMs) || intervalMs < MIN_INTERVAL_MS || intervalMs > MAX_INTERVAL_MS) {
+			throw new SchedulerConfigError(
+				`Scheduler job "${name}" in component ${componentName}: interval "${interval}" must be between 1 second and 365 days (e.g. 90s, 5m, 1h, 1d)`
+			);
+		}
+		job.intervalMs = intervalMs;
+	}
+	return job;
+}
+
+/**
+ * Resolve a `<module path>#<named export>` handler reference to a callable,
+ * loading the module inside the component's own realm via scope.import so the
+ * handler sees the same globals (tables, databases, …) as the rest of the
+ * component's code. Resolving eagerly makes a bad reference fail the component
+ * load — visible at deploy time — instead of failing silently at first fire.
+ */
+async function resolveHandler(
+	scope,
+	jobName: string,
+	handlerReference: string
+): Promise<(context: JobRunContext) => unknown> {
+	const hashIndex = handlerReference.indexOf('#');
+	const modulePath = hashIndex >= 0 ? handlerReference.slice(0, hashIndex) : handlerReference;
+	const exportName = hashIndex >= 0 ? handlerReference.slice(hashIndex + 1) : 'default';
+	const absolutePath = isAbsolute(modulePath) ? modulePath : join(scope.directory, modulePath);
+	let handlerModule;
+	try {
+		handlerModule = await scope.import(absolutePath);
+	} catch (error) {
+		// User modules can throw primitives or frozen errors, so wrap (with
+		// cause) instead of mutating the caught value's message
+		const loadError = new SchedulerConfigError(
+			`Scheduler job "${jobName}" in component ${scope.appName}: could not load handler module "${modulePath}": ${safeErrorMessage(error)}`
+		);
+		loadError.cause = error;
+		throw loadError;
+	}
+	const handler = handlerModule?.[exportName];
+	if (typeof handler !== 'function') {
+		throw new SchedulerConfigError(
+			`Scheduler job "${jobName}" in component ${scope.appName}: "${modulePath}" has no function export named "${exportName}"`
+		);
+	}
+	return handler;
+}

package/security/auth.ts

@@ -424,6 +424,7 @@ export function handleApplication(scope: import('../components/Scope.ts').Scope)
 	started = true;
 	const { port, securePort }: any = scope.options.getAll() as { port?: number; securePort?: number };
 	const httpOpts = port || securePort ? ({ port, securePort } as any) : ({ port: 'all' } as any);
+	httpOpts.name = 'authentication';
 	scope.server.http(authentication, httpOpts);
 }
 

package/security/jsLoader.ts

@@ -3,6 +3,8 @@ import { contextStorage, transaction } from '../resources/transaction.ts';
 import { RequestTarget } from '../resources/RequestTarget.ts';
 import { tables, databases } from '../resources/databases.ts';
 import { models as harperModelsSingleton } from '../resources/models/Models.ts';
+import { defineTable, types } from '../resources/defineTable.ts';
+import { defineResource, t, schemaOf, projectTableFragment } from '../resources/defineResource.ts';
 import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
@@ -805,6 +807,12 @@ function getHarperExports(scope: ApplicationScope) {
 		Resource,
 		tables,
 		databases,
+		defineTable,
+		types,
+		defineResource,
+		t,
+		schemaOf,
+		projectTableFragment,
 		// `harper.models` — same singleton that's surfaced as the top-level
 		// `models` package export (see `resources/models/Models.ts`).  The
 		// registry it reads from is populated at boot by

package/security/keys.ts

@@ -820,6 +820,139 @@ if (typeof globalThis.Bun === 'undefined') {
 
 let caCerts = new Map();
 
+const SECLEVEL_PATTERN = /@SECLEVEL=(\d+)/i;
+/** Split a cipher string into its suite list and its explicit `@SECLEVEL` (undefined when unset). */
+function parseCipherString(ciphers) {
+	const match = SECLEVEL_PATTERN.exec(ciphers);
+	return {
+		suite: ciphers.replace(SECLEVEL_PATTERN, '').trim() || undefined,
+		level: match ? Number(match[1]) : undefined,
+	};
+}
+
+/**
+ * Whether a certificate (record or `tls[]` entry) can affect the given listener, mirroring
+ * createTLSSelector's tolerant selection: no `uses` is a generic certificate, `'https'` is the
+ * legacy generic use, and an authority matters exactly when the listener verifies client chains.
+ */
+function ciphersCandidateRelevant(usesRaw, isAuthority, servesCertificate, type, verifiesClientCerts) {
+	if (isAuthority && verifiesClientCerts) return true;
+	if (!servesCertificate) return false;
+	// normalize: stored as scalar in legacy/manual entries, expected array
+	const uses = Array.isArray(usesRaw) ? usesRaw : usesRaw ? [usesRaw] : [];
+	return uses.length === 0 || uses.includes(type) || uses.includes('https');
+}
+
+/**
+ * Resolve the single cipher string that actually governs a TLS listener.
+ *
+ * OpenSSL takes the cipher list — and any `@SECLEVEL=n` embedded in it, which controls
+ * client-certificate chain verification — from the context the server was created with. A context
+ * swapped in later by the SNI callback does not carry its own cipher list onto the connection,
+ * so per-certificate `ciphers` — whether on a `tls` array entry or a certificate record — cannot
+ * take effect on their own; a listener has exactly one effective cipher string. Historically only
+ * `tls.ciphers ?? tls[0].ciphers` was applied and every other configured value was silently
+ * ignored, including a CA record needing a relaxed security level to verify legacy client chains
+ * (e.g. SHA-1-signed CAs requiring `DEFAULT@SECLEVEL=0`, which fail with
+ * `authorizationError: UNSPECIFIED` at the default level).
+ *
+ * Resolution composes rather than picks a winner, because `@SECLEVEL` and the suite list are
+ * separable OpenSSL commands:
+ * 1. Candidates come from the listener's config layers in priority order (`configLayers`, e.g.
+ *    `operationsApi.tls` before root `tls` — an object's `ciphers` directly, an array's entries
+ *    filtered by {@link ciphersCandidateRelevant}) and then from relevant certificate records.
+ * 2. The suite list comes from the highest-priority suite-bearing candidate — a CA needing a
+ *    relaxed level must not replace or broaden the listener's configured suites.
+ * 3. The security level is the minimum explicit `@SECLEVEL` across candidates (a chain that needs
+ *    the relaxed level fails outright without it; the others merely also accept it). Candidates
+ *    without an explicit `@SECLEVEL` keep the runtime default — no level is assumed for them,
+ *    since the OpenSSL default varies across Node builds.
+ * Anything composed across sources or dropped (extra suite lists) is logged as a warning.
+ */
+export function resolveEffectiveTlsCiphers(configLayers, certRecords, type, verifiesClientCerts): string | undefined {
+	const candidates = [];
+	for (const { source, config } of configLayers ?? []) {
+		if (!config) continue;
+		if (Array.isArray(config)) {
+			for (let index = 0; index < config.length; index++) {
+				const entry = config[index];
+				if (!entry?.ciphers) continue;
+				const isAuthority = Boolean(entry.certificateAuthority);
+				const servesCertificate = Boolean(entry.certificate) || !isAuthority;
+				if (ciphersCandidateRelevant(entry.uses, isAuthority, servesCertificate, type, verifiesClientCerts)) {
+					candidates.push({ source: `${source}[${index}]`, ciphers: entry.ciphers });
+				}
+			}
+		} else if (config.ciphers) {
+			// an object layer's ciphers is the listener config's own knob — always relevant
+			candidates.push({ source: `${source}.ciphers`, ciphers: config.ciphers });
+		}
+	}
+	for (const cert of certRecords ?? []) {
+		if (!cert?.ciphers) continue;
+		// authority records are never served as listener certs — they matter only for verification
+		if (
+			ciphersCandidateRelevant(cert.uses, Boolean(cert.is_authority), !cert.is_authority, type, verifiesClientCerts)
+		) {
+			candidates.push({ source: `certificate '${cert.name}'`, ciphers: cert.ciphers });
+		}
+	}
+	if (candidates.length === 0) return undefined;
+
+	const parsed = candidates.map((candidate) => ({ ...candidate, ...parseCipherString(candidate.ciphers) }));
+	const suiteBearing = parsed.filter((candidate) => candidate.suite);
+	const suiteSource = suiteBearing[0];
+	let levelSource;
+	for (const candidate of parsed) {
+		if (candidate.level !== undefined && (levelSource === undefined || candidate.level < levelSource.level)) {
+			levelSource = candidate;
+		}
+	}
+	// no suite anywhere means a bare @SECLEVEL override — anchor it to DEFAULT
+	const suite = suiteSource?.suite ?? 'DEFAULT';
+	const effective = levelSource === undefined ? suite : `${suite}@SECLEVEL=${levelSource.level}`;
+
+	const notes = [];
+	const droppedSuites = suiteBearing.filter((candidate) => candidate.suite !== suiteSource.suite);
+	if (droppedSuites.length) {
+		notes.push(
+			`suites from ${suiteSource.source} ('${suiteSource.suite}'); ignoring suite lists from ${droppedSuites
+				.map((candidate) => `${candidate.source} ('${candidate.suite}')`)
+				.join(', ')}`
+		);
+	}
+	if (levelSource !== undefined && levelSource.source !== suiteSource?.source) {
+		notes.push(`security level ${levelSource.level} required by ${levelSource.source}`);
+	}
+	if (notes.length) {
+		logger.warn?.(
+			`Composed TLS cipher configuration for the '${type}' listener ('${effective}'): ${notes.join('; ')} — a listener has a single effective cipher string`
+		);
+	}
+	return effective;
+}
+
+/**
+ * Resolve the effective cipher string for a listener from the live config and certificate table.
+ * Safe to call before the certificate table exists (install, early boot) — config-only then.
+ */
+export function getEffectiveTlsCiphers(type, mtlsOptions?): string | undefined {
+	let certRecords;
+	try {
+		certRecords = databases?.system?.hdb_certificate?.search([]);
+	} catch (error) {
+		logger.trace?.('Certificate table not available while resolving TLS ciphers', error);
+	}
+	const configLayers = [];
+	// the operations API listener has its own tls section (merged separately by config
+	// composition, may inherit the root certificate while overriding ciphers) — it outranks root
+	if (type === 'operations-api') {
+		configLayers.push({ source: 'operationsApi.tls', config: envManager.get(CONFIG_PARAMS.OPERATIONSAPI_TLS) });
+	}
+	configLayers.push({ source: 'tls', config: envManager.get('tls') });
+	return resolveEffectiveTlsCiphers(configLayers, certRecords, type, Boolean(mtlsOptions));
+}
+
 /**
  * Create a TLS selector that will choose the best TLS configuration/context for a given hostname
  * @param type
@@ -952,6 +1085,25 @@ export function createTLSSelector(type, mtlsOptions?, liveReload = true): any {
 							logger.error?.('Error applying TLS for', cert.name, error);
 						}
 					}
+					// The listener's cipher string (and its @SECLEVEL, which governs client-cert chain
+					// verification) is fixed at server creation and cannot be swapped by rebuilding SNI
+					// contexts. If a rebuild finds the effective value has changed (e.g. a certificate
+					// record with `ciphers` was added), the listener won't honor it until restart — warn
+					// instead of silently serving with the stale value.
+					if (server && server.appliedCiphers !== undefined) {
+						// use the same verifies-client-certs flag the listener was created with (http servers
+						// derive it from more than the selector's mtlsOptions) so this compares like with like
+						const effectiveCiphers =
+							getEffectiveTlsCiphers(type, server.verifiesClientCerts ?? Boolean(mtlsOptions)) ?? null;
+						// latch per distinct value: rebuilds recur (cert-table changes, key reloads) and the
+						// pending change shouldn't re-warn on every cycle until the restart happens
+						if (effectiveCiphers !== server.appliedCiphers && server.lastWarnedCiphers !== effectiveCiphers) {
+							server.lastWarnedCiphers = effectiveCiphers;
+							logger.warn?.(
+								`TLS cipher configuration for the '${type}' listener is now '${effectiveCiphers}' but the listener was started with '${server.appliedCiphers}' — a restart is required to apply it`
+							);
+						}
+					}
 					server?.secureContextsListeners.forEach((listener) => listener());
 					resolve(defaultContext);
 				} catch (error) {

package/server/REST.ts

@@ -1,3 +1,5 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { serialize, serializeMessage, getDeserializer } from '../server/serverHelpers/contentTypes.ts';
 import { addAnalyticsListener, recordAction, recordActionBinary } from '../resources/analytics/write.ts';
 import * as harperLogger from '../utility/logging/harper_logger.ts';
@@ -8,6 +10,10 @@ import { IterableEventQueue } from '../resources/IterableEventQueue.ts';
 import { transaction } from '../resources/transaction.ts';
 import { Headers, mergeHeaders } from '../server/serverHelpers/Headers.ts';
 import { generateJsonApi } from '../resources/openApi.ts';
+import { getConfigPath } from '../config/configUtils.ts';
+import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import { ASIDE_STAGING_DIR } from '../components/Application.ts';
+import { restartNeeded } from '../components/requestRestart.ts';
 
 import { Request } from '../server/serverHelpers/Request.ts';
 import { RequestTarget } from '../resources/RequestTarget';
@@ -71,6 +77,45 @@ function finalizeResponse(responseData, headers, status, request) {
 	return responseData;
 }
 
+/**
+ * A component deployed to disk (via `deploy_component`) but not yet loaded into this
+ * server's live router — because Harper hasn't restarted since — produces a route miss
+ * indistinguishable from a URL that never existed. If the URL's first segment names a
+ * components-root directory, surface that distinction instead of a generic 404 (harper#674).
+ * `name` is decoded and checked for path-traversal characters before being joined into a
+ * filesystem path. Uses `stat`/`isDirectory` (not `access`) so a stray non-directory file
+ * directly under the components root (e.g. `README.md`, `.DS_Store`) can't be mistaken for
+ * a deployed component.
+ */
+async function findInactiveComponent(url: string): Promise<string | undefined> {
+	const firstSegment = url.split(/[/?]/, 1)[0];
+	if (!firstSegment) return undefined;
+	let name: string;
+	try {
+		name = decodeURIComponent(firstSegment);
+	} catch {
+		return undefined;
+	}
+	if (
+		!name ||
+		name === '.' ||
+		name === '..' ||
+		name === 'node_modules' ||
+		name === ASIDE_STAGING_DIR ||
+		name.includes('/') ||
+		name.includes('\\')
+	)
+		return undefined;
+	const componentsRoot = getConfigPath(CONFIG_PARAMS.COMPONENTSROOT);
+	if (!componentsRoot || typeof componentsRoot !== 'string') return undefined;
+	try {
+		const stats = await stat(join(componentsRoot, name));
+		return stats.isDirectory() ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 async function http(request: Request, nextHandler) {
 	const headersObject = request.headers.asObject;
 	const isSse = headersObject.accept === 'text/event-stream';
@@ -88,7 +133,31 @@ async function http(request: Request, nextHandler) {
 		let resource: typeof Resource;
 		if (url !== OPENAPI_DOMAIN) {
 			const entry = resources.getMatch(url, isSse ? 'sse' : 'rest');
-			if (!entry) return nextHandler(request); // no resource handler found
+			if (!entry) {
+				// Only surface the actionable "needs a restart" 404 when a restart is genuinely
+				// pending — i.e. a component was deployed (restart:false) since this server last
+				// loaded its routes, so restartNeeded() is set. Without a pending restart, a
+				// directory under componentsRoot is either an already-active component (which would
+				// have matched a route above) or not a live component at all, so fall back to the
+				// generic 404 rather than claiming a restart would activate it. (harper#674)
+				//
+				// Also gated on an authenticated super_user: this check runs before any resource is
+				// matched, so no auth gate has run yet for this request. Only reveal the actionable
+				// message to a super_user — otherwise a caller could use the response difference
+				// (actionable vs. generic 404) as an oracle to probe which component directories
+				// exist on disk. `getComponents` (utility/operation_authorization.ts) already treats
+				// "which components are deployed" as super_user-only information; match that here.
+				if (restartNeeded() && request?.user?.role?.permission?.super_user) {
+					const inactiveComponent = await findInactiveComponent(url);
+					if (inactiveComponent) {
+						throw new ClientError(
+							`Component '${inactiveComponent}' is deployed but Harper may need to be restarted before its routes are active.`,
+							404
+						);
+					}
+				}
+				return nextHandler(request); // no resource handler found
+			}
 			request.handlerPath = entry.path;
 			target = new RequestTarget(entry.relativeURL); // TODO: We don't want to have to remove the forward slash and then re-add it
 			if (entry.params) Object.assign(target, entry.params); // bind parameterised path segments (e.g. :id, *rest)

package/server/Server.ts

@@ -87,6 +87,12 @@ export interface HttpOptions extends ServerOptions {
 		headers?: boolean;
 	};
 	lastModified?: boolean;
+	/**
+	 * Header name -> value, applied as defaults to HTTP responses on app ports (e.g.
+	 * X-Frame-Options, X-Content-Type-Options). A header the application/route already set
+	 * on a response always takes precedence over the configured value.
+	 */
+	securityHeaders?: Record<string, string | number | boolean>;
 }
 export interface ContentTypeHandler {
 	serialize(data: any): Buffer | string;