dsh-lan-guard

DSH LAN Guard

Expose the desktop DSH Web UI to your LAN safely: a gated reverse proxy with self-signed HTTPS by default and a QR code to open it on a phone. DSH's own loopback binding and the official UI stay untouched.

English | 中文

What it does · Quick start · Settings · Compatibility · Security boundary · Troubleshooting · Changelog

DSH LAN Guard is a DeepSeek Harness community plugin. It registers one section in the official settings page (settings.section), replaces no official layout, and modifies neither DSH source nor DSH's own listen binding.

DSH serves its Web UI on 127.0.0.1 only, and it deliberately refuses to bind 0.0.0.0. This plugin leaves that binding alone and opens a second, gated listener on another port, proxying the official UI outward as-is: a password gate, self-signed HTTPS by default, a QR code to open it on a phone, and device pairing you can approve or block one by one. One restart after install is all it takes — no hand-written configuration.

What it does

• Gated reverse proxy — relays HTTP and WebSocket end to end (including the official UI's /api/remote.mux long connection), rewrites Host/Origin, strips hop-by-hop headers, and answers 502 when the upstream is down. DSH's own binding and configuration are never touched.
• LAN-ready by default, but reachable is not the same as enterable — it binds 0.0.0.0, so one restart after install is enough. The gate is on by default and refuses every device until you set an access password, and TLS is self-signed by default — nothing travels in clear. Switch to "this machine only" in the settings page if you prefer.
• Two passwords — PBKDF2-SHA256 (600,000 iterations). The access password logs visitor devices in; the admin password unlocks this settings page's management console (it falls back to the access password). Plus a dsh_ passwordless link, persistent visitor sessions, per-IP lockout and CSRF checks.
• Self-signed HTTPS by default, with a stable CA — generates a DSH LAN Guard CA and signs a leaf certificate for the current NIC addresses. Changing IP only re-signs the leaf, so each device trusts the CA once.
• Your own machine is never locked — direct 127.0.0.1 access is physically unlocked (whoever can use this computer could change these settings anyway). Remote access follows adminPolicy: read-only (default), password-unlocked, or open.
• Device pairing and permanent blocking — a phone names itself once when it first passes the gate, receives an HttpOnly device-identity cookie, and appears under 已授权设备 (name / created / last used / source IP) where you can revoke and block it. Blocking does not rely on device fingerprinting: re-pairing with the access password from another browser is refused too, and unblocking is the only way back.
• Settings inside the official page — the "局域网访问" section has four tabs: QR access, authentication, authorised devices, and connection & certificates. All typography and colours use the official design tokens; no official layout is replaced.
• Adding a workspace from a phone (smart routing) — DSH resolves its directory picker once at boot, and a loopback bind with a display resolves to native: tapping "添加工作区" on a phone actually opens the folder dialog on the host's screen. This plugin shadows the official pick flow from the browser half at a lower slot priority, so the local browser keeps the OS dialog while a remote device gets an in-page directory browser (breadcrumbs, shortcuts, directory list). The chosen path still goes through DSH's own workspace flow — this plugin only reads directories, never writes anything.
• Configurable port and listen scope — defaults to 3081 (DSH's port + 1) and walks up to ten ports when that one is taken, with an availability check in the settings page. The listen scope toggles between "LAN (default)" and "this machine only"; both need a DSH restart.
• Optional mDNS — off by default; advertises _dsh-lan-guard._tcp when enabled.
• Update check — the settings page shows "current version → latest on npm" with a copyable upgrade command. The plugin never installs or restarts anything itself.

Quick start

Requirements:

• DeepSeek Harness with a Web profile
• Node.js 20 or newer
• Verified DeepSeek Harness: 0.2.1-rc.3 (API review, type checking and automated regression; phone/browser acceptance on rc.3 is pending).

Install from npm:

dsh plugin --profile web add dsh-lan-guard@latest

Install from GitHub:

dsh plugin --profile web add "github:idoall/dsh-lan-guard"

Install from a local clone:

git clone https://github.com/idoall/dsh-lan-guard.git
cd dsh-lan-guard
pnpm install && pnpm run build
dsh plugin --profile web add "link:$(pwd)"

Then restart DSH once and open Settings → 局域网访问. After that restart the plugin is already listening on the LAN (default 0.0.0.0:3081, self-signed HTTPS + gate); all you do is:

1. Set an access password (at least 8 characters) under 安全认证. Until you do, the gate refuses every device.
2. Check the listen scope under 连接与证书 (LAN by default) and pick the NIC to publish on — the NIC decides which IP the QR code / access URL uses and which addresses the self-signed certificate covers.
3. Scan the QR under 扫码访问, trust DSH LAN Guard CA once on the phone, enter the access password, and name the device. The phone then runs the official DSH UI.

Remote devices are read-only by default (adminPolicy: local_only): they can use DSH but cannot change plugin settings. Switch the policy on the desktop if you want a phone to manage them.

Settings

Everything lives under Settings → 局域网访问, in four tabs. The non-sensitive switches (enabled, listenPort, listenHost, networkInterface, settingsUnlock, answerHeartbeat, socketWatchdog, mobileCompat, mobileScrollFix, mobileTurnRail, auth.mode, auth.adminPolicy, auth.adminProtection, auth.allowLoopback, auth.requirePairing, auth.requireApproval) are editable directly; listenPort and listenHost take effect on the next DSH restart; settingsUnlock, socketWatchdog, mobileCompat, mobileScrollFix and mobileTurnRail take effect on the next page load while answerHeartbeat also applies to connections that are already open; dataDir and tls.* are startup fields that need a profile-patch edit.

The plugin reads its config from its Cordis entry. Every key has a usable default, so a fresh install works as-is:

# ~/.dsh/profiles/web/cordis.patch.yml (optional: write only what you want to change)
- id: dsh-lan-guard
  config:
    listenHost: 0.0.0.0              # LAN-facing by default; '127.0.0.1' = this machine only, or one NIC IP
    listenPort: 3081                 # DSH port + 1; auto-walks up to 10 ports when taken
    networkInterface: en0            # optional: publish on one NIC (empty = automatic)
    settingsUnlock: true             # LAN devices may use the official settings page (default on)
    answerHeartbeat: true            # proxy answers the WebSocket heartbeat (default on)
    socketWatchdog: true             # page-side socket watchdog (default on)
    mobileCompat: true               # mobile compatibility shims (default on)
    mobileTurnRail: false            # show DSH's own turn rail on narrow screens (default off)
    dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard   # optional; this is the derived default
    tls:
      mode: self-signed              # 'self-signed' (default) | 'provided' | 'off'
      allowInsecureLan: false        # required acknowledgement for LAN plain HTTP
    mdns:
      enabled: false                 # advertise _dsh-lan-guard._tcp
    auth:
      mode: token_and_password       # 'token_and_password' | 'password' | 'token'
      adminPolicy: local_only        # 'local_only' (default) | 'password_unlock' | 'open'
      adminProtection: true          # admin console needs the admin password
      allowLoopback: true            # 127.0.0.1 visitors skip the gate (physically unlocked)
      requirePairing: true           # new remote devices must name themselves once

dataDir is the only key that needs explaining: omit it and the plugin uses <active profile>/data/dsh-lan-guard (e.g. ~/.dsh/profiles/web/data/dsh-lan-guard); set it and your value wins (a leading ~ is expanded). It only decides where the plugin's private state (password hashes, device-token hashes, sessions, self-signed CA) lives — never whether the plugin works.

Compatibility

Current version: plugin 0.7.6, compatible with DeepSeek Harness 0.2.1-rc.3. Each row below is one plugin release: the DSH versions it was verified against, and what that release did.

• Declared range >=0.1.7-rc.1 <0.3.0 (dsh.engines.dsh); verified releases: 0.1.7-rc.1, 0.1.7-rc.2, 0.2.0-rc.1, 0.2.0-rc.2, 0.2.1-alpha.1, 0.2.1-alpha.3, 0.2.1-alpha.4, 0.2.1-alpha.5, 0.2.1-rc.2, 0.2.1-rc.3 (10 releases; the rc.3 verification scope is described above). DSH versions not listed are unverified — verify them yourself before use. The upper bound was widened from <0.2.0 in 0.4.3 because profile load refuses a bundle whose range excludes the running release, and a plain <0.2.0 would exclude the 0.2.0 stable.
• Host/client interfaces this plugin uses: webServer.register / webServer.tapIndex (indexTaps), connection.requestRejection, connection.authenticatedUrl, the additive settings.section seat, @deepseek-ai/schemastery, and profileContext (for deriving the default data directory).
• Breaking default change (from 0.3.2): listenHost now defaults to 0.0.0.0 instead of 127.0.0.1, so one restart after install is enough; 0.3.1 and earlier default to loopback only. The gate and self-signed TLS defaults are unchanged (with no password the gate still refuses every device). See the CHANGELOG.
• 0.4.0 verification status: all three changes carry measurements, not just specs.
  1. Proxy answers the heartbeat: a Node client against the real DSH measured a 6.0 s reap after it stopped sending Pongs (close 1006, no Close frame); with the answerer on the same link survived 20 s (10 pings answered). An end-to-end spec reproduces the pair against a DSH-shaped upstream (40 ms pings, destroy after two misses): reaps without the answerer, survives with it.
  2. Page patches: the injected scripts are executed in the suite against a fake environment and clock — "a socket stuck in CONNECTING is closed after 8 s", "never reloads while one socket is OPEN", "never reloads a page that created no socket", "reloads once after a resume with nothing open, then backs off within the cooldown and cap", "never reloads while hidden".
  3. Browser verification (BrowserSkill, Chrome 154, through a temporary loopback forward that still traverses the whole plugin path): /api/remote.mux handshake 3 ms; the session/follow snapshot arrives in 43–110 ms as a single 2.1 MB frame; 310 frames over 12 s with no interruption; and with the page's main thread frozen for 12 s a connection without the answerer received close 1006. The suite is green at 349 specs (330 in 0.3.6). The real-DSH install verification follows the release (this machine runs the installed 0.3.6, so the code takes effect after a reinstall plus a DSH restart).

Why a phone's session socket dies (measured 2026-09-28)

The session transcript — the 「载入历史…」 part of the UI — rides the WebSocket only; the session list, the goal chip and the statistics arrive over HTTP, which is why the failure looks like "everything is there except the conversation". Three facts define it:

Three layers ship in this release, all on by default and each individually switchable:

1. answerHeartbeat — while relaying, the proxy reads the upstream→browser control frames and answers a Ping with a masked Pong on the client's behalf. RFC 6455 allows an unsolicited Pong and the host only resets its counter on "a Pong arrived", so the phone's own duplicate is harmless. This is the only layer that stops the host from reaping a suspended phone.
2. socketWatchdog — the page-side half: close a socket that is stuck in CONNECTING, and reload once when a resume leaves nothing open.
3. mobileCompat — AbortSignal.any/timeout, Promise.withResolvers, Iterator and the mobile metas. DSH's client calls AbortSignal.any on its session-stream path, and Session.doOpen re-throws non-transport errors, so a missing API shows up as a permanent 「载入历史…」 with no error text.

Settings → 局域网访问 → 连接与证书 → 手机连接与自愈 carries a connection health check: it inspects which APIs this browser lacks, which patches the page received, runs a real WebSocket handshake against the current origin, and shows the proxy-side counters (open connections, upgrades, refusals, answered heartbeats) plus the last connection's duration, bytes and whether it died abnormally.

• 0.3.6 verification status: the change spans the host side (a new directory-listing route and cookie relaying) and the client side (the directory browser, t