From 245a9fdf521b8be02716c3f744f646ee49f15f3e Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 23 Sep 2026 14:38:22 +0200 Subject: [PATCH] Isolate the QUIC native pump from a faulting connection, fix release()'s UAF ordering, and make 64-bit koffi decodes honest Soul's fix batch, findings 1, 2 and 7: - The pump's dispatch had no fault boundary: a malformed frame, a stream-kind mismatch, or a throwing caller callback (certificate validator, waiter) threw out of `dispatch` and killed the pump, taking the whole process with it. `dispatch` now catches per-connection, shuts that connection down at the native level, removes its listener, and hands the error to an optional `onFault` callback registered alongside the listener. Every other connection, and the pump itself, keep running. - `release()` called `runtimeClose` before awaiting the pump's exit, so a queued-but-not-yet-started `nextEvent.async` call could begin after close and run against freed memory. It now marks closed, awaits the pump loop (it wakes within its 250 ms timeout), and only then closes. It also refuses a release with no outstanding reference instead of silently flooring at zero. - koffi decodes a 64-bit `uint64_t`/`void *` as a plain `number` when it fits a safe integer, not `bigint` (probed on the pinned 3.3.0 build against the real bridge). Every declared type here promises `bigint`; `toBigInt64` is now the single boundary conversion, applied to every 64-bit decode, so the mismatch that made `event.code === BigInt(CULTMESH_QUIC_SEND_CANCELED)` never true is fixed at its source instead of patched at that one comparison. Subtraction: deleted the unused `lastStatus` export (wired but never called), and collapsed the stacked eslint-disable-next-line pair over one line into one. Co-Authored-By: Claude Sonnet 5 --- .../cultmesh-ts/src/realtime-quic-native.ts | 122 +++++++++++++++--- 1 file changed, 101 insertions(+), 21 deletions(-) diff --git a/packages/cultmesh-ts/src/realtime-quic-native.ts b/packages/cultmesh-ts/src/realtime-quic-native.ts index 5e4f6bff..e9f9a99e 100644 --- a/packages/cultmesh-ts/src/realtime-quic-native.ts +++ b/packages/cultmesh-ts/src/realtime-quic-native.ts @@ -24,9 +24,13 @@ // position (a bare `null` is read by the bridge as a null out parameter and // refused with -1) and its return value is the plain scalar `int32_t`, not an // object. Every out parameter here is therefore `koffi.alloc(type, 1)`, -// decoded with `koffi.decode(buffer, type)` after the call. A `void *` value -// — the runtime handle, and every listener/connection/stream id, since ids -// share the 64-bit width — decodes as a JavaScript `bigint`. +// decoded with `koffi.decode(buffer, type)` after the call. A decoded 64-bit +// value (`void *`, `uint64_t`) comes back from koffi as a plain JavaScript +// `number` when it fits the safe-integer range, not a `bigint` (probed +// against the pinned 3.3.0 build: a decoded `uint64_t` field reads +// `typeof === "number"`). Every such decode is coerced through `toBigInt64` +// below, once, at this boundary, so every exported type in this module keeps +// its honest `bigint` declaration. import { existsSync } from "node:fs"; import { join } from "node:path"; @@ -63,6 +67,16 @@ export const CULTMESH_QUIC_RESULT_BAD_CALL = -1; export const CULTMESH_QUIC_RESULT_BAD_ARGUMENT = -2; type NativeEventListener = (event: CultMeshQuicNativeEvent) => void; +/** Invoked once when a connection is faulted: a throwing listener, a malformed + * frame, or any other error raised while dispatching an event for it. */ +type NativeFaultHandler = (error: Error) => void; + +/** koffi decodes a 64-bit value as `number` when it fits a safe integer and as + * `bigint` otherwise (probed on the pinned 3.3.0 build); this is the single + * place that coerces either into the `bigint` every exported type promises. */ +function toBigInt64(value: number | bigint): bigint { + return typeof value === "bigint" ? value : BigInt(value); +} /** The opaque native runtime handle: a `void *`, decoded by koffi as a `bigint`. */ export type CultMeshQuicNativeHandle = bigint; @@ -117,7 +131,6 @@ interface NativeBindings { payloadCapacity: number, ): Promise<{ status: number; event: NativeEventStruct | null; required: number }>; lastError(runtime: CultMeshQuicNativeHandle, destination: Uint8Array, capacity: number): number; - lastStatus(runtime: CultMeshQuicNativeHandle): number; } let bindingsCache: NativeBindings | undefined; @@ -148,8 +161,7 @@ function loadBindings(): NativeBindings { // Untyped on purpose: koffi's own type declarations are ESM-flavored and // fight a CommonJS `typeof import(...)` reference under Node16 resolution. - // eslint-disable-next-line @typescript-eslint/no-var-requires - // eslint-disable-next-line @typescript-eslint/no-explicit-any + // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-explicit-any const koffi: any = require("koffi"); const { bridge, dependency } = platformFileNames(); const dir = resolveNativeDir(); @@ -222,7 +234,6 @@ function loadBindings(): NativeBindings { const lastErrorFn = bridgeLib.func( "int32_t cultmesh_quic_last_error(void *runtime, uint8_t *destination, int32_t capacity)", ); - const lastStatusFn = bridgeLib.func("int32_t cultmesh_quic_last_status(void *runtime)"); // eslint-disable-next-line @typescript-eslint/no-var-requires const { promisify } = require("node:util") as typeof import("node:util"); @@ -239,7 +250,7 @@ function loadBindings(): NativeBindings { runtimeOpen: (appName) => { const out = koffi.alloc("void *", 1); const status = runtimeOpenFn(appName, out); - return { status, runtime: status === 0 ? (koffi.decode(out, "void *") as CultMeshQuicNativeHandle) : null }; + return { status, runtime: status === 0 ? toBigInt64(koffi.decode(out, "void *")) : null }; }, runtimeClose: (runtime) => runtimeCloseFn(runtime), listenerOpen: (runtime, host, port, pkcs12, pkcs12Length, password) => { @@ -248,7 +259,7 @@ function loadBindings(): NativeBindings { const status = listenerOpenFn(runtime, host, port, pkcs12, pkcs12Length, password, outListenerId, outBoundPort); return { status, - listenerId: status === 0 ? (koffi.decode(outListenerId, "uint64_t") as bigint) : 0n, + listenerId: status === 0 ? toBigInt64(koffi.decode(outListenerId, "uint64_t")) : 0n, boundPort: status === 0 ? (koffi.decode(outBoundPort, "uint16_t") as number) : 0, }; }, @@ -256,7 +267,7 @@ function loadBindings(): NativeBindings { connectionOpen: (runtime, host, port) => { const out = koffi.alloc("uint64_t", 1); const status = connectionOpenFn(runtime, host, port, out); - return { status, connectionId: status === 0 ? (koffi.decode(out, "uint64_t") as bigint) : 0n }; + return { status, connectionId: status === 0 ? toBigInt64(koffi.decode(out, "uint64_t")) : 0n }; }, connectionCertificateComplete: (runtime, connectionId, accept) => connectionCertificateCompleteFn(runtime, connectionId, accept), @@ -264,7 +275,7 @@ function loadBindings(): NativeBindings { streamOpen: (runtime, connectionId, kind) => { const out = koffi.alloc("uint64_t", 1); const status = streamOpenFn(runtime, connectionId, kind, out); - return { status, streamId: status === 0 ? (koffi.decode(out, "uint64_t") as bigint) : 0n }; + return { status, streamId: status === 0 ? toBigInt64(koffi.decode(out, "uint64_t")) : 0n }; }, streamSendFrame: (runtime, streamId, encodedFrame, length, fin) => streamSendFrameFn(runtime, streamId, encodedFrame, length, fin), @@ -273,14 +284,20 @@ function loadBindings(): NativeBindings { const outEvent = koffi.alloc(CultMeshQuicEvent, 1); const outRequired = koffi.alloc("int32_t", 1); const status = await nextEventAsyncRaw(runtime, timeoutMs, outEvent, payload, payloadCapacity, outRequired); + const decoded = status === 1 ? (koffi.decode(outEvent, CultMeshQuicEvent) as NativeEventStruct) : null; return { status, - event: status === 1 ? (koffi.decode(outEvent, CultMeshQuicEvent) as NativeEventStruct) : null, + event: decoded && { + ...decoded, + listener_id: toBigInt64(decoded.listener_id), + connection_id: toBigInt64(decoded.connection_id), + stream_id: toBigInt64(decoded.stream_id), + code: toBigInt64(decoded.code), + }, required: koffi.decode(outRequired, "int32_t") as number, }; }, lastError: (runtime, destination, capacity) => lastErrorFn(runtime, destination, capacity), - lastStatus: (runtime) => lastStatusFn(runtime), }; return bindingsCache; } @@ -305,7 +322,10 @@ export class CultMeshQuicNativeRuntime { private readonly handle: CultMeshQuicNativeHandle; private readonly bindings: NativeBindings; private readonly listenerListeners = new Map(); - private readonly connectionListeners = new Map(); + private readonly connectionListeners = new Map< + bigint, + { listener: NativeEventListener; onFault?: NativeFaultHandler } + >(); private closed = false; private pumpLoop: Promise; @@ -328,14 +348,26 @@ export class CultMeshQuicNativeRuntime { return CultMeshQuicNativeRuntime.shared; } - /** Drops one reference; closes the shared runtime once none remain. */ + /** + * Drops one reference; closes the shared runtime once none remain. Refuses + * a release when no reference is outstanding. The bridge header (section 4) + * forbids any host call beginning once `cultmesh_quic_runtime_close` has + * started, so this marks the runtime closed and waits for the pump to exit + * — it wakes within its 250 ms `nextEvent` timeout — before making that + * call. Closing first and awaiting the pump after (the previous order) let + * a queued, not-yet-started `nextEvent` call begin after close and run + * against freed memory. + */ async release(): Promise { - CultMeshQuicNativeRuntime.refCount = Math.max(0, CultMeshQuicNativeRuntime.refCount - 1); + if (CultMeshQuicNativeRuntime.refCount === 0) { + throw new Error("CultMeshQuicNativeRuntime.release called with no outstanding reference."); + } + CultMeshQuicNativeRuntime.refCount -= 1; if (CultMeshQuicNativeRuntime.refCount > 0) return; this.closed = true; - this.bindings.runtimeClose(this.handle); CultMeshQuicNativeRuntime.shared = undefined; await this.pumpLoop; + this.bindings.runtimeClose(this.handle); } onListenerEvent(listenerId: bigint, listener: NativeEventListener): void { @@ -346,8 +378,16 @@ export class CultMeshQuicNativeRuntime { this.listenerListeners.delete(listenerId); } - onConnectionEvent(connectionId: bigint, listener: NativeEventListener): void { - this.connectionListeners.set(connectionId, listener); + /** + * Registers the event listener for one connection. `onFault`, if given, is + * invoked exactly once if `listener` (or anything it calls synchronously, + * such as a caller-supplied certificate validator) throws while dispatching + * an event for this connection: the pump isolates the fault to this + * connection, shuts it down at the native level, removes the listener, and + * keeps running for every other connection. + */ + onConnectionEvent(connectionId: bigint, listener: NativeEventListener, onFault?: NativeFaultHandler): void { + this.connectionListeners.set(connectionId, { listener, onFault }); } offConnectionEvent(connectionId: bigint): void { @@ -412,6 +452,15 @@ export class CultMeshQuicNativeRuntime { this.bindings.streamShutdown(this.handle, streamId, code); } + /** + * Isolates the faulting connection so one bad event never brings down the + * pump: a malformed frame, a stream-kind/delivery mismatch, or a throwing + * caller-supplied listener (certificate validator, waiter) faults only its + * own connection. The listener is removed, the connection is shut down at + * the native level, and `onFault` (if registered) is told, so pending and + * future work on that connection can reject with the error. Every other + * connection, and the pump itself, keep running. + */ private dispatch(event: NativeEventStruct, payload: Uint8Array): void { const decoded: CultMeshQuicNativeEvent = { type: event.type, @@ -424,10 +473,41 @@ export class CultMeshQuicNativeRuntime { payload, }; if (decoded.type === CULTMESH_QUIC_EVENT_LISTENER_NEW_CONNECTION || decoded.type === CULTMESH_QUIC_EVENT_LISTENER_STOPPED) { - this.listenerListeners.get(decoded.listenerId)?.(decoded); + try { + this.listenerListeners.get(decoded.listenerId)?.(decoded); + } catch (error) { + // No fault contract for listener-level events today; do not let a + // throwing handler crash the pump. + this.reportUnhandledDispatchError(error); + } return; } - this.connectionListeners.get(decoded.connectionId)?.(decoded); + const entry = this.connectionListeners.get(decoded.connectionId); + if (!entry) return; + try { + entry.listener(decoded); + } catch (error) { + this.faultConnection(decoded.connectionId, error instanceof Error ? error : new Error(String(error)), entry.onFault); + } + } + + private faultConnection(connectionId: bigint, error: Error, onFault: NativeFaultHandler | undefined): void { + this.connectionListeners.delete(connectionId); + try { + this.bindings.connectionShutdown(this.handle, connectionId, 0n); + } catch { + // Best-effort: the connection may already be gone. + } + if (onFault) { + onFault(error); + } else { + this.reportUnhandledDispatchError(error); + } + } + + private reportUnhandledDispatchError(error: unknown): void { + // eslint-disable-next-line no-console + console.error("CultMesh QUIC native event dispatch failed with no fault handler registered:", error); } private async pump(): Promise {