harper 5.1.20 → 5.2.0-alpha.5

package/server/itc/serverHandlers.js

@@ -11,6 +11,7 @@ const harperBridge =
 	require('../../dataLayer/harperBridge/harperBridge.ts').default ||
 	require('../../dataLayer/harperBridge/harperBridge.ts');
 const process = require('process');
+const { isMainThread, workerData } = require('worker_threads');
 const { resetDatabases } = require('../../resources/databases.ts');
 
 /**
@@ -22,6 +23,13 @@ const serverItcHandlers = {
 	[hdbTerms.ITC_EVENT_TYPES.USER]: userHandler,
 	[hdbTerms.ITC_EVENT_TYPES.COMPONENT_STATUS_REQUEST]: componentStatusRequestHandler,
 	[hdbTerms.ITC_EVENT_TYPES.RESOURCE_OPENAPI_REQUEST]: resourceOpenApiRequestHandler,
+	[hdbTerms.ITC_EVENT_TYPES.MIDDLEWARE_CHAINS_REQUEST]: middlewareChainsRequestHandler,
+	// #1736 cross-thread registered-operation bridge. Lazy require: this module loads on every
+	// thread via itc.js, and registeredOperations pulls in the serverUtilities module graph.
+	[hdbTerms.ITC_EVENT_TYPES.OPERATION_REGISTERED]: (event) =>
+		require('../serverHelpers/registeredOperations.ts').operationRegisteredHandler(event),
+	[hdbTerms.ITC_EVENT_TYPES.OPERATION_EXECUTE_REQUEST]: (event) =>
+		require('../serverHelpers/registeredOperations.ts').operationExecuteRequestHandler(event),
 };
 
 /**
@@ -105,6 +113,31 @@ userHandler.addListener = function (listener) {
 	userListeners.push(listener);
 };
 
+const resourceListeners = [];
+/**
+ * Local-only fan-out for "JS resources just registered" (resources.js loaded via the jsResource
+ * plugin). Unlike schema/user changes this is NOT an ITC event: each worker loads and registers
+ * its own JS resources, so a listener (e.g. the MCP application-tool rebuild) only needs to run in
+ * the worker where the registration happened. Surfaces author opt-ins (`static mcpTools`/
+ * `mcpPrompts`) that land on the resource registry after the MCP component's boot scan (#1448).
+ */
+function resourceHandler() {
+	for (const listener of resourceListeners) {
+		try {
+			listener();
+		} catch (err) {
+			hdbLogger.error(err);
+		}
+	}
+}
+resourceHandler.addListener = function (listener) {
+	resourceListeners.push(listener);
+};
+// Test seam: drop registered listeners so a unit suite doesn't leak fakes into later suites.
+resourceHandler._resetListenersForTest = function () {
+	resourceListeners.length = 0;
+};
+
 /**
  * Handles incoming requests for component status from inter-thread communication (ITC).
  * Validates the event, retrieves the current thread's component statuses, and sends a response
@@ -211,8 +244,45 @@ async function resourceOpenApiRequestHandler(event) {
 	}
 }
 
+/**
+ * Handles the main thread's request for the resolved HTTP/upgrade/WebSocket middleware chains (#1573).
+ * Only HTTP workers reply: the main thread carries just the operations-API middleware (so it stays
+ * silent even though it has responders), and job workers have none. HTTP workers answer even when
+ * they have no middleware (empty chains) so get_status doesn't wait out the request timeout. First
+ * worker to answer wins — all HTTP workers register identically, so any one is representative.
+ */
+async function middlewareChainsRequestHandler(event) {
+	try {
+		const validate = validateEvent(event);
+		if (validate) {
+			hdbLogger.error(validate);
+			return;
+		}
+
+		if (isMainThread || workerData?.name !== hdbTerms.THREAD_TYPES.HTTP) return;
+		const { describeMiddlewareChains } = require('../http.ts');
+
+		const responseMessage = {
+			type: hdbTerms.ITC_EVENT_TYPES.MIDDLEWARE_CHAINS_RESPONSE,
+			message: {
+				requestId: event.message.requestId,
+				chains: describeMiddlewareChains(),
+			},
+		};
+
+		if (!threads.sendToThread(event.message.originator, responseMessage)) {
+			hdbLogger.trace(
+				`Dropping middleware chains response for request ${event.message.requestId}: originator thread ${event.message.originator} is unreachable`
+			);
+		}
+	} catch (error) {
+		hdbLogger.error('Error handling middleware chains request:', error);
+	}
+}
+
 module.exports = serverItcHandlers;
 // Named exports so consumers (e.g., MCP listChanged) can subscribe via
 // `userHandler.addListener(fn)` / `schemaHandler.addListener(fn)`.
 module.exports.userHandler = userHandler;
 module.exports.schemaHandler = schemaHandler;
+module.exports.resourceHandler = resourceHandler;

package/server/liveSubscriptionAuth.ts

@@ -0,0 +1,152 @@
+import hdbLogger from '../utility/logging/harper_logger.ts';
+
+/**
+ * Continuous re-authorization for live subscriptions (#1414).
+ *
+ * Subscribe-time authorization is a point-in-time check: once a stream (SSE / WebSocket / MQTT)
+ * is open, it keeps delivering even if the principal later loses access (drop_user, role/permission
+ * change) or its bearer token expires. This registry re-evaluates each live subscription's
+ * authorization — at the TABLE/RBAC level, matching how the subscription was granted; there is no
+ * per-record evaluation — and terminates any that no longer authorize.
+ *
+ * Triggers: (1) immediately on the ITC user-change broadcast (the same signal that rebuilds the
+ * user/role cache), and (2) on a fixed interval as a backstop and to catch token expiry, which is
+ * not event-signaled.
+ */
+
+// Backstop interval; also catches token expiry, which is not event-signaled. Overridable for tests.
+const RECHECK_INTERVAL_MS = Number(process.env.HARPER_SUBSCRIPTION_REAUTH_INTERVAL_MS) || 30_000;
+
+interface LiveSubscription {
+	username: string;
+	/** JWT `exp` (seconds since epoch) of the credential the subscription was opened with, if any. */
+	authExpiresAt?: number;
+	/** Returns true if the principal is still authorized for this subscription. */
+	recheck: () => Promise<boolean>;
+	/** Stop delivery and tear down the subscription. */
+	terminate: () => void;
+}
+
+const registry = new Set<LiveSubscription>();
+let sweepTimer: any = null;
+let itcListenerInstalled = false;
+let sweeping = false;
+
+function ensureStarted(): void {
+	if (!sweepTimer) {
+		sweepTimer = setInterval(() => void sweep(), RECHECK_INTERVAL_MS);
+		// don't keep the worker alive solely for the recheck timer
+		sweepTimer.unref?.();
+	}
+	if (!itcListenerInstalled) {
+		try {
+			// Fire an immediate sweep when a user/role mutation propagates. serverHandlers rebuilds the
+			// user/role cache before invoking listeners, so recheck() observes the new permissions.
+			const handlers = require('./itc/serverHandlers.js');
+			if (handlers?.userHandler?.addListener) {
+				handlers.userHandler.addListener(() => void sweep());
+				itcListenerInstalled = true;
+			}
+		} catch (error) {
+			hdbLogger.trace?.(`liveSubscriptionAuth: ITC userHandler unavailable: ${(error as Error).message}`);
+		}
+	}
+}
+
+function stopIfIdle(): void {
+	if (registry.size === 0 && sweepTimer) {
+		clearInterval(sweepTimer);
+		sweepTimer = null;
+	}
+}
+
+/**
+ * Register a live subscription for continuous re-authorization. The returned subscription's normal
+ * teardown (end()/close) automatically unregisters it, so callers don't need to.
+ */
+export function registerLiveSubscription(opts: {
+	subscription: any;
+	username: string;
+	authExpiresAt?: number;
+	recheck: () => Promise<boolean>;
+}): void {
+	const { subscription, username, authExpiresAt, recheck } = opts;
+	if (!subscription || typeof subscription !== 'object') return;
+
+	const entry: LiveSubscription = {
+		username,
+		authExpiresAt,
+		recheck,
+		terminate: () => {
+			// emit('close') runs the subscription's own teardown wiring; end() removes it from the
+			// broadcast notify loop so no further events are delivered. Both are idempotent.
+			try {
+				subscription.emit?.('close');
+			} catch {
+				/* ignore */
+			}
+			try {
+				subscription.end?.();
+			} catch {
+				/* ignore */
+			}
+		},
+	};
+	registry.add(entry);
+
+	const unregister = () => {
+		registry.delete(entry);
+		stopIfIdle();
+	};
+	// Both transports ultimately call end() on normal teardown (MQTT unsubscribe/disconnect; SSE close
+	// is wired to end()); wrap it so a closed stream never leaks a registry entry. Also listen for
+	// 'close' to cover any iterable that closes without an end().
+	const originalEnd = typeof subscription.end === 'function' ? subscription.end.bind(subscription) : null;
+	if (originalEnd) {
+		subscription.end = function (...args: any[]) {
+			unregister();
+			return originalEnd(...args);
+		};
+	}
+	subscription.on?.('close', unregister);
+
+	ensureStarted();
+}
+
+async function sweep(): Promise<void> {
+	if (sweeping) return; // a slow recheck must not overlap with the next tick/event
+	sweeping = true;
+	try {
+		const now = Date.now();
+		for (const entry of registry) {
+			try {
+				const expired = entry.authExpiresAt != null && now >= entry.authExpiresAt * 1000;
+				const stillAuthorized = expired ? false : await entry.recheck();
+				const revoke = expired || !stillAuthorized;
+				if (revoke) {
+					registry.delete(entry);
+					entry.terminate();
+				}
+			} catch (error) {
+				// fail closed: if authorization can't be confirmed, revoke
+				registry.delete(entry);
+				try {
+					entry.terminate();
+				} catch {
+					/* ignore */
+				}
+				hdbLogger.warn?.(
+					`liveSubscriptionAuth: revoked subscription for ${entry.username} after recheck error: ${(error as Error).message}`
+				);
+			}
+		}
+	} finally {
+		sweeping = false;
+		stopIfIdle();
+	}
+}
+
+/** Test-only: current number of tracked subscriptions. */
+export function _liveSubscriptionCount(): number {
+	return registry.size;
+}

package/server/loadRootComponents.js

@@ -6,6 +6,7 @@ const configUtils = require('../config/configUtils.ts');
 const { dirname } = require('path');
 const { loadCertificates } = require('../security/keys.ts');
 const { installApplications } = require('../components/Application.ts');
+const { errorForLog } = require('../utility/logging/harper_logger.ts');
 
 let loadedComponents = new Map();
 /**
@@ -16,7 +17,7 @@ async function loadRootComponents(isWorkerThread = false) {
 	try {
 		if (isMainThread && !process.env.HARPER_SAFE_MODE) await installApplications();
 	} catch (error) {
-		console.error(error);
+		console.error(errorForLog(error));
 	}
 
 	let resources = resetResources();

package/server/middlewareChain.ts

@@ -8,6 +8,18 @@ export type HttpEntry = {
 	host?: string;
 };
 
+/**
+ * A single route's resolved middleware order. `order` is the topologically sorted
+ * list of entries the chain will invoke, outermost first. `host`/`urlPath` are the
+ * route scope (both undefined for the default route). This is the observable form of
+ * what `buildRoutedChain`/`buildLinearChain` actually execute — see `describeChains`.
+ */
+export type ResolvedChain = {
+	host?: string;
+	urlPath?: string;
+	order: HttpEntry[];
+};
+
 /**
  * Topological sort of middleware entries respecting `before`/`after` constraints.
  * Uses the original registration index as a tiebreaker so config order is preserved
@@ -92,7 +104,7 @@ export function topoSort(entries: HttpEntry[], onCycle?: () => void): HttpEntry[
  */
 export function buildLinearChain(sorted: HttpEntry[], fallback: Function): Function {
 	let next = fallback;
-	for (let i = sorted.length; i > 0; ) {
+	for (let i = sorted.length; i > 0;) {
 		const { listener } = sorted[--i];
 		const callback = next;
 		next = (...args: any[]) => listener(...args, callback);
@@ -208,12 +220,16 @@ export function stripPrefix(request: any, prefix: string): any {
  * The matched (and prefix-stripped) request is substituted back into the same
  * position before forwarding to the inner chain.
  */
-export function buildRoutedChain(
-	portEntries: HttpEntry[],
-	fallback: Function,
-	onCycle?: () => void,
-	requestArgIndex: number = 0
-): Function {
+/**
+ * Resolves the per-route middleware order for a port that has sub-routes.
+ * Returns each sub-route in dispatch priority order (host+path > host-only > path-only;
+ * longer paths win ties), followed by the default route last. Each route's `order` is the
+ * `after`-dependency-resolved, topologically sorted entry list the chain will invoke.
+ *
+ * This is the single source of ordering truth: `buildRoutedChain` builds callbacks from it,
+ * 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>();
 	for (const entry of portEntries) {
@@ -233,19 +249,36 @@ export function buildRoutedChain(
 	const defaultGroup = routeGroups.find((g) => !g.host && !g.urlPath);
 	const subRouteGroups = routeGroups.filter((g) => g.host || g.urlPath);
 
-	const subRouteChains = subRouteGroups.map((group) => {
-		const resolved = resolveDeps(group.entries, nameToEntry);
-		return { host: group.host, urlPath: group.urlPath, chain: buildLinearChain(topoSort(resolved, onCycle), fallback) };
-	});
+	const subRoutes: ResolvedChain[] = subRouteGroups.map((group) => ({
+		host: group.host,
+		urlPath: group.urlPath,
+		order: topoSort(resolveDeps(group.entries, nameToEntry), onCycle),
+	}));
 
-	subRouteChains.sort((a, b) => {
+	subRoutes.sort((a, b) => {
 		const aSpec = (a.host ? 2 : 0) + (a.urlPath ? 1 : 0);
 		const bSpec = (b.host ? 2 : 0) + (b.urlPath ? 1 : 0);
 		if (aSpec !== bSpec) return bSpec - aSpec;
 		return (b.urlPath?.length ?? 0) - (a.urlPath?.length ?? 0);
 	});
 
-	const defaultChain = buildLinearChain(topoSort(defaultGroup?.entries ?? [], onCycle), fallback);
+	return [...subRoutes, { order: topoSort(defaultGroup?.entries ?? [], onCycle) }];
+}
+
+export function buildRoutedChain(
+	portEntries: HttpEntry[],
+	fallback: Function,
+	onCycle?: () => void,
+	requestArgIndex: number = 0
+): Function {
+	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);
+	const subRouteChains = resolved.slice(0, -1).map((route) => ({
+		host: route.host,
+		urlPath: route.urlPath,
+		chain: buildLinearChain(route.order, fallback),
+	}));
 
 	return function dispatch(...args: any[]) {
 		const request = args[requestArgIndex];
@@ -263,20 +296,77 @@ export function buildRoutedChain(
 	};
 }
 
+export type UnresolvedOrderingRef = { entryName?: string; kind: 'before' | 'after'; target: string };
+
+/**
+ * Returns the `before`/`after` references among `entries` that name no registered entry.
+ * topoSort silently ignores these, so they deserve a diagnostic (see makeCallbackChain).
+ */
+export function findUnresolvedOrderingRefs(entries: HttpEntry[]): UnresolvedOrderingRef[] {
+	const names = new Set<string>();
+	for (const { name } of entries) {
+		if (name) names.add(name);
+	}
+	const unresolved: UnresolvedOrderingRef[] = [];
+	for (const { name, before, after } of entries) {
+		if (before && !names.has(before)) unresolved.push({ entryName: name, kind: 'before', target: before });
+		if (after && !names.has(after)) unresolved.push({ entryName: name, kind: 'after', target: after });
+	}
+	return unresolved;
+}
+
 /**
  * Builds the complete middleware chain for a given port from the full responders list.
  * Uses a flat linear chain when no sub-routes are present (fast path),
  * or a route-dispatching chain when any entry has urlPath or host.
+ *
+ * @param onUnresolved - called (once per unresolved reference) when a `before`/`after` names no
+ * registered entry, so a typo or legacy config key doesn't silently drop the ordering constraint.
+ * Reported on the chain's first dispatch, not at build time: the chain is rebuilt on every
+ * registration, so an early build may reference an entry that a later registration resolves.
  */
 export function makeCallbackChain(
 	responders: HttpEntry[],
 	portNum: number | string,
 	fallback: Function,
 	onCycle?: () => void,
-	requestArgIndex: number = 0
+	requestArgIndex: number = 0,
+	onUnresolved?: (ref: UnresolvedOrderingRef) => void
 ): Function {
 	const portEntries = responders.filter(({ port }) => port === portNum || port === 'all');
-	if (portEntries.some((e) => e.urlPath || e.host))
-		return buildRoutedChain(portEntries, fallback, onCycle, requestArgIndex);
-	return buildLinearChain(topoSort(portEntries, onCycle), fallback);
+	const chain = portEntries.some((e) => e.urlPath || e.host)
+		? buildRoutedChain(portEntries, fallback, onCycle, requestArgIndex)
+		: buildLinearChain(topoSort(portEntries, onCycle), fallback);
+	if (onUnresolved) {
+		const unresolved = findUnresolvedOrderingRefs(portEntries);
+		if (unresolved.length > 0) {
+			let reported = false;
+			return (...args: any[]) => {
+				if (!reported) {
+					reported = true;
+					for (const ref of unresolved) onUnresolved(ref);
+				}
+				return chain(...args);
+			};
+		}
+	}
+	return chain;
+}
+
+/**
+ * Describes the resolved middleware order for a port without building callbacks.
+ * Mirrors `makeCallbackChain`'s branch selection and reuses the same resolvers, so the
+ * returned order is exactly what a request on that port would traverse. Used for the
+ * chain-build debug log and for `get_status` introspection (issue #1573).
+ */
+export function describeChains(
+	responders: HttpEntry[],
+	portNum: number | string,
+	onCycle?: () => void
+): ResolvedChain[] {
+	// Must use the exact same port selection and routing branch as makeCallbackChain so that, for a
+	// given portNum, the described order equals the order the built chain actually serves.
+	const portEntries = responders.filter(({ port }) => port === portNum || port === 'all');
+	if (portEntries.some((e) => e.urlPath || e.host)) return resolveRoutedChains(portEntries, onCycle);
+	return [{ order: topoSort(portEntries, onCycle) }];
 }

package/server/mqtt.ts

@@ -463,7 +463,8 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					break;
 				case 'pubcomp':
 				case 'puback':
-					session.acknowledge(packet.messageId);
+					await session.acknowledge(packet.messageId);
+					emitEvent('acknowledged', session, packet);
 					break;
 				case 'pingreq':
 					sendPacket({ cmd: 'pingresp' });

package/server/operationsServer.ts

@@ -25,7 +25,7 @@ import {
 	serverErrorHandler,
 	reqBodyValidationHandler,
 } from './serverHelpers/serverHandlers.js';
-import { registerBunFastifyInstance } from './http.ts';
+import { registerFastifyInstance } from './http.ts';
 import { registerContentHandlers } from './serverHelpers/contentTypes.ts';
 import { getConfigObj } from '../config/configUtils.ts';
 import { registerMcpProfile } from '../components/mcp/index.ts';
@@ -94,7 +94,7 @@ async function operationsServer(options: ServerOptions & { resources?: Resources
 			// On Bun, register the Fastify instance so requests can be delegated via inject()
 			if (typeof globalThis.Bun !== 'undefined') {
 				const port = options.port || options.securePort || env.get(CONFIG_PARAMS.OPERATIONSAPI_NETWORK_PORT);
-				if (port) registerBunFastifyInstance(port, server);
+				if (port) registerFastifyInstance(port, server);
 			}
 			if (!server.server.closeIdleConnections) {
 				// before Node v18, closeIdleConnections is not available, and we have to setup a listener for fastify

package/server/serverHelpers/Headers.ts

@@ -60,6 +60,30 @@ export class Headers extends Map<string, [string, string | string[]]> {
 	}
 }
 
+/**
+ * Add a field-name token to the `Vary` response header, appending to (and de-duplicating against) any
+ * existing value rather than overwriting it. Used to declare cache-partitioning dimensions (Origin,
+ * Authorization, Cookie) so a shared cache/CDN keys the response correctly (#1518, #1565).
+ */
+export function addVaryHeader(
+	headers: { get(name: string): any; set(name: string, value: string): any },
+	token: string
+) {
+	const existing = headers.get('Vary');
+	if (!existing) {
+		headers.set('Vary', token);
+		return;
+	}
+	const existingString = Array.isArray(existing) ? existing.join(', ') : existing;
+	const lowerToken = token.toLowerCase();
+	for (const part of existingString.split(',')) {
+		const trimmed = part.trim().toLowerCase();
+		// a `Vary: *` already covers every dimension, and an exact token match is a no-op
+		if (trimmed === lowerToken || trimmed === '*') return;
+	}
+	headers.set('Vary', existingString + ', ' + token);
+}
+
 export function appendHeader(headers, name, value, commaDelimited) {
 	if (headers.append) {
 		headers.append(name, value, commaDelimited);

package/server/serverHelpers/JSONStream.ts

@@ -129,7 +129,7 @@ class JSONStream extends Readable {
 				}
 			},
 			(error) => {
-				console.error(error);
+				console.error(harperLogger.errorForLog(error));
 				this.done = true;
 				this.push(errorToString(error));
 				this.push(null);
@@ -201,7 +201,7 @@ class JSONStream extends Readable {
 				}
 			} while (this.push(nextString));
 		} catch (error) {
-			console.error(error);
+			console.error(harperLogger.errorForLog(error));
 			this.push(errorToString(error));
 			this.push(null);
 			return true;
@@ -218,7 +218,7 @@ class JSONStream extends Readable {
 }
 
 function handleError(error) {
-	console.error(error);
+	console.error(harperLogger.errorForLog(error));
 	return JSON.stringify(errorToString(error));
 }
 

package/server/serverHelpers/Request.ts

@@ -436,6 +436,133 @@ export class BunRequest {
 	}
 }
 
+/**
+ * uWebSockets.js Request adapter. Wraps the data extracted from a uWS HttpRequest/HttpResponse
+ * (which is only valid synchronously inside the route handler) into Harper's request interface,
+ * matching BunRequest. Intended for the plaintext-UDS-behind-symphony path: TLS/mTLS are
+ * terminated upstream, so peerCertificate/authorized are not available here and the real client
+ * IP arrives via the X-Forwarded-For header.
+ */
+export class UwsRequest {
+	#body: UwsRequestBody | undefined;
+	#isSecure: boolean;
+	#ip: string | undefined;
+	#signal: AbortSignal | undefined;
+	public _nodeRequest: any = null;
+	public _nodeResponse: any = null;
+	public method: string;
+	public url: string;
+	public headers: RequestHeaders;
+	public isWebSocket?: boolean;
+	public user?: any;
+	public response: {
+		status?: number;
+		headers: ResponseHeaders;
+	};
+	public __harperRequestUpgraded: boolean;
+
+	constructor(source: {
+		method: string;
+		url: string;
+		headers: Record<string, string | string[]>;
+		ip?: string;
+		secure?: boolean;
+		body?: UwsRequestBody;
+		signal?: AbortSignal;
+	}) {
+		this.method = source.method;
+		this.url = source.url;
+		this.headers = new RequestHeaders(source.headers);
+		this.#isSecure = !!source.secure;
+		this.#ip = source.ip;
+		this.#body = source.body;
+		this.#signal = source.signal;
+		this.__harperRequestUpgraded = false;
+	}
+	get absoluteURL() {
+		return this.protocol + '://' + this.host + this.url;
+	}
+	get pathname() {
+		const queryStart = this.url.indexOf('?');
+		if (queryStart > -1) return this.url.slice(0, queryStart);
+		return this.url;
+	}
+	set pathname(pathname) {
+		const queryStart = this.url.indexOf('?');
+		if (queryStart > -1) this.url = pathname + this.url.slice(queryStart);
+		else this.url = pathname;
+	}
+	get protocol() {
+		// Behind symphony the on-the-wire hop is plaintext; the original scheme is conveyed
+		// by the proxy (X-Forwarded-Proto) or assumed from the listener's secure flag.
+		const xfp = this.headers.get('x-forwarded-proto');
+		if (xfp) return Array.isArray(xfp) ? xfp[0] : xfp;
+		return this.#isSecure ? 'https' : 'http';
+	}
+	get ip() {
+		// A real peer address (direct-TCP path) is authoritative and unspoofable, so it wins. Only the
+		// symphony-UDS path — where the socket has no client address (#ip is left unset) and symphony is
+		// the trusted setter/stripper of X-Forwarded-For — falls back to XFF. This prevents a direct
+		// client from spoofing `X-Forwarded-For: 127.0.0.1` to satisfy local auth (security/auth.ts).
+		if (this.#ip) return this.#ip;
+		const xff = this.headers.get('x-forwarded-for');
+		if (xff) return (Array.isArray(xff) ? xff[0] : xff).split(',')[0].trim();
+		return '';
+	}
+	get authorized() {
+		// TLS terminated upstream — client authorization not available at this hop.
+		return undefined;
+	}
+	get peerCertificate() {
+		return null;
+	}
+	get mtlsConfig() {
+		return undefined;
+	}
+	get body() {
+		// Bodyless requests get an already-ended empty stream so consumers can still read it uniformly.
+		if (!this.#body) {
+			this.#body = new UwsRequestBody();
+			this.#body.push(null);
+		}
+		return this.#body;
+	}
+	get host() {
+		return this.headers.get('host') as string;
+	}
+	get hostname() {
+		return this.headers.get('host') as string;
+	}
+	get httpVersion() {
+		return '1.1';
+	}
+	get isAborted() {
+		return this.#signal?.aborted ?? false;
+	}
+	get signal(): AbortSignal {
+		return this.#signal ?? new AbortController().signal;
+	}
+	_abort(): void {
+		// Abort is driven by the uWS res.onAborted handler wired into the provided signal.
+	}
+	get nodeRequest() {
+		return null;
+	}
+	sendEarlyHints(_link: string, _headers: Record<string, any> = {}) {
+		// Early hints not wired for the uWS path
+	}
+}
+
+// A push-based Readable: the uWS server pushes each request-body chunk (and the terminating null) in
+// as it arrives off the socket, so consumers (streamToBuffer, future streaming deserializers) see a
+// real stream instead of a pre-buffered blob. Extends Readable so it matches the RequestBody/
+// BunRequestBody contract — on/pipe, `for await` async iteration, destroy() for abort handling.
+// _read() is a no-op because flow is driven by push() from the uWS onData callback; uWS has no inbound
+// backpressure, so pushed-but-unread chunks queue here (bounded by the server's maxBodyBytes ceiling).
+export class UwsRequestBody extends Readable {
+	_read() {}
+}
+
 class RequestBody {
 	#nodeRequest: IncomingMessage;
 	constructor(nodeRequest: IncomingMessage) {

package/server/serverHelpers/contentTypes.ts

@@ -623,15 +623,10 @@ function transformIterable(iterable, transform) {
 				next() {
 					const step = iterator.next();
 					if (step.then) {
-						return step.then((step) => ({
-							value: transform(step.value),
-							done: step.done,
-						}));
+						// don't transform the terminal sentinel step, whose value is undefined
+						return step.then((result) => (result.done ? result : { value: transform(result.value), done: false }));
 					}
-					return {
-						value: transform(step.value),
-						done: step.done,
-					};
+					return step.done ? step : { value: transform(step.value), done: false };
 				},
 				return(value) {
 					return iterator.return(value);