dsh-remote 0.8.53 → 0.8.60

package/lib/pool.js

@@ -20,6 +20,12 @@ const { Client } = ssh2
  * caller can keep using `new SshPool(...)`-shaped code — this factory only has
  * to decide which class to instantiate.
  */
+/** Hard cap on proxy-chain depth. OpenSSH's ProxyJump has no explicit limit;
+ *  this exists to turn a config CYCLE into a clear error instead of unbounded
+ *  recursion. A legitimate chain is 1-3 hops.
+ *  @type {number} */
+export const MAX_JUMP_HOPS = 8
+
 export function createPool(config, opts) {
   return isSystemOpenSshBackend(config)
     ? new SystemOpenSshPool(config, opts)
@@ -168,6 +174,7 @@ export class ActivePool {
   connect() { return this.delegate.connect() }
   exec(cmd, opts) { return this.delegate.exec(cmd, opts) }
   sftp() { return this.delegate.sftp() }
+  shell(opts) { return this.delegate.shell(opts) }
   detect() { return this.delegate.detect() }
   invalidate() { return this.delegate.invalidate() }
   close() { return this.delegate.close() }
@@ -284,19 +291,42 @@ export class SshPool {
     }
 
     // Proxy jump: SSH to the bastion first, then tunnel to the target through it.
+    //
+    // MULTI-HOP (OpenSSH `ProxyJump a,b,c` semantics): each bastion may itself
+    // carry a `proxy`, and the chain is built from the FARTHEST hop inward — hop
+    // N is dialed through the already-open connection to hop N-1. The recursion
+    // IS the mechanism, so there is no depth limit beyond what the config
+    // expresses; MAX_JUMP_HOPS is a cycle/typo guard, not a feature limit.
     let sock = null
     const proxyCfg = this.config.proxy
     if (proxyCfg && proxyCfg.host) {
       try {
+        const depth = Number(this.config._hopDepth) || 0
+        if (depth >= MAX_JUMP_HOPS) {
+          throw new Error(`proxy chain is deeper than ${MAX_JUMP_HOPS} hops — check the machine config for a proxy cycle`)
+        }
         this.proxyPool = new SshPool({
           ...this.config,
           host: proxyCfg.host,
           port: Number(proxyCfg.port) || 22,
           username: proxyCfg.username || this.config.username || 'root',
+          // CREDENTIALS DO NOT INHERIT ACROSS HOPS. `...this.config` brings the
+          // TARGET's key/passphrase along, which is wrong in two ways: it may
+          // not be authorized on the bastion, and presenting the target's key to
+          // an intermediate host hands that host a credential it should never
+          // see. A hop with no key of its own falls back to the agent/default
+          // discovery path, which is what an operator's own ssh setup provides.
           password: proxyCfg.password || '',
           privateKeyPath: proxyCfg.privateKeyPath || '',
           passphrase: proxyCfg.passphrase || '',
-          proxy: undefined,
+          ...(proxyCfg.useAgent !== undefined ? { useAgent: !!proxyCfg.useAgent } : {}),
+          ...(proxyCfg.keyboardInteractive !== undefined ? { keyboardInteractive: !!proxyCfg.keyboardInteractive } : {}),
+          ...(proxyCfg.hostKeyMode ? { hostKeyMode: proxyCfg.hostKeyMode } : {}),
+          // The nested hop keeps its OWN proxy — that is what builds the chain —
+          // and carries an incremented depth so a cycle is reported instead of
+          // recursing until the process dies.
+          proxy: proxyCfg.proxy && proxyCfg.proxy.host ? proxyCfg.proxy : undefined,
+          _hopDepth: depth + 1,
         }, { knownHostsFile: this._knownHostsFile })
         const pclient = await this.proxyPool.connect()
         if (!isCurrent()) throw new Error('ssh target changed during proxy connect')
@@ -347,9 +377,16 @@ export class SshPool {
           hostVerifier: (key) => guard.verifier(key),
         }
         if (sock) opts.sock = sock
+        // `useAgent` asks for agent auth, but ssh2 can only offer it when this
+        // PROCESS has an agent socket. On Windows there is no agent by default,
+        // so the flag alone used to fall through to the generic "no credentials"
+        // error — which reads as "the plugin lost my settings" rather than "this
+        // machine has no agent". Track the intent so the failure can say which.
+        let agentRequested = false
         if (this.config.useAgent) {
           const sockPath = process.env.SSH_AUTH_SOCK
           if (sockPath) opts.agent = sockPath
+          else agentRequested = true
         }
         let password = this.config.password || ''
         if (!password && this.passwordResolver) {
@@ -375,7 +412,9 @@ export class SshPool {
           opts.privateKey = key
           opts.passphrase = this.config.passphrase || undefined
         } else if (!password && !opts.agent) {
-          throw new Error('no credentials: set a password, a privateKeyPath, or enable useAgent to connect')
+          throw new Error(agentRequested
+            ? 'no SSH agent available: useAgent is enabled for this machine but SSH_AUTH_SOCK is not set in the DSH host process (Windows has no agent by default) — start an agent (or Pageant) before launching DSH, or save a password / private key for this machine'
+            : 'no credentials: set a password, a privateKeyPath, or enable useAgent to connect')
         }
         return opts
       }
@@ -643,6 +682,60 @@ export class SshPool {
     )
   }
 
+  /**
+   * Open an INTERACTIVE shell channel on the remote host (PTY-backed).
+   *
+   * This is what an embedded terminal needs and what `exec` cannot provide:
+   * `exec` runs one command and closes, with no PTY and no stdin after the
+   * writer returns. A shell channel keeps the session alive across commands, so
+   * `vim`, `top`, `sudo` prompts and anything else that talks to a terminal
+   * works the way it does in an ssh session.
+   *
+   * The returned stream is ssh2's channel: write to it for keystrokes, listen
+   * for `data` for output, call `setWindow(rows, cols, height, width)` on
+   * resize, and `end()`/`close()` to hang up. Columns/rows are negotiated per
+   * channel, so two terminals on the same pooled connection stay independent.
+   *
+   * @param {{cols?: number, rows?: number, term?: string, pty?: boolean}} [opts]
+   * @returns {Promise<object>} the ssh2 Channel (interactive stream).
+   */
+  shell(opts = {}) {
+    const cols = Math.max(2, Math.min(Number(opts.cols) || 80, 1000))
+    const rows = Math.max(2, Math.min(Number(opts.rows) || 24, 1000))
+    const term = String(opts.term || 'xterm-256color')
+    return this.connect().then(
+      (client) =>
+        new Promise((resolve, reject) => {
+          let retried = false
+          const runOn = (c) => {
+            const wndopts = { cols, rows, height: 0, width: 0, term }
+            // A shell on a Windows remote is a cmd/PowerShell via the default
+            // sshd shell; the PTY request is identical either way.
+            c.shell(wndopts, opts.pty === false ? {} : { pty: wndopts }, (err, stream) => {
+              if (err) {
+                // Same stale-connection recovery as exec/sftp: a session
+                // termination means the pooled client died server-side.
+                if (!retried && /channel open failure|open failed|session termination|disconnect/i.test(String((err && err.message) || err))) {
+                  retried = true
+                  this.invalidate()
+                  return this.connect().then(
+                    (fresh) => runOn(fresh),
+                    (e2) => reject(new Error('ssh shell failed (reconnect): ' + ((e2 && e2.message) || e2))),
+                  )
+                }
+                return reject(new Error('ssh shell failed: ' + ((err && err.message) || err)))
+              }
+              // An idle shell must not be killed by the connection's own idle
+              // handling: keepalive is already on, and the channel lives until
+              // the client calls end(). Nothing to schedule here.
+              resolve(stream)
+            })
+          }
+          runOn(client)
+        }),
+    )
+  }
+
   /** Resolve a promisified SFTP client. All paths normalized via toSftpPath(). */
   sftp() {
     return this.connect().then(

package/lib/registry.js

@@ -58,15 +58,213 @@ export function saveMachines(file, list, currentId, keepCurrentKey = true) {
   writeFileSync(file, JSON.stringify(payload, null, 2))
 }
 
-/** Strip secrets before sending a machine to the client. */
+/**
+ * Does this record actually HAVE a password the plugin can use?
+ *
+ * `passwordSet` used to be `!!m.password`, i.e. "a PLAINTEXT password exists in
+ * machines.json". A machine whose password lives in the OS keychain stores
+ * `password: ''` (by design — issue #30), so it reported `passwordSet: false`
+ * and the settings page showed an empty password box with no indication that a
+ * credential was saved. That is the difference between "the plugin forgot my
+ * password" and "the plugin has it and will not echo it".
+ *
+ * `secretStored` is written by the save route from the keychain result, so new
+ * records carry the truth. Records saved before that flag existed only carry the
+ * backend name, which is the best evidence available for them (a non-plain
+ * backend means a secret was meant to live in the OS store).
+ *
+ * @param {object} m - a registry record.
+ * @returns {boolean}
+ */
+export function hasStoredPassword(m) {
+  if (!m) return false
+  if (m.password) return true
+  if (m.secretStored === true) return true
+  if (m.secretStored === undefined && m.credentialBackend && m.credentialBackend !== 'plain') return true
+  return false
+}
+
+/** Strip secrets before sending a machine to the client.
+ *
+ *  Secrets never round-trip to the browser: a password is replaced by
+ *  `passwordSet`, and the private-key `passphrase` — which IS stored in the
+ *  record — is replaced by `passphraseSet`. Both flags exist so the settings form
+ *  can say "已保存（••••••••），留空 = 不修改" instead of showing an empty box that
+ *  looks like the plugin lost the value. */
 export function sanitizeMachine(m) {
   if (!m) return m
-  const { password, proxy, ...rest } = m
-  const out = { ...rest, passwordSet: !!(m.password && m.password.length) }
-  if (proxy) out.proxy = { ...proxy, password: proxy.password ? '' : undefined, passwordSet: !!(proxy.password && proxy.password.length) }
+  const { password, passphrase, proxy, ...rest } = m
+  const out = {
+    ...rest,
+    passwordSet: hasStoredPassword(m),
+    passphraseSet: !!(passphrase && String(passphrase).length),
+  }
+  if (proxy) {
+    out.proxy = {
+      ...proxy,
+      password: proxy.password ? '' : undefined,
+      passwordSet: !!(proxy.password && proxy.password.length),
+    }
+  }
+  return out
+}
+
+/**
+ * Resolve the credentials a TEST probe must dial with (issue: "编辑已连接机器 → 测试
+ * 连接" always failed with `no credentials`).
+ *
+ * The settings form never receives stored secrets, so an edit-then-test posted an
+ * EMPTY password while a real connect (which resolves the keychain/plain secret
+ * through the pool's `passwordResolver`) worked fine. The probe therefore has to
+ * be a MERGE: the form is an override layer, and anything it leaves blank falls
+ * back to what is stored for that machine.
+ *
+ * Rules, deliberately one-way (a form value never gets discarded):
+ *   · a non-empty form string wins;
+ *   · an empty/absent form string keeps the stored value;
+ *   · booleans (`useAgent`, `keyboardInteractive`) are taken from the form when
+ *     the form actually supplied a boolean, otherwise from the record — the
+ *     probe must exercise the SAME auth method the machine will use;
+ *   · a jump-host (`proxy`) password the form did not re-supply is carried over
+ *     from the stored proxy, otherwise a bastion-protected machine "fails to
+ *     test" for a reason that has nothing to do with the target.
+ *
+ * @param {object} body - the probe request body (form values).
+ * @param {object|null} rec - the saved machine record, if any.
+ * @param {string} [storedPassword] - the record's resolvable password (may come
+ *   from the OS keychain, hence the separate argument).
+ * @returns {{password:string,passphrase:string,privateKeyPath:string,useAgent:boolean,
+ *   keyboardInteractive:boolean,hostKeyMode:string,sshBinary:string,backend:string,
+ *   proxy:object|undefined,usedSavedCredential:boolean}}
+ */
+export function resolveProbeCredentials(body = {}, rec = null, storedPassword = '') {
+  const form = body || {}
+  const saved = rec || {}
+  const str = (v) => (v === undefined || v === null ? '' : String(v))
+  const pick = (formVal, storedVal) => {
+    const f = str(formVal).trim()
+    return f !== '' ? str(formVal) : str(storedVal)
+  }
+  const pickBool = (formVal, storedVal) => (typeof formVal === 'boolean' ? formVal : !!storedVal)
+
+  const formPassword = str(form.password)
+  const password = formPassword !== '' ? formPassword : str(storedPassword)
+  const formProxy = form.proxy && form.proxy.host ? form.proxy : null
+  const savedProxy = saved.proxy && saved.proxy.host ? saved.proxy : null
+  const baseProxy = formProxy || savedProxy
+  const proxy = baseProxy
+    ? {
+        host: String(baseProxy.host),
+        port: Number(baseProxy.port) || 22,
+        username: str(baseProxy.username),
+        password: formProxy && str(formProxy.password) !== ''
+          ? str(formProxy.password)
+          : str(savedProxy && savedProxy.password),
+        privateKeyPath: str(baseProxy.privateKeyPath),
+      }
+    : undefined
+
+  return {
+    password,
+    passphrase: pick(form.passphrase, saved.passphrase),
+    privateKeyPath: pick(form.privateKeyPath, saved.privateKeyPath),
+    useAgent: pickBool(form.useAgent, saved.useAgent),
+    keyboardInteractive: pickBool(form.keyboardInteractive, saved.keyboardInteractive),
+    hostKeyMode: pick(form.hostKeyMode, saved.hostKeyMode),
+    sshBinary: pick(form.sshBinary, saved.sshBinary),
+    backend: pick(form.backend, saved.backend) || 'native',
+    proxy,
+    // True when the form could not supply the credential and the stored one had
+    // to be used — the UI says so, because "测试成功" with an empty password box
+    // is otherwise indistinguishable from a form-only probe.
+    usedSavedCredential: formPassword === '' && password !== '',
+  }
+}
+
+/** Machine grouping metadata (host organisation).
+ *
+ *  A flat list does not survive contact with reality: once a user has a dozen
+ *  machines (prod/staging/GPU boxes/laptops) "pick the right one" becomes the
+ *  dominant failure mode, and picking the WRONG one on a destructive tool is
+ *  how accidents happen. These four fields are pure LABELS — they change no
+ *  connection behaviour — so they live beside it and can be edited freely.
+ *
+ *  Normalization is deliberately conservative: a bad value is dropped (not
+ *  coerced into something surprising), and every field is optional so existing
+ *  registries keep loading byte-for-byte.
+ *
+ *  @param {object} raw - a (possibly partial) group patch.
+ *  @returns {{environment?: string, location?: string, description?: string, tags?: string[]}}
+ */
+export function normalizeMachineGroup(raw) {
+  const out = {}
+  if (!raw || typeof raw !== 'object') return out
+  const str = (v, max) => {
+    const s = typeof v === 'string' ? v.trim() : ''
+    return s ? s.slice(0, max) : ''
+  }
+  const env = str(raw.environment, 40)
+  if (env) out.environment = env
+  const loc = str(raw.location, 40)
+  if (loc) out.location = loc
+  const desc = str(raw.description, 200)
+  if (desc) out.description = desc
+  // Tags: accept an array or a comma/space separated string (what a UI text box
+  // naturally produces), then de-duplicate case-insensitively while KEEPING the
+  // first spelling so the display stays stable.
+  let tags = raw.tags
+  if (typeof tags === 'string') tags = tags.split(/[,\s]+/)
+  if (Array.isArray(tags)) {
+    const seen = new Set()
+    const kept = []
+    for (const t of tags) {
+      const s = str(t, 32)
+      if (!s) continue
+      const k = s.toLowerCase()
+      if (seen.has(k)) continue
+      seen.add(k)
+      kept.push(s)
+      if (kept.length >= 12) break // a dozen labels is already too many to scan
+    }
+    if (kept.length) out.tags = kept
+  }
   return out
 }
 
+/**
+ * Select machines by group metadata — the predicate behind "run this on every
+ * staging box". All supplied filters must match (AND); tags are OR within
+ * themselves (any requested tag qualifies) which is how people read a tag row.
+ *
+ * @param {Array<object>} machines
+ * @param {{environment?: string, location?: string, tags?: string[]|string, query?: string}} filter
+ * @returns {Array<object>}
+ */
+export function filterMachinesByGroup(machines, filter = {}) {
+  const list = Array.isArray(machines) ? machines : []
+  const env = typeof filter.environment === 'string' ? filter.environment.trim().toLowerCase() : ''
+  const loc = typeof filter.location === 'string' ? filter.location.trim().toLowerCase() : ''
+  let wantTags = filter.tags
+  if (typeof wantTags === 'string') wantTags = wantTags.split(/[,\s]+/)
+  wantTags = (Array.isArray(wantTags) ? wantTags : []).map((t) => String(t).trim().toLowerCase()).filter(Boolean)
+  const query = typeof filter.query === 'string' ? filter.query.trim().toLowerCase() : ''
+  return list.filter((m) => {
+    if (!m) return false
+    if (env && String(m.environment || '').toLowerCase() !== env) return false
+    if (loc && String(m.location || '').toLowerCase() !== loc) return false
+    if (wantTags.length) {
+      const have = (Array.isArray(m.tags) ? m.tags : []).map((t) => String(t).toLowerCase())
+      if (!wantTags.some((t) => have.includes(t))) return false
+    }
+    if (query) {
+      const hay = [m.name, m.host, m.username, m.environment, m.location, m.description, ...(Array.isArray(m.tags) ? m.tags : [])]
+        .filter(Boolean).join(' ').toLowerCase()
+      if (!hay.includes(query)) return false
+    }
+    return true
+  })
+}
+
 /** Apply a machine's fields onto the live config object (pool + tools read it). */
 export function applyMachine(config, m) {
   if (!m) return

package/lib/remote-sandbox.js

@@ -0,0 +1,183 @@
+// dsh-remote — remote sandbox semantics (issue: parity with local sandbox).
+//
+// The gap this closes: a local agent session runs under `ctx.sandboxPolicy`
+// (read-only / workspace-write / danger-full-access), but every rw_* tool ran
+// remote commands with NO policy at all. A confined session could therefore
+// reach a remote host and mutate anything — the sandbox was not bypassed by a
+// flaw in its enforcement, it simply had no say over a different machine.
+//
+// Why this is a TOOL-LAYER fence rather than `ctx.sandbox.confine()`: the core
+// sandbox service wraps argv for a LOCAL spawn (`confine(argv, policy)` returns
+// argv to spawn on THIS host). A remote host has no sandbox runner, so wrapping
+// local argv cannot constrain a process on the other end of an SSH channel. The
+// core's own docs say exactly this — "Containers, microVMs, and remote
+// execution replace the surrounding capability seam instead". So the honest
+// enforcement point is here: decide, per operation, whether this session's mode
+// permits that remote path/command, and refuse with the OFFICIAL denial shape
+// so the model's escalation affordances keep working.
+//
+// Threat model (stated plainly, matching the official dsh-fs-sandbox header):
+// this is CONTAINMENT, not a security boundary. Paths are compared lexically, so
+// symlinks and TOCTOU races inside the remote host can escape; a remote command
+// can `cd` anywhere once bash runs with the user's own privileges. What it does
+// buy, and what the issue asked for: a confined session can no longer mutate a
+// remote tree outside its workspace BY ACCIDENT through the file tools, and
+// `rw_exec` refuses outright under read-only instead of silently running
+// anything. Deployments needing a hard boundary must confine on the REMOTE side
+// (containers, per-user accounts, filesystem ACLs).
+
+import path from 'node:path'
+import { normalizeRemotePath, relPathUnder } from './paths.js'
+
+/** The three file-effect modes, mirroring `@deepseek-ai/dsh-sandbox`. */
+export const REMOTE_SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access']
+
+/** Denial marker prefix, matching the official `sandboxDenialMarker` shape. */
+const DENIAL_PREFIX = '[sandbox: '
+
+/**
+ * Whether `target` lies inside `root` using lexical, separator-aware
+ * comparison. Mirrors the official `isPathInsideWorkspace`: both sides are
+ * normalized so `..` cannot escape, and `/tmp/foo` does not contain
+ * `/tmp/foobar`.
+ *
+ * A root of `/` contains everything (the whole filesystem is the workspace),
+ * which is what makes "workspace = filesystem root" a legal, permissive setup
+ * (issue #60) rather than a denial of everything.
+ *
+ * @param {string} target - the remote path being touched.
+ * @param {string} root - the remote workspace root.
+ * @returns {boolean}
+ */
+export function isInsideRemote(target, root) {
+  if (typeof target !== 'string' || typeof root !== 'string') return false
+  // POSIX-absolute only. `normalizeRemotePath` deliberately coerces a relative
+  // input to an absolute one (`tmp/foo` → `/tmp/foo`, `../foo` → `/foo`), which
+  // is right for a user-supplied path but WRONG for a fence: it would turn an
+  // unprovable root into a confident one. A root that is not absolute proves
+  // nothing, so refuse before normalizing.
+  if (!isPosixAbsolute(root)) return false
+  const t = normalizeRemotePath(target)
+  let r = normalizeRemotePath(root)
+  if (r === '/' || r === '') return true
+  r = r.replace(/\/+$/, '')
+  if (t === r) return true
+  return t.startsWith(r + '/')
+}
+
+/**
+ * Whether a path is an absolute POSIX or Windows-Drive path, WITHOUT the
+ * coercing normalization `normalizeRemotePath` performs.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isPosixAbsolute(p) {
+  const s = String(p || '')
+  if (!s) return false
+  if (s.startsWith('/')) return true            // POSIX
+  if (/^[a-zA-Z]:[\\/]/.test(s)) return true    // Windows drive
+  if (/^\\\\[^\\]+/.test(s)) return true        // Windows UNC
+  return false
+}
+
+/**
+ * Decide whether one remote operation is permitted under a mode.
+ *
+ * `operation` is the coarse kind the tools act with:
+ *   - `read`   — reading remote data (never denied: read-only still reads)
+ *   - `write`  — creating/replacing/removing a REMOTE PATH (path fence)
+ *   - `exec`   — running an arbitrary remote command
+ *   - `tunnel` — opening a port forward
+ *   - `connect`— dialing/authenticating a machine (never denied: without it
+ *                nothing else could work, and it changes no remote state)
+ *
+ * @param {object} arg
+ * @param {string} arg.mode - the resolved sandbox mode.
+ * @param {string} arg.operation - see above.
+ * @param {string} [arg.path] - the remote path a `write` targets.
+ * @param {string} arg.workspaceRoot - the remote workspace root.
+ * @returns {{allowed: boolean, reason?: string, mode: string, subject?: string}}
+ */
+export function checkRemoteSandbox({ mode, operation, path: target, workspaceRoot }) {
+  const m = REMOTE_SANDBOX_MODES.includes(mode) ? mode : 'read-only'
+  // Fail closed on an unknown mode, exactly like the official renderPolicyContext.
+  const effective = m
+
+  if (operation === 'read' || operation === 'connect') return { allowed: true, mode: effective }
+
+  if (effective === 'danger-full-access') return { allowed: true, mode: effective }
+
+  if (effective === 'read-only') {
+    // read-only refuses every state-changing remote operation. This is the
+    // strict reading of the official mode ("`read-only` permits only required
+    // sinks such as /dev/null") and the one that keeps a confined session
+    // honest on a machine whose filesystem it cannot police.
+    return {
+      allowed: false,
+      mode: effective,
+      subject: operation === 'exec' ? 'command' : operation === 'tunnel' ? 'tunnel' : 'operation',
+      reason:
+        operation === 'exec'
+          ? 'read-only sessions may not run commands on a remote host'
+          : operation === 'tunnel'
+            ? 'read-only sessions may not open remote port forwards'
+            : 'read-only sessions may not modify a remote host',
+    }
+  }
+
+  // workspace-write: writes must stay inside the workspace; exec and tunnel are
+  // allowed because a command's effects cannot be bounded lexically (and the
+  // official bash tool under workspace-write DOES run commands, confining them
+  // via the OS). Refusing exec here would make workspace-write useless for the
+  // primary remote use case (builds, tests), while pretending to confine it
+  // would be worse than saying we do not.
+  if (operation === 'exec' || operation === 'tunnel') return { allowed: true, mode: effective }
+
+  // A write with no resolvable workspace root cannot be proven inside it.
+  if (!workspaceRoot) {
+    return {
+      allowed: false,
+      mode: effective,
+      subject: 'operation',
+      reason: 'workspace-write needs a remote workspace root to fence writes; none is set',
+    }
+  }
+  if (isInsideRemote(target, workspaceRoot)) return { allowed: true, mode: effective }
+  return {
+    allowed: false,
+    mode: effective,
+    subject: 'operation',
+    reason: `workspace-write only permits changes inside ${workspaceRoot}`,
+  }
+}
+
+/**
+ * Render a denial into the official error shape so the model sees the same
+ * thing it would from a local sandbox denial (and can use the same escalation
+ * affordances when the composition advertises them).
+ *
+ * @param {{mode: string, reason?: string, subject?: string}} denial
+ * @returns {Error}
+ */
+export function remoteSandboxDenial(denial) {
+  const mode = (denial && denial.mode) || 'read-only'
+  const subject = (denial && denial.subject) || 'operation'
+  const hint = `[escalation: raise sandbox mode to retry the ${subject} once]`
+  const err = new Error(`${DENIAL_PREFIX}${mode}]\n${denial && denial.reason ? denial.reason + '\n' : ''}${hint}`)
+  err.code = 'FS_SANDBOX_DENIED'
+  err.remoteSandbox = { mode, subject }
+  return err
+}
+
+/**
+ * Relative path of a remote target under the workspace root, for diagnostics.
+ * Returns null when the target is outside it.
+ * @param {string} target
+ * @param {string} root
+ * @returns {string|null}
+ */
+export function remoteRelUnder(target, root) {
+  const rel = relPathUnder(root, target)
+  return rel === null ? null : rel
+}

package/lib/routes-fs.js

@@ -37,7 +37,17 @@ export function createFsRoutes({
       path: '/dsh-remote/ls',
       handler: async (req, res) => {
         try {
-          const hint = requestSessionHint(req)
+          // A POST body counts. This route used to read the session hint from the
+          // QUERY STRING only, so `POST /ls {sessionId}` silently listed the ACTIVE
+          // machine instead of the caller's — the wrong-host hazard issue #25 is
+          // about, reachable through the API even though the browser always uses
+          // GET. `/read`, `/write` and `/fs` already honoured the body; now this one
+          // does too, and `path` may come from either place.
+          let body = {}
+          if (req.method === 'POST') {
+            try { body = JSON.parse((await readBody(req)) || '{}') } catch { body = {} }
+          }
+          const hint = requestSessionHint(req, body)
           const b = await bindOrReply(req, res, hint)
           if (!b) return
           // Identity echo (external-switch defense): name the machine this
@@ -53,7 +63,9 @@ export function createFsRoutes({
           }
           await b.pool.detect()
           const q = new URL(req.url, 'http://localhost').searchParams
-          const raw = q.get('path') ? decodeURIComponent(q.get('path')) : (b.ws || '')
+          const raw = q.get('path')
+            ? decodeURIComponent(q.get('path'))
+            : (body.path ? String(body.path) : (b.ws || ''))
           const canon = normalizeRemotePath(raw)
           const win = b.pool.platform === 'windows'
           if (canon === '/' || raw === '' || raw === '/') {