dsh-zen-remote 2.0.3 → 2.2.0

package/lib/relay-server.js

@@ -26,12 +26,17 @@
  * a 404.
  */
 import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { decideHttpRoute, decideInvoke, decideStream, decideUploadQuery, parseEventResultBody } from './relay-access.js';
 import { createWorkspaceFollowState, filterControlFrame, filterJobListFrame, filterModelCatalogResult, filterSessionListResult, filterWorkspaceFrame, } from './relay-filter.js';
 import { SESSION_REFERENCE_URI, collectReferenceTexts, decodeSessionReferenceUri } from './session-reference.js';
+import { routeMethodsOf, routeMaxBodyOf } from './plugin-bridge.js';
+import { validatePluginCall } from './plugin-tunnel.js';
+import { isLoopbackAuthError } from './plugin-loopback.js';
+import { matchAdapterRoute, locateAdapterIds, adapterOwnsRegistryEntry, AdapterMultiValueQueryError } from './plugin-adapter-core.js';
 /**
  * Registration prefix on the host webServer. Deliberately WITHOUT the
  * trailing slash: the webserver matches a prefix route as `pathname === p ||
@@ -112,6 +117,8 @@ const MAX_INVOKES_PER_DEVICE = 32;
  * in-process dispatch writing to the attachments store — behind this route.
  */
 const MAX_UPLOADS_PER_DEVICE = 8;
+/** Concurrent bridged plugin GETs one device may keep in flight (PB-3). */
+const MAX_PLUGIN_REQUESTS_PER_DEVICE = 8;
 /** Most recent forwarded waterfall events remembered per `$zr/events`
  * subscription (T32-fix): the registry is only an ownership record, so this
  * bounds a pathological burst the same way the job cache does — past the
@@ -214,6 +221,17 @@ function responseJson(res, status, body) {
     res.writeHead(status);
     res.end(bytes);
 }
+/**
+ * One plugin-bridge refusal (PB-3): the same JSON envelope as every other
+ * relay refusal, plus the `x-zen-remote-error` marker header — the
+ * sub-client's passthrough layer reads the CODE off a response whose body
+ * it must not have to parse (the success path streams opaque plugin bytes;
+ * keeping the refusal marker a header lets one code path classify both).
+ */
+function relayPluginError(res, status, code) {
+    res.setHeader('x-zen-remote-error', code);
+    responseJson(res, status, { ok: false, error: { code } });
+}
 /** First (and in practice only) value of one request header. */
 function headerValue(req, name) {
     const raw = req.headers[name];
@@ -493,6 +511,16 @@ export function createRelayHandler(options) {
     const invokesByDevice = new Map();
     /** Uploads currently in flight per device id, for the upload budget (T51-fix). */
     const uploadsByDevice = new Map();
+    /**
+     * Bridged plugin GETs currently in flight per device id (PB-3): the same
+     * per-device budget discipline as the invoke and upload counters above.
+     * The cap is 8 — the upload budget's number — because a bridged call is
+     * one panel's data fetch, a burst of a handful per session view; the slot
+     * stays taken for the WHOLE stream (a slow plugin response pins one slot
+     * until its last byte), which is exactly what the budget bounds. Past the
+     * cap the request answers 429 `busy` without touching the counter.
+     */
+    const pluginsByDevice = new Map();
     /**
      * The device NAME this process last saw per device id (T59): every relay
      * request rides the gateway's fresh `x-zen-remote-device-name` marking
@@ -768,6 +796,20 @@ export function createRelayHandler(options) {
             catch {
                 fingerprints = {};
             }
+            // PB-2: the plugin bridge table, computed FRESH per handshake (the
+            // registry and the row's consent map are both live state), with the
+            // SAME guard: a throwing source answers the empty table — the field
+            // still travels, so the client reads "no plugins on this server"
+            // (not-on-server), never a failed handshake. The field is ALWAYS
+            // present in the reply: only its ABSENCE (an older server) can ever
+            // mean server-too-old on the client.
+            let plugins = {};
+            try {
+                plugins = serverInfo.plugins?.() ?? {};
+            }
+            catch {
+                plugins = {};
+            }
             responseJson(res, 200, {
                 ok: true,
                 relayProtocol: RELAY_PROTOCOL,
@@ -777,6 +819,9 @@ export function createRelayHandler(options) {
                 // T42: the server's own interface fingerprints (empty when the wiring
                 // had nothing to compute — the client judges group by group).
                 fingerprints,
+                // PB-2: the plugin bridge table (empty when the wiring had nothing to
+                // register — the client judges plugin by plugin).
+                plugins,
                 // T59: the CALLING device's name, as the gateway's device table holds
                 // it at this moment (the header is written fresh per forward, so a
                 // just-renamed device reads its new name here). Undefined without the
@@ -1112,6 +1157,594 @@ export function createRelayHandler(options) {
             }
             return;
         }
+        if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/plugin`) {
+            // The plugin bridge's forwarding route (PB-3, write requests since
+            // PB-9): the sub-client hands over one call against a BRIDGED plugin's
+            // route (coordinates in the x-zr-* headers), and this server re-issues
+            // it against its OWN plugin over loopback HTTP (docs/adr/0001),
+            // streaming the answer back. The METHOD rides `x-zr-method` (PB-9,
+            // default GET); a body rides as the raw byte stream, forwarded
+            // verbatim.
+            const bridge = options.pluginBridge;
+            if (bridge === undefined) {
+                responseJson(res, 501, { ok: false, error: { code: 'unsupported' } });
+                return;
+            }
+            // The method, before anything else — it decides whether a body is
+            // even legal. GET/HEAD stay bodyless by protocol: the coordinates
+            // ride the headers, so anything at all in the body is a shape
+            // violation. One byte settles it; a real body is drained (bounded,
+            // timed — the upload route's discipline) AFTER the answer, like every
+            // oversized read here.
+            const pluginMethod = headerValue(req, 'x-zr-method') ?? 'GET';
+            const bodylessMethod = pluginMethod === 'GET' || pluginMethod === 'HEAD';
+            let bodyBytes = 0;
+            if (bodylessMethod) {
+                for await (const chunk of req) {
+                    bodyBytes += chunk.length;
+                    break;
+                }
+                if (bodyBytes > 0) {
+                    relayPluginError(res, 400, 'bad-request');
+                    await drainUpload(req, 0, drainDeadlineMs);
+                    return;
+                }
+            }
+            // The coordinates, verbatim off the wire — `x-zr-path` is matched
+            // UNDECODED (the module-wide no-decode discipline), the query parsed
+            // exactly once below.
+            const pluginName = headerValue(req, 'x-zr-plugin');
+            const pluginVersion = headerValue(req, 'x-zr-plugin-version');
+            const pluginDigest = headerValue(req, 'x-zr-plugin-digest');
+            const routePath = headerValue(req, 'x-zr-path');
+            const rawQuery = headerValue(req, 'x-zr-query') ?? '';
+            if (pluginName === undefined || pluginName === '' ||
+                pluginVersion === undefined || pluginVersion === '' ||
+                pluginDigest === undefined || pluginDigest === '' ||
+                routePath === undefined || !routePath.startsWith('/')) {
+                relayPluginError(res, 400, 'bad-request');
+                return;
+            }
+            // ---- PB-11: the adapter routes claim the request BEFORE the
+            // cooperative chain. An adapter route matches by equality or one
+            // segment deeper (not the cooperative exact equality), its ids live
+            // wherever ITS locator says (query, path segment, JSON body), and the
+            // loopback receives the coordinates VERBATIM — the sub-client has
+            // already rewritten every virtual id to its real half, so what gets
+            // validated here is exactly what the local plugin will see. A YIELDED
+            // adapter (the plugin registered its own declaration) falls through to
+            // the cooperative chain below, whose digest check refuses the stale
+            // adapter coordinates with `plugin-mismatch`.
+            const adapterHit = matchAdapterRoute(options.pluginBridge?.adapters, routePath);
+            if (adapterHit !== undefined) {
+                const { adapter, route: adapterRoute } = adapterHit;
+                if (adapterOwnsRegistryEntry(adapter, bridge.registry.get(adapter.plugin))) {
+                    // Coordinates first: the forwarded version/digest must be the
+                    // adapter's registered pair.
+                    if (pluginVersion !== adapter.declaration.version || pluginDigest !== adapter.digest) {
+                        relayPluginError(res, 409, 'plugin-mismatch');
+                        return;
+                    }
+                    // Whole-machine data by definition: the live consent wall, the
+                    // same knob the cooperative server-scope routes read.
+                    let adapterConsent = {};
+                    try {
+                        adapterConsent = bridge.getConsent();
+                    }
+                    catch {
+                        adapterConsent = {};
+                    }
+                    if (adapterConsent[adapter.plugin] !== true) {
+                        relayPluginError(res, 403, 'consent-off');
+                        return;
+                    }
+                    if (!adapterRoute.methods.includes(pluginMethod)) {
+                        relayPluginError(res, 405, 'method-undeclared');
+                        return;
+                    }
+                    // The per-device budget — the SAME table the cooperative forwards
+                    // share, held for the whole response stream.
+                    const adapterDevice = headerValue(req, 'x-zen-remote-device') ?? '';
+                    if ((pluginsByDevice.get(adapterDevice) ?? 0) >= MAX_PLUGIN_REQUESTS_PER_DEVICE) {
+                        relayPluginError(res, 429, 'busy');
+                        return;
+                    }
+                    pluginsByDevice.set(adapterDevice, (pluginsByDevice.get(adapterDevice) ?? 0) + 1);
+                    let adapterGone = false;
+                    let multiValueRefusal = false;
+                    let adapterQueryOverride;
+                    const adapterHangUp = new AbortController();
+                    const onAdapterGone = () => {
+                        adapterGone = true;
+                        if (!res.writableEnded)
+                            adapterHangUp.abort();
+                    };
+                    res.on('close', onAdapterGone);
+                    res.on('error', onAdapterGone);
+                    try {
+                        // Locate ONCE, over the same routing rule the sub-client used:
+                        // the query parses once, the path segments decode off the
+                        // rewritten pathname, and a body-locating route buffers its
+                        // (bounded) JSON body. A duplicated query id throws — the
+                        // cooperative shape violation (PB-12 review).
+                        const adapterSearch = new URLSearchParams(rawQuery);
+                        let parsedBody;
+                        let bodyGiven = false;
+                        let bufferedBody;
+                        if (!bodylessMethod && adapterRoute.locator.in === 'json-body') {
+                            const chunks = [];
+                            let size = 0;
+                            let over = false;
+                            for await (const chunk of req) {
+                                size += chunk.length;
+                                if (size > adapterRoute.maxBody) {
+                                    over = true;
+                                    break;
+                                }
+                                chunks.push(Buffer.from(chunk));
+                            }
+                            if (over) {
+                                relayPluginError(res, 413, 'body-too-large');
+                                void drainUpload(req, 0, drainDeadlineMs);
+                                return;
+                            }
+                            bufferedBody = Buffer.concat(chunks);
+                            if (bufferedBody.length > 0) {
+                                try {
+                                    parsedBody = JSON.parse(bufferedBody.toString('utf8'));
+                                    bodyGiven = true;
+                                }
+                                catch {
+                                    relayPluginError(res, 400, 'bad-request');
+                                    return;
+                                }
+                            }
+                        }
+                        const hits = (() => {
+                            try {
+                                return locateAdapterIds(adapterRoute, routePath, adapterSearch, bodyGiven ? parsedBody : undefined);
+                            }
+                            catch (error) {
+                                if (error instanceof AdapterMultiValueQueryError) {
+                                    multiValueRefusal = true;
+                                    return [];
+                                }
+                                throw error;
+                            }
+                        })();
+                        if (multiValueRefusal) {
+                            relayPluginError(res, 400, 'bad-query');
+                            return;
+                        }
+                        // The sub-client only forwards a classified-remote request, so
+                        // an adapter request that locates NOTHING is malformed here.
+                        if (hits.length === 0) {
+                            relayPluginError(res, 400, 'bad-request');
+                            return;
+                        }
+                        // EVERY located id must be a shared session — one unshared id
+                        // among several refuses the whole request.
+                        for (const hit of hits) {
+                            if (!isAccessible(hit.value)) {
+                                relayPluginError(res, 403, 'not-shared');
+                                return;
+                            }
+                        }
+                        // The server hook: refuse, or replace the parsed body (strip a
+                        // `cwd`, pin a field…). The loopback coordinates stay verbatim.
+                        let loopbackBody;
+                        if (bodyGiven)
+                            loopbackBody = Buffer.from(JSON.stringify(parsedBody), 'utf8');
+                        const serverHook = adapter.hooks.server?.request;
+                        if (serverHook !== undefined) {
+                            let verdict;
+                            try {
+                                verdict = serverHook({ method: pluginMethod, pathname: routePath, route: adapterRoute, query: adapterSearch, body: bodyGiven ? parsedBody : undefined });
+                            }
+                            catch {
+                                relayPluginError(res, 403, 'internal');
+                                return;
+                            }
+                            if (!verdict.allow) {
+                                relayPluginError(res, 403, verdict.reason);
+                                return;
+                            }
+                            if (bodyGiven && verdict.body !== undefined) {
+                                loopbackBody = Buffer.from(JSON.stringify(verdict.body), 'utf8');
+                            }
+                            // A hook may also rewrite the query (the file/upload routes'
+                            // `cwd` strip rides this) — the loopback then sends the
+                            // hook's serialization instead of the verbatim rawQuery.
+                            adapterQueryOverride = verdict.query !== undefined ? verdict.query.toString() : undefined;
+                        }
+                        // The loopback body: a body-locating route sends its (possibly
+                        // hook-rewritten) buffer; any other body rides the cooperative
+                        // counting gate.
+                        const adapterAccept = headerValue(req, 'accept');
+                        const adapterRange = headerValue(req, 'range');
+                        const adapterContentType = headerValue(req, 'content-type');
+                        let adapterBodyStream = null;
+                        let adapterBodyGateError;
+                        if (!bodylessMethod && adapterRoute.locator.in === 'json-body') {
+                            adapterBodyStream = Readable.from(loopbackBody ?? Buffer.alloc(0));
+                        }
+                        else if (!bodylessMethod) {
+                            let pumped = 0;
+                            const gate = new Transform({
+                                transform(chunk, _encoding, callback) {
+                                    pumped += chunk.length;
+                                    if (pumped > adapterRoute.maxBody) {
+                                        callback(new Error('body-too-large'));
+                                        return;
+                                    }
+                                    callback(null, chunk);
+                                },
+                            });
+                            gate.on('error', (error) => {
+                                adapterBodyGateError = error;
+                                adapterHangUp.abort();
+                            });
+                            req.pipe(gate);
+                            adapterBodyStream = gate;
+                        }
+                        // The loopback: the coordinates travel VERBATIM, on purpose —
+                        // the sub-client has already rewritten every located virtual id
+                        // to its real half (query re-serialized, path segment
+                        // re-encoded, JSON body re-serialized), so what the server
+                        // validated (the share check below ran over the SAME locate)
+                        // is byte-for-byte what the local plugin will see. Re-locating
+                        // here would only risk divergence. The ONE exception is an
+                        // explicit hook verdict (`query` above): the better-sidebar
+                        // adapter strips the file/upload routes' `cwd` so the backend
+                        // resolves it from the session.
+                        const outbound = await bridge.loopback.request(pluginMethod, routePath, adapterQueryOverride ?? rawQuery, {
+                            ...(adapterAccept !== undefined ? { accept: adapterAccept } : {}),
+                            ...(adapterRange !== undefined ? { range: adapterRange } : {}),
+                            ...(adapterContentType !== undefined ? { contentType: adapterContentType } : {}),
+                        }, adapterBodyStream, adapterHangUp.signal);
+                        if (adapterBodyGateError !== undefined && !res.headersSent) {
+                            relayPluginError(res, 413, 'body-too-large');
+                            void drainUpload(req, 0, drainDeadlineMs);
+                            return;
+                        }
+                        // The adapter header allowlist (PB-12): the HTML preview's CSP
+                        // sandbox and download dispositions ride through to the phone.
+                        // The loopback collected them into `extraHeaders`.
+                        res.writeHead(outbound.status, {
+                            ...(outbound.contentType !== undefined ? { 'Content-Type': outbound.contentType } : {}),
+                            ...(outbound.contentLength !== undefined ? { 'Content-Length': outbound.contentLength } : {}),
+                            ...(outbound.cacheControl !== undefined ? { 'Cache-Control': outbound.cacheControl } : {}),
+                            ...outbound.extraHeaders,
+                        });
+                        await new Promise((resolve, reject) => {
+                            const upstream = outbound.stream;
+                            upstream.on('data', (chunk) => {
+                                if (adapterGone || res.destroyed || res.writableEnded) {
+                                    upstream.destroy();
+                                    return;
+                                }
+                                if (!res.write(chunk)) {
+                                    upstream.pause();
+                                    res.once('drain', () => upstream.resume());
+                                }
+                            });
+                            upstream.on('end', () => resolve());
+                            upstream.on('error', reject);
+                        });
+                        await new Promise((resolve) => {
+                            if (res.writableEnded || res.destroyed) {
+                                resolve();
+                                return;
+                            }
+                            const watchdog = setTimeout(() => {
+                                try {
+                                    res.destroy();
+                                }
+                                catch {
+                                    // Already gone.
+                                }
+                            }, endDrainTimeoutMs);
+                            if (typeof watchdog.unref === 'function')
+                                watchdog.unref();
+                            const settled = () => {
+                                clearTimeout(watchdog);
+                                resolve();
+                            };
+                            res.once('finish', settled);
+                            res.once('close', settled);
+                            res.end();
+                        });
+                    }
+                    catch (error) {
+                        if (adapterHangUp.signal.aborted) {
+                            try {
+                                res.destroy();
+                            }
+                            catch {
+                                // Already gone.
+                            }
+                        }
+                        else if (isLoopbackAuthError(error)) {
+                            relayPluginError(res, 502, 'loopback-auth');
+                        }
+                        else if (!res.headersSent) {
+                            relayPluginError(res, 502, 'internal');
+                        }
+                        else {
+                            try {
+                                res.destroy();
+                            }
+                            catch {
+                                // Already gone.
+                            }
+                        }
+                    }
+                    finally {
+                        res.off('close', onAdapterGone);
+                        res.off('error', onAdapterGone);
+                        const remaining = (pluginsByDevice.get(adapterDevice) ?? 1) - 1;
+                        if (remaining <= 0)
+                            pluginsByDevice.delete(adapterDevice);
+                        else
+                            pluginsByDevice.set(adapterDevice, remaining);
+                    }
+                    return;
+                }
+                // A yielded adapter falls through: the cooperative chain's digest
+                // check refuses these stale coordinates below.
+            }
+            // ---- the validation chain, in order, first failure answers --------
+            // Steps 1/2/3 and 4-6 (registry, version+digest, exact route, the
+            // parse-once query, the share table, the consent wall) are SHARED with
+            // the tunnel open route — see validatePluginCall. This route's own
+            // extras are the method check (3b) and the body gate (3c) below.
+            const validation = validatePluginCall(bridge, { pluginName, pluginVersion, pluginDigest, routePath, rawQuery }, isAccessible);
+            if (!validation.ok) {
+                relayPluginError(res, validation.status, validation.code);
+                return;
+            }
+            const route = validation.route;
+            // 3b. (PB-9) the METHOD must be one the route declared — the write
+            //     surface is exactly as explicit as the read one was in 2.1: a
+            //     route that declared no `methods` forwards GET only, and an
+            //     undeclared method answers 405 rather than reaching the plugin.
+            if (!routeMethodsOf(route).includes(pluginMethod)) {
+                relayPluginError(res, 405, 'method-undeclared');
+                return;
+            }
+            // 3c. (PB-9) the body gate: a declared Content-Length over the route's
+            //     `maxBody` refuses BEFORE a byte moves (the T51 pre-check
+            //     discipline — the tail is drained after the answer); a chunked
+            //     body carries no length header and is counted while it streams,
+            //     in the pump below.
+            const maxBody = routeMaxBodyOf(route);
+            const declaredLength = Number(headerValue(req, 'content-length'));
+            if (!bodylessMethod && Number.isFinite(declaredLength) && declaredLength > maxBody) {
+                relayPluginError(res, 413, 'body-too-large');
+                await drainUpload(req, 0, drainDeadlineMs);
+                return;
+            }
+            const params = validation.params;
+            const normalizedQuery = validation.normalizedQuery;
+            // 7. the per-device budget — taken only after every wall above, held
+            //    for the whole response stream, released in the finally.
+            const device = headerValue(req, 'x-zen-remote-device') ?? '';
+            if ((pluginsByDevice.get(device) ?? 0) >= MAX_PLUGIN_REQUESTS_PER_DEVICE) {
+                relayPluginError(res, 429, 'busy');
+                return;
+            }
+            pluginsByDevice.set(device, (pluginsByDevice.get(device) ?? 0) + 1);
+            // A sub-client hang-up cancels the loopback request mid-stream, like
+            // the invoke route's wiring; the pump below reads the same flag (and
+            // 'error' rides along, v1/stream's discipline).
+            let clientGone = false;
+            // The counting gate's recorded failure (PB-9), read by the catch —
+            // declared here because the gate itself lives inside the try.
+            let bodyGateError;
+            const hangUp = new AbortController();
+            const onClientGone = () => {
+                clientGone = true;
+                if (!res.writableEnded)
+                    hangUp.abort();
+            };
+            res.on('close', onClientGone);
+            res.on('error', onClientGone);
+            try {
+                const accept = headerValue(req, 'accept');
+                const range = headerValue(req, 'range');
+                const contentType = headerValue(req, 'content-type');
+                // The forwarded body (PB-9): the relay request's body streamed
+                // through a counting gate — node's pipe owns the backpressure, and
+                // the route's `maxBody` is enforced ON THE STREAM (a chunked body
+                // carries no length header, so the declared-length pre-check above
+                // could not see it). Past the cap the gate errors, which tears the
+                // loopback request down mid-write and lands as 413 below (headers
+                // not yet sent — the plugin's response cannot have arrived while we
+                // are still sending its request body).
+                let bodyStream = null;
+                // The gate's own failure must REACH the loopback request (tearing it
+                // down mid-write) and this route's catch — an unhandled Transform
+                // 'error' would crash the process instead. The dedicated abort
+                // signal does both: the loopback dials hang on it, and the catch
+                // reads the recorded error first.
+                const bodyAbort = new AbortController();
+                const bodySignal = AbortSignal.any([hangUp.signal, bodyAbort.signal]);
+                if (!bodylessMethod) {
+                    let pumped = 0;
+                    const gate = new Transform({
+                        transform(chunk, _encoding, callback) {
+                            pumped += chunk.length;
+                            if (pumped > maxBody) {
+                                req.pause();
+                                callback(new Error('body-too-large'));
+                                return;
+                            }
+                            callback(null, chunk);
+                        },
+                    });
+                    gate.on('error', (error) => {
+                        if (bodyGateError === undefined)
+                            bodyGateError = error;
+                        bodyAbort.abort();
+                    });
+                    req.on('error', (error) => {
+                        if (bodyGateError === undefined)
+                            bodyGateError = error;
+                        gate.destroy(error);
+                    });
+                    gate.on('close', () => { if (!res.writableEnded)
+                        req.pause(); });
+                    bodyStream = gate;
+                    req.pipe(gate);
+                }
+                const outbound = await bridge.loopback.request(pluginMethod, routePath, normalizedQuery, {
+                    ...(accept !== undefined ? { accept } : {}),
+                    ...(range !== undefined ? { range } : {}),
+                    ...(contentType !== undefined ? { contentType } : {}),
+                }, bodyStream, bodySignal);
+                // Success: status plus the three whitelisted headers travel, the
+                // body streams — and NO x-zen-remote-error (the marker is refusal-
+                // only, so the client can classify with one header read).
+                res.writeHead(outbound.status, {
+                    ...(outbound.contentType !== undefined ? { 'Content-Type': outbound.contentType } : {}),
+                    ...(outbound.contentLength !== undefined ? { 'Content-Length': outbound.contentLength } : {}),
+                    ...(outbound.cacheControl !== undefined ? { 'Cache-Control': outbound.cacheControl } : {}),
+                });
+                // The pump: chunk-for-chunk with real backpressure — a full socket
+                // pauses the plugin's response instead of buffering it here, so a
+                // slow phone reads a big file without this process ever holding
+                // more than a socket buffer of it. Every chunk re-checks the
+                // response's liveness first (the v1/stream write discipline): a
+                // client that died mid-stream stops the pump on its next chunk
+                // instead of racing one more write into a dead socket, and a
+                // response 'error' (a write racing a destroyed socket surfaces
+                // there) reacts exactly like the hang-up.
+                let clientGoneSeen = false;
+                await new Promise((resolve, reject) => {
+                    const upstream = outbound.stream;
+                    upstream.on('data', (chunk) => {
+                        if (clientGone || res.destroyed || res.writableEnded) {
+                            upstream.destroy();
+                            return;
+                        }
+                        if (!res.write(chunk)) {
+                            upstream.pause();
+                            res.once('drain', () => upstream.resume());
+                        }
+                    });
+                    upstream.on('end', () => resolve());
+                    upstream.on('error', reject);
+                });
+                // The v1/stream finish discipline (T43-A): the tail is in the
+                // kernel's hands now, and a client that stopped reading must not
+                // pin this device slot forever — one watchdog, disarmed by `finish`
+                // (the honest drained signal) or `close`, destroys otherwise.
+                await new Promise((resolve) => {
+                    if (res.writableEnded || res.destroyed) {
+                        resolve();
+                        return;
+                    }
+                    const watchdog = setTimeout(() => {
+                        try {
+                            res.destroy();
+                        }
+                        catch {
+                            // Already gone.
+                        }
+                    }, endDrainTimeoutMs);
+                    if (typeof watchdog.unref === 'function')
+                        watchdog.unref();
+                    const settled = () => {
+                        clearTimeout(watchdog);
+                        resolve();
+                    };
+                    res.once('finish', settled);
+                    res.once('close', settled);
+                    res.end();
+                });
+            }
+            catch (error) {
+                if (!res.headersSent && bodyGateError !== undefined && bodyGateError.message === 'body-too-large') {
+                    // The counting gate tripped mid-forward (PB-9): a chunked body
+                    // past the route's `maxBody`. The plugin's answer cannot have
+                    // started while we were still writing its request body, so the
+                    // honest 413 still fits on the wire; the relay body's tail is
+                    // drained after the answer, bounded and timed like every
+                    // oversized read here.
+                    relayPluginError(res, 413, 'body-too-large');
+                    void drainUpload(req, 0, drainDeadlineMs);
+                }
+                else if (hangUp.signal.aborted) {
+                    // The sub-client is gone mid-stream: its socket is dead, and the
+                    // abort already tore the loopback request down.
+                    try {
+                        res.destroy();
+                    }
+                    catch {
+                        // Already gone.
+                    }
+                }
+                else if (isLoopbackAuthError(error)) {
+                    // The cookie could not be obtained (no token URL on this host, a
+                    // failed exchange) — the relay's own wall, not a business answer.
+                    relayPluginError(res, 502, 'loopback-auth');
+                }
+                else if (!res.headersSent) {
+                    // Any other loopback failure before the answer started (the web
+                    // server moved, the plugin route crashed early) is this server's
+                    // fault: the bare internal code, no message.
+                    relayPluginError(res, 502, 'internal');
+                }
+                else {
+                    // Mid-stream failure with headers already on the wire: the status
+                    // cannot be changed, so the response is cut — the client sees a
+                    // truncated body, the honest shape of a broken stream.
+                    try {
+                        res.destroy();
+                    }
+                    catch {
+                        // Already gone.
+                    }
+                }
+            }
+            finally {
+                res.off('close', onClientGone);
+                res.off('error', onClientGone);
+                const remaining = (pluginsByDevice.get(device) ?? 1) - 1;
+                if (remaining <= 0)
+                    pluginsByDevice.delete(device);
+                else
+                    pluginsByDevice.set(device, remaining);
+            }
+            return;
+        }
+        if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/plugin-tunnel/open`) {
+            const tunnel = options.pluginBridge?.tunnel;
+            if (tunnel === undefined) {
+                responseJson(res, 501, { ok: false, error: { code: 'unsupported' } });
+                return;
+            }
+            await tunnel.open(req, res);
+            return;
+        }
+        if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/plugin-tunnel/send`) {
+            const tunnel = options.pluginBridge?.tunnel;
+            if (tunnel === undefined) {
+                responseJson(res, 501, { ok: false, error: { code: 'unsupported' } });
+                return;
+            }
+            await tunnel.send(req, res);
+            return;
+        }
+        if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/plugin-tunnel/close`) {
+            const tunnel = options.pluginBridge?.tunnel;
+            if (tunnel === undefined) {
+                responseJson(res, 501, { ok: false, error: { code: 'unsupported' } });
+                return;
+            }
+            await tunnel.close(req, res);
+            return;
+        }
         if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/upload`) {
             // The binary upload channel (T51): the sub-client's wrapped
             // `/api/session/uploadFileBinary` forwards a remote session's raw