dsh-zen-remote 2.0.2 → 2.2.0

package/src/relay-server.ts

@@ -27,6 +27,7 @@
  */
 
 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'
@@ -42,6 +43,13 @@ import {
   filterWorkspaceFrame,
 } from './relay-filter.js'
 import { SESSION_REFERENCE_URI, collectReferenceTexts, decodeSessionReferenceUri } from './session-reference.js'
+import type { ServerPluginEntry, BridgeRegistry } from './plugin-bridge.js'
+import { routeMethodsOf, routeMaxBodyOf } from './plugin-bridge.js'
+import { createPluginTunnel, validatePluginCall, type PluginTunnelRoutes } from './plugin-tunnel.js'
+import type { PluginLoopback } from './plugin-loopback.js'
+import { isLoopbackAuthError } from './plugin-loopback.js'
+import type { NormalizedAdapter, AdapterVerdict } from './plugin-adapter-core.js'
+import { matchAdapterRoute, locateAdapterIds, adapterOwnsRegistryEntry, AdapterMultiValueQueryError } from './plugin-adapter-core.js'
 
 /**
  * Registration prefix on the host webServer. Deliberately WITHOUT the
@@ -134,6 +142,9 @@ const MAX_INVOKES_PER_DEVICE = 32
  */
 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
@@ -224,12 +235,17 @@ export interface RelayGateway {
  * callback too (T42), awaited per handshake so a just-restarted server never
  * serves a stale map; a THROWN compute degrades to the empty map here so a
  * broken fingerprint source can never fail the handshake itself — the
- * client's comparison judges every group `unavailable`, never `different`. */
+ * client's comparison judges every group `unavailable`, never `different`.
+ * `plugins` is the same discipline for the plugin bridge (PB-2): computed
+ * FRESH per handshake (the local registry and the row's consent map are both
+ * live), a THROWN compute degrades to the empty table — the handshake still
+ * succeeds and the client reads every local plugin `not-on-server`. */
 export interface RelayServerInfo {
   serverId: string
   serverName: () => string
   dshVersion: string
   fingerprints?: () => Record<string, string> | Promise<Record<string, string>>
+  plugins?: () => Record<string, ServerPluginEntry>
 }
 
 export interface RelayHandlerOptions {
@@ -268,6 +284,28 @@ export interface RelayHandlerOptions {
    * destroyed (the {@link DRAIN_DEADLINE_MS} bound); defaults to 10000.
    * Tests inject a small value so the deadline path stays cheap to drive. */
   drainDeadlineMs?: number
+  /** The plugin bridge's server half (PB-3). Absent — a wiring that never
+   * mounted it, old tests — and `POST relay/v1/plugin` answers 501
+   * `unsupported`, exactly like the `/api` passthrough without a dispatcher. */
+  pluginBridge?: {
+    /** THIS process's bridge declaration registry (the `zenRemote` service's
+     * backing table) — the source of truth for "which plugin, which version,
+     * which routes". */
+    registry: BridgeRegistry
+    /** The row's per-plugin whole-machine-data consent, read LIVE per request
+     * (a volatile row field — never snapshotted). */
+    getConsent: () => Record<string, boolean>
+    /** The loopback executor performing the actual plugin GET. */
+    loopback: PluginLoopback
+    /** The WebSocket byte tunnel's server half (PB-10). Absent — a wiring
+     * that predates the tunnels — and the three `plugin-tunnel` routes
+     * answer 501 `unsupported` like an unwired bridge. */
+    tunnel?: PluginTunnelRoutes
+    /** The validated adapters (PB-11), as the wiring registered them.
+     * Absent/empty — the pluggable default — and `v1/plugin` serves
+     * cooperative declarations only, exactly as before. */
+    adapters?: readonly NormalizedAdapter[]
+  }
 }
 
 /**
@@ -358,6 +396,18 @@ function responseJson(res: ServerResponse, status: number, body: unknown): void
   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: ServerResponse, status: number, code: string): void {
+  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: IncomingMessage, name: string): string | undefined {
   const raw = req.headers[name]
@@ -611,6 +661,16 @@ function drainUpload(req: IncomingMessage, fromBytes: number, deadlineMs: number
   })
 }
 
+
+/** The 200 error envelope for a failed gateway call, `details` included when
+ *  the host error carried a sanitized one (see errorOf). */
+function errorEnvelopeOf(error: unknown): { ok: false; error: Record<string, unknown> } {
+  const { code, message, details } = errorOf(error)
+  const inner: Record<string, unknown> = message === undefined ? { code } : { code, message }
+  if (details !== undefined) inner.details = details
+  return { ok: false, error: inner }
+}
+
 /**
  * What may travel to the client about a failed gateway call. DSH's own errors
  * always carry a `namespace/name`-shaped string `code` — those pass through
@@ -618,7 +678,7 @@ function drainUpload(req: IncomingMessage, fromBytes: number, deadlineMs: number
  * error whose `code` (`ENOENT`, …) and message (`… '/Users/x/…'`) quote the
  * server's filesystem — reports `internal` and NO message at all (T22a-fix).
  */
-function errorOf(error: unknown): { code: string; message?: string } {
+function errorOf(error: unknown): { code: string; message?: string; details?: Record<string, unknown> } {
   const code =
     error !== null && typeof error === 'object' && typeof (error as { code?: unknown }).code === 'string'
       ? (error as { code: string }).code
@@ -629,7 +689,23 @@ function errorOf(error: unknown): { code: string; message?: string } {
   // error would, so only the code travels.
   if (code.endsWith('/internal')) return { code }
   const text = error instanceof Error ? error.message : String(error)
-  return { code, message: text.slice(0, MAX_MESSAGE_CHARS) }
+  // The structured `details` beside code/message (2026-10-10): the host
+  // rejects an image-bearing prompt with `session/attachment-invalid` whose
+  // `details.reason` (`MODEL_DOES_NOT_SUPPORT_IMAGES`, …) is what the client
+  // UI maps onto a user-facing line — dropped here, the UI prints
+  // `undefined`. Scalars and clipped strings only, bounded key count;
+  // nested objects/arrays stay out so server internals cannot ride this.
+  const raw = (error as { details?: unknown }).details
+  const details: Record<string, unknown> = {}
+  if (isPlainObject(raw)) {
+    for (const [key, value] of Object.entries(raw).slice(0, 16)) {
+      if (typeof value === 'string') details[key] = value.slice(0, MAX_MESSAGE_CHARS)
+      else if (typeof value === 'number' || typeof value === 'boolean' || value === null) details[key] = value
+    }
+  }
+  const out: { code: string; message?: string; details?: Record<string, unknown> } = { code, message: text.slice(0, MAX_MESSAGE_CHARS) }
+  if (Object.keys(details).length > 0) out.details = details
+  return out
 }
 
 /**
@@ -720,6 +796,17 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
   /** Uploads currently in flight per device id, for the upload budget (T51-fix). */
   const uploadsByDevice = new Map<string, number>()
 
+  /**
+   * 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<string, number>()
+
   /**
    * 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
@@ -1005,6 +1092,19 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
       } 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: Record<string, ServerPluginEntry> = {}
+      try {
+        plugins = serverInfo.plugins?.() ?? {}
+      } catch {
+        plugins = {}
+      }
       responseJson(res, 200, {
         ok: true,
         relayProtocol: RELAY_PROTOCOL,
@@ -1014,6 +1114,9 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         // 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
@@ -1117,8 +1220,7 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         )) as unknown
         responseJson(res, 200, isPlainObject(envelope) ? envelope : { ok: false, error: { code: 'internal' } })
       } catch (error) {
-        const { code, message } = errorOf(error)
-        responseJson(res, 200, message === undefined ? { ok: false, error: { code } } : { ok: false, error: { code, message } })
+        responseJson(res, 200, errorEnvelopeOf(error))
       } finally {
         res.off('close', onClientGone)
       }
@@ -1266,8 +1368,7 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         // The gateway's own failures (unknown namespace, absent service) are
         // business answers, not transport errors: they ride a 200 envelope
         // like every other result, with the gateway's string code preserved.
-        const { code, message } = errorOf(error)
-        responseJson(res, 200, message === undefined ? { ok: false, error: { code } } : { ok: false, error: { code, message } })
+        responseJson(res, 200, errorEnvelopeOf(error))
       } finally {
         res.off('close', onClientGone)
         // The invoke is over — answered, refused mid-flight, or its client
@@ -1350,6 +1451,584 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
       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 as Buffer).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: Record<string, boolean> = {}
+          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: string | undefined
+          const adapterHangUp = new AbortController()
+          const onAdapterGone = (): void => {
+            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: unknown
+            let bodyGiven = false
+            let bufferedBody: Buffer | undefined
+            if (!bodylessMethod && adapterRoute.locator.in === 'json-body') {
+              const chunks: Buffer[] = []
+              let size = 0
+              let over = false
+              for await (const chunk of req) {
+                size += (chunk as Buffer).length
+                if (size > adapterRoute.maxBody) {
+                  over = true
+                  break
+                }
+                chunks.push(Buffer.from(chunk as Uint8Array))
+              }
+              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: Buffer | undefined
+            if (bodyGiven) loopbackBody = Buffer.from(JSON.stringify(parsedBody), 'utf8')
+            const serverHook = adapter.hooks.server?.request
+            if (serverHook !== undefined) {
+              let verdict: AdapterVerdict
+              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: import('node:stream').Readable | null = null
+            let adapterBodyGateError: Error | undefined
+            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: Buffer, _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<void>((resolve, reject) => {
+              const upstream = outbound.stream
+              upstream.on('data', (chunk: Buffer) => {
+                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<void>((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 = (): void => {
+                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: Error | undefined
+      const hangUp = new AbortController()
+      const onClientGone = (): void => {
+        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: import('node:http').IncomingMessage | import('node:stream').Readable | null = 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: Buffer, _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<void>((resolve, reject) => {
+          const upstream = outbound.stream
+          upstream.on('data', (chunk: Buffer) => {
+            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<void>((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 = (): void => {
+            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
@@ -1927,8 +2606,7 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
             // DOCUMENTED normal end, swallowed whole.
             closeWith(null)
           } else {
-            const { code, message } = errorOf(error)
-            closeWith(message === undefined ? { type: 'error', error: { code } } : { type: 'error', error: { code, message } })
+            closeWith({ type: 'error', error: errorEnvelopeOf(error).error })
           }
         } finally {
           openStreamKills.delete(killThisStream)