dsh-zen-remote 2.3.2 → 2.3.4

package/src/plugin-tunnel.ts

@@ -28,45 +28,124 @@ import { connect as tlsConnect } from 'node:tls'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { Socket } from 'node:net'
 import { pluginBridgeError, responseJson } from './http.js'
-import { routeUpgradesOf } from './plugin-bridge.js'
+import { adapterPathMatches, adapterTailShapeViolation, locateAdapterIds, type NormalizedAdapterRoute } from './plugin-adapter-core.js'
+import { routeLocatorOf, routeMaxBodyOf, routeMethodsOf, routePrefixOf, routeUpgradesOf } from './plugin-bridge.js'
 import type { BridgeRegistry, NormalizedBridgeRoute, NormalizedDeclaration } from './plugin-bridge.js'
 import type { PluginLoopback } from './plugin-loopback.js'
 
 /** The shared validation verdict for the two plugin routes (PB-3, reused by
  * the tunnel open in PB-10): the whole chain from the coordinate headers to
  * the consent wall, minus each route's own extras (the method check for
- * `v1/plugin`, the upgrade mark here). First failure wins, in this order. */
+ * `v1/plugin`, the upgrade mark here). First failure wins, in this order.
+ * `bufferedBody` carries a json-body route's request bytes (PB-24: the share
+ * check must read the located id, so the body is consumed by validating) —
+ * the loopback sends THIS buffer, never a re-read of the request. */
 export type PluginCallValidation =
-  | { ok: true; declaration: NormalizedDeclaration; route: NormalizedBridgeRoute; params: URLSearchParams; sessionId: string; normalizedQuery: string }
+  | { ok: true; declaration: NormalizedDeclaration; route: NormalizedBridgeRoute; params: URLSearchParams; sessionId: string; normalizedQuery: string; bufferedBody?: Buffer }
   | { ok: false; status: number; code: string }
 
+/** The json-body locator's body reader (PB-24): the caller owns the request
+ * stream — `v1/plugin` buffers it bounded by the route's `maxBody` (413 past
+ * the cap, mirroring the adapter half's discipline), the tunnel open omits
+ * the reader entirely (an open request is empty-bodied by contract, so a
+ * body-locating upgrade route can never be validated and refuses). */
+export type PluginCallBodyReader = (maxBody: number) => Promise<
+  | { kind: 'body'; buffered: Buffer; parsed?: unknown }
+  | { kind: 'over' }
+  | { kind: 'corrupt' }
+>
+
+/** The cooperative route through the adapter core's matcher (PB-23): the
+ * path rule is ONE rule on both halves — {@link adapterPathMatches} decides,
+ * fed the declaration route converted to its shape (exact by default;
+ * `prefix: true` becomes the adapter's `match: 'prefix'`). A hand-copied
+ * predicate here could drift from the adapter segment's rule; the conversion
+ * cannot. Only `path` and `match` are actually read by the matcher. */
+function asAdapterRoute(route: NormalizedBridgeRoute): NormalizedAdapterRoute {
+  return {
+    path: route.path,
+    match: routePrefixOf(route) ? 'prefix' : 'exact',
+    methods: routeMethodsOf(route),
+    maxBody: routeMaxBodyOf(route),
+    stream: route.stream,
+    upgrade: routeUpgradesOf(route),
+    locator: routeLocatorOf(route),
+    local: false,
+  }
+}
+
 /** Validate one plugin-bridge call's coordinates — the parse-once query
  * discipline (the re-serialization of THIS parse is the only string the
  * tunnel's upgrade request may carry), the share table with its ancestor
  * walk, and the live consent wall. `bridge.getConsent()` throwing reads as
- * unknown consent, and unknown consent stays home. */
-export function validatePluginCall(
+ * unknown consent, and unknown consent stays home. The share wall reads the
+ * route's EFFECTIVE locator (PB-24): the query convention — `sessionParam`
+ * folded in by {@link routeLocatorOf} — keeps its exactly-once rule, while a
+ * declaration-v2 locator re-locates over the SAME adapter-core rule the
+ * sub-client classified with and share-checks EVERY hit; a json-body route's
+ * body is consumed by validating (the reader above), and the verdict carries
+ * the bytes for the loopback. */
+export async function validatePluginCall(
   bridge: { registry: BridgeRegistry; getConsent: () => Record<string, boolean> },
   coords: { pluginName: string; pluginVersion: string; pluginDigest: string; routePath: string; rawQuery: string },
   isAccessible: (sessionId: string) => boolean,
-): PluginCallValidation {
+  readJsonBody?: PluginCallBodyReader,
+): Promise<PluginCallValidation> {
   const declaration = bridge.registry.get(coords.pluginName)
   if (declaration === undefined) return { ok: false, status: 404, code: 'plugin-unknown' }
   if (declaration.version !== coords.pluginVersion || declaration.digest !== coords.pluginDigest) {
     return { ok: false, status: 409, code: 'plugin-mismatch' }
   }
-  const route = declaration.routes.find((candidate) => candidate.path === coords.routePath)
+  // First hit in the declaration's (path-sorted) order wins. PB-23: an
+  // exact-declared route matches equality alone; a `prefix: true` route also
+  // admits every deeper RAW path (`x-zr-path` is matched undecoded, the
+  // module-wide discipline) — the SAME rule the adapter segment applies, so
+  // the sub-client's prefix forwarding (PB-21) is checked here against the
+  // declaration instead of being trusted.
+  const route = declaration.routes.find((candidate) => adapterPathMatches(asAdapterRoute(candidate), coords.routePath))
   if (route === undefined) return { ok: false, status: 404, code: 'route-undeclared' }
+  // PB-23b: a prefix hit's variable tail carries the declaration-side shape
+  // red lines itself (`?`, `#`, `..` — encoded forms included — and
+  // whitespace; the shared rule, the adapter segment's too). 400
+  // `bad-request`, the coordinate-shape code this chain already answers.
+  if (adapterTailShapeViolation(asAdapterRoute(route), coords.routePath)) {
+    return { ok: false, status: 400, code: 'bad-request' }
+  }
   let params: URLSearchParams
   try {
     params = new URLSearchParams(coords.rawQuery)
   } catch {
     return { ok: false, status: 400, code: 'bad-query' }
   }
-  const ids = params.getAll(route.sessionParam)
-  const sessionId = ids.length === 1 ? ids[0] : undefined
-  if (sessionId === undefined || sessionId === '') return { ok: false, status: 400, code: 'bad-query' }
-  if (!isAccessible(sessionId)) return { ok: false, status: 403, code: 'not-shared' }
+  const locator = routeLocatorOf(route)
+  let sessionId: string
+  let bufferedBody: Buffer | undefined
+  if (locator.in === 'query') {
+    const ids = params.getAll(locator.name)
+    const queryId = ids.length === 1 ? ids[0] : undefined
+    if (queryId === undefined || queryId === '') return { ok: false, status: 400, code: 'bad-query' }
+    if (!isAccessible(queryId)) return { ok: false, status: 403, code: 'not-shared' }
+    sessionId = queryId
+  } else {
+    let parsedBody: unknown
+    if (locator.in === 'json-body') {
+      if (readJsonBody === undefined) return { ok: false, status: 400, code: 'bad-request' }
+      const read = await readJsonBody(routeMaxBodyOf(route))
+      if (read.kind === 'over') return { ok: false, status: 413, code: 'body-too-large' }
+      if (read.kind === 'corrupt') return { ok: false, status: 400, code: 'bad-query' }
+      bufferedBody = read.buffered
+      parsedBody = read.parsed
+    }
+    const hits = locateAdapterIds(asAdapterRoute(route), coords.routePath, params, parsedBody)
+    // The sub-client only forwards a classified-remote request, so a v2
+    // locator call that locates NOTHING is malformed here — the adapter
+    // half's rule verbatim.
+    if (hits.length === 0) return { ok: false, status: 400, code: 'bad-request' }
+    for (const hit of hits) {
+      if (!isAccessible(hit.value)) return { ok: false, status: 403, code: 'not-shared' }
+    }
+    sessionId = hits[0].value
+  }
   if (route.scope === 'server') {
     let consent: Record<string, boolean> = {}
     try {
@@ -76,7 +155,7 @@ export function validatePluginCall(
     }
     if (consent[coords.pluginName] !== true) return { ok: false, status: 403, code: 'consent-off' }
   }
-  return { ok: true, declaration, route, params, sessionId, normalizedQuery: params.toString() }
+  return { ok: true, declaration, route, params, sessionId, normalizedQuery: params.toString(), ...(bufferedBody !== undefined ? { bufferedBody } : {}) }
 }
 
 /** Largest single downstream data LINE (base64 will inflate by 4/3 — the cap
@@ -257,7 +336,10 @@ export function createPluginTunnel(options: CreatePluginTunnelOptions): PluginTu
         pluginBridgeError(res, 400, 'bad-request')
         return
       }
-      const validation = validatePluginCall(bridge, coords, options.isAccessible)
+      // No body reader here: an open request is empty-bodied by contract, so
+      // a json-body-locator route can never be validated and answers
+      // bad-request inside the shared chain.
+      const validation = await validatePluginCall(bridge, coords, options.isAccessible)
       if (!validation.ok) {
         pluginBridgeError(res, validation.status, validation.code)
         return

package/src/relay-server.ts

@@ -50,8 +50,9 @@ import { createPluginTunnel, validatePluginCall, type PluginTunnelRoutes } from
 import type { PluginLoopback } from './plugin-loopback.js'
 import { isLoopbackAuthError } from './plugin-loopback.js'
 import { INVOKE_BINARY_RESULT_METHODS, markInvokeBinary } from './invoke-binary.js'
+import { MAX_INVOKE_BODY_BYTES, MAX_UPLOAD_BYTES } from './upload-limits.js'
 import type { NormalizedAdapter, AdapterVerdict } from './plugin-adapter-core.js'
-import { matchAdapterRoute, locateAdapterIds, adapterOwnsRegistryEntry, AdapterMultiValueQueryError } from './plugin-adapter-core.js'
+import { matchAdapterRoute, adapterTailShapeViolation, locateAdapterIds, adapterOwnsRegistryEntry, AdapterMultiValueQueryError } from './plugin-adapter-core.js'
 
 /**
  * Registration prefix on the host webServer. Deliberately WITHOUT the
@@ -67,50 +68,16 @@ const RELAY_PROTOCOL = 1
 /** Request body ceiling for the POST routes other than invoke. */
 const MAX_BODY_BYTES = 1024 * 1024
 
-/**
- * Body ceiling for the binary upload channel alone (T51): a shared session's
- * non-image file attachments. DSH's own upload route has NO byte cap — the
- * host stores the stream verbatim (`saveFileStreamVerbatim` →
- * `publishImmutableObjectStream`, RT dsh-attachment-local lib/index.js
- * ~699-716; the 20 MiB `maxImageBytes` there covers INLINE images only), so
- * there is no host number to mirror and this relay picks its own: 500 MiB
- * per upload, checked first against `Content-Length` (refused before a byte
- * moves) and then counted while the stream is pumped (a chunked body has no
- * length header — the sub-client's undici forbids hand-set length headers,
- * so the streaming count is the path its uploads normally take). Past the
- * cap the forward is aborted, the rest of the request is drained and the
- * answer is 413 `payload-too-large`.
- *
- * SLOW-LINK BOUND (T51-fix, for the docs): a single legitimate upload is
- * also bounded in TIME. The sub-client's own round-trip budget now caps at
- * 15 minutes (relay-client.ts, the T31-fix rule), but the HOST's HTTP server
- * keeps Node's default 300 s request deadline — that is the binding limit:
- * a 500 MiB body needs roughly 14 Mbps sustained end to end, and a slower
- * link fails the call (the client-side refusal keeps the connection state)
- * rather than hanging. Raising the cap past what that deadline can carry
- * would only move the failure, so 500 MiB is the honest ceiling for the
- * current transport.
- */
-export const MAX_UPLOAD_BYTES = 500 * 1024 * 1024
+// The binary upload channel's ceiling lives in upload-limits.ts with the
+// plugin's other upload numbers (its full sizing rationale is there too);
+// re-exported here so the established `lib/relay-server.js` import path —
+// the tests, the fetch-route intercept — keeps working.
+export { MAX_UPLOAD_BYTES }
 
 /** The `/api` route the upload channel dispatches into, verbatim from the
  * host's own registration (RT dsh-client-file-upload lib/index.js:73). */
 export const UPLOAD_HTTP_PATH = '/api/session/uploadFileBinary'
 
-/**
- * Body ceiling for the invoke route alone: the prompt routes carry inline
- * images in their content blocks (`session/prompt` / `subagents/prompt` take
- * base64 `image` parts; DSH admits one image up to 20 MiB by default —
- * `maxImageBytes`, dsh-attachment-local — which base64 inflates to ~27 MiB),
- * so one full-size inline image plus its envelope needs 32 MiB. It is NOT
- * sized for `fileUploads/upload`: the UI's real file uploads ride the HTTP
- * route `api/session/uploadFileBinary` (T41b), not this JSON relay. The
- * buffer only ever grows to the REAL body size; the cap decides
- * accept/refuse, and a body that outgrows it is drained and answered 413
- * like any other oversized read.
- */
-const MAX_INVOKE_BODY_BYTES = 32 * 1024 * 1024
-
 /** Error messages forwarded to the client are clipped to this many chars. */
 const MAX_MESSAGE_CHARS = 500
 
@@ -1634,6 +1601,15 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
             relayPluginError(res, 409, 'plugin-mismatch')
             return
           }
+          // PB-23b: the prefix tail's shape red line — the SAME shared rule
+          // the cooperative chain applies inside validatePluginCall (400
+          // `bad-request`), so an illegal tail (`?`, `#`, `..` in any
+          // encoding, whitespace) never reaches the loopback through either
+          // half.
+          if (adapterTailShapeViolation(adapterRoute, routePath)) {
+            relayPluginError(res, 400, 'bad-request')
+            return
+          }
           // Whole-machine data by definition: the live consent wall, the
           // same knob the cooperative server-scope routes read.
           let adapterConsent: Record<string, boolean> = {}
@@ -1892,17 +1868,48 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         // 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(
+      // Steps 1/2/3 and 4-6 (registry, version+digest, the declared-route
+      // match — exact, or a prefix route's deeper RAW paths — 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. PB-24: a json-body
+      // route's body is consumed BY validating (the share wall reads the
+      // located id), bounded by the route's maxBody — the loopback then
+      // sends exactly that share-checked buffer, never a re-read.
+      const validation = await validatePluginCall(
         bridge,
         { pluginName, pluginVersion, pluginDigest, routePath, rawQuery },
         isAccessible,
+        async (maxBody) => {
+          const chunks: Buffer[] = []
+          let size = 0
+          try {
+            for await (const chunk of req) {
+              size += (chunk as Buffer).length
+              if (size > maxBody) return { kind: 'over' as const }
+              chunks.push(Buffer.from(chunk as Uint8Array))
+            }
+          } catch {
+            // A read error (the client hung up mid-body) folds into the
+            // corrupt verdict — readJsonObject's `error` fold — never a
+            // throw into the host webserver's outer catch.
+            return { kind: 'corrupt' as const }
+          }
+          const buffered = Buffer.concat(chunks)
+          if (buffered.length === 0) return { kind: 'body' as const, buffered }
+          try {
+            return { kind: 'body' as const, buffered, parsed: JSON.parse(buffered.toString('utf8')) }
+          } catch {
+            return { kind: 'corrupt' as const }
+          }
+        },
       )
       if (!validation.ok) {
         relayPluginError(res, validation.status, validation.code)
+        // The reader's over-limit stop leaves the request half-read — the
+        // tail drains after the answer (the T51 discipline; only the reader
+        // can produce this code on this path).
+        if (validation.code === 'body-too-large') void drainUpload(req, 0, drainDeadlineMs)
         return
       }
       const route = validation.route
@@ -1918,10 +1925,11 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
       //     `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.
+      //     in the pump below. A json-body route skips this gate: its body
+      //     was already consumed and bounded by validating.
       const maxBody = routeMaxBodyOf(route)
       const declaredLength = Number(headerValue(req, 'content-length'))
-      if (!bodylessMethod && Number.isFinite(declaredLength) && declaredLength > maxBody) {
+      if (!bodylessMethod && validation.bufferedBody === undefined && Number.isFinite(declaredLength) && declaredLength > maxBody) {
         relayPluginError(res, 413, 'body-too-large')
         await drainUpload(req, 0, drainDeadlineMs)
         return
@@ -1970,7 +1978,11 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         // reads the recorded error first.
         const bodyAbort = new AbortController()
         const bodySignal = AbortSignal.any([hangUp.signal, bodyAbort.signal])
-        if (!bodylessMethod) {
+        if (validation.bufferedBody !== undefined) {
+          // PB-24: the json-body route's bytes were consumed by validating —
+          // the loopback sends exactly the share-checked buffer.
+          bodyStream = Readable.from(validation.bufferedBody)
+        } else if (!bodylessMethod) {
           let pumped = 0
           const gate = new Transform({
             transform(chunk: Buffer, _encoding, callback) {

package/src/upload-limits.ts

@@ -0,0 +1,69 @@
+/**
+ * The one home of every upload/body ceiling this plugin enforces (the
+ * upload unification, 2026-10-28). Three paths move bytes through the
+ * plugin, each with its own number, and the numbers used to live beside
+ * their enforcement sites — where they drifted: the docs still said
+ * 100 MiB, the nginx snippet capped at 128m under a 500 MiB relay, and
+ * the better-sidebar adapter hand-copied the relay budget (kept in step
+ * only by a paired test). Defining them here once makes each number
+ * greppable to exactly one place; scripts/check-upload-limits.mjs pins
+ * the rest — no second MiB-scale constant definition anywhere in src/,
+ * and the docs / nginx snippet stay in sync with MAX_UPLOAD_BYTES.
+ *
+ * Pure constants, ZERO imports (the virtual-id.ts precedent): the relay
+ * server, the phone-upload route, the sub-client's fetch-route intercept,
+ * the adapter core and the adapters themselves all import from here — an
+ * adapter may only lean on pure utility modules, so anything less pure
+ * would have kept the hand-copies alive.
+ */
+
+/**
+ * Body ceiling for the binary upload channel alone (T51): a shared session's
+ * non-image file attachments. DSH's own upload route has NO byte cap — the
+ * host stores the stream verbatim (`saveFileStreamVerbatim` →
+ * `publishImmutableObjectStream`, RT dsh-attachment-local lib/index.js
+ * ~699-716; the 20 MiB `maxImageBytes` there covers INLINE images only), so
+ * there is no host number to mirror and this relay picks its own: 500 MiB
+ * per upload, checked first against `Content-Length` (refused before a byte
+ * moves) and then counted while the stream is pumped (a chunked body has no
+ * length header — the sub-client's undici forbids hand-set length headers,
+ * so the streaming count is the path its uploads normally take). Past the
+ * cap the forward is aborted, the rest of the request is drained and the
+ * answer is 413 `payload-too-large`.
+ *
+ * SLOW-LINK BOUND (T51-fix, for the docs): a single legitimate upload is
+ * also bounded in TIME. The sub-client's own round-trip budget now caps at
+ * 15 minutes (relay-client.ts, the T31-fix rule), but the HOST's HTTP server
+ * keeps Node's default 300 s request deadline — that is the binding limit:
+ * a 500 MiB body needs roughly 14 Mbps sustained end to end, and a slower
+ * link fails the call (the client-side refusal keeps the connection state)
+ * rather than hanging. Raising the cap past what that deadline can carry
+ * would only move the failure, so 500 MiB is the honest ceiling for the
+ * current transport.
+ */
+export const MAX_UPLOAD_BYTES = 500 * 1024 * 1024
+
+/**
+ * Body cap when the plugin row sets no `maxUploadBytes`. This governs ONLY
+ * the phone composer's attachment upload (`/_dsh/mobile-nav/upload`) — the
+ * remote relay channel reads {@link MAX_UPLOAD_BYTES} and must never be
+ * sized from this: `maxUploadBytes` is a user-facing knob for phone picks
+ * (default 20 MB), and wiring it into the relay would drop remote
+ * attachments from 500 MiB back down to it (a regression the README's
+ * 500 MiB promise forbids).
+ */
+export const DEFAULT_MAX_UPLOAD_BYTES = 20 * 1024 * 1024
+
+/**
+ * Body ceiling for the relay's invoke route alone: the prompt routes carry
+ * inline images in their content blocks (`session/prompt` / `subagents/prompt`
+ * take base64 `image` parts; DSH admits one image up to 20 MiB by default —
+ * `maxImageBytes`, dsh-attachment-local — which base64 inflates to ~27 MiB),
+ * so one full-size inline image plus its envelope needs 32 MiB. It is NOT
+ * sized for `fileUploads/upload`: the UI's real file uploads ride the HTTP
+ * route `api/session/uploadFileBinary` (T41b), not this JSON relay. The
+ * buffer only ever grows to the REAL body size; the cap decides
+ * accept/refuse, and a body that outgrows it is drained and answered 413
+ * like any other oversized read.
+ */
+export const MAX_INVOKE_BODY_BYTES = 32 * 1024 * 1024

package/src/wizard/proxy-snippets.ts

@@ -47,9 +47,10 @@ function validatedParts(input: SnippetInput): { domain: string; upstream: string
  * nginx: a complete server block. The WebSocket upgrade map sits outside
  * the server (http-level context) — the snippet says so in a comment, the
  * user pastes it into the http/server scope their setup offers. Long
- * idle tunnels need the 3600s read/send timeouts, uploads the 128m
- * client body cap, and streaming the buffering switch — all three are
- * the shapes DSH's relay traffic actually needs.
+ * idle tunnels need the 3600s read/send timeouts, uploads the 512m
+ * client body cap (nginx's `m` is MiB — 512m covers the relay's 500 MiB
+ * upload ceiling with headroom), and streaming the buffering switch — all
+ * three are the shapes DSH's relay traffic actually needs.
  */
 export function nginxSnippet(input: SnippetInput): SnippetResult {
   const parts = validatedParts(input)
@@ -76,7 +77,7 @@ export function nginxSnippet(input: SnippetInput): SnippetResult {
     '        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;',
     '        proxy_set_header X-Forwarded-Proto $scheme;',
     '        proxy_buffering off;',
-    '        client_max_body_size 128m;',
+    '        client_max_body_size 512m;',
     '        proxy_read_timeout 3600s;',
     '        proxy_send_timeout 3600s;',
     '    }',