dsh-wsl-desktop 0.2.0

package/lib/wsl/confinement.js

@@ -0,0 +1,424 @@
+/**
+ * Linux-side confinement for commands that run inside a WSL distribution.
+ *
+ * The host's `ctx.sandbox` provider cannot confine a `wsl.exe` process: its
+ * children execute on the Linux kernel side. Confinement therefore happens
+ * *inside* the distribution, by wrapping the inner shell command in a mount
+ * namespace whose root is read-only and whose only writable paths are the
+ * session workspace and a private `/tmp`.
+ *
+ * The runner needs root, because the WSL kernel refuses bind mounts inside a
+ * user namespace (`unshare -Ur --mount` succeeds but `mount --bind` fails with
+ * "wrong fs type"). `sudo -n unshare …` is used when the distribution's user
+ * has passwordless sudo; otherwise the confined modes fail loud rather than
+ * running unconfined.
+ *
+ * Entering the namespace through `sudo` changes the effective user, so the
+ * command is dropped back to the original uid/gid with `setpriv`. Without that
+ * step every file the command creates would be owned by root.
+ * @module dsh-wsl-desktop/wsl/confinement
+ */
+
+import { shellQuote } from './paths.js'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+/** Shipped helper script, installed by the operator (see README). */
+export const HELPER_SOURCE = join(dirname(fileURLToPath(import.meta.url)), 'dsh-wsl-confine.sh')
+
+/** The direct runner: sudo-wrapped unshare with the fence built in-process. */
+export const RUNNER_SUDO_UNSHARE = 'sudo-unshare'
+
+/** The hardened runner: a root-owned helper that always fences before exec. */
+export const RUNNER_HELPER = 'helper'
+
+/** Where the operator installs the confinement helper (see README). */
+export const HELPER_PATH = '/usr/local/sbin/dsh-wsl-confine'
+
+/** stderr text the kernel produces for a write blocked by the read-only root. */
+export const DENIAL_SIGNATURES = ['Read-only file system', 'read-only file system']
+
+/** Cached probe results, keyed by distribution and user. */
+const identityCache = new Map()
+const runnerCache = new Map()
+const noNewPrivsCache = new Map()
+
+/** Cache key for one distribution/user pair. */
+function keyFor(distro, username) {
+  return `${distro}\u0000${username ?? ''}`
+}
+
+/**
+ * Resolve the uid/gid a command must run as after the namespace is entered.
+ * @param {object} options - probe inputs.
+ * @param {string} options.distro - distribution name.
+ * @param {string} [options.username] - Linux user; omitted uses the distribution default.
+ * @param {(options: object) => Promise<{ stdout: string, exitCode: number | null }>} options.run - command runner.
+ * @returns {Promise<{ uid: string, gid: string } | null>} the identity, or null when it cannot be read.
+ */
+export async function resolveIdentity({ distro, username, run }) {
+  const key = keyFor(distro, username)
+  if (identityCache.has(key)) return identityCache.get(key)
+  const probe = () => run({
+    distro,
+    linuxCwd: '/',
+    ...username !== undefined && username !== '' ? { username } : {},
+    // The home directory is read before `sudo` runs, so it is the session
+    // user's; a confined login shell started through `sudo` would otherwise
+    // inherit HOME=/root and read the wrong profile.
+    command: 'echo __DSH_IDENTITY__; id -u; id -g; printf "%s\\n" "$HOME"; id -un',
+    // Non-login + sentinel on purpose: profile scripts must not be able to
+    // print identity facts (a model-writable dotfile printing 0/0//root/root
+    // would otherwise drop every confined command to root via setpriv) or
+    // shift the positional parse. Exactly the marker plus four probe lines is
+    // accepted; anything else fails closed for this command. The 60s ceiling
+    // plus the one timed-out retry below covers the desktop's first wsl.exe
+    // spawn after a restart, which can outlive a short ceiling on a cold VM.
+    loginShell: false,
+    timeoutMs: 60_000,
+  })
+  let result = await probe()
+  if (result.timedOut) {
+    // One transparent retry: the same probe. A second timeout surfaces as the
+    // diagnosable parse failure below (timedOut included in the message).
+    result = await probe()
+  }
+  const lines = result.stdout.trim().split('\n')
+  const markerAt = lines.indexOf('__DSH_IDENTITY__')
+  const [uid, gid, home, name] = markerAt >= 0 && lines.length - markerAt === 5
+    ? lines.slice(markerAt + 1)
+    : []
+  const identity = uid !== undefined && gid !== undefined && home !== undefined
+    && /^\d+$/.test(uid) && /^\d+$/.test(gid) && home.startsWith('/')
+    ? { uid, gid, home, name: (name ?? '').trim() }
+    : null
+  // A failed parse is a diagnosable event, not a silent null: surface what the
+  // probe actually saw so the caller's SandboxUnavailableError carries the
+  // evidence (trimmed) instead of a bare "identity unresolvable".
+  if (identity === null) {
+    throw new Error(
+      `身份探针输出无法解析（exit=${String(result.exitCode)} timedOut=${String(result.timedOut)}）：stdout=${JSON.stringify(result.stdout.slice(0, 400))} stderr=${JSON.stringify(result.stderr.slice(0, 200))}`,
+    )
+  }
+  // Cache only a resolved identity, mirroring detectRunner: a transient
+  // wsl.exe failure must not stick `null` for the process lifetime and deny
+  // every later confined command after the distribution recovered. An
+  // uncached failure still fails closed for THIS command; the next one
+  // re-probes.
+  if (identity !== null) identityCache.set(key, identity)
+  return identity
+}
+
+/**
+ * Detect whether the distribution can run the confinement runner.
+ *
+ * Probed once per distribution/user pair: the answer cannot change while the
+ * process runs, and every confined command would otherwise pay a `sudo` round
+ * trip.
+ * @param {object} options - probe inputs.
+ * @param {string} options.distro - distribution name.
+ * @param {string} [options.username] - Linux user.
+ * @param {(options: object) => Promise<{ stdout: string }>} options.run - command runner.
+ * @returns {Promise<string | null>} the runner id, or null when unavailable.
+ */
+export async function detectRunner({ distro, username, run }) {
+  const key = keyFor(distro, username)
+  if (runnerCache.has(key)) return runnerCache.get(key)
+  const probeOnce = async () => {
+    try {
+      // Prefer the hardened helper when the operator installed it: the
+      // sudoers grant is narrowed to the helper alone, which always applies
+      // the fence before exec-ing — the retained-grant self-escape is closed.
+      const helperProbe = await run({
+        distro,
+        linuxCwd: '/',
+        ...username !== undefined && username !== '' ? { username } : {},
+        command: `test -x ${shellQuote(HELPER_PATH)} && sudo -n ${shellQuote(HELPER_PATH)} --version 2>/dev/null | grep -q '^dsh-wsl-confine' && echo yes || echo no`,
+        loginShell: false,
+        timeoutMs: 60_000,
+      })
+      if (helperProbe.stdout.trim() === 'yes') return RUNNER_HELPER
+      const result = await run({
+        distro,
+        linuxCwd: '/',
+        ...username !== undefined && username !== '' ? { username } : {},
+        command: 'sudo -n true >/dev/null 2>&1 && command -v unshare >/dev/null 2>&1 && command -v setpriv >/dev/null 2>&1 && echo yes || echo no',
+        // Non-login: with rc output excluded, the answer is exactly 'yes' or
+        // 'no' and can be compared strictly instead of by substring. The 60s
+        // ceiling matches the identity probe (cold VM first spawn).
+        loginShell: false,
+        timeoutMs: 60_000,
+      })
+      return result.stdout.trim() === 'yes' ? RUNNER_SUDO_UNSHARE : null
+    } catch {
+      // An unreachable distribution is reported by the caller's own failure path.
+      return null
+    }
+  }
+  // One transparent retry: the desktop's first wsl.exe spawns after a restart
+  // can fail inside the cold-start window (same rationale as the identity
+  // probe's retry). The retry repeats the SAME probe; a persistent absence
+  // still fails closed for THIS command, uncached.
+  let runner = await probeOnce()
+  if (runner === null) {
+    await new Promise((resolve) => { setTimeout(resolve, 1_000) })
+    runner = await probeOnce()
+  }
+  if (runner !== null) runnerCache.set(key, runner)
+  return runner
+}
+
+/**
+ * Forget cached probe results. Used by tests and by a settings change.
+ */
+export function resetConfinementCache() {
+  identityCache.clear()
+  runnerCache.clear()
+  noNewPrivsCache.clear()
+}
+
+/**
+ * Detect whether the distribution's `setpriv` supports `--no-new-privs`.
+ *
+ * When supported, the confined drop sets NO_NEW_PRIVS for the whole command
+ * subtree: setuid/file-caps elevation fails loudly, which closes the
+ * retained-sudo self-escape (the session user keeps a passwordless sudo grant
+ * — the same primitive the runner itself uses — and without NNP that grant
+ * voids the file fence at will). Probed once per distribution/user pair;
+ * availability cannot change while the process runs.
+ * @param {object} options - probe inputs.
+ * @param {string} options.distro - distribution name.
+ * @param {string} [options.username] - Linux user.
+ * @param {(options: object) => Promise<{ stdout: string }>} options.run - command runner.
+ * @returns {Promise<boolean>} whether the drop can set NO_NEW_PRIVS.
+ */
+export async function detectNoNewPrivs({ distro, username, run }) {
+  const key = keyFor(distro, username)
+  if (noNewPrivsCache.has(key)) return noNewPrivsCache.get(key)
+  let supported = false
+  try {
+    const result = await run({
+      distro,
+      linuxCwd: '/',
+      ...username !== undefined && username !== '' ? { username } : {},
+      command: 'setpriv --help 2>&1 | grep -q -- --no-new-privs && echo yes || echo no',
+      loginShell: false,
+      timeoutMs: 60_000,
+    })
+    supported = result.stdout.trim() === 'yes'
+  } catch {
+    supported = false
+  }
+  noNewPrivsCache.set(key, supported)
+  return supported
+}
+
+/**
+ * Translate a session workspace root into a Linux path.
+ * @param {string | undefined} workspaceRoot - the resolved policy's workspace root.
+ * @param {string} linuxCwd - the command's Linux working directory.
+ * @param {(path: string) => string | null} toLinux - host-to-Linux translator.
+ * @returns {string | null} the Linux workspace root, or null when it is not addressable.
+ */
+export function workspaceRootInLinux(workspaceRoot, linuxCwd, toLinux) {
+  if (workspaceRoot === undefined || workspaceRoot.length === 0) return linuxCwd
+  const mapped = toLinux(workspaceRoot)
+  return mapped === null || mapped === '' ? null : mapped
+}
+
+/**
+ * Exit code the confinement script reserves for its own failure.
+ *
+ * A command that fails and a confinement that could not be established are
+ * different outcomes: the caller must be able to tell them apart, because the
+ * second one means the command ran under a weaker boundary than promised.
+ */
+export const SETUP_FAILURE_EXIT = 97
+
+/** stderr marker identifying a confinement setup failure rather than a command failure. */
+export const SETUP_FAILURE_MARKER = 'dsh-wsl-sandbox: setup failed'
+
+/**
+ * Mounts deliberately left writable: device nodes and kernel state.
+ *
+ * These are not file storage, so a read-only remount would break the process
+ * (writing to `/dev/null` on a read-only devtmpfs fails with `EROFS`) without
+ * protecting any file. Exact matches only — `/dev/shm` is a separate tmpfs and
+ * IS file storage, so it is remounted read-only like everything else.
+ */
+export const KERNEL_SURFACES = new Set(['/dev', '/dev/pts', '/dev/mqueue', '/proc', '/sys'])
+
+/**
+ * Escape ERE metacharacters so a path can only ever match itself.
+ * @param {string} text - a mount target or exempt path.
+ * @returns {string} the regex-escaped text.
+ */
+function escapeEre(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The assembled grep -E pattern for one sweep/postcondition: regex-escaped
+ * entries joined with alternation, anchored both ends.
+ * @param {string[]} keep - mount targets that stay writable.
+ * @returns {string} the pattern, as data (the caller quotes it for the shell).
+ */
+function exemptPattern(keep) {
+  return `^(${[...new Set([...keep, ...KERNEL_SURFACES])].map(escapeEre).join('|')})$`
+}
+
+/**
+ * The shell fragment that makes every remaining writable mount read-only.
+ *
+ * Enumerated at run time from `findmnt` rather than from a fixed list, because a
+ * list is only ever as complete as the machine it was written on: a new drvfs
+ * drive or a runtime tmpfs would reopen the hole silently.
+ * @param {string[]} keep - mount targets that stay writable.
+ * @returns {string} the fragment.
+ */
+function readOnlySweep(keep) {
+  const pattern = exemptPattern(keep)
+  return [
+    // Line-driven, not word-split: `$(…)` in a for-loop would split a mount
+    // target containing whitespace into two bogus targets. The pattern is ONE
+    // shellQuoted word over regex-escaped entries, so shell/regex
+    // metacharacters in a path stay inert data. A failing grep (invalid ERE,
+    // unexpected errors) calls fail() — exit 97 inside the pipeline's subshell
+    // reaches the script through `set -o pipefail` — never a vacuous pass.
+    //
+    // findmnt -r hex-escapes unsafe characters in TARGET (\x20 space, \x09
+    // tab, \x0a newline, \x5c backslash) — a spaced target swept under its
+    // escaped literal name would ENOENT the remount (swallowed below) and
+    // stay WRITABLE while the postcondition tested the bogus name. Decode
+    // before matching: findmnt only ever emits \xNN for literal characters
+    // (literal backslash arrives as \x5c), so bash's %b is lossless here.
+    `findmnt -rno TARGET | while IFS= read -r raw; do printf '%b\\n' "$raw"; done | { grep -Ev ${shellQuote(pattern)} || fail ${shellQuote('exemption grep failed')}; } | while IFS= read -r target; do`,
+    '  mount -o remount,ro,bind "$target" >/dev/null 2>&1 || true;',
+    'done',
+  ].join('\n')
+}
+
+/**
+ * The post-condition: the namespace must be what was asked for.
+ *
+ * Every step above tolerates its own failure so that one unmountable target does
+ * not abort the rest, which means the only trustworthy statement about the
+ * boundary is one read back from inside it. A target that is still writable
+ * outside the allow-list is a setup failure, not a command failure.
+ * @param {string[]} keep - mount targets that may stay writable.
+ * @returns {string} the fragment.
+ */
+function postConditions(keep) {
+  const pattern = exemptPattern(keep)
+  return [
+    'mountpoint -q /tmp || fail "/tmp is not a private tmpfs"',
+    'findmnt -rno OPTIONS / | grep -q "^ro" || fail "/ is not read-only"',
+    // Same line-driven loop, decode-before-match, and single-quoted pattern
+    // as the sweep (fail() is defined in the setup steps). The trailing
+    // `true` matters: the while is the LAST element of a pipeline, so a body
+    // that ends with a failing `[ -w ]` (the normal case — every swept target
+    // IS read-only) would otherwise fail the whole pipeline under
+    // `set -o pipefail` and abort the script before the command runs. A real
+    // `fail` still exits 97 from inside the loop, which pipefail turns into
+    // the script's own setup failure — the marker and exit code still
+    // surface.
+    `findmnt -rno TARGET | while IFS= read -r raw; do printf '%b\\n' "$raw"; done | { grep -Ev ${shellQuote(pattern)} || fail ${shellQuote('exemption grep failed')}; } | while IFS= read -r target; do`,
+    '  [ -w "$target" ] && fail "$target is still writable";',
+    '  true;',
+    'done',
+    'true',
+  ].join('\n')
+}
+
+/**
+ * Build the inner script that establishes the confinement and runs the command.
+ *
+ * Order matters: the writable paths are bound *before* the root is remounted
+ * read-only, because a bind created afterwards inherits the read-only state.
+ *
+ * The script fails closed. It runs under `set -euo pipefail`, every step is a
+ * separate statement whose failure aborts it, and it ends by verifying the
+ * boundary it just built — a failed `mount` used to leave the command running
+ * with a writable root while the caller was told the sandbox was fully enforced.
+ * @param {object} options - confinement plan inputs.
+ * @param {string} options.command - the caller's shell source.
+ * @param {string} options.linuxCwd - absolute Linux working directory.
+ * @param {'read-only' | 'workspace-write'} options.mode - the confined mode.
+ * @param {string | undefined} options.workspaceLinuxRoot - writable root for `workspace-write`.
+ * @param {{ uid: string, gid: string }} options.identity - identity to drop back to.
+ * @returns {string} the script to run inside the namespace.
+ */
+export function buildNamespaceScript({ command, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs }) {
+  const keep = ['/tmp']
+  const steps = ['set -euo pipefail']
+  // The failure helper is defined before the sweep so BOTH the sweep and the
+  // postcondition can fail closed through it.
+  steps.push(`fail() { printf '%s: %s\\n' ${shellQuote(SETUP_FAILURE_MARKER)} "$1" >&2; exit ${SETUP_FAILURE_EXIT}; }`)
+  if (mode === 'workspace-write') {
+    if (workspaceLinuxRoot === undefined || workspaceLinuxRoot === '') {
+      throw new Error('wsl-sandbox: workspace-write 需要一个工作区根目录')
+    }
+    // The workspace may not be a mount point, so the bind is its own source and
+    // target; the following remount of `/` leaves this nested mount writable.
+    steps.push(`mount --bind ${shellQuote(workspaceLinuxRoot)} ${shellQuote(workspaceLinuxRoot)}`)
+    keep.push(workspaceLinuxRoot)
+  }
+  steps.push('mount -t tmpfs tmpfs /tmp')
+  steps.push('mount -o remount,ro,bind /')
+  steps.push(readOnlySweep(keep))
+  steps.push(postConditions(keep))
+  const inner = `cd ${shellQuote(linuxCwd)} && ${command}`
+  // `sudo` leaves HOME pointing at root; without restoring it a login shell
+  // reads the wrong profile and reports "Permission denied" on every command.
+  const environment = [`HOME=${shellQuote(identity.home)}`]
+  if (identity.name !== undefined && identity.name !== '') environment.push(`USER=${shellQuote(identity.name)}`, `LOGNAME=${shellQuote(identity.name)}`)
+  // NO_NEW_PRIVS on the drop (when the distro's setpriv supports it) blocks
+  // setuid/file-caps elevation for the whole command subtree — without it the
+  // session user's retained passwordless sudo grant re-invokes the very
+  // privileged primitive this fence was built from (unfenced unshare, or
+  // remount,rw inside the namespace), voiding the file fence at will.
+  const nnp = noNewPrivs === true ? '--no-new-privs ' : ''
+  const drop = `setpriv ${nnp}--reuid=${identity.uid} --regid=${identity.gid} --init-groups `
+    + `env ${environment.join(' ')} bash -lc ${shellQuote(inner)}`
+  steps.push(`exec ${drop}`)
+  return steps.join('\n')
+}
+
+/**
+ * Build the command the executor hands to the distribution's outer shell.
+ * @param {object} options - confinement plan inputs.
+ * @param {string} options.command - the caller's shell source.
+ * @param {string} options.linuxCwd - absolute Linux working directory.
+ * @param {'read-only' | 'workspace-write'} options.mode - the confined mode.
+ * @param {string | undefined} options.workspaceLinuxRoot - writable root for `workspace-write`.
+ * @param {{ uid: string, gid: string }} options.identity - identity to drop back to.
+ * @param {boolean} [options.noNewPrivs] - set NO_NEW_PRIVS on the drop when the
+ *   distro's setpriv supports it (blocks setuid elevation inside the fence).
+ * @param {string} [options.runner] - the resolved runner: 'helper' routes the
+ *   command through the root-owned dsh-wsl-confine helper (the hardened path);
+ *   'sudo-unshare' (default) keeps the direct sudo-unshare runner.
+ * @param {boolean} [options.isolateProcesses] - add a PID namespace.
+ * @returns {string} the outer shell command.
+ */
+export function buildConfinedCommand({ command, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs, runner, isolateProcesses = true }) {
+  // The hardened helper path: the root-owned helper applies the identical
+  // fence itself and setpriv-exec's the command with NO_NEW_PRIVS — the
+  // command text travels as argv after `--` and is never evaluated as root.
+  if (runner === RUNNER_HELPER) {
+    const flags = [
+      `--uid ${identity.uid}`,
+      `--gid ${identity.gid}`,
+      `--home ${shellQuote(identity.home)}`,
+      `--cwd ${shellQuote(linuxCwd)}`,
+      ...(workspaceLinuxRoot !== undefined && workspaceLinuxRoot !== '' ? [`--workspace ${shellQuote(workspaceLinuxRoot)}`] : []),
+      ...(isolateProcesses ? [] : ['--no-pidns']),
+      '--',
+      shellQuote(command),
+    ]
+    return `sudo -n ${shellQuote(HELPER_PATH)} ${flags.join(' ')}`
+  }
+  const script = buildNamespaceScript({ command, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs })
+  const flags = ['--mount', '--propagation', 'private']
+  if (isolateProcesses) flags.push('--pid', '--fork')
+  return `sudo -n unshare ${flags.join(' ')} bash -c ${shellQuote(script)}`
+}

package/lib/wsl/dsh-wsl-confine.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# dsh-wsl-confine v1 — DSH WSL confinement helper.
+#
+# Root-owned fence executor: the ONLY thing this helper does is apply the
+# mount-namespace fence (workspace bind, tmpfs /tmp, read-only /, read-only
+# sweep with postconditions) and then drop to the target user and exec their
+# command. The sudoers grant is narrowed to this helper alone, so re-invoking
+# the privileged primitive from inside a confined command can only re-fence
+# from the already-fenced context — the fence is no longer voidable by the
+# principal it constrains.
+#
+# Install (one-time, per distribution, as root):
+#   install -m 0755 -o root -g root <this file> /usr/local/sbin/dsh-wsl-confine
+#   echo '<session-user> ALL=(root) NOPASSWD: /usr/local/sbin/dsh-wsl-confine *' \
+#     > /etc/sudoers.d/dsh-wsl-confine && chmod 0440 /etc/sudoers.d/dsh-wsl-confine
+#
+# Contract: parameters are strictly validated (numeric uid/gid, absolute
+# paths); the caller's command travels as argv after `--` and is executed only
+# AFTER the setpriv drop (with NO_NEW_PRIVS) — root never evaluates caller text.
+set -euo pipefail
+VERSION='dsh-wsl-confine v1'
+SETUP_FAILURE_EXIT=97
+
+uid=; gid=; home=; cwd=; workspace=; pidns=1
+ARGS=()
+while (($#)); do
+  case "$1" in
+    --uid) uid="${2:-}"; shift 2 ;;
+    --gid) gid="${2:-}"; shift 2 ;;
+    --home) home="${2:-}"; shift 2 ;;
+    --cwd) cwd="${2:-}"; shift 2 ;;
+    --workspace) workspace="${2:-}"; shift 2 ;;
+    --no-pidns) pidns=0; shift ;;
+    --version) echo "$VERSION"; exit 0 ;;
+    --) shift; ARGS=("$@"); break ;;
+    *) echo "dsh-wsl-confine: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ "$uid" =~ ^[0-9]+$ && "$gid" =~ ^[0-9]+$ ]] || { echo 'dsh-wsl-confine: uid/gid must be numeric' >&2; exit 2; }
+[[ -n "$cwd" && "$cwd" = /* && -n "$home" && "$home" = /* ]] || { echo 'dsh-wsl-confine: --cwd/--home must be absolute Linux paths' >&2; exit 2; }
+[[ -z "$workspace" || "$workspace" = /* ]] || { echo 'dsh-wsl-confine: --workspace must be absolute' >&2; exit 2; }
+((${#ARGS[@]} >= 1)) || { echo 'dsh-wsl-confine: no command' >&2; exit 2 }
+command -v unshare >/dev/null 2>&1 || { echo 'dsh-wsl-confine: unshare not found' >&2; exit 97; }
+command -v setpriv >/dev/null 2>&1 || { echo 'dsh-wsl-confine: setpriv not found' >&2; exit 97; }
+command -v findmnt >/dev/null 2>&1 || { echo 'dsh-wsl-confine: findmnt not found' >&2; exit 97; }
+
+# The fence script is built HERE from the validated parameters — the caller
+# never supplies script text. It is identical in effect to the in-process
+# builder (bind workspace before ro, tmpfs /tmp, decoded sweep, postconditions,
+# NO_NEW_PRIVS drop).
+FENCE='set -euo pipefail
+fail() { printf "%s: %s\n" "dsh-wsl-confine" "$1" >&2; exit 97; }
+if [[ -n "${WORKSPACE:-}" ]]; then
+  mount --bind "$WORKSPACE" "$WORKSPACE"
+  KEEP=("/tmp" "$WORKSPACE")
+else
+  KEEP=("/tmp")
+fi
+mount -t tmpfs tmpfs /tmp
+mount -o remount,ro,bind /
+findmnt -rno TARGET | while IFS= read -r raw; do printf "%b\n" "$raw"; done | { grep -Ev "^($(printf "%s|" "${KEEP[@]}" | sed "s/|$//")|/dev$|/proc$|/sys$")$" || fail "exemption grep failed"; } | while IFS= read -r target; do
+  mount -o remount,ro,bind "$target" >/dev/null 2>&1 || true
+done
+mountpoint -q /tmp || fail "/tmp is not a private tmpfs"
+findmnt -rno OPTIONS / | grep -q "^ro" || fail "/ is not read-only"
+findmnt -rno TARGET | while IFS= read -r raw; do printf "%b\n" "$raw"; done | { grep -Ev "^($(printf "%s|" "${KEEP[@]}" | sed "s/|$//")|/dev$|/proc$|/sys$")$" || fail "exemption grep failed"; } | while IFS= read -r target; do
+  [[ -w "$target" ]] && fail "$target is still writable"
+  true
+done
+cd "$CWD"
+exec setpriv --no-new-privs --reuid="$UID" --regid="$GID" --init-groups env HOME="$HOME_DIR" USER="$USER_NAME" LOGNAME="$USER_NAME" bash -lc "$COMMAND"'
+
+PID_FLAG=''
+[[ "$pidns" = 1 ]] && PID_FLAG='--pid --fork'
+
+exec unshare --mount --propagation private $PID_FLAG bash -c "$FENCE" \
+  dsh-wsl-confine \
+  UID="$uid" GID="$gid" HOME_DIR="$home" USER_NAME="${SUDO_USER:-user}" \
+  CWD="$cwd" WORKSPACE="$workspace" COMMAND="${ARGS[*]}"

package/lib/wsl/fence.js

@@ -0,0 +1,121 @@
+/**
+ * Pure containment mechanics for the WSL filesystem fence.
+ *
+ * The fence itself lives on `WslFileSystem` (`./fs.js`), but the comparison
+ * and allow-list derivation are path algebra with no harness dependency, so
+ * they live here where a plain Node process can load and verify them (the same
+ * split as `./paths.js` and `./confinement.js`).
+ *
+ * The rule mirrors the shipped backend (`@deepseek-ai/dsh-fs-sandbox` +
+ * `@deepseek-ai/dsh-sandbox/roots`), translated into this world: comparison
+ * happens in the HOST namespace, because a targetKey is a Windows spelling and
+ * its UNC prefix carries the distribution — same-Linux-path targets of another
+ * distro stay outside, and the Windows temp dir (reachable through
+ * `/mnt/<drive>`) can still be a granted root.
+ * @module dsh-wsl-desktop/wsl/fence
+ */
+
+import { stat } from 'node:fs/promises'
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { win32 } from 'node:path'
+import { joinWslUnc } from './paths.js'
+
+/**
+ * Canonicalize a writable root the way the shipped derivation does
+ * (`@deepseek-ai/dsh-sandbox/roots`): a root that cannot be resolved stays as
+ * spelled, which matches nothing until it exists — the conservative outcome.
+ * @param {string} path - the root as configured or platform-reported.
+ * @returns {string} the canonical path, or the input when resolution fails.
+ */
+export function canonicalHostPath(path) {
+  try {
+    return realpathSync.native(path)
+  } catch {
+    return path
+  }
+}
+
+/**
+ * Lexical containment with a separator boundary, case-insensitive because
+ * targetKeys are Windows spellings (`\\wsl.localhost\…` or a drive path). The
+ * boundary is what stops `/proj` matching `/proj-secret`.
+ * @param {string} targetKey - the canonical host path of the candidate.
+ * @param {string} root - the canonical host path of the writable root.
+ * @returns {boolean} true when the target is the root or below it.
+ */
+export function isLexicallyUnderHost(targetKey, root) {
+  const target = targetKey.toLowerCase()
+  const prefix = root.toLowerCase()
+  if (target === prefix) return true
+  const bounded = prefix.endsWith('\\') || prefix.endsWith('/') ? prefix : `${prefix}\\`
+  return target.startsWith(bounded)
+}
+
+const MISSING_CODES = new Set(['ENOENT', 'ENOTDIR'])
+
+/**
+ * Record one stat outcome, distinguishing "absent" from a real I/O fault.
+ * @param {string} path - the path to stat.
+ * @returns {Promise<object | undefined>} the bigint stats, or undefined when absent.
+ */
+async function statIfPresent(path) {
+  try {
+    return await stat(path, { bigint: true })
+  } catch (error) {
+    if (MISSING_CODES.has(error?.code)) return undefined
+    throw error
+  }
+}
+
+/**
+ * Containment for the fs fence: the lexical fast path over canonical
+ * spellings, then a filesystem-identity walk that recognizes alias-equivalent
+ * roots (casing, short names) without weakening containment to a textual
+ * approximation. Mirrors `@deepseek-ai/dsh-fs-sandbox/containment`.
+ * @param {string} targetKey - the canonical host path of the candidate.
+ * @param {string} root - the canonical host path of the writable root.
+ * @returns {Promise<boolean>} true when the target is the root or below it.
+ */
+export async function isUnderHost(targetKey, root) {
+  if (isLexicallyUnderHost(targetKey, root)) return true
+  const rootInfo = await statIfPresent(root)
+  if (rootInfo === undefined) return false
+  let ancestor = targetKey
+  for (;;) {
+    const info = await statIfPresent(ancestor)
+    if (info !== undefined && info.dev === rootInfo.dev && info.ino === rootInfo.ino) return true
+    const parent = win32.dirname(ancestor)
+    if (parent === ancestor) return false
+    ancestor = parent
+  }
+}
+
+/**
+ * The roots one workspace-write mutation may land under, in the host spellings
+ * targetKeys use. This mirrors `writableRoots` translated into this world: the
+ * workspace root, the *distribution's* temp area on the share (what a Linux
+ * `/tmp/…` request resolves to here — the shipped derivation's POSIX `/tmp`
+ * entry is meaningless on a Windows host), and the Windows temp dir, reachable
+ * through `/mnt/<drive>`.
+ *
+ * Like the shipped derivation, only `workspace-write` grants roots: an unknown
+ * mode yields an empty allow-list, which denies — fail-closed.
+ * @param {{ mode?: string, workspaceRoot?: string }} policy - the per-call policy.
+ * @param {string} distro - the distribution this backend is pinned to.
+ * @returns {string[]} canonical host paths; empty unless workspace-write.
+ */
+export function writableHostRootsFor(policy, distro) {
+  if (policy?.mode !== 'workspace-write') return []
+  // joinWslUnc throws for an invalid distro name; converting the throw to a
+  // filtered-out entry keeps this function total (never throws) so the caller
+  // sees an empty allow-list (fail-closed) rather than a raw Error escaping
+  // checkedTarget as a non-sandbox failure.
+  const distroTmp = (() => { try { return joinWslUnc(distro, '/tmp') } catch { return null } })()
+  const roots = [policy.workspaceRoot, distroTmp, tmpdir()]
+  return [...new Set(
+    roots
+      .filter((root) => typeof root === 'string' && root.length > 0)
+      .map(canonicalHostPath),
+  )]
+}