@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/server/REST.ts

@@ -23,7 +23,6 @@ import { entryMap } from '../resources/RecordEncoder.ts';
 const { errorToString, errorForLog } = harperLogger;
 const etagBytes = new Uint8Array(8);
 const etagFloat = new Float64Array(etagBytes.buffer, 0, 1);
-let httpOptions = {};
 
 const OPENAPI_DOMAIN = 'openapi';
 
@@ -118,7 +117,7 @@ async function findInactiveComponent(url: string): Promise<string | undefined> {
 	}
 }
 
-async function http(request: Request, nextHandler) {
+async function http(request: Request, nextHandler, resources: Resources, httpOptions: any) {
 	const headersObject = request.headers.asObject;
 	const isSse = headersObject.accept === 'text/event-stream';
 	const method = isSse ? 'CONNECT' : request.method;
@@ -395,24 +394,41 @@ async function http(request: Request, nextHandler) {
 	}
 }
 
-let started = false;
-let resources: Resources;
+// One registration per distinct route mount, not one per process. Two applications that both
+// enable `rest` under different root-config mounts each need their own chain — a single global
+// `started` flag registered only the first, silently 404ing the other application's REST API.
+const startedMounts = new Set<string>();
 let addedMetrics;
 let connectionCount = 0;
 
 export function handleApplication(scope: import('../components/Scope.ts').Scope) {
-	httpOptions = scope.options.getAll();
+	// A deploy pre-flight validation scope exists only to validate config, and may share a live
+	// component's identity — registering real HTTP/WS handlers from it would splice a validation
+	// run into the live request path, and permanently marking its mount as started below would
+	// leave the REAL scope's later registration silently skipped (review finding).
+	if (scope.isTransientValidation) return;
+
+	const httpOptions = scope.options.getAll();
 	if ((httpOptions as any).includeExpensiveRecordCountEstimates) {
 		// If they really want to enable expensive record count estimates
 		(Request.prototype as any).includeExpensiveRecordCountEstimates = true;
 	}
-	resources = scope.resources;
-	if (started) return;
-	started = true;
+	// Captured per-mount in this closure — not a shared module-level variable — so each mount's
+	// registered handler always reads ITS OWN resources/options, not whichever mount happened to
+	// register last (review finding: two mounts sharing mutable module globals).
+	const resources = scope.resources;
+	// Key on the route this registration will actually answer on, not on the parts it is composed
+	// from: two configurations that resolve to the same route are the same chain and must dedupe,
+	// while two that resolve to different routes must not collide. Concatenating the mount and the
+	// plugin's raw urlPath did collide (mount '/a' + 'bc' and mount '/ab' + 'c' both gave '/abc').
+	const route = scope.routeFor(httpOptions as any);
+	const mountKey = `${route.host ?? ''}|${route.urlPath ?? ''}`;
+	if (startedMounts.has(mountKey)) return;
+	startedMounts.add(mountKey);
 	scope.server.http(
 		async (request: any, nextHandler) => {
 			if (request.isWebSocket) return;
-			return http(request, nextHandler);
+			return http(request, nextHandler, resources, httpOptions);
 		},
 		{ after: 'authentication', ...(httpOptions as any) }
 	);

package/server/fastifyRoutes.ts

@@ -1,6 +1,7 @@
 import { dirname, basename } from 'path';
 import { existsSync } from 'fs';
 import { deriveRoutePrefix } from './fastifyRoutes/helpers/deriveRoutePrefix.ts';
+import { resolveBaseURLPath } from '../components/resolveBaseURLPath.ts';
 import fastify from 'fastify';
 import fastifyCors from '@fastify/cors';
 import requestTimePlugin from './serverHelpers/requestTimePlugin.js';
@@ -38,6 +39,19 @@ const routeFolders = new Set();
 export function handleApplication(scope: import('../components/Scope.ts').Scope) {
 	// if we have a secure port, need to use the secure HTTP server for fastify (it can be used for HTTP as well)
 	const isHttps = (scope.options.getAll() as { securePort?: number }).securePort > 0;
+	// Fastify is registered as a global fallback below (`server.http(built.server)` on the bare
+	// server, not the scoped one), so it never joins a routed middleware chain. A `urlPath` mount
+	// still works — it becomes the fastify route prefix, which is matched against the full external
+	// path — but a `host` mount cannot constrain it: these routes would stay reachable under every
+	// Host header, silently dropping the isolation the operator declared. Refuse to load rather than
+	// imply isolation the fallback doesn't provide (review finding) — contained to this component by
+	// the loader's per-component try/catch, so it does not take down the rest of the application.
+	const mountedHost = scope.mount?.host ?? (scope.options.getAll() as { host?: string })?.host;
+	if (mountedHost) {
+		throw new Error(
+			`Application '${basename(scope.appName)}' is mounted on host '${mountedHost}', but its fastifyRoutes cannot be constrained by host: legacy fastify routes are registered as a global fallback and would remain reachable on every host. Port them to server.http() to get host routing, or drop the host mount.`
+		);
+	}
 	scope.handleEntry(async (entry) => {
 		if (entry.eventType !== 'add') {
 			scope.requestRestart();
@@ -62,7 +76,12 @@ export function handleApplication(scope: import('../components/Scope.ts').Scope)
 		// ignores the deprecated `path` alias, so it can't express the app-name namespace.
 		// `appName` may be an absolute path (loaded via RUN_HDB_APP), hence basename().
 		const config = (scope.options.getAll() as { urlPath?: string; path?: string }) ?? {};
-		const prefix = deriveRoutePrefix(basename(scope.appName), config.urlPath ?? config.path);
+		// Fastify is registered on the bare server, so nothing strips the application's mount before
+		// it matches — unlike a routed chain, its prefix must be the full external path.
+		const prefix = deriveRoutePrefix(
+			basename(scope.appName),
+			scope.externalBasePath(resolveBaseURLPath(basename(scope.appName), config.urlPath ?? config.path))
+		);
 		if (!routeFolders.has(routeFolder)) {
 			routeFolders.add(routeFolder);
 			try {

package/server/http.ts

@@ -28,7 +28,7 @@ import {
 import { Blob } from '../resources/blob.ts';
 import { recordAction, recordActionBinary } from '../resources/analytics/write.ts';
 import { Readable, Writable, pipeline } from 'node:stream';
-import { mkdirSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs';
+import { mkdirSync, writeFileSync, unlinkSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { server, type ServerOptions, type HttpOptions, type UpgradeOptions, UpgradeListener } from './Server.ts';
 import { setPortServerMap, SERVERS, socketOptionDefaults } from './serverRegistry.ts';
@@ -67,7 +67,14 @@ export const uwsServeConfigs: Record<string, any> = {};
 // backends that don't register their own Node http server (Bun, and the uWS HTTP path). Keeping
 // them out of SERVERS is what prevents a competing Node server from binding the same port.
 const fallbackServers: Record<string | number, any> = {};
-const udsCleanupPaths: { socketPath: string; yamlPath: string }[] = [];
+// `ino`/`dev` are set once this worker's own bind is confirmed (see recordUdsBindSuccess) and are
+// what make cleanupUdsFiles/markUdsBindFailed ownership-aware: on an overlapping restart (see
+// restartWorkers()), the replacement worker rebinds this exact path before the outgoing worker
+// exits, so by the time the outgoing worker cleans up, the identity on disk may already belong to
+// the replacement, not to it. Captured as bigint (statSync's `{ bigint: true }` form): a plain
+// Number loses precision above 2^53, which some filesystems (e.g. XFS with inode64) can exceed,
+// letting two genuinely different inodes compare equal.
+const udsCleanupPaths: { socketPath: string; yamlPath: string; identity?: { dev: bigint; ino: bigint } }[] = [];
 // Sockets whose listen() has failed (see threadServer.js's fail-soft UDS handling). A TLS mirror's
 // YAML metadata is written on its own schedule (SNICallback readiness / cert reload), independent of
 // whether the mirror socket ever actually bound, so a failed bind must both cancel any metadata write
@@ -79,24 +86,100 @@ export function registerUdsCleanupPaths(socketPath: string, yamlPath: string) {
 	udsCleanupPaths.push({ socketPath, yamlPath });
 }
 
-/** Mark a Unix domain socket's listen() as failed: suppress its metadata and remove any already written. */
+/**
+ * Record that this worker's own bind at `socketPath` succeeded, capturing the (dev, inode) pair that
+ * proves ownership. Call right after a mirror socket starts listening (see the bind sites in
+ * threadServer.js — the Node/h2/raw-socket mirrors via listenOnDomainSocket's onListening, the Bun
+ * path right after Bun.serve() returns, and the uWS path once createUwsServer() resolves). A no-op
+ * if `socketPath` was never registered.
+ */
+export function recordUdsBindSuccess(socketPath: string) {
+	const entry = udsCleanupPaths.find((candidate) => candidate.socketPath === socketPath);
+	if (!entry) return;
+	try {
+		const stat = statSync(socketPath, { bigint: true });
+		entry.identity = { dev: stat.dev, ino: stat.ino };
+	} catch (error) {
+		// Extremely unlikely (we just bound this path), but silent failure here is expensive: the
+		// entry is permanently treated as unowned, so this worker leaks both files at shutdown with
+		// nothing in the logs to explain why.
+		harperLogger.warn(`Could not stat freshly bound UDS mirror at ${socketPath}`, error);
+	}
+}
+
+/**
+ * 'owned' — the (dev, inode) this worker recorded at bind time still matches what's on disk.
+ * 'foreign' — a socket exists at the path, but with a different identity (or none was ever
+ *   recorded): something else — almost always a replacement worker — currently owns it. Also the
+ *   safe default when statSync fails for any reason other than ENOENT (e.g. EACCES): we can't
+ *   confirm the path is genuinely empty, so treat it as though something we can't verify owns it.
+ * 'absent' — statSync confirmed ENOENT: nothing is on disk at the path. There is no live owner to
+ *   protect.
+ */
+function ownershipOf(entry: {
+	socketPath: string;
+	identity?: { dev: bigint; ino: bigint };
+}): 'owned' | 'foreign' | 'absent' {
+	let current: { dev: bigint; ino: bigint };
+	try {
+		const stat = statSync(entry.socketPath, { bigint: true });
+		current = { dev: stat.dev, ino: stat.ino };
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'foreign';
+	}
+	return entry.identity !== undefined && current.dev === entry.identity.dev && current.ino === entry.identity.ino
+		? 'owned'
+		: 'foreign';
+}
+
+/**
+ * Mark a Unix domain socket's listen() as failed: suppress its metadata, and remove any already
+ * written UNLESS a live socket at this path currently belongs to someone else (a replacement worker
+ * that already rebound it). Unlike cleanupUdsFiles, a failed bind never produced a socket of its own,
+ * so 'absent' here just means no bind ever won this path — not evidence of a live replacement — and
+ * is safe to retract stale metadata for (see server/DESIGN.md's UDS ownership note for why this can't
+ * require 'owned': the only real caller, an overlong path, fails before listen() ever runs, so this
+ * worker's own identity is never recorded).
+ */
 export function markUdsBindFailed(socketPath: string) {
 	failedUdsPaths.add(socketPath);
 	const entry = udsCleanupPaths.find((candidate) => candidate.socketPath === socketPath);
-	if (entry) {
-		try {
-			unlinkSync(entry.yamlPath);
-		} catch {}
-	}
+	if (!entry || ownershipOf(entry) === 'foreign') return;
+	try {
+		unlinkSync(entry.yamlPath);
+	} catch {}
 }
 
 export function cleanupUdsFiles() {
-	for (const { socketPath, yamlPath } of udsCleanupPaths) {
+	for (const entry of udsCleanupPaths) {
+		// ownershipOf() and the unlinks below are separate syscalls, so a replacement that unlinks
+		// and rebinds in the gap between them would still lose its files — unavoidable in Node
+		// (no unlink-if-inode-matches primitive), but this narrows that window from the
+		// seconds-wide one this fix closes down to microseconds.
+		const ownership = ownershipOf(entry);
+		// Consume this entry's recorded identity on first use, regardless of outcome. This function
+		// runs twice per worker (threadServer.js's SHUTDOWN handler, while this worker's own
+		// socket is still open, then again from process.on('exit') after closeServers() has
+		// released it) — and a freed inode can be handed to an unrelated later bind before the
+		// second call runs. Leaving the stale value in place would let that second call
+		// coincidentally re-match a path it no longer has any claim to; clearing it here makes a
+		// repeat call a guaranteed no-op instead of a second chance to delete a stranger's files.
+		entry.identity = undefined;
+		// Unlike markUdsBindFailed (where 'absent' is genuinely safe — its only caller runs
+		// synchronously before any bind attempt, with no window for anyone else to be mid-flight),
+		// this function's second call (process.on('exit')) can land seconds after the first, while
+		// a concurrently-booting replacement — on the non-overlapping-restart platforms, started
+		// right after this worker's SHUTDOWN, not after it fully exits — may have already written
+		// its own fresh yaml (SNICallback.ready resolves independently of its bind) without having
+		// bound its socket yet. Treating that window's 'absent' as retractable would delete the
+		// replacement's yaml out from under it. Only 'owned' is safe here; a stale yaml this worker
+		// never bound (or no longer owns) is left for markUdsBindFailed or the startup sweep.
+		if (ownership !== 'owned') continue;
 		try {
-			unlinkSync(socketPath);
+			unlinkSync(entry.socketPath);
 		} catch {}
 		try {
-			unlinkSync(yamlPath);
+			unlinkSync(entry.yamlPath);
 		} catch {}
 	}
 }
@@ -161,9 +244,13 @@ export function writeUdsMetadata(
 	}
 }
 
-/** Clean all files in the sockets directory. Call from main thread on process startup. */
+/**
+ * Clean all files in the sockets directory. Call from main thread on process startup, before any
+ * worker can bind. Unconditional on the current TLS_UNIXDOMAINSOCKETS setting — the directory is
+ * Harper-owned and holds nothing but mirror .sock/.yaml files, so a crash that left stale ones
+ * behind while UDS was enabled must still be swept even if this boot has since disabled it.
+ */
 export function cleanupSocketsDirectory() {
-	if (!env.get(terms.CONFIG_PARAMS.TLS_UNIXDOMAINSOCKETS)) return;
 	const socketsDir = join(env.getHdbBasePath(), 'sockets');
 	try {
 		for (const file of readdirSync(socketsDir)) {

package/server/itc/serverHandlers.js

@@ -12,7 +12,7 @@ const harperBridge =
 	require('../../dataLayer/harperBridge/harperBridge.ts');
 const process = require('process');
 const { isMainThread, workerData } = require('worker_threads');
-const { resetDatabases } = require('../../resources/databases.ts');
+const { resetDatabases, closeDatabase } = require('../../resources/databases.ts');
 
 /**
  * This object/functions are passed to the ITC client instance and dynamically added as event handlers.
@@ -46,6 +46,12 @@ async function schemaHandler(event) {
 	}
 
 	hdbLogger.trace(`ITC schemaHandler received schema event:`, event);
+	// restore_backup: this thread must release its store handles so the restore can purge and
+	// rewrite the database directory. The rescan below (resetDatabases) skips reloading it while
+	// the restoring marker is present, and reloads it on the completion signal (marker gone).
+	if (event.message?.operation === hdbTerms.OPERATIONS_ENUM.RESTORE_BACKUP && event.message.schema) {
+		closeDatabase(event.message.schema);
+	}
 	await cleanLmdbMap(event.message);
 	await syncSchemaMetadata(event.message);
 	for (let listener of schemaListeners) {

package/server/jobs/jobProcess.ts

@@ -77,7 +77,24 @@ const JOB_ID = JOB_NAME.substring(4);
 		jobObj.message = err.message ? err.message : err;
 		jobObj.end_datetime = moment().valueOf();
 	} finally {
-		await jobs.updateJob(jobObj);
+		// A rejected updateJob must not skip handle cleanup and exit scheduling below (that would
+		// leak this worker's process-global RocksDB handles and leave the worker hanging).
+		try {
+			await jobs.updateJob(jobObj);
+		} catch (updateErr) {
+			harperLogger.error('Error updating job record on job worker exit:', updateErr);
+		}
+		// Release this worker's RocksDB handles before it exits. A job worker opens the whole
+		// database graph via getDatabases(); rocksdb-js's registry is process-global and a thread
+		// that exits without closing leaks its handles process-wide, which (among other costs)
+		// blocks an online restore_backup from confirming the target database is closed. Best
+		// effort — never let cleanup mask the job result.
+		try {
+			const { closeLoadedDatabases } = await import('../../resources/databases.ts');
+			closeLoadedDatabases();
+		} catch (closeErr) {
+			harperLogger.warn('Error releasing database handles on job worker exit:', closeErr);
+		}
 		// On Bun 1.3.13, calling process.exit() in a worker thread with lmdb-js loaded
 		// while sibling workers are running causes a NAPI fatal error crash. Unref
 		// parentPort (which broadcastWithAcknowledgement may have ref'd during schema

package/server/jobs/jobRunner.ts

@@ -10,6 +10,7 @@ import log from '../../utility/logging/harper_logger.ts';
 import * as jobs from './jobs.ts';
 import * as hdbExport from '../../dataLayer/export.ts';
 import * as hdbDelete from '../../dataLayer/delete.ts';
+import * as rocksdbBackup from '../../dataLayer/rocksdbBackup.ts';
 import * as threadsStart from '../threads/manageThreads.js';
 import * as transactionLog from '../../utility/logging/transactionLog.ts';
 import * as restart from '../../bin/restart.ts';
@@ -79,6 +80,15 @@ async function parseMessage(runnerMessage: any) {
 		case hdbTerms.JOB_TYPE_ENUM.delete_transaction_logs_before:
 			await runJob(runnerMessage, transactionLog.deleteTransactionLogsBefore);
 			break;
+		case hdbTerms.JOB_TYPE_ENUM.create_backup:
+			await runJob(runnerMessage, rocksdbBackup.createBackup);
+			break;
+		case hdbTerms.JOB_TYPE_ENUM.verify_backup:
+			await runJob(runnerMessage, rocksdbBackup.verifyBackup);
+			break;
+		case hdbTerms.JOB_TYPE_ENUM.restore_backup:
+			await runJob(runnerMessage, rocksdbBackup.restoreBackup);
+			break;
 		case hdbTerms.JOB_TYPE_ENUM.restart_service:
 			await runJob(runnerMessage, restart.restartService);
 			return `Restarting ${runnerMessage.json.service}`;

package/server/jobs/jobs.ts

@@ -20,6 +20,7 @@ import * as hdbUtil from '../../utility/common_utils.ts';
 import { promisify } from 'util';
 import moment from 'moment';
 import * as fileLoadValidator from '../../validation/fileLoadValidator.ts';
+import * as rocksdbBackup from '../../dataLayer/rocksdbBackup.ts';
 import bulkDeleteValidator from '../../validation/bulkDeleteValidator.ts';
 import { deleteTransactionLogsBeforeValidator } from '../../validation/transactionLogValidator.ts';
 import { handleHDBError, ClientError } from '../../utility/errors/hdbError.ts';
@@ -122,6 +123,16 @@ export async function addJob(jsonBody: any) {
 				throw handleHDBError(new Error(), 'Invalid service', HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
 			}
 			break;
+		// backup job validators throw ClientError (with statusCode) directly on failure
+		case hdbTerms.OPERATIONS_ENUM.CREATE_BACKUP:
+			await rocksdbBackup.validateCreateBackup(jsonBody);
+			break;
+		case hdbTerms.OPERATIONS_ENUM.VERIFY_BACKUP:
+			await rocksdbBackup.validateVerifyBackup(jsonBody);
+			break;
+		case hdbTerms.OPERATIONS_ENUM.RESTORE_BACKUP:
+			await rocksdbBackup.validateRestoreBackup(jsonBody);
+			break;
 		default:
 			break;
 	}

package/server/middlewareChain.ts

@@ -151,17 +151,43 @@ export function normalizeUrlPath(urlPath: string | undefined): string | undefine
 	return urlPath.length <= 1 ? undefined : urlPath;
 }
 
+/**
+ * Extracts the hostname from a Host/`:authority` header value: the port is dropped and an IPv6
+ * literal is unwrapped from its brackets ('[::1]:9926' -> '::1'), so a bracket-less configured
+ * host can match. Lowercased because hostnames are case-insensitive (RFC 4343) — a configured
+ * 'API.example.com' must match the 'api.example.com' a client actually sends. A trailing dot
+ * (the absolute-FQDN form some resolvers/clients emit, e.g. 'api.example.com.') is stripped —
+ * it names the same origin per RFC 1035.
+ */
+export function hostnameFromHeader(hostHeader: string): string {
+	if (hostHeader.startsWith('[')) {
+		const end = hostHeader.indexOf(']');
+		if (end !== -1) return hostHeader.slice(1, end).toLowerCase();
+	}
+	const colon = hostHeader.indexOf(':');
+	const hostname = (colon === -1 ? hostHeader : hostHeader.slice(0, colon)).toLowerCase();
+	return hostname.endsWith('.') ? hostname.slice(0, -1) : hostname;
+}
+
+/**
+ * Reads the request's authority for host matching: `request.host` (Harper's `Request` class)
+ * already resolves this correctly for both HTTP/1 (`Host` header) and HTTP/2 (`:authority`
+ * pseudo-header — HTTP/2 clients don't send `Host` at all). The header fallbacks below only
+ * cover request-like objects that don't carry that getter (e.g. bare fakes in tests).
+ */
+function requestAuthority(request: any): string {
+	return request.host ?? request.headers?.asObject?.[':authority'] ?? request.headers?.asObject?.host ?? '';
+}
+
 /**
  * Returns true when `request` satisfies the route's host and urlPath constraints.
  * urlPath matching is prefix-based and segment-boundary-aware:
  *   '/api' matches '/api' and '/api/foo' but NOT '/api2'.
- * Trailing slashes on `route.urlPath` are ignored.
+ * Trailing slashes on `route.urlPath` are ignored. Host matching ignores the port and case.
  */
 export function matchesRoute(request: any, route: { host?: string; urlPath?: string }): boolean {
 	if (route.host) {
-		const hostHeader: string = request.headers?.asObject?.host ?? '';
-		const requestHost = hostHeader.split(':')[0];
-		if (requestHost !== route.host) return false;
+		if (hostnameFromHeader(requestAuthority(request)) !== route.host.toLowerCase()) return false;
 	}
 	const urlPath = normalizeUrlPath(route.urlPath);
 	if (urlPath) {
@@ -230,10 +256,18 @@ export function stripPrefix(request: any, prefix: string): any {
  * and `describeChains` reports it, so the observed order can never drift from the served one.
  */
 export function resolveRoutedChains(portEntries: HttpEntry[], onCycle?: () => void): ResolvedChain[] {
-	// Global name registry across all routes (first registration wins)
-	const nameToEntry = new Map<string, HttpEntry>();
+	// Global name registry, but restricted to unmounted (no host/urlPath) entries — e.g.
+	// `authentication` — so it only ever supplies dependencies that are meant to apply everywhere.
+	// A mounted route's own plugins are resolved separately per-group below; if this stayed global
+	// across ALL routes (mounted or not), two applications mounted at different hosts/paths that
+	// each happen to register a same-named plugin (e.g. both enable `rest`) would resolve `after:
+	// 'rest'` to whichever one registered first — silently splicing one application's handler into
+	// another's request chain (review finding).
+	const globalNameToEntry = new Map<string, HttpEntry>();
 	for (const entry of portEntries) {
-		if (entry.name && !nameToEntry.has(entry.name)) nameToEntry.set(entry.name, entry);
+		if (entry.name && !entry.host && !entry.urlPath && !globalNameToEntry.has(entry.name)) {
+			globalNameToEntry.set(entry.name, entry);
+		}
 	}
 
 	// Group entries by (host, normalized urlPath) so that '/api' and '/api/' coalesce.
@@ -249,11 +283,24 @@ export function resolveRoutedChains(portEntries: HttpEntry[], onCycle?: () => vo
 	const defaultGroup = routeGroups.find((g) => !g.host && !g.urlPath);
 	const subRouteGroups = routeGroups.filter((g) => g.host || g.urlPath);
 
-	const subRoutes: ResolvedChain[] = subRouteGroups.map((group) => ({
-		host: group.host,
-		urlPath: group.urlPath,
-		order: topoSort(resolveDeps(group.entries, nameToEntry), onCycle),
-	}));
+	const subRoutes: ResolvedChain[] = subRouteGroups.map((group) => {
+		// This route's own plugins take priority over the global (unmounted) registry for the
+		// same name, so a same-named handler local to this mount always wins over an unrelated
+		// unmounted one — but the lookup never reaches into another mounted route's plugins.
+		const localNameToEntry = new Map(globalNameToEntry);
+		const seenInGroup = new Set<string>();
+		for (const entry of group.entries) {
+			if (entry.name && !seenInGroup.has(entry.name)) {
+				seenInGroup.add(entry.name);
+				localNameToEntry.set(entry.name, entry);
+			}
+		}
+		return {
+			host: group.host,
+			urlPath: group.urlPath,
+			order: topoSort(resolveDeps(group.entries, localNameToEntry), onCycle),
+		};
+	});
 
 	subRoutes.sort((a, b) => {
 		const aSpec = (a.host ? 2 : 0) + (a.urlPath ? 1 : 0);
@@ -274,23 +321,35 @@ export function buildRoutedChain(
 	const resolved = resolveRoutedChains(portEntries, onCycle);
 	// resolveRoutedChains returns sub-routes (dispatch order) followed by the default route last.
 	const defaultChain = buildLinearChain(resolved[resolved.length - 1].order, fallback);
+	// hostLower/urlPathWithSlash are computed once here rather than per request/per candidate:
+	// `route.urlPath` is already normalized by resolveRoutedChains, but `route.host` isn't
+	// (plugin-config hosts via routeFor aren't pre-lowercased), and matchesRoute's generic form
+	// would otherwise re-run toLowerCase()/a regex/a concat on every probe of every request —
+	// this dispatch is the mainline path once a port has any mounted route.
 	const subRouteChains = resolved.slice(0, -1).map((route) => ({
-		host: route.host,
+		hostLower: route.host?.toLowerCase(),
 		urlPath: route.urlPath,
+		urlPathWithSlash: route.urlPath ? route.urlPath + '/' : undefined,
 		chain: buildLinearChain(route.order, fallback),
 	}));
+	const anyHostRoute = subRouteChains.some((route) => route.hostLower);
 
 	return function dispatch(...args: any[]) {
 		const request = args[requestArgIndex];
+		// The request's authority is the same for every candidate probed below, so it's
+		// extracted once per request rather than once per candidate — and skipped entirely
+		// when no mounted route in this chain matches on host at all.
+		const requestHost = anyHostRoute ? hostnameFromHeader(requestAuthority(request)) : undefined;
+		const pathname: string = request.pathname ?? '/';
 		for (const route of subRouteChains) {
-			if (matchesRoute(request, route)) {
-				if (route.urlPath) {
-					const newArgs = args.slice();
-					newArgs[requestArgIndex] = stripPrefix(request, route.urlPath);
-					return route.chain(...newArgs);
-				}
-				return route.chain(...args);
+			if (route.hostLower && requestHost !== route.hostLower) continue;
+			if (route.urlPath) {
+				if (pathname !== route.urlPath && !pathname.startsWith(route.urlPathWithSlash as string)) continue;
+				const newArgs = args.slice();
+				newArgs[requestArgIndex] = stripPrefix(request, route.urlPath);
+				return route.chain(...newArgs);
 			}
+			return route.chain(...args);
 		}
 		return defaultChain(...args);
 	};

package/server/operationsServer.ts

@@ -137,10 +137,8 @@ export interface ImpersonatePayload {
 
 interface BaseOperationRequestBody {
 	operation: OperationFunctionName;
-	bypassAuth: boolean;
 	hdb_user?: userSchema.User;
 	hdbAuthHeader?: unknown;
-	bypass_auth?: boolean;
 	impersonate?: ImpersonatePayload;
 	password?: string;
 	payload?: string;

package/server/serverHelpers/multipartParser.ts

@@ -11,6 +11,7 @@ interface MultipartBody {
 
 const FIELD_SIZE_LIMIT = 1024 * 1024; // 1 MB per non-file field — generous for JSON params
 const MAX_FIELDS = 64;
+const UNSAFE_FIELD_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
 // Operation handlers stream the file part directly into extraction (gunzip + tar-fs),
 // so there is no separate filesize cap to enforce here. Backpressure flows through busboy
 // → the file Readable → the consumer, bounded by disk space rather than memory.
@@ -73,6 +74,14 @@ export function parseMultipartRequest(
 			logger.warn?.(`Multipart field "${name}" arrived after the file part; ignoring`);
 			return;
 		}
+		if (UNSAFE_FIELD_NAMES.has(name)) {
+			const error = new ClientError(`Multipart field "${name}" is not allowed`, 400);
+			callDone(error);
+			// Stop accepting bytes from a malicious request immediately. The raw-stream error
+			// handler below also tears down busboy, so a later file part cannot remain unread.
+			rawStream.destroy(error);
+			return;
+		}
 		body[name] = decodeFieldValue(value);
 	});
 

package/server/serverHelpers/operationAuthorizationState.ts

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const operationAuthorizationState = new AsyncLocalStorage<boolean>();
+
+export function runWithOperationAuthorizationBypass<T>(bypassAuth: boolean, callback: () => T): T {
+	return operationAuthorizationState.run(bypassAuth === true, callback);
+}
+
+export function isOperationAuthorizationBypassed(): boolean {
+	return operationAuthorizationState.getStore() === true;
+}

package/server/serverHelpers/registeredOperations.ts

@@ -27,6 +27,7 @@ import harperLogger from '../../utility/logging/harper_logger.ts';
 import { ServerError } from '../../utility/errors/hdbError.ts';
 import { sendItcEvent } from '../threads/itc.js';
 import { onMessageByType, onThreadExit } from '../threads/manageThreads.js';
+import { runWithOperationAuthorizationBypass } from './operationAuthorizationState.ts';
 
 const operationLog = harperLogger.loggerWithTag('operation');
 
@@ -49,7 +50,7 @@ const EXECUTE_TIMEOUT_MS = env.get(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_TIM
 // survive the dist build). A worker can only receive an execute request after announcing a
 // registration — which goes through serverUtilities — so these are always set on that path.
 let localDispatch: {
-	chooseOperation: (body: any) => Function;
+	chooseOperation: (body: any, bypassAuth?: boolean) => Function;
 	processLocalTransaction: (req: any, operationFunction: Function) => Promise<any>;
 };
 export function setLocalOperationDispatch(dispatch: typeof localDispatch) {
@@ -99,10 +100,13 @@ let rotation = 0;
  * function and metadata that `verifyPerms` needs only exist on the worker, which runs the full
  * `chooseOperation` check with the forwarded `hdb_user`.
  */
-export function getRemoteOperationFunction(name: string): ((body: any) => Promise<any>) | undefined {
+export function getRemoteOperationFunction(
+	name: string,
+	bypassAuth = false
+): ((body: any) => Promise<any>) | undefined {
 	if (!isMainThread) return undefined;
 	if (!registeredByWorker.has(name)) return undefined;
-	return (body: any) => executeRemoteOperation(name, body);
+	return (body: any) => executeRemoteOperation(name, body, bypassAuth);
 }
 
 function attachMainListeners() {
@@ -135,7 +139,7 @@ function attachMainListeners() {
 	});
 }
 
-async function executeRemoteOperation(name: string, body: any): Promise<any> {
+async function executeRemoteOperation(name: string, body: any, bypassAuth: boolean): Promise<any> {
 	attachMainListeners();
 	const workerIds = registeredByWorker.get(name);
 	const forwardBody = { ...body };
@@ -151,7 +155,7 @@ async function executeRemoteOperation(name: string, body: any): Promise<any> {
 		try {
 			sent = threads.sendToThread(targetThreadId, {
 				type: terms.ITC_EVENT_TYPES.OPERATION_EXECUTE_REQUEST,
-				message: { requestId, body: forwardBody, originator: threadId },
+				message: { requestId, body: forwardBody, bypassAuth, originator: threadId },
 			});
 		} catch (error) {
 			// Structured-clone failure (e.g. a function or native handle on the request body) is a
@@ -198,20 +202,20 @@ async function executeRemoteOperation(name: string, body: any): Promise<any> {
  * (permission check + processLocalTransaction) and send the result back to the main thread.
  */
 export async function operationExecuteRequestHandler(event: {
-	message: { requestId: number; body: any; originator: number };
+	message: { requestId: number; body: any; bypassAuth?: boolean; originator: number };
 }) {
-	const { requestId, body, originator } = event.message;
+	const { requestId, body, bypassAuth, originator } = event.message;
 	let response;
 	try {
 		if (!localDispatch) throw new ServerError('This worker thread cannot execute operations', 503);
-		// bypass_auth is trusted as forwarded: the main thread already strips it from external
-		// HTTP requests (handlePostRequest, before any dispatch decision), and an internal caller
-		// legitimately setting it (server.operation(op, context, false)) must see the same
-		// authorize:false behavior whether the operation happens to run locally or via this bridge.
-		// ITC is an internal, same-process trust boundary — a worker able to forge this message
-		// already has direct DB access and gains nothing by spoofing bypass_auth.
-		const operationFunction = localDispatch.chooseOperation(body);
-		const result = await localDispatch.processLocalTransaction({ body }, operationFunction);
+		// Authorization state travels in the trusted same-process ITC envelope, never in the
+		// caller-controlled operation body. This preserves server.operation(..., false) across
+		// worker forwarding without creating a client-spoofable request property.
+		const trustedBypassAuth = bypassAuth === true;
+		const result = await runWithOperationAuthorizationBypass(trustedBypassAuth, () => {
+			const operationFunction = localDispatch.chooseOperation(body, trustedBypassAuth);
+			return localDispatch.processLocalTransaction({ body }, operationFunction);
+		});
 		if (result instanceof Readable || typeof result?.pipe === 'function') {
 			// Streaming results would need MessagePort transfer plumbing — explicitly unsupported
 			// for worker-registered operations for now (#1736), rather than failing opaquely.