dsh-zen-remote 2.3.5 → 2.3.7

package/lib/plugin-route-intercept.js

@@ -60,9 +60,17 @@
  * fetch-route-intercept.ts).
  */
 import { routeDeniesRemoteOf, routeLocatorOf, routeMaxBodyOf, routeMethodsOf, routePrefixOf, routeRewriteFieldsOf, routeRewritesIdsOf, routeUpgradesOf } from './plugin-bridge.js';
-import { PassThrough, Readable, Transform } from 'node:stream';
+import { PassThrough, Readable, Transform, Duplex } from 'node:stream';
+import { createHash } from 'node:crypto';
 import { fromVirtual, isVirtual, toVirtual } from './virtual-id.js';
-import { adapterPathMatches, classifyAdapterRequest, rewriteAdapterRequest, adapterOwnsRegistryEntry, MAX_ADAPTER_RESPONSE_BUFFER_BYTES, ADAPTER_RESPONSE_HEADER_ALLOWLIST, AdapterMultiValueQueryError } from './plugin-adapter-core.js';
+import { encodeRfc6455Frame, parseRfc6455Frames } from './plugin-tunnel.js';
+import { adapterPathMatches, classifyAdapterRequest, locateAdapterIds, rewriteAdapterRequest, adapterOwnsRegistryEntry, MAX_ADAPTER_RESPONSE_BUFFER_BYTES, ADAPTER_RESPONSE_HEADER_ALLOWLIST, AdapterMultiValueQueryError } from './plugin-adapter-core.js';
+/** The RFC 6455 handshake GUID — the SHA-1 input of Sec-WebSocket-Accept. */
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+/** The byte triplet that ends every HTTP/1.1 header block — the seam where
+ * an upgrade answer's HEAD stops and its WebSocket frames begin (PB-26b:
+ * both directions strip or buffer up to this mark). */
+const HEADER_END = Buffer.from('\r\n\r\n', 'utf8');
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -113,8 +121,11 @@ function deepRewriteIds(value, known, knownIds, serverId) {
  * array elements stay the value scan's business (the declaration refuses
  * numeric segments outright). Already-virtual values are skipped, so a known
  * id sitting on a declared path is rewritten exactly once, by whichever half
- * reached it first. */
+ * reached it first. Returns the virtual ids this pass MINTED (PB-26a) —
+ * exactly the positions it wrapped, deduped; a position the value scan
+ * already wrapped is not a mint (that row is in the browser's view). */
 function rewriteIdsAtFields(root, fields, serverId) {
+    const minted = new Set();
     for (const field of fields) {
         const segments = field.split('.');
         let node = root;
@@ -125,9 +136,13 @@ function rewriteIdsAtFields(root, fields, serverId) {
             continue;
         const key = segments[segments.length - 1];
         const value = node[key];
-        if (typeof value === 'string' && value !== '' && !isVirtual(value))
-            node[key] = toVirtual(serverId, value);
+        if (typeof value === 'string' && value !== '' && !isVirtual(value)) {
+            const virtualId = toVirtual(serverId, value);
+            node[key] = virtualId;
+            minted.add(virtualId);
+        }
     }
+    return [...minted];
 }
 /** Pump a response body reader into the browser response with real
  * backpressure — the one discipline every verbatim passthrough runs. The
@@ -160,8 +175,11 @@ async function pumpResponse(res, reader) {
  * untouched (the adapter discipline): a rewrite is strictly
  * better-than-nothing, never a reason to mangle or refuse an answer. The
  * caller has already handled the relay's refusal marker — this owns the
- * entire normal answer. */
-async function answerRewriteIds(res, response, known, fields, serverId, knownIds) {
+ * entire normal answer. PB-26a: the virtual ids the position rewrite minted
+ * are reported through `onMinted` — at most once per answer, only when there
+ * are any, and only after the rewritten body is what the browser receives
+ * (a serialization failure passes the original bytes and reports nothing). */
+async function answerRewriteIds(res, response, known, fields, serverId, knownIds, onMinted) {
     const contentType = response.headers.get('content-type');
     const verbatimHeaders = {
         ...(contentType !== null ? { 'content-type': contentType } : {}),
@@ -213,10 +231,11 @@ async function answerRewriteIds(res, response, known, fields, serverId, knownIds
     }
     const text = Buffer.concat(chunks).toString('utf8');
     let outBody;
+    let minted = [];
     try {
         const scanned = deepRewriteIds(JSON.parse(text), known, knownIds, serverId);
         if (fields !== undefined)
-            rewriteIdsAtFields(scanned, fields, serverId);
+            minted = rewriteIdsAtFields(scanned, fields, serverId);
         outBody = Buffer.from(JSON.stringify(scanned), 'utf8');
     }
     catch {
@@ -230,6 +249,15 @@ async function answerRewriteIds(res, response, known, fields, serverId, knownIds
     }
     res.writeHead(response.status, { ...verbatimHeaders, 'content-length': String(outBody.length) });
     res.end(outBody);
+    if (minted.length > 0 && onMinted !== undefined) {
+        try {
+            onMinted(minted);
+        }
+        catch {
+            // Bookkeeping for the sidebar — never a reason to fail an answer
+            // the browser already has.
+        }
+    }
 }
 /** Pure inspection of the RAW webServer instance — nothing is mutated, so a
  * failed check leaves every route exactly as it was. */
@@ -303,6 +331,7 @@ export function installPluginRouteIntercept(options) {
     const adapters = options.adapters ?? [];
     const getCurrentSession = options.getCurrentSession;
     const getKnownRealIds = options.getKnownRealIds;
+    const onMintedVirtualIds = options.onMintedVirtualIds;
     const target = webServer;
     const savedMatch = target.match;
     let installed = true;
@@ -599,7 +628,7 @@ export function installPluginRouteIntercept(options) {
             // known inventory, read live right here (undefined when the wiring
             // passed no getter — the scan stays request-local).
             if (declared.rewriteIds) {
-                await answerRewriteIds(res, response, idMapping, declared.rewriteFields, parts.serverId, getKnownRealIds?.());
+                await answerRewriteIds(res, response, idMapping, declared.rewriteFields, parts.serverId, getKnownRealIds?.(), onMintedVirtualIds);
                 return;
             }
             const contentType = response.headers.get('content-type');
@@ -913,7 +942,7 @@ export function installPluginRouteIntercept(options) {
                 return;
             }
             if (declared.rewriteIds) {
-                await answerRewriteIds(res, response, idMapping, declared.rewriteFields, locatedServerId, getKnownRealIds?.());
+                await answerRewriteIds(res, response, idMapping, declared.rewriteFields, locatedServerId, getKnownRealIds?.(), onMintedVirtualIds);
                 return;
             }
             const contentType = response.headers.get('content-type');
@@ -1283,12 +1312,21 @@ export function installPluginRouteIntercept(options) {
             }
             const text = Buffer.concat(chunks).toString('utf8');
             let rewrittenBody;
+            // PB-26a: every id the hook virtualizes is a row the browser is
+            // about to learn of (sidechat.start's childId) — collected here,
+            // reported only once the hook's answer is what the browser gets.
+            const minted = new Set();
             try {
                 rewrittenBody = responseHook({
                     status: response.status,
                     pathname,
                     body: JSON.parse(text),
-                    virtualize: (id) => toVirtual(serverId ?? '', id),
+                    virtualize: (id) => {
+                        const virtualId = toVirtual(serverId ?? '', id);
+                        if (isVirtual(virtualId))
+                            minted.add(virtualId);
+                        return virtualId;
+                    },
                     isVirtual: (value) => isVirtual(value),
                 });
             }
@@ -1313,6 +1351,15 @@ export function installPluginRouteIntercept(options) {
                 'content-length': String(outBody.length),
             });
             res.end(outBody);
+            if (minted.size > 0 && onMintedVirtualIds !== undefined) {
+                try {
+                    onMintedVirtualIds([...minted]);
+                }
+                catch {
+                    // Sidebar bookkeeping — never a reason to fail an answer the
+                    // browser already has.
+                }
+            }
         }
         catch (error) {
             if (controller?.signal.aborted || res.destroyed || res.headersSent) {
@@ -1388,12 +1435,453 @@ export function installPluginRouteIntercept(options) {
                         path: route.path,
                         sessionParam: route.sessionParam,
                         deny: routeDeniesRemoteOf(route),
+                        locator: routeLocatorOf(route),
+                        rewriteIds: routeRewritesIdsOf(route),
+                        rewriteFields: routeRewriteFieldsOf(route),
+                        view: bridgeRouteAsAdapterRoute(route),
+                        adapter: adapterRouteOf(pathname)?.adapter,
                     };
                 }
             }
         }
         return undefined;
     };
+    /** PB-26b: the json-body upgrade surrogate — the frame-level twin of the
+     * HTTP surrogates. The exchange: the browser gets the 101 IMMEDIATELY (its
+     * `onopen` fires and the first frame — better-sidebar's sidechat watch —
+     * is on the wire), then every incoming text frame is located against the
+     * route's locator and classified. LOCAL ids pipe the exchange into the
+     * plugin's own upgrade handler over an in-memory socket (the handler's
+     * 101 head is stripped — the browser already has one). VIRTUAL ids open a
+     * PB-10 byte tunnel whose upstream is RE-FRAMED masked (each text frame's
+     * ids rewritten real, per-frame — the server's send gate re-checks them
+     * against the share wall) and whose downstream frames are rewritten
+     * virtual (the adapter's response hook, or the cooperative rewriteIds
+     * scan) before the browser sees them. A mixed or foreign-server frame
+     * kills the exchange — docs/adr/0001 holds frame by frame. */
+    const jsonBodyUpgrade = (declared, originalHandler, req, socket, head) => (async () => {
+        const plugin = declared.plugin;
+        const socketGone = () => socket.destroyed || !socket.writable;
+        const destroySocket = () => {
+            try {
+                socket.destroy();
+            }
+            catch {
+                // Already gone.
+            }
+        };
+        // The post-101 refusal channel: the handshake is OUT, so no HTTP
+        // status fits anymore — the refusal is recorded and the socket dies.
+        const refuseAndDie = (reason) => {
+            recordRefusal(plugin, reason);
+            log?.('plugin upgrade refused for %s: %s', plugin, reason);
+            destroySocket();
+        };
+        // The deny wall (the HTTP halves' current-session rule, pre-101 — the
+        // answerUnbridgedSocket answer still fits here): a remote panel never
+        // opens this route at all.
+        if (declared.deny) {
+            const current = getCurrentSession?.();
+            if (current !== undefined && isVirtual(current)) {
+                answerUnbridgedSocket(socket, plugin, 'route-denied');
+                return;
+            }
+        }
+        // The two headers the handshake cannot exist without — we answer it
+        // OURSELVES this time, so a missing one refuses before anything is
+        // written.
+        const wsKey = typeof req.headers['sec-websocket-key'] === 'string' ? req.headers['sec-websocket-key'] : undefined;
+        const wsVersion = typeof req.headers['sec-websocket-version'] === 'string' ? req.headers['sec-websocket-version'] : undefined;
+        if (wsKey === undefined || wsVersion === undefined) {
+            answerUnbridgedSocket(socket, plugin, 'bad-query');
+            return;
+        }
+        // The 101 goes out NOW: the browser's onopen fires and its first frame
+        // is what decides the route below. Extensions are offered to nobody —
+        // not echoed here, not offered upstream (the tunnel opens with the
+        // key and version alone) — so every frame stays plain text and the
+        // rewrites below can never land on compressed bytes.
+        try {
+            socket.write(`HTTP/1.1 101 Switching Protocols\r\n` +
+                `Upgrade: websocket\r\n` +
+                `Connection: Upgrade\r\n` +
+                `Sec-WebSocket-Accept: ${createHash('sha1').update(wsKey + WS_GUID).digest('base64')}\r\n` +
+                `\r\n`);
+        }
+        catch {
+            return;
+        }
+        // ---- the local pipe: an in-memory socket behind the real handler ----
+        let localSocket;
+        const startLocal = () => {
+            if (typeof originalHandler !== 'function') {
+                // No local handler to serve the local verdict through — the
+                // exchange is dead either way.
+                destroySocket();
+                return;
+            }
+            // The handler's writes arrive through the Duplex's writable side;
+            // its reads come from OUR writes. The 101 head the handler produces
+            // is stripped (the browser already has one) — every byte after the
+            // header end is a WebSocket frame and crosses verbatim.
+            const pipe = new Duplex({
+                write(chunk, _encoding, callback) {
+                    forwardFromLocal(chunk);
+                    callback();
+                },
+                read() { },
+            });
+            // net.Socket methods the handler may call that a Duplex lacks.
+            const socketShaped = pipe;
+            socketShaped.setTimeout = () => { };
+            socketShaped.setNoDelay = () => { };
+            let headerSeen = false;
+            let headerBuffer = Buffer.alloc(0);
+            const forwardFromLocal = (chunk) => {
+                if (socketGone())
+                    return;
+                if (headerSeen) {
+                    socket.write(chunk);
+                    return;
+                }
+                headerBuffer = Buffer.concat([headerBuffer, chunk]);
+                const end = headerBuffer.indexOf(HEADER_END);
+                if (end === -1)
+                    return;
+                headerSeen = true;
+                const rest = headerBuffer.subarray(end + HEADER_END.length);
+                headerBuffer = Buffer.alloc(0);
+                if (rest.length > 0)
+                    socket.write(rest);
+            };
+            pipe.on('close', () => destroySocket());
+            socket.on('close', () => {
+                try {
+                    pipe.destroy();
+                }
+                catch {
+                    // Already gone.
+                }
+            });
+            localSocket = pipe;
+            // The handler owns the exchange from here — its async body runs on
+            // its own, exactly as the host would run it.
+            const handler = originalHandler;
+            void Promise.resolve(handler(req, pipe, Buffer.alloc(0))).catch(() => destroySocket());
+        };
+        // ---- the remote pipe: the PB-10 tunnel, frame by frame -------------
+        let tunnelHandle;
+        // The connection-wide real→virtual mapping the rewriteIds deep scan
+        // consults: EVERY validated remote frame's ids merge in (a watch list
+        // that grows mid-connection makes the later answers rewritable too —
+        // the deep scan only knows the ids this exchange has carried).
+        const idMapping = new Map();
+        let upstreamSeq = 0;
+        let upstreamBroken = false;
+        let teardownTunnel = () => { };
+        const killExchange = () => {
+            teardownTunnel();
+            destroySocket();
+        };
+        /** ONE text frame onto the OPEN tunnel: the ids named by `hits`
+         * rewritten real (an empty list — the unsubscribe-all — crosses
+         * verbatim), re-framed MASKED (client style — the server's send gate
+         * parses and re-checks them), sent in the chain's order. A transport
+         * failure tears the whole exchange down (counter, close, socket) —
+         * never a silent broken flag: that would leak `tunnelsCurrent` and
+         * leave the browser hanging on a dead tunnel. */
+        const sendTextUpstream = async (frame, parsedJson, hits) => {
+            if (upstreamBroken || tunnelHandle === undefined)
+                return;
+            const rewrite = hits.length > 0
+                ? rewriteAdapterRequest(declared.view, declared.path, new URLSearchParams(), parsedJson, hits, (virtualId) => fromVirtual(virtualId).id)
+                : undefined;
+            const payload = rewrite?.bodyText !== undefined ? Buffer.from(rewrite.bodyText, 'utf8') : frame.payload;
+            const seq = upstreamSeq;
+            upstreamSeq += 1;
+            try {
+                await relay.pluginTunnelSend(tunnelHandle.tunnel, seq, encodeRfc6455Frame(0x1, payload, true, frame.fin));
+            }
+            catch {
+                killExchange();
+            }
+        };
+        /** The downstream river: the tunnel's byte frames → rewritten text
+         * frames on the browser socket. The plugin's 101 head is stripped
+         * FIRST (the browser already has ours); each text frame is rewritten
+         * (adapter hook, else the cooperative rewriteIds scan) and re-framed
+         * UNMASKED (server style); every other frame crosses verbatim. */
+        const startDownstream = (opened, serverId) => {
+            void (async () => {
+                let downstream = Buffer.alloc(0);
+                let headerSeen = false;
+                try {
+                    for await (const chunk of opened.frames) {
+                        if (socketGone())
+                            break;
+                        downstream = Buffer.concat([downstream, chunk]);
+                        if (!headerSeen) {
+                            const end = downstream.indexOf(HEADER_END);
+                            if (end === -1)
+                                continue;
+                            headerSeen = true;
+                            downstream = downstream.subarray(end + HEADER_END.length);
+                        }
+                        const parsed = parseRfc6455Frames(downstream);
+                        downstream = downstream.subarray(parsed.consumed);
+                        if (parsed.violated)
+                            break;
+                        for (const frame of parsed.frames) {
+                            if (frame.opcode !== 0x1) {
+                                socket.write(frame.raw);
+                                continue;
+                            }
+                            let outPayload = frame.payload;
+                            try {
+                                const parsedJson = JSON.parse(frame.payload.toString('utf8'));
+                                const responseHook = declared.adapter?.hooks.client?.response;
+                                let hooked = false;
+                                if (responseHook !== undefined) {
+                                    outPayload = Buffer.from(JSON.stringify(responseHook({
+                                        status: 200,
+                                        pathname: declared.path,
+                                        body: parsedJson,
+                                        virtualize: (id) => toVirtual(serverId, id),
+                                        isVirtual: (value) => isVirtual(value),
+                                    })), 'utf8');
+                                    hooked = true;
+                                }
+                                else if (declared.rewriteIds) {
+                                    const scanned = deepRewriteIds(parsedJson, idMapping, getKnownRealIds?.(), serverId);
+                                    if (declared.rewriteFields !== undefined)
+                                        rewriteIdsAtFields(scanned, declared.rewriteFields, serverId);
+                                    outPayload = Buffer.from(JSON.stringify(scanned), 'utf8');
+                                    hooked = true;
+                                }
+                                // Neither hook applies: the frame crosses verbatim.
+                                if (!hooked)
+                                    outPayload = frame.payload;
+                            }
+                            catch {
+                                // A frame that will not parse (or a hook that threw)
+                                // crosses untouched — a rewrite is better-than-nothing,
+                                // never a reason to mangle a push.
+                            }
+                            if (socketGone())
+                                break;
+                            // The re-frame carries the ORIGINAL frame's fin bit — a
+                            // fragmented push stays fragmented, a whole frame stays
+                            // whole.
+                            if (!socket.write(encodeRfc6455Frame(0x1, outPayload, false, frame.fin))) {
+                                await new Promise((resolve) => {
+                                    const settled = () => {
+                                        socket.off('drain', settled);
+                                        socket.off('close', settled);
+                                        resolve();
+                                    };
+                                    socket.once('drain', settled);
+                                    socket.once('close', settled);
+                                });
+                                if (socketGone())
+                                    break;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // The tunnel transport died — the browser socket follows below.
+                }
+                if (!socketGone())
+                    destroySocket();
+            })();
+        };
+        /** ONE text frame through the walls. The FIRST one decides the
+         * exchange's path (local pipe or remote tunnel) and the connection
+         * never switches: a frame that would take the OTHER path is a
+         * cross-frame mix and kills the exchange (docs/adr/0001, frame by
+         * frame). The one exception is the id-LESS frame on a tunnel-bound
+         * connection — better-sidebar's `{"op":"watch","threadIds":[]}`
+         * unsubscribe-all carries no id and no local meaning, so it keeps
+         * riding the tunnel verbatim. */
+        const handleTextFrame = async (frame) => {
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(frame.payload.toString('utf8'));
+            }
+            catch {
+                refuseAndDie('bad-query');
+                return;
+            }
+            let verdict;
+            try {
+                verdict = classifyAdapterRequest(declared.view, declared.path, new URLSearchParams(), parsedJson);
+            }
+            catch {
+                refuseAndDie('bad-query');
+                return;
+            }
+            if (verdict.kind === 'mixed') {
+                refuseAndDie('bad-query');
+                return;
+            }
+            const rawHits = locateAdapterIds(declared.view, declared.path, new URLSearchParams(), parsedJson);
+            if (verdict.kind === 'local') {
+                if (tunnelHandle !== undefined) {
+                    // Bound to the remote tunnel: the id-less frame stays on it, a
+                    // REAL local id is a cross-frame mix — never a pivot to the
+                    // local plugin.
+                    if (rawHits.length === 0) {
+                        await sendTextUpstream(frame, parsedJson, []);
+                        return;
+                    }
+                    refuseAndDie('bad-query');
+                    killExchange();
+                    return;
+                }
+                if (localSocket === undefined) {
+                    startLocal();
+                    if (localSocket === undefined)
+                        return;
+                }
+                // The browser's frame enters the handler's READ side (push) — the
+                // Duplex's write side is the handler's own answer channel.
+                localSocket.push(frame.raw);
+                return;
+            }
+            // Remote. The FIRST remote frame opens the tunnel; every hit must
+            // belong to THIS handshake's server. A connection already bound to
+            // the local pipe never pivots to the tunnel.
+            if (localSocket !== undefined) {
+                refuseAndDie('bad-query');
+                try {
+                    localSocket.destroy();
+                }
+                catch {
+                    // Already gone.
+                }
+                return;
+            }
+            const serverId = getServerId();
+            if (serverId === undefined) {
+                refuseAndDie('server-changed');
+                return;
+            }
+            const mapping = new Map();
+            for (const idHit of verdict.hits) {
+                const parts = fromVirtual(idHit.value);
+                if (parts === undefined || parts.id === '' || parts.serverId !== serverId) {
+                    refuseAndDie('server-changed');
+                    return;
+                }
+                mapping.set(parts.id, idHit.value);
+            }
+            // This frame's ids join the connection-wide mapping (see idMapping).
+            for (const [key, value] of mapping)
+                idMapping.set(key, value);
+            if (tunnelHandle === undefined) {
+                const status = getStatus().find((entry) => entry.plugin === plugin);
+                if (status === undefined || !status.bridged) {
+                    refuseAndDie(status?.reason ?? 'not-on-server');
+                    return;
+                }
+                const controller = new AbortController();
+                socket.on('close', () => controller.abort());
+                let opened;
+                try {
+                    log?.('opening tunnel for %s', declared.path);
+                    opened = await relay.pluginTunnelOpen({
+                        plugin,
+                        version: declared.version,
+                        digest: declared.digest,
+                        path: declared.path,
+                        query: '',
+                        wsHeaders: { 'sec-websocket-key': wsKey, 'sec-websocket-version': wsVersion },
+                    }, controller.signal);
+                }
+                catch (error) {
+                    const rawCode = error?.code;
+                    refuseAndDie(typeof rawCode === 'string' && rawCode !== '' ? rawCode : 'offline');
+                    return;
+                }
+                tunnelsCurrent += 1;
+                tunnelsOpened += 1;
+                tunnelHandle = opened;
+                log?.('tunnel open for %s: %s', declared.path, opened.tunnel);
+                teardownTunnel = () => {
+                    if (upstreamBroken)
+                        return;
+                    upstreamBroken = true;
+                    tunnelsCurrent -= 1;
+                    tunnelsClosed += 1;
+                    void relay.pluginTunnelClose(opened.tunnel).catch(() => { });
+                };
+                socket.on('close', teardownTunnel);
+                socket.on('error', teardownTunnel);
+                startDownstream(opened, serverId);
+            }
+            await sendTextUpstream(frame, parsedJson, verdict.hits);
+        };
+        const handleFrame = async (frame) => {
+            // Control frames (close/ping/pong) carry no session ids and cross
+            // VERBATIM on whichever path exists — the close handshake completes
+            // the honest way (the plugin's reply close rides back downstream,
+            // the socket-close handlers tear the tunnel down in turn). With no
+            // path yet, a close just closes.
+            if (frame.opcode !== 0x1 && frame.opcode !== 0x2) {
+                if (localSocket !== undefined) {
+                    localSocket.push(frame.raw);
+                    return;
+                }
+                if (tunnelHandle !== undefined && !upstreamBroken) {
+                    const seq = upstreamSeq;
+                    upstreamSeq += 1;
+                    try {
+                        await relay.pluginTunnelSend(tunnelHandle.tunnel, seq, frame.raw);
+                    }
+                    catch {
+                        // The send died: tear the exchange down COMPLETELY — the
+                        // counter, the close, the browser socket (a bare broken flag
+                        // would leak `tunnelsCurrent` and hang the browser).
+                        killExchange();
+                    }
+                    return;
+                }
+                if (frame.opcode === 0x8)
+                    killExchange();
+                return;
+            }
+            await handleTextFrame(frame);
+        };
+        // ---- frame intake: the early head bytes, then every socket byte ----
+        // Complete frames dispatch through ONE serialized chain (the arrival
+        // order is the wire order the plugin and the browser both assume); a
+        // declared-oversize frame is a broken sender — refused, never awaited.
+        let intake = Buffer.from(head);
+        let chain = Promise.resolve();
+        socket.on('data', (chunk) => {
+            if (socketGone())
+                return;
+            intake = Buffer.concat([intake, chunk]);
+            const parsedFrames = parseRfc6455Frames(intake);
+            intake = intake.subarray(parsedFrames.consumed);
+            if (parsedFrames.violated) {
+                refuseAndDie('bad-query');
+                return;
+            }
+            for (const frame of parsedFrames.frames) {
+                chain = chain
+                    .then(() => handleFrame(frame))
+                    .catch(() => destroySocket());
+            }
+        });
+    })().catch(() => {
+        try {
+            socket.destroy();
+        }
+        catch {
+            // Already gone.
+        }
+    });
     /** The tunnel's surrogate upgrade handler. Every outcome — refusal,
      * teardown, the byte pumping — owns the socket's whole remaining life. */
     const surrogateUpgrade = (declared, originalHandler) => (req, socket, head) => {
@@ -1401,6 +1889,13 @@ export function installPluginRouteIntercept(options) {
         // its own and every failure path owns the socket's teardown.
         void (async () => {
             log?.('upgrade entered for %s', declared.path);
+            // PB-26b: a json-body upgrade's ids ride the POST-HANDSHAKE frames —
+            // there is no session query parameter for the byte-tunnel half below
+            // to read, so the frame-level half owns the whole exchange.
+            if (declared.locator.in !== 'query') {
+                await jsonBodyUpgrade(declared, originalHandler, req, socket, head);
+                return;
+            }
             const socketGone = () => socket.destroyed || !socket.writable;
             const passthrough = () => {
                 if (typeof originalHandler === 'function') {