dsh-web-guard

DSH Web Guard

A password gate for the DeepSeek Harness Web UI —

one plugin that fixes four deployment problems at once and adds a native settings page.

中文说明

= 22.19">

= 0.2.2-rc.1">

| Problem | Vanilla behaviour | dsh-web-guard |

|---|---|---|

| No human login | A per-process ?token= printed to the terminal, new on every restart | One password + revocable sessions |

| /api returns 403 behind a proxy | The browser-trust fence requires Host to arrive unrewritten; NPM/Caddy rewrite it | The proxy rewrites Host/Origin to the loopback authority, which the fence accepts |

| Token lives in the journal | journalctl \| grep token before you can get in | Exchanged in-process; the browser never sees a token |

| UI breaks on plain HTTP | crypto.randomUUID is not a function outside a secure context | Injects a getRandomValues polyfill |

Zero runtime dependencies (Node standard library only). The npm package ships prebuilt JavaScript, so dsh plugin add needs no toolchain; building from a checkout is a maintainer command (npm run build).

Requires DeepSeek Harness 0.2.2-rc.1 or newer (engines.dsh: >=0.2.2-rc.1 <0.3.0). On an incompatible host the whole bundle is skipped — for a front door that means the gate does not start, so upgrade DSH rather than removing the plugin.

Screenshots

 

Login page  ·  sign-out confirmation  ·  native DSH Web Guard page in the harness settings (follows the harness light/dark theme)

How it works

browser ──HTTP(S)──> dsh-web-guard :3081 ──> DSH listener (loopback)
                          │
                          ├─ not signed in → /login
                          ├─ signed in → forward, Host/Origin rewritten to loopback
                          └─ injects the harness cookie (never exposed to the browser)

The harness fence accepts a loopback authority, so making every upstream request look like one removes the 403 entirely. Authentication happens in the proxy, not as a front-end overlay — a request without a session cookie never reaches the harness.

A small browser half (dsh.client) adds the management page to the harness Settings panel; the gate itself is entirely server-side and keeps working if the browser half cannot load.

Install

# npm
dsh plugin --profile web add @lvxianchao/dsh-web-guard

# from GitHub
dsh plugin --profile web add "github:lvxianchao/dsh-web-guard"

# from a local checkout
dsh plugin --profile web add /path/to/dsh-web-guard

main only ever carries released code (development happens on dev), so this

installs the latest stable release. Installing is enough — the package declares dsh.bundle, so the guard row is

mounted automatically. Restart dsh.

On first start a password is generated, printed to the terminal and stored

(hashed) in /data/dsh-web-guard.json with mode 0600. To pin your own,

add a row to ~/.dsh/profiles/web/cordis.patch.yml (it overrides the bundle

defaults):

- id: guard
  config:
    listenHost: '0.0.0.0'
    listenPort: 3081

Note that a profile patch replaces the whole config object, so restate every

key you care about.

Upgrading from v2: the bottom-right shield button and /__guard/admin are gone; management lives in Settings → DSH Web Guard. Reinstall the package (or update to 3.0.0) and restart DSH. The password hash, session cache and settings file keep their format, so nobody is signed out and your configuration carries over.

> The harness itself must listen on loopback (its default). If it is bound to a LAN address, clients can bypass the gate by connecting there directly — the plugin detects this at startup and warns.

⚠️ This is the front door, not an optional plugin

Once installed, dsh-web-guard is the only way in: it listens on 3081 and forwards to a DSH that is bound to loopback only (3080). If the plugin stops loading, 3081 stops listening and both your LAN and the internet lose access at once — while DSH itself keeps running, with your sessions and data intact. That is the dangerous shape: the door is welded shut and you are standing outside it.

If you exposed this address to the internet, take this seriously.

Three rules:

1. Do not uninstall it and do not disable it. Concretely: don't run dsh plugin --profile web remove @lvxianchao/dsh-web-guard, don't drop the entry from dsh.profile.bundles in the profile's package.json, and don't add disabled: true to it in cordis.patch.yml.