@harperfast/harper 5.2.10 → 5.3.0-alpha.1

package/server/serverHelpers/serverUtilities.ts

@@ -41,6 +41,8 @@ import * as status from '../status/index.ts';
 import * as regDeprecated from '../../resources/registrationDeprecated.ts';
 import * as deploymentOperations from '../../components/deploymentOperations.ts';
 import * as secretOperations from '../../components/secretOperations.ts';
+import * as trustPolicyOperations from '../../security/authn/oidc/trustPolicyOperations.ts';
+import * as tokenExchange from '../../security/authn/oidc/tokenExchange.ts';
 import { contextStorage } from '../../resources/transaction.ts';
 import { isMainThread } from 'node:worker_threads';
 import {
@@ -49,6 +51,7 @@ import {
 	setLocalOperationDispatch,
 } from './registeredOperations.ts';
 import { runWithOperationAuthorizationBypass } from './operationAuthorizationState.ts';
+import { stripSuppliedParsedSqlObject } from './requestSanitization.ts';
 
 const pSearchSearch = util.promisify(search.search);
 let pEvaluateSql: (sql: string) => Promise<any>;
@@ -79,6 +82,42 @@ export type OperationFunctionName = ValueOf<typeof terms.OPERATIONS_ENUM>;
  * handles the response to the sender.
  */
 // TODO: Replace Function type with an actual function type (e.g. (): Thingy)
+/**
+ * Fields stripped from an operation body before it reaches the operations log.
+ *
+ * `credentials` carries a transient token on deploy_component (`registryAuth` is its pre-rename
+ * name — still stripped, since this runs ahead of the validation that now rejects it). `value` /
+ * `values` carry .env secrets from set_env_value; `value` / `envelope` carry secrets from
+ * set_secret. `token` is the login-purpose token (login) and the CI identity token
+ * (exchange_oidc_token), and is also stripped defensively — no operation declares a top-level `token`,
+ * but validation allows unknown keys, so a mistyped `harper deploy setup token=…` must not log a live
+ * credential. `refresh_token` is the 30-day credential (refresh_operation_token).
+ *
+ * Redaction runs *before* the handler, so a rejected request logs a still-spendable credential —
+ * which is why a new secret-bearing field belongs here rather than left to the default (harper#1527
+ * was this same miss for set_env_value).
+ */
+export const UNLOGGABLE_OPERATION_FIELDS = [
+	'hdb_user',
+	'hdbAuthHeader',
+	'password',
+	'payload',
+	'credentials',
+	'registryAuth',
+	'value',
+	'values',
+	'envelope',
+	'token',
+	'refresh_token',
+];
+
+/** Callers gate this on log level: it allocates, and the operations log is often off. */
+export function redactForOperationLog(body: Record<string, any>): Record<string, any> {
+	const clean = { ...body };
+	for (const field of UNLOGGABLE_OPERATION_FIELDS) delete clean[field];
+	return clean;
+}
+
 export async function processLocalTransaction(req: OperationRequest, operationFunction: Function) {
 	try {
 		if (
@@ -87,31 +126,7 @@ export async function processLocalTransaction(req: OperationRequest, operationFu
 				harperLogger.logLevel === terms.LOG_LEVELS.DEBUG ||
 				harperLogger.logLevel === terms.LOG_LEVELS.TRACE)
 		) {
-			// Need to remove auth variables and secret-bearing fields, but we don't want to create
-			// an object unless the logging is actually going to happen. credentials carries a
-			// transient token on deploy_component (registryAuth is its pre-rename name — still
-			// stripped, since this runs ahead of the validation that now rejects it, and a stale
-			// caller's token must not reach the log); value/values carry .env secrets from
-			// set_env_value; value/envelope carry secrets from set_secret — none may reach the
-			// operations log. `token` is stripped defensively: no operation declares one at the top
-			// level today, but validation allows unknown keys, so a caller that sends one anyway (a
-			// mistyped `harper deploy setup token=…`) would otherwise log a live credential.
-			/* eslint-disable no-unused-vars, @typescript-eslint/no-unused-vars */
-			const {
-				hdb_user,
-				hdbAuthHeader,
-				password,
-				payload,
-				credentials,
-				registryAuth,
-				value,
-				values,
-				envelope,
-				token,
-				...cleanBody
-			} = req.body;
-			/* eslint-enable no-unused-vars, @typescript-eslint/no-unused-vars */
-			operationLog.info(cleanBody);
+			operationLog.info(redactForOperationLog(req.body));
 		}
 	} catch (e) {
 		operationLog.error(e);
@@ -172,6 +187,10 @@ export type OperationDefinition = {
 	requiresSuperUser?: boolean;
 };
 
+// Operation names this API installed a permission entry for, so a later registration that drops
+// `requiresSuperUser` can retract exactly that entry and nothing else.
+const declaredPermissionNames = new Set<string>();
+
 /**
  * Register an operation function with the server.
  * @param operationDefinition
@@ -181,7 +200,14 @@ server.registerOperation = (operationDefinition: OperationDefinition) => {
 	if (isDeployValidating()) return;
 	const { name, execute, requiresSuperUser } = operationDefinition;
 	let handler = execute;
-	if (requiresSuperUser !== undefined) {
+	if (requiresSuperUser === undefined) {
+		// A re-registration that drops the flag must also drop the entry the earlier one installed, or
+		// declaration and enforcement disagree: main retracts the grantable mark while this worker keeps
+		// honouring an already-persisted role grant. Scoped to names declared through this API, so one it
+		// never declared is untouched — a component that declared a built-in's name already overwrote
+		// that entry by declaring it, and this only follows.
+		if (declaredPermissionNames.delete(name)) opAuth.unregisterOperationPermission(name);
+	} else {
 		// verifyPerms keys requiredPermissions by the handler's function `.name`, but registered ops
 		// are typically anonymous arrows (all named "execute") which collide and can't be keyed. Wrap
 		// in a FRESH function named after the op so the lookup resolves the right entry. Wrap rather
@@ -191,12 +217,14 @@ server.registerOperation = (operationDefinition: OperationDefinition) => {
 		handler = (...args: any[]) => (execute as any)(...args);
 		Object.defineProperty(handler, 'name', { value: name, configurable: true });
 		opAuth.registerOperationPermission(name, { requiresSu: requiresSuperUser });
+		declaredPermissionNames.add(name);
 	}
 	OPERATION_FUNCTION_MAP.set(name as any, new OperationFunctionObject(handler));
 	// Components load per-worker, so a registration made there is invisible to the main-thread
 	// ops-API dispatcher (each thread has its own OPERATION_FUNCTION_MAP instance). Announce it
-	// so the main thread can forward calls to this worker (#1736).
-	if (!isMainThread) announceRegisteredOperation(name);
+	// so the main thread can forward calls here (#1736), and can mirror the role-allowlist mark that
+	// registerOperationPermission above made only in this thread's scope.
+	if (!isMainThread) announceRegisteredOperation(name, requiresSuperUser !== undefined);
 };
 
 // Register the durable MCP quota policy as a function (see components/mcp/quota.ts). Worker-local,
@@ -233,10 +261,30 @@ export function chooseOperation(json: OperationRequestBody, bypassAuth = false)
 		if (json.operation === 'sql' || (json.search_operation && json.search_operation.operation === 'sql')) {
 			const sql = require('../../sqlTranslator/index');
 			const sqlStatement = json.operation === 'sql' ? json.sql : json.search_operation.sql;
+			// Before this dispatch's own parse is assigned, so a body-supplied object cannot survive it.
+			stripSuppliedParsedSqlObject(json);
 			const parsedSqlObject = sql.convertSQLToAST(sqlStatement);
 			json.parsed_sql_object = parsedSqlObject;
 			if (!bypassAuth) {
-				const astPermCheck = sql.checkASTPermissions(json, parsedSqlObject);
+				// The SQL path never reaches verifyPerms, so the role `operations` allowlist must be
+				// enforced here — otherwise an allowlisted role reaches unlisted operations via `sql`.
+				// json.operation is already the API name ('sql', or the outer job op like 'export_local').
+				const allowlistDenial = opAuth.verifyOperationsAllowlist(json, json.operation);
+				if (allowlistDenial) {
+					operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
+					operationLog.warn(`User '${json.hdb_user?.username}' is not permitted to ${json.operation}`);
+					throw handleHDBError(
+						new Error(),
+						allowlistDenial,
+						hdbErrors.HTTP_STATUS_CODES.FORBIDDEN,
+						undefined,
+						undefined,
+						true
+					);
+				}
+				// `json.operation` explicitly — the operation this dispatch already resolved, not a
+				// field read back off the request body.
+				const astPermCheck = sql.checkASTPermissions(json, parsedSqlObject, json.operation);
 				if (astPermCheck) {
 					operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
 					operationLog.warn(`User '${json.hdb_user?.username}' is not permitted to ${json.operation}`);
@@ -255,7 +303,10 @@ export function chooseOperation(json: OperationRequestBody, bypassAuth = false)
 			!bypassAuth &&
 			json.operation !== terms.OPERATIONS_ENUM.CREATE_AUTHENTICATION_TOKENS &&
 			json.operation !== terms.OPERATIONS_ENUM.LOGIN &&
-			json.operation !== terms.OPERATIONS_ENUM.LOGOUT
+			json.operation !== terms.OPERATIONS_ENUM.LOGOUT &&
+			// Same rationale: the OIDC exchange authenticates its own caller (#2171), so there is no
+			// hdb_user for verifyPerms to check against.
+			json.operation !== terms.OPERATIONS_ENUM.EXCHANGE_OIDC_TOKEN
 		) {
 			const functionToCheck = job_operation_function === undefined ? operation_function : job_operation_function;
 			const operation_json = json.search_operation ? json.search_operation : json;
@@ -263,7 +314,12 @@ export function chooseOperation(json: OperationRequestBody, bypassAuth = false)
 				operation_json.hdb_user = json.hdb_user;
 			}
 
-			const verifyPermsResult = opAuth.verifyPerms(operation_json, functionToCheck);
+			// Pass the top-level operation for the token-scope check: for an export job, operation_json
+			// is the nested search_operation, so json.operation (export_local/export_to_s3) is the op the
+			// scope must gate — not the inner search.
+			const verifyPermsResult = opAuth.verifyPerms(operation_json, functionToCheck, {
+				apiOperation: json.operation,
+			});
 
 			if (verifyPermsResult) {
 				operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
@@ -357,6 +413,9 @@ async function catchup(req: CatchupOperationRequest) {
 				case terms.OPERATIONS_ENUM.UPSERT:
 					await insert.upsert(transaction);
 					break;
+				case terms.OPERATIONS_ENUM.PUT:
+					await insert.put(transaction);
+					break;
 				case terms.OPERATIONS_ENUM.DELETE:
 					await delete_.deleteRecord(transaction);
 					break;
@@ -411,6 +470,7 @@ function initializeOperationFunctionMap(): Map<OperationFunctionName, OperationF
 	opFuncMap.set(terms.OPERATIONS_ENUM.INSERT, new OperationFunctionObject(insert.insert));
 	opFuncMap.set(terms.OPERATIONS_ENUM.UPDATE, new OperationFunctionObject(insert.update));
 	opFuncMap.set(terms.OPERATIONS_ENUM.UPSERT, new OperationFunctionObject(insert.upsert));
+	opFuncMap.set(terms.OPERATIONS_ENUM.PUT, new OperationFunctionObject(insert.put));
 	opFuncMap.set(terms.OPERATIONS_ENUM.SEARCH_BY_CONDITIONS, new OperationFunctionObject(search.searchByConditions));
 	opFuncMap.set(terms.OPERATIONS_ENUM.SEARCH_BY_HASH, new OperationFunctionObject(search.searchByHash));
 	opFuncMap.set(terms.OPERATIONS_ENUM.SEARCH_BY_ID, new OperationFunctionObject(search.searchByHash));
@@ -581,6 +641,19 @@ function initializeOperationFunctionMap(): Map<OperationFunctionName, OperationF
 		terms.OPERATIONS_ENUM.GET_SECRETS_PUBLIC_KEY,
 		new OperationFunctionObject(secretOperations.getSecretsPublicKey)
 	);
+	opFuncMap.set(terms.OPERATIONS_ENUM.ADD_OIDC_TRUST, new OperationFunctionObject(trustPolicyOperations.addOidcTrust));
+	opFuncMap.set(
+		terms.OPERATIONS_ENUM.LIST_OIDC_TRUST,
+		new OperationFunctionObject(trustPolicyOperations.listOidcTrust)
+	);
+	opFuncMap.set(
+		terms.OPERATIONS_ENUM.DROP_OIDC_TRUST,
+		new OperationFunctionObject(trustPolicyOperations.dropOidcTrust)
+	);
+	opFuncMap.set(
+		terms.OPERATIONS_ENUM.EXCHANGE_OIDC_TOKEN,
+		new OperationFunctionObject(tokenExchange.exchangeOidcToken)
+	);
 	opFuncMap.set(
 		terms.OPERATIONS_ENUM.READ_TRANSACTION_LOG,
 		new OperationFunctionObject(transactionLog.readTransactionLog)

package/server/serverHelpers/sharedMessageEncoding.ts

@@ -0,0 +1,307 @@
+import { serializeMessage, getMessageSerializer } from './contentTypes.ts';
+import { logger } from '../../utility/logging/logger.ts';
+
+/**
+ * The encoding work that every subscriber of a topic would otherwise redo for the same message.
+ * `payload` is the serialized message body; `frames` holds fully encoded protocol frames that are
+ * byte-identical across subscribers (MQTT QoS 0 PUBLISH packets), keyed by whatever the frame
+ * still varies on. `next` chains the encodings for any further content types the same message was
+ * delivered in — a chain rather than a map because a topic's subscribers realistically negotiate
+ * one or two content types, and this keeps the single-content-type case to one allocation.
+ *
+ * `hits` counts the subscribers after the first, so a caller can skip caching anything derived
+ * from the payload until a fan-out is known to exist. `failed` is a distinct state from an
+ * undefined `payload`, which a serializer can legitimately return (JSON of `undefined`).
+ * `bytes` is everything this entry holds — payload plus frames — and `epoch` records which
+ * generation those bytes are charged to, so work that lands after a rotation (a serialization that
+ * resolves late) is not charged to a budget it does not belong to, and a promotion re-charges the
+ * entry exactly once. That is what makes the budget an actual accounting rather than an estimate.
+ */
+export interface SharedMessageEncoding {
+	serializer: Function;
+	version: number | undefined;
+	payload: Buffer | string | Promise<Buffer | string> | undefined;
+	failed: boolean;
+	hits: number;
+	bytes: number;
+	epoch: number;
+	frames: Map<number, Map<string, Buffer>> | undefined;
+	next: SharedMessageEncoding | undefined;
+}
+
+// A message that carries its own content type is passed through verbatim and never negotiated, so
+// every subscriber shares one entry no matter what it negotiated. This sentinel stands in for the
+// serializer that was deliberately not consulted.
+const PASS_THROUGH = function passThrough() {};
+
+// THE IDENTITY CONTRACT. A fan-out has a single shared origin: the same message object instance is
+// dispatched to every subscription of a key (resources/transactionBroadcast.ts), so identity is
+// what lets the first subscriber to encode do the work for all of them. This is only sound because
+// every internal producer yields a *fresh object per version* — transactionBroadcast hands one
+// auditRecord to every subscription, auditStore's getValue memoizes the decode in its closure, and
+// primaryStore.getEntry is guarded by a version check — so identity implies equal content, and a
+// miss (a primitive message, or a store cache eviction between subscribers) only costs the
+// redundant encode we have today rather than yielding stale bytes.
+//
+// A custom Resource is not bound by that, so identity alone is not trusted: the event's record
+// version is part of the key (see getSharedMessageEncoding), which makes reusing one envelope
+// across publishes correct as long as the version advances, and refuses to share at all when there
+// is no version to tell one publish from the next.
+//
+// Retention is bounded by rotating generations rather than by the message object's lifetime: for
+// record events the message IS the store's cached record, so hanging encodings off it alone would
+// keep serialized copies and whole PUBLISH buffers resident for as long as the record stays cached,
+// while sharing is only ever needed for the duration of one fan-out. Two generations are kept so a
+// fan-out spanning a rotation still hits; dropping a generation releases all of it at once.
+const ROTATE_INTERVAL_MS = 10_000;
+// Time alone bounds how LONG an entry is retained, not how MUCH: at high throughput on
+// single-subscriber topics the interval's worth of payloads would all be live at once, for no
+// benefit. The byte budget puts a ceiling on that, at the cost of a fan-out that spans an early
+// rotation falling back to re-encoding — slower, never wrong. Note this is the ceiling for ONE
+// generation; the previous generation can hold as much again, so steady-state retention is up to
+// twice this per worker thread.
+export const MAX_RETAINED_BYTES = 4_000_000;
+let currentGeneration = new WeakMap<object, SharedMessageEncoding>();
+let previousGeneration = new WeakMap<object, SharedMessageEncoding>();
+// Rotation runs on a timer, not on a delivery counter: the bound has to hold when traffic stops,
+// which is exactly when a delivery-gated check would never fire again. Insert counts only decide
+// when the timer can stop — a WeakMap can not be asked whether it is empty.
+let rotationTimer: ReturnType<typeof setInterval> | undefined;
+let currentInserts = 0;
+let currentBytes = 0;
+// Identifies the generation an entry's bytes are charged to. Work can land after a rotation — a
+// serialization that resolves late, a frame generated by a subscriber that arrived slowly — and
+// charging that to the current budget would bill a generation the bytes do not belong to, then bill
+// them again when a promotion re-charges the entry.
+const UNRETAINED = -1;
+// starts at 1 so UNRETAINED can never collide with `currentEpoch - 1`, which would make charge()
+// treat a never-retained entry as one still live in the previous generation
+let currentEpoch = 1;
+
+/** Retire the older generation. Exported for the rotation timer and for tests. */
+export function rotateSharedEncodings() {
+	previousGeneration = currentGeneration;
+	currentGeneration = new WeakMap();
+	currentEpoch++;
+	const rotatedInserts = currentInserts;
+	currentInserts = 0;
+	currentBytes = 0;
+	if (rotatedInserts === 0 && rotationTimer !== undefined) {
+		// nothing is retained in either generation, so stop ticking until the next insert
+		clearInterval(rotationTimer);
+		rotationTimer = undefined;
+	}
+}
+
+/** Whether the rotation timer is currently armed. Introspection for tests. */
+export function isRotationScheduled(): boolean {
+	return rotationTimer !== undefined;
+}
+
+/** Bytes charged to the live generation. Introspection so tests can pin the accounting exactly. */
+export function getRetainedBytes(): number {
+	return currentBytes;
+}
+
+function retainedSize(payload: SharedMessageEncoding['payload']): number {
+	// a pending promise is accounted for when it resolves
+	if (typeof payload === 'string') return Buffer.byteLength(payload);
+	return (payload as Buffer)?.byteLength ?? 0;
+}
+
+/** Add to an entry's footprint, and to the budget if the entry is live. */
+function charge(encoding: SharedMessageEncoding, bytes: number) {
+	encoding.bytes += bytes;
+	if (encoding.epoch === currentEpoch) currentBytes += bytes;
+	else if (encoding.epoch === currentEpoch - 1) {
+		// Bytes can land after a rotation — a serialization resolving late, or a frame generated by a
+		// subscriber whose await spanned one. The entry is still live in the previous generation, so
+		// fold its whole footprint into the live budget; charging only the new bytes would leave the
+		// rest counted by no generation at all, and charging nothing would under-report the ceiling.
+		encoding.epoch = currentEpoch;
+		currentBytes += encoding.bytes;
+	}
+}
+
+/** Give back everything a chain holds, for an entry that is being discarded rather than refilled. */
+function release(encoding: SharedMessageEncoding) {
+	for (let node = encoding; node !== undefined; node = node.next) {
+		if (node.epoch === currentEpoch) currentBytes -= node.bytes;
+		node.epoch = UNRETAINED;
+	}
+}
+
+function retain(message: object, encoding: SharedMessageEncoding) {
+	if (currentBytes >= MAX_RETAINED_BYTES) rotateSharedEncodings();
+	currentGeneration.set(message, encoding);
+	currentInserts++;
+	// charges the whole chain: on a promotion this re-charges everything the entry holds, since
+	// rotation zeroed the counter but the bytes are still live
+	for (let node = encoding; node !== undefined; node = node.next) {
+		if (node.epoch !== currentEpoch) {
+			node.epoch = currentEpoch;
+			currentBytes += node.bytes;
+		}
+	}
+	if (rotationTimer === undefined) {
+		rotationTimer = setInterval(rotateSharedEncodings, ROTATE_INTERVAL_MS);
+		rotationTimer.unref?.();
+	}
+}
+
+function fill(encoding: SharedMessageEncoding, message: any, request: any) {
+	// whatever this entry was holding is being replaced, so give the bytes back before re-charging
+	if (encoding.epoch === currentEpoch) currentBytes -= encoding.bytes;
+	encoding.bytes = 0;
+	encoding.frames = undefined;
+	// Pessimistic: an entry is only valid once a payload is actually in hand. Set optimistically,
+	// a synchronous throw here would leave an already-retained entry claiming success with no
+	// payload, and every later subscriber would send an empty PUBLISH instead of erroring.
+	encoding.failed = true;
+	encoding.payload = undefined;
+	const payload = serializeMessage(message, request);
+	encoding.payload = payload;
+	encoding.failed = false;
+	// A pass-through payload IS the message's own data, already reachable from the WeakMap key, so
+	// caching it retains nothing extra and must not be billed against the budget.
+	if (encoding.serializer === PASS_THROUGH) return;
+	if (typeof (payload as any)?.then === 'function')
+		// collapse an async serialization in place so later subscribers, and frame sharing, see the
+		// finished buffer rather than re-entering the async path
+		encoding.payload = (payload as Promise<Buffer | string>).then(
+			(resolved) => {
+				charge(encoding, retainedSize(resolved));
+				return (encoding.payload = resolved);
+			},
+			(error) => {
+				// mark for retry rather than memoize the failure: a shared rejected promise would turn
+				// one transient serialization error into a permanent one for every later subscriber
+				encoding.failed = true;
+				encoding.payload = undefined;
+				throw error;
+			}
+		);
+	else charge(encoding, retainedSize(payload));
+}
+
+function encode(message: any, request: any, serializer: Function, version?: number): SharedMessageEncoding {
+	const encoding: SharedMessageEncoding = {
+		serializer,
+		version,
+		payload: undefined,
+		failed: false,
+		hits: 0,
+		bytes: 0,
+		epoch: UNRETAINED,
+		frames: undefined,
+		next: undefined,
+	};
+	fill(encoding, message, request);
+	return encoding;
+}
+
+function reuse(encoding: SharedMessageEncoding, message: any, request: any): SharedMessageEncoding {
+	encoding.hits++;
+	if (encoding.failed) fill(encoding, message, request);
+	return encoding;
+}
+
+/**
+ * Get the encoding shared by every subscriber that negotiated the same content type. Keyed on the
+ * message object's identity, the serializer function (which is what `serializeMessage` output
+ * varies on), and the event's record `version`.
+ *
+ * The version is part of the key, not a permission to share. Identity alone would be unsafe for a
+ * producer that reuses one mutable envelope across publishes — an app Resource wrapping a table
+ * subscription to enrich events can easily do that, and copies the version straight through with a
+ * spread — so a cached entry whose version does not match is treated as a miss and re-encoded.
+ * That leaves only same-object-and-same-version mutation, which is indistinguishable from "the same
+ * message". An event with no version at all is not shared: nothing then distinguishes one publish
+ * from the next.
+ */
+export function getSharedMessageEncoding(message: any, request?: any, version?: number): SharedMessageEncoding {
+	// Negotiation must not run for a pass-through message: an Accept header naming only unsupported
+	// types throws 406, which would kill a delivery that used to succeed by returning message.data.
+	const serializer =
+		message?.contentType != null && message.data != null ? PASS_THROUGH : getMessageSerializer(request);
+	// primitives can not key a WeakMap, and are cheap to encode anyway; these stay per-subscriber
+	if (message === null || typeof message !== 'object' || typeof version !== 'number')
+		return encode(message, request, serializer);
+	let encoding = currentGeneration.get(message);
+	if (encoding === undefined) {
+		encoding = previousGeneration.get(message);
+		// promote a surviving entry so it lives through the next rotation
+		if (encoding !== undefined && encoding.version === version) retain(message, encoding);
+	}
+	if (encoding !== undefined && encoding.version !== version) {
+		// the same object carrying a new version: every content type on the chain is stale, so give
+		// back what the whole chain held and start over rather than serving the earlier message
+		release(encoding);
+		encoding = undefined;
+	}
+	if (encoding === undefined) {
+		retain(message, (encoding = encode(message, request, serializer, version)));
+		return encoding;
+	}
+	let last: SharedMessageEncoding;
+	do {
+		if (encoding.serializer === serializer) return reuse(encoding, message, request);
+		last = encoding;
+		encoding = encoding.next;
+	} while (encoding !== undefined);
+	// a second content type on an already-retained message is retained with it, so it is charged too
+	const chained = encode(message, request, serializer, version);
+	chained.epoch = last.epoch;
+	if (chained.epoch === currentEpoch) currentBytes += chained.bytes;
+	return (last.next = chained);
+}
+
+/**
+ * Resolve a still-pending shared serialization, retrying once through a fresh lookup if it failed.
+ * Every subscriber currently in the fan-out awaits the same promise, so without this one transient
+ * failure would disconnect all of them, where before the encoding was shared each subscriber
+ * serialized — and so retried — on its own.
+ */
+export async function resolveSharedPayload(
+	encoding: SharedMessageEncoding,
+	message: any,
+	request: any,
+	version?: number
+): Promise<Buffer | string> {
+	try {
+		return await (encoding.payload as Promise<Buffer | string>);
+	} catch (error) {
+		// otherwise a failure that the retry recovers from leaves no trace at all
+		logger.debug?.('Shared message serialization failed, retrying for this subscriber', error);
+		// The entry is marked for retry, or a peer in this same wave has already refilled it — either
+		// way, ask again. The first subscriber here re-encodes and the rest share that attempt; if it
+		// fails too, that rejection propagates and the caller handles it as it did before sharing.
+		return await getSharedMessageEncoding(message, request, version).payload;
+	}
+}
+
+/**
+ * Look up a fully encoded frame shared across subscribers, or undefined if it has not been
+ * generated yet. Split from `setSharedFrame` so a cache hit — the whole point on a fan-out —
+ * allocates nothing, not even a generator closure.
+ */
+export function getSharedFrame(encoding: SharedMessageEncoding, version: number, topic: string): Buffer | undefined {
+	return encoding.frames?.get(version)?.get(topic);
+}
+
+/**
+ * Store a generated frame for reuse by the remaining subscribers, and return it. Call only when
+ * `encoding.hits > 0`: a frame stored for a fan-out of one is never read, and would keep a whole
+ * PUBLISH buffer reachable from the message object for the rest of its retention window.
+ */
+export function setSharedFrame(encoding: SharedMessageEncoding, version: number, topic: string, frame: Buffer): Buffer {
+	let frames = encoding.frames;
+	if (frames === undefined) encoding.frames = frames = new Map();
+	let byTopic = frames.get(version);
+	if (byTopic === undefined) frames.set(version, (byTopic = new Map()));
+	// concurrent subscribers can each generate before any of them stores; only the retained buffer
+	// is charged, or the budget would bill every duplicate that is immediately garbage
+	if (!byTopic.has(topic)) charge(encoding, frame.byteLength);
+	byTopic.set(topic, frame);
+	return frame;
+}

package/server/serverHelpers/uwsServer.ts

@@ -225,8 +225,23 @@ export async function createUwsServer(options: UwsServerOptions): Promise<{ app:
 	app.any('/*', withBody);
 
 	await new Promise<void>((resolve, reject) => {
-		const onListen = (listenSocket: unknown) =>
-			listenSocket ? resolve() : reject(new Error(`uWS failed to bind ${host ?? ''}:${port ?? socketPath}`));
+		let settled = false;
+		// Backstop against the native listen callback never firing at all — without it, a stuck
+		// bind is indistinguishable from a slow one, and nothing here ever rejects.
+		const bindTimeout = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			reject(
+				new Error(`uWS timed out waiting to bind ${host ?? ''}:${port ?? socketPath} (listen callback never fired)`)
+			);
+		}, 30_000);
+		const onListen = (listenSocket: unknown) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(bindTimeout);
+			if (listenSocket) resolve();
+			else reject(new Error(`uWS failed to bind ${host ?? ''}:${port ?? socketPath}`));
+		};
 		// uWS shares the port across workers (SO_REUSEPORT) by default, matching the Node reusePort path.
 		if (port != null) {
 			if (host) app.listen(host, port, onListen);

package/server/static.ts

@@ -5,6 +5,7 @@ import { resolveBaseURLPath } from '../components/resolveBaseURLPath.ts';
 import { convertToMS } from '../utility/common_utils.ts';
 import { isMatch } from 'micromatch';
 import send from 'send';
+import { settleDeferredCredentialRejection } from '../security/deferredAuthentication.ts';
 
 /**
  * The static plugin handles serving static files from the respective application directory.
@@ -337,40 +338,30 @@ export function handleApplication(scope: Scope) {
 					// Retrieve index entry
 					staticFile = indexEntries.get(req.pathname);
 
-					// The router strips both '/assets' and '/assets/' down to '/', so the mount root
-					// must be disambiguated via the unstripped pathname (exposed by stripPrefix):
-					// redirect the no-slash form so relative links on the index page resolve under
-					// the mount (#1583). Query string is preserved across both redirects; compute it
-					// lazily inside each branch so the common (non-redirect) index serve stays allocation-free.
-					// Gated on the EXTERNAL base path, not the plugin-local one: a root-level static
-					// plugin (baseURLPath === '/') still needs this redirect when the application
-					// itself carries a host/urlPath mount, since the client-visible mount root is then
-					// externalBaseURLPath, not '/' (review finding).
-					if (staticFile && req.pathname === '/' && externalBaseURLPath !== '/') {
-						const originalPathname: string | undefined = (req as any).originalPathname;
-						if (originalPathname && !originalPathname.endsWith('/')) {
-							const queryIndex = (req.url as string).indexOf('?');
-							const query = queryIndex === -1 ? '' : (req.url as string).slice(queryIndex);
-							return {
-								status: 301,
-								headers: {
-									Location: externalBaseURLPath + query,
-								},
-							};
-						}
-					}
+					// Prefix stripping makes `originalPathname` necessary to distinguish mounted roots (#1583).
+					const originalPathname: string | undefined = (req as any).originalPathname;
+					const redirectsMountRoot = !!(
+						staticFile &&
+						req.pathname === '/' &&
+						externalBaseURLPath !== '/' &&
+						originalPathname &&
+						!originalPathname.endsWith('/')
+					);
 
-					// If `null`, redirect to trailing slash. req.pathname arrives with the mount
-					// prefix stripped, so rebuild the external path for the Location header (#1583)
-					if (staticFile === null) {
-						const externalPath =
-							externalBaseURLPath === '/' ? req.pathname : externalBaseURLPath.slice(0, -1) + req.pathname;
+					if (redirectsMountRoot || staticFile === null) {
+						const settledCredentialRejection = settleDeferredCredentialRejection(req);
+						if (settledCredentialRejection) return settledCredentialRejection;
 						const queryIndex = (req.url as string).indexOf('?');
 						const query = queryIndex === -1 ? '' : (req.url as string).slice(queryIndex);
+						const location = redirectsMountRoot
+							? externalBaseURLPath + query
+							: (externalBaseURLPath === '/' ? req.pathname : externalBaseURLPath.slice(0, -1) + req.pathname) +
+								'/' +
+								query;
 						return {
 							status: 301,
 							headers: {
-								Location: externalPath + '/' + query,
+								Location: location,
 							},
 						};
 					}
@@ -393,6 +384,8 @@ export function handleApplication(scope: Scope) {
 
 			// If an entry matched, serve it
 			if (staticFile) {
+				const settledCredentialRejection = settleDeferredCredentialRejection(req);
+				if (settledCredentialRejection) return settledCredentialRejection;
 				// The benefit to using `send` is that it handles a lot of edge cases and headers for us.
 				return {
 					handlesHeaders: true,
@@ -405,7 +398,8 @@ export function handleApplication(scope: Scope) {
 				return next(req);
 			}
 
-			// Otherwise, handle not found
+			const settledCredentialRejection = settleDeferredCredentialRejection(req);
+			if (settledCredentialRejection) return settledCredentialRejection;
 
 			const notFound = scope.options.get(['notFound']);