@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/security/jsLoader.ts

@@ -6,7 +6,7 @@ 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 { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { SourceTextModule, SyntheticModule, createContext, runInContext, runInThisContext } from 'node:vm';
 import { ApplicationScope } from '../components/ApplicationScope.ts';
@@ -28,7 +28,6 @@ import {
 	statSync,
 	realpathSync,
 } from 'node:fs';
-import { join } from 'node:path';
 import { EventEmitter } from 'node:events';
 import { whenComponentsLoaded } from '../server/threads/threadServer.js';
 
@@ -105,6 +104,7 @@ async function importScoped(moduleUrl: string, scope?: ApplicationScope) {
 				return await loadModuleWithVM(moduleUrl, scope, true);
 			}
 		}
+		if (scope) scope.markNativeRuntime?.();
 		// important! we need to await the import, otherwise the error will not be caught
 		return await import(moduleUrl);
 	} catch (err) {
@@ -178,7 +178,10 @@ function walkExportsConditions(entry: unknown, conditions: readonly string[]): s
  * ERR_PACKAGE_PATH_NOT_EXPORTED for pure-ESM packages (exports map with only "import"
  * conditions and no "require").
  */
-function resolveESMPackageExports(specifier: string, fromDir: string): string | null {
+function resolveESMPackageExports(
+	specifier: string,
+	fromDir: string
+): { resolvedUrl: string; packageJsonUrl: string; packageJsonSource: Buffer } | null {
 	const isScoped = specifier.startsWith('@');
 	const parts = specifier.split('/');
 	const packageName = isScoped ? `${parts[0]}/${parts[1]}` : parts[0];
@@ -189,8 +192,11 @@ function resolveESMPackageExports(specifier: string, fromDir: string): string |
 	while (true) {
 		const pkgRoot = join(dir, 'node_modules', packageName);
 		let pkgJson: any;
+		let packageJsonSource: Buffer;
+		const packageJsonPath = join(pkgRoot, 'package.json');
 		try {
-			pkgJson = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8'));
+			packageJsonSource = readFileSync(packageJsonPath);
+			pkgJson = JSON.parse(packageJsonSource.toString());
 		} catch {
 			const parent = dirname(dir);
 			if (parent === dir) return null;
@@ -220,10 +226,25 @@ function resolveESMPackageExports(specifier: string, fromDir: string): string |
 		const relative = walkExportsConditions(entry, ['import', 'node', 'default']);
 		if (!relative) return null;
 
-		return pathToFileURL(join(pkgRoot, relative)).toString();
+		return {
+			resolvedUrl: pathToFileURL(realpathSync(join(pkgRoot, relative))).toString(),
+			packageJsonUrl: pathToFileURL(realpathSync(packageJsonPath)).toString(),
+			packageJsonSource,
+		};
 	}
 }
 
+function normalizeImportedModule(importedModule: any): any {
+	const cjsModule = importedModule['module.exports'];
+	if (cjsModule) {
+		importedModule = importedModule.default ? { default: importedModule.default, ...cjsModule } : cjsModule;
+	}
+	if (!importedModule.default) {
+		importedModule = { default: importedModule, ...importedModule };
+	}
+	return importedModule;
+}
+
 /**
  * Load a module using Node's vm.Module API with optional sandboxing
  * @param moduleUrl - The URL of the module to load
@@ -286,11 +307,18 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 		try {
 			const resolved = createRequire(resolveReferrer).resolve(specifier);
 			if (isAbsolute(resolved)) {
-				return pathToFileURL(resolved).toString();
+				const resolvedUrl = pathToFileURL(resolved).toString();
+				scope.recordModuleResolution?.(specifier, resolveReferrer, resolvedUrl);
+				return resolvedUrl;
 			}
 			return resolved;
 		} catch (err) {
-			if ((err as any)?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+			const errorCode = (err as { code?: string })?.code;
+			const isBarePackage = !specifier.startsWith('.') && !isAbsolute(specifier) && !specifier.includes(':');
+			if (
+				isBarePackage &&
+				(errorCode === 'ERR_PACKAGE_PATH_NOT_EXPORTED' || (process.versions.bun && errorCode === 'MODULE_NOT_FOUND'))
+			) {
 				// Pure-ESM package: CJS resolver cannot match an exports map that only has
 				// "import" conditions (no "require"). Resolve the entry file by walking
 				// the filesystem and evaluating the exports map with ESM import conditions.
@@ -298,7 +326,10 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 					? dirname(fileURLToPath(resolveReferrer))
 					: dirname(resolveReferrer);
 				const esmResolved = resolveESMPackageExports(specifier, referrerDir);
-				if (esmResolved) return esmResolved;
+				if (esmResolved) {
+					scope.recordLoadedModule?.(esmResolved.packageJsonUrl, esmResolved.packageJsonSource);
+					return esmResolved.resolvedUrl;
+				}
 			}
 			throw err;
 		}
@@ -336,8 +367,15 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 				return getHarperExports(scope);
 			}
 			if (resolvedUrl.startsWith('file://')) {
-				const source = readFileSync(new URL(resolvedUrl), { encoding: 'utf-8' });
-				return loadCJS(resolvedUrl, source).exports;
+				if (resolvedUrl.endsWith('.node')) {
+					checkAllowedModulePath(resolvedUrl, scope.allowedPath);
+					const nativeModule = require(fileURLToPath(resolvedUrl));
+					scope.markNativeRuntime?.();
+					return nativeModule;
+				}
+				const contents = readFileSync(new URL(resolvedUrl));
+				scope.recordLoadedModule?.(resolvedUrl, contents);
+				return loadCJS(resolvedUrl, contents.toString('utf-8')).exports;
 			}
 			return require(resolvedUrl);
 		};
@@ -456,11 +494,11 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 		if (specifier.startsWith('.')) {
 			return true;
 		}
-
 		// Check the dependencyLoader for definitive settings, if it is native we always use native loader
 		if (scope.dependencyLoader === 'native') {
 			return false;
 		}
+		if (isApplicationLocalModule(resolvedUrl)) return true;
 
 		// If it is set to always use the app module loader
 		if (scope.dependencyLoader === 'app') {
@@ -474,6 +512,16 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 		return false;
 	}
 
+	function isApplicationLocalModule(url: string): boolean {
+		if (!scope.runtimeRoot || !url.startsWith('file://') || url.includes('/node_modules/')) return false;
+		const modulePath = fileURLToPath(url);
+		const relativePath = relative(resolve(scope.runtimeRoot), modulePath);
+		return (
+			relativePath === '' ||
+			(!relativePath.startsWith(`..${sep}`) && relativePath !== '..' && !isAbsolute(relativePath))
+		);
+	}
+
 	/**
 	 * Linker function for module resolution during instantiation.
 	 * This is synchronous because Node's module.link() requires the linker
@@ -544,22 +592,6 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 		);
 	}
 
-	/**
-	 * Normalize imported module to ensure it has proper exports including default
-	 */
-	function normalizeImportedModule(importedModule: any): any {
-		const cjsModule = importedModule['module.exports'];
-		if (cjsModule) {
-			// back-compat import
-			importedModule = importedModule.default ? { default: importedModule.default, ...cjsModule } : cjsModule;
-		}
-		// Ensure there's a default export for ESM imports that expect it
-		if (!importedModule.default) {
-			importedModule = { default: importedModule, ...importedModule };
-		}
-		return importedModule;
-	}
-
 	/**
 	 * Create a SourceTextModule or SyntheticModule from source code
 	 */
@@ -638,8 +670,14 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 
 		if (url.startsWith('file://') && usePrivateGlobal) {
 			checkAllowedModulePath(url, scope.allowedPath);
-			const source = readFileSync(new URL(url), { encoding: 'utf-8' });
-			return createModuleFromSource(url, source, usePrivateGlobal);
+			if (url.endsWith('.node')) {
+				const nativeModule = createRequire(url)(fileURLToPath(url));
+				scope.markNativeRuntime?.();
+				return createSyntheticModule(url, normalizeImportedModule(nativeModule));
+			}
+			const contents = readFileSync(new URL(url));
+			scope.recordLoadedModule?.(url, contents);
+			return createModuleFromSource(url, contents.toString('utf-8'), usePrivateGlobal);
 		}
 
 		// For Node.js built-in modules (node:) and npm packages without application loader for dependency
@@ -647,6 +685,7 @@ async function loadModuleWithVM(moduleUrl: string, scope: ApplicationScope, useC
 		if (replacedModule) {
 			return createSyntheticModule(url, normalizeImportedModule(replacedModule));
 		}
+		if (isApplicationLocalModule(url)) scope.markNativeRuntime?.();
 		return import(url).then((importedModule) => createSyntheticModule(url, normalizeImportedModule(importedModule)));
 	}
 	// Load the entry module
@@ -679,6 +718,7 @@ async function getCompartment(scope: ApplicationScope, globals) {
 				const resolved = createRequire(moduleReferrer).resolve(moduleSpecifier);
 				if (isAbsolute(resolved)) {
 					const resolvedURL = pathToFileURL(resolved).toString();
+					scope.recordModuleResolution?.(moduleSpecifier, moduleReferrer, resolvedURL);
 					return resolvedURL;
 				}
 				return moduleSpecifier;
@@ -693,8 +733,22 @@ async function getCompartment(scope: ApplicationScope, globals) {
 							Object.assign(exports, harperExports);
 						},
 					};
+				} else if (moduleSpecifier.startsWith('file:') && moduleSpecifier.endsWith('.node')) {
+					checkAllowedModulePath(moduleSpecifier, scope.allowedPath);
+					const nativeModule = createRequire(moduleSpecifier)(fileURLToPath(moduleSpecifier));
+					scope.markNativeRuntime?.();
+					const moduleExports = normalizeImportedModule(nativeModule);
+					return {
+						imports: [],
+						exports: Object.keys(moduleExports),
+						execute(exports) {
+							Object.assign(exports, moduleExports);
+						},
+					};
 				} else if (moduleSpecifier.startsWith('file:') && !moduleSpecifier.includes('node_modules')) {
-					let moduleText = await readFile(new URL(moduleSpecifier), { encoding: 'utf-8' });
+					const moduleContents = await readFile(new URL(moduleSpecifier));
+					scope.recordLoadedModule?.(moduleSpecifier, moduleContents);
+					let moduleText = moduleContents.toString('utf-8');
 					// Handle JSON files in compartment mode the same way as in VM mode
 					if (moduleSpecifier.endsWith('.json')) {
 						const jsonData = parseJsonModule(moduleText, moduleSpecifier);

package/security/role.ts

@@ -16,6 +16,7 @@ import SearchObject from '../dataLayer/SearchObject.ts';
 import SearchByHashObject from '../dataLayer/SearchByHashObject.ts';
 import { handleHDBError } from '../utility/errors/hdbError.ts';
 import { HDB_ERROR_MSGS, HTTP_STATUS_CODES } from '../utility/errors/commonErrors.ts';
+import { assertActiveSuperUserRemains } from './user.ts';
 
 import { UserEventMsg } from '../server/threads/itc.js';
 
@@ -104,6 +105,12 @@ export async function alterRole(role: any) {
 
 	role = scrubRoleDetails(role);
 
+	if (role.permission) {
+		await assertActiveSuperUserRemains((user) =>
+			user.role?.id === role.id ? { ...user, role: { ...user.role, permission: role.permission } } : user
+		);
+	}
+
 	let updateObject = {
 		operation: 'update',
 		schema: 'system',

package/security/superUserGuard.ts

@@ -0,0 +1,20 @@
+import type { User } from './user.ts';
+
+function isActiveSuperUser(user?: User): boolean {
+	return Boolean(user?.active && user.role?.permission?.super_user);
+}
+
+/**
+ * Whether an active super_user still exists once `simulate` is applied to every user; `simulate`
+ * returns undefined for a user the change removes. True when none exists beforehand — there is no
+ * last one to protect, and refusing would block the repair that restores one.
+ */
+export function activeSuperUserRemains(users: Iterable<User>, simulate: (user: User) => User | undefined): boolean {
+	let present = false;
+	let remains = false;
+	for (const user of users) {
+		if (isActiveSuperUser(user)) present = true;
+		if (isActiveSuperUser(simulate(user))) remains = true;
+	}
+	return remains || !present;
+}

package/security/tokenAuthentication.ts

@@ -18,6 +18,7 @@ import { findAndValidateUser, type User } from './user.ts';
 import { update } from '../dataLayer/insert.ts';
 import UpdateObject from '../dataLayer/UpdateObject.ts';
 import * as signalling from '../utility/signalling.ts';
+import { isOperationAuthorizationBypassed } from '../server/serverHelpers/operationAuthorizationState.ts';
 import { UserEventMsg } from '../server/threads/itc.js';
 import * as env from '../utility/environment/environmentManager.ts';
 env.initSync();
@@ -52,7 +53,6 @@ interface AuthObject {
 	password?: string;
 	role?: string;
 	expires_in?: string | number;
-	bypass_auth?: boolean;
 	hdb_user?: User;
 	// 'login' mints a single short-lived, login-scoped token instead of an operation/refresh pair —
 	// see TOKEN_TYPE.LOGIN.
@@ -135,8 +135,11 @@ export async function createTokens(authObj: AuthObject): Promise<JWTTokens> {
 
 	let user: any;
 	try {
-		// bypassAuth will be set to true if this is called from a component
-		let validatePassword: boolean = authObj.bypass_auth !== true;
+		// Trusted bypass is dispatch/async-context state (set by a component calling
+		// server.operation(..., false)), never a body field — authObj.bypass_auth is
+		// caller-controlled and would let anyone mint tokens for an arbitrary username
+		// without a password (see operationAuthorizationState.ts).
+		let validatePassword: boolean = !isOperationAuthorizationBypassed();
 		if (!authObj.username && !authObj.password) {
 			// if the username and password are not provided, use the hdb_user making the request.
 			authObj.username = authObj.hdb_user?.username;

package/security/user.ts

@@ -9,6 +9,7 @@ const ACTIVE_BOOLEAN = 'active must be true or false';
 export {
 	addUser,
 	alterUser,
+	assertActiveSuperUserRemains,
 	dropUser,
 	getSuperUser,
 	userInfo,
@@ -105,6 +106,7 @@ import * as password from '../utility/password.ts';
 import { server } from '../server/Server.ts';
 import * as terms from '../utility/hdbTerms.ts';
 import { expandOperationsPerms } from '../utility/operationPermissions.ts';
+import { activeSuperUserRemains } from './superUserGuard.ts';
 
 server.getUser = (username: string, password?: string | null): Promise<User> => {
 	return findAndValidateUser(username, password, password != null);
@@ -202,6 +204,7 @@ async function alterUser(jsonMessage) {
 		throw new Error(EMPTY_ROLE);
 	}
 	// Invalid roles will be found in the role search
+	let nextRole;
 	if (cleanUser.role) {
 		const roleData = await search.searchByValue({
 			schema: 'system',
@@ -217,7 +220,16 @@ async function alterUser(jsonMessage) {
 		if (roleData.length > 1)
 			throw new ClientError(HDB_ERROR_MSGS.DUP_ROLES_FOUND(cleanUser.role), HTTP_STATUS_CODES.CONFLICT);
 
-		cleanUser.role = roleData[0].id;
+		nextRole = roleData[0];
+		cleanUser.role = nextRole.id;
+	}
+
+	if (nextRole !== undefined || cleanUser.active !== undefined) {
+		await assertActiveSuperUserRemains((user) =>
+			user.username === cleanUser.username
+				? { ...user, role: nextRole ?? user.role, active: cleanUser.active ?? user.active }
+				: user
+		);
 	}
 
 	const updateResponse = await insert.update({
@@ -240,6 +252,8 @@ async function dropUser(user: User | any): Promise<string> {
 	if (usersWithRolesMap.get(user.username) === undefined)
 		throw new ClientError(HDB_ERROR_MSGS.USER_NOT_EXIST(user.username), HTTP_STATUS_CODES.NOT_FOUND);
 
+	await assertActiveSuperUserRemains((existing) => (existing.username === user.username ? undefined : existing));
+
 	const deleteResponse = await promiseDelete({
 		table: 'hdb_user',
 		schema: 'system',
@@ -381,6 +395,17 @@ async function getUsersWithRolesCache() {
 	return usersWithRolesMap;
 }
 
+/**
+ * `simulate` maps each user to what the pending change would make it; undefined means removed.
+ * Local view only — `system` is replicated, so a lagging node can approve what another rejects.
+ */
+async function assertActiveSuperUserRemains(simulate: (user: User) => User | undefined): Promise<void> {
+	const users = await getUsersWithRolesCache();
+	if (!users) return;
+	if (activeSuperUserRemains(users.values(), simulate)) return;
+	throw new ClientError(HDB_ERROR_MSGS.LAST_SUPER_USER, HTTP_STATUS_CODES.CONFLICT);
+}
+
 /**
  * iterates global.hdb_users to find and validate the username & optionally the password as well as if they are active.
  * @param {string} username

package/server/DESIGN.md

@@ -43,20 +43,20 @@ A request entering `http.ts` does **not** go through Fastify. The two `handleApp
 
 ### Helpers
 
-| File                                       | Purpose                                                                         |
-| ------------------------------------------ | ------------------------------------------------------------------------------- |
-| `serverHelpers/Request.ts`                 | Wraps `IncomingMessage` with Harper-specific fields (user, response, headers).  |
-| `serverHelpers/Headers.ts`                 | Header mutation/merge utilities.                                                |
-| `serverHelpers/contentTypes.ts`            | (de)serialization registry; `serialize`, `serializeMessage`, `getDeserializer`. |
-| `serverHelpers/serverUtilities.ts`         | `OperationDefinition` and shared helpers.                                       |
-| `serverHelpers/OperationFunctionObject.ts` | Wraps an operation handler with metadata.                                       |
-| `serverHelpers/JSONStream.ts`              | Streaming JSON output for large responses.                                      |
-| `nodeName.ts`                              | Resolves this node's name (config → hostname).                                  |
-| `static.ts`                                | Static file serving for component-bundled assets.                               |
-| `throttle.ts`                              | Per-IP / per-user request throttling.                                           |
-| `storageReclamation.ts`                    | Disk-pressure signals to downstream consumers.                                  |
-| `serverRegistry.ts`                        | Trivial registry export.                                                        |
-| `status/`                                  | Server status reporting (cluster status, per-port info).                        |
+| File                                       | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `serverHelpers/Request.ts`                 | Wraps `IncomingMessage` with Harper-specific fields (user, response, headers).                                                                                                                                                                                                                                                                                                                                                                         |
+| `serverHelpers/Headers.ts`                 | Header mutation/merge utilities.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `serverHelpers/contentTypes.ts`            | (de)serialization registry; `serialize`, `serializeMessage`, `getDeserializer`.                                                                                                                                                                                                                                                                                                                                                                        |
+| `serverHelpers/serverUtilities.ts`         | `OperationDefinition` and shared helpers.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `serverHelpers/OperationFunctionObject.ts` | Wraps an operation handler with metadata.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `serverHelpers/JSONStream.ts`              | Streaming JSON output for large responses.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `nodeName.ts`                              | Resolves this node's name (config → hostname).                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `static.ts`                                | Static file serving for component-bundled assets.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `throttle.ts`                              | Per-IP / per-user request throttling.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `storageReclamation.ts`                    | Disk-pressure signals to downstream consumers; `getStorageSpaceStats()` is the shared quota-aware (falls back to `statfs`) source of available/free/size storage numbers — used by `Table.getStorageStats()` (#1976). NOT used for blob storage path weighting (`resources/blob.ts`): quota-status.json is a single instance-wide figure, so it can't distinguish between multiple `STORAGE_BLOBPATHS` disks — that still needs raw per-path `statfs`. |
+| `serverRegistry.ts`                        | Trivial registry export.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `status/`                                  | Server status reporting (cluster status, per-port info).                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ### Threads
 
@@ -88,26 +88,26 @@ Single-instance background tasks pick their thread by what state they touch:
 
 Every entry is a top-level function or named const. Jump via go-to-symbol or `grep -n 'function <name>' server/http.ts`.
 
-| Symbol                                                                                      | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registerUdsCleanupPaths`, `cleanupUdsFiles`, `writeUdsMetadata`, `cleanupSocketsDirectory` | UDS socket / metadata file lifecycle.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `handleApplication(scope)`                                                                  | Component entry point — captures `httpOptions` for the scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `getHttpOptions()`                                                                          | Returns the current scope's `HttpOptions`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `deliverSocket()`                                                                           | IPC-delivered socket handoff from `socketRouter`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `proxyRequest()`                                                                            | Cross-port request routing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `registerServer()`                                                                          | Records a server for a port in the `SERVERS` map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `getPorts()`                                                                                | Resolves listener options → list of `{port, secure}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `httpServer()`                                                                              | Main listener registration entry point.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `getHTTPServer(port, secure, options)`                                                      | **The largest function in the file.** Creates/retrieves the underlying Node HTTP/HTTPS server. Wires `request`, `upgrade`, error handlers, TLS context, and the per-port middleware chain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `makeCallbackChain()`                                                                       | Builds the per-port handler chain via `middlewareChain.topoSort`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `unhandled()`                                                                               | Terminal 404 handler.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `onRequest()`                                                                               | Thin alias of `httpServer({requestOnly: true})`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `onUpgrade()` / `upgradeListeners` (const)                                                  | Register HTTP upgrade listener; underlying list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `onWebSocket()` / `websocketListeners` (const)                                              | Register WebSocket listener; auto-adds default upgrade handler the first time it runs for a port. Underlying list of registrations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `enableProxyProtocol()`                                                                     | PROXY v1/v2 stripping on UDS mirrors (Node 24+-compatible workaround). Decoding lives in `serverHelpers/proxyProtocol.ts`; v2 TLVs forward the client source address plus the connection's TLS facts a fronting proxy (symphony) observed — ALPN, SNI authority, TLS version/cipher, JA3/JA4 fingerprints, and the mTLS client cert chain. These are surfaced on `request.connectionInfo` (see below); the verified cert chain is additionally exposed with TLSSocket semantics (`authorized`, `getPeerCertificate()`) so HTTP/MQTT mTLS auth works unchanged, and the SSL TLV lets `request.protocol` report `https` on the plaintext UDS mirror. A peer that stalls mid-header is destroyed after `prehandoffTimeout` (default 10s), matching `withProxyProtocol`'s guard on the raw-socket path. |
-| `defaultNotFound()`                                                                         | Default 404 response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `logRequest()`                                                                              | Per-request access log line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `getRequestId()`                                                                            | Generates the per-request correlation ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Symbol                                                                                                                                   | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerUdsCleanupPaths`, `recordUdsBindSuccess`, `cleanupUdsFiles`, `markUdsBindFailed`, `writeUdsMetadata`, `cleanupSocketsDirectory` | UDS socket / metadata file lifecycle. Ownership-aware: `recordUdsBindSuccess` captures the inode a worker's own bind confirmed; `cleanupUdsFiles`/`markUdsBindFailed` only unlink a path when the inode on disk still matches, so an overlapping restart's outgoing worker can never delete the replacement that already rebound the same path (see restartWorkers() in manageThreads.js). `cleanupSocketsDirectory` is the separate crash-path sweep, run once from `socketRouter.ts`'s `startHTTPThreads` on main-thread startup, before any worker can bind.                                                                                                                                                                                                                                     |
+| `handleApplication(scope)`                                                                                                               | Component entry point — captures `httpOptions` for the scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `getHttpOptions()`                                                                                                                       | Returns the current scope's `HttpOptions`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `deliverSocket()`                                                                                                                        | IPC-delivered socket handoff from `socketRouter`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `proxyRequest()`                                                                                                                         | Cross-port request routing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `registerServer()`                                                                                                                       | Records a server for a port in the `SERVERS` map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `getPorts()`                                                                                                                             | Resolves listener options → list of `{port, secure}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `httpServer()`                                                                                                                           | Main listener registration entry point.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `getHTTPServer(port, secure, options)`                                                                                                   | **The largest function in the file.** Creates/retrieves the underlying Node HTTP/HTTPS server. Wires `request`, `upgrade`, error handlers, TLS context, and the per-port middleware chain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `makeCallbackChain()`                                                                                                                    | Builds the per-port handler chain via `middlewareChain.topoSort`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `unhandled()`                                                                                                                            | Terminal 404 handler.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `onRequest()`                                                                                                                            | Thin alias of `httpServer({requestOnly: true})`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `onUpgrade()` / `upgradeListeners` (const)                                                                                               | Register HTTP upgrade listener; underlying list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `onWebSocket()` / `websocketListeners` (const)                                                                                           | Register WebSocket listener; auto-adds default upgrade handler the first time it runs for a port. Underlying list of registrations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `enableProxyProtocol()`                                                                                                                  | PROXY v1/v2 stripping on UDS mirrors (Node 24+-compatible workaround). Decoding lives in `serverHelpers/proxyProtocol.ts`; v2 TLVs forward the client source address plus the connection's TLS facts a fronting proxy (symphony) observed — ALPN, SNI authority, TLS version/cipher, JA3/JA4 fingerprints, and the mTLS client cert chain. These are surfaced on `request.connectionInfo` (see below); the verified cert chain is additionally exposed with TLSSocket semantics (`authorized`, `getPeerCertificate()`) so HTTP/MQTT mTLS auth works unchanged, and the SSL TLV lets `request.protocol` report `https` on the plaintext UDS mirror. A peer that stalls mid-header is destroyed after `prehandoffTimeout` (default 10s), matching `withProxyProtocol`'s guard on the raw-socket path. |
+| `defaultNotFound()`                                                                                                                      | Default 404 response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `logRequest()`                                                                                                                           | Per-request access log line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `getRequestId()`                                                                                                                         | Generates the per-request correlation ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 ### Middleware ordering (`before` / `after`)
 
@@ -119,8 +119,35 @@ Components register listeners with optional `before: 'name'` / `after: 'name'` o
 
 The default WebSocket upgrade handler is registered automatically inside `onWebSocket()` the first time it runs for a given port.
 
+### Application mounts (`host` / `urlPath` in the root config)
+
+An operator mounts an application by putting `host`/`urlPath` on its entry in the **root** config; `components/scopeMount.ts` models it and the loader threads it into every `Scope` for that application (both load paths — the root-config `package` recursion and the components-root directory scan).
+
+**The mount is applied at exactly one place: `Scope.routeFor()`, used by the `scope.server` proxy.** Do not push it anywhere else. In particular, do not compose it into the plugin config the entry pipeline reads: `entry.urlPath` is what `graphqlSchema` and `jsResource` derive **resource** paths from, and the router strips the mount _before_ REST resolves them. Composing it there registers a table at `/v1/Thing` while REST looks up `Thing`, and every mounted REST route 404s. A single-app `static` test will not catch it — static de-prefixes its own map keys, so it stays self-consistent either way.
+
+Consequences worth knowing:
+
+- Everything inside an application addresses itself **mount-relative**. Only two things need the absolute path: code that emits a URL back to the client (use `Scope.externalBasePath()` — static's redirect `Location`), and code that bypasses the routed chain (legacy fastify registers on the bare server, so its route prefix must be the full external path). `static.ts`'s mount-root redirect gates on the _external_ base path, not the plugin-local one — a root-level static plugin (`baseURLPath === '/'`) still needs the redirect when the application itself carries a mount, since the client-visible mount root is then `externalBaseURLPath`, not `/`.
+- A plugin registering per-mount state must key it on `Scope.routeFor()`'s resolved route, not on the parts it composes from — distinct `(mount, pluginUrlPath)` pairs can flatten to the same string (`/a`+`bc` and `/ab`+`c`). `REST.ts`'s `startedMounts` does this; it replaced a process-global `started` flag that silently 404'd the second mounted application's REST API. `handleApplication` also closes over `resources`/`httpOptions` per call rather than a module-level var, and skips deploy pre-flight validation scopes (`scope.isTransientValidation`) entirely — registering handlers from a throwaway validation scope would splice a validation run into the live request path and permanently mark that mount started, silently skipping the real scope's later registration.
+- A mount is routing, **not** isolation: exported resources stay instance-wide, and a `host` mount cannot constrain legacy fastify routes — `fastifyRoutes.ts` refuses to load (throws) rather than warn when a `host` mount is configured, since the fallback really is reachable on every host.
+- An invalid mount (unparseable `host`/`urlPath`) fails the application **closed**: `componentLoader.tryRootConfigMount` skips loading it entirely rather than falling back to unmounted access — loading unconstrained would silently drop the isolation the operator asked for, which is worse than not loading at all.
+- Two applications mounted at different routes can register same-named middleware (e.g. both enable `rest`) without colliding: `middlewareChain.resolveRoutedChains` resolves `before`/`after` name references against a registry scoped to that route's own group, falling back to a _global_ registry that only holds genuinely unmounted entries (e.g. `authentication`) — never another mounted route's entries.
+- `host` matching reads `request.host` (Harper's `Request.host` getter), not the raw `Host` header — HTTP/2 clients send `:authority`, never `Host`, so reading the header directly silently 404s every host-mounted app under h2 while h1 keeps working. `hostnameFromHeader` also strips a trailing dot (`api.example.com.`, the absolute-FQDN form some resolvers emit) since it names the same origin.
+- `scopeMount.normalizeMountHost` validates against the same grammar as the `deploy_component` operation's `host` field (bare DNS hostname or IPv6 literal) and throws otherwise, so a hand-typed root-config `host` with a port/scheme/path fails the application closed too, instead of loading it unreachably. `nestScopeMount` logs a warning when a child's `host` is discarded by the parent-authority rule, so that isn't silent.
+
 ---
 
+## Operations authorization boundary
+
+Operations request bodies are untrusted data. `serverHandlers.js → handlePostRequest()` rejects
+prototype-mutating property names and strips the legacy `bypass_auth` property before dispatch.
+`serverUtilities.ts → chooseOperation()` never reads authorization control from the body: trusted
+internal callers pass bypass state as a separate argument and expose it to operation handlers only
+through `operationAuthorizationState.ts`'s async context. When an operation registered by a component
+must run on a worker, `registeredOperations.ts` carries that state in the same-process ITC envelope,
+separately from the structured-cloned body. Never attach trusted dispatch state to an operation
+payload.
+
 ## Resource ↔ HTTP boundary
 
 `REST.ts → http(request, nextHandler)` is the chief integration point: it takes a `Request`, asks the `Resources` registry for a match, builds a `RequestTarget`, and dispatches into the Resource class's static method. Cache headers are translated to `request.expiresAt` / `onlyIfCached` / `noCache` flags within the same function.