dsh-rgate
中文 | English
A remote access login gate for the DeepSeek Harness Web UI. Put a password wall in front of the whole browser surface: anonymous visitors on a public (non-loopback) address see only a login page, and every /api RPC is refused until they authenticate.
Why
The Harness's built-in browser-trust fence (trustedHosts) is a DNS-rebinding defense, explicitly not authentication. Anyone whose Host header passes the fence can use the Web UI. This plugin adds the missing authentication layer for self-hosted deployments: IP scanners hit a login page instead of your agent.
What it does
- Full-page login wall — a gate script is injected into every
index.html (via webServer.tapIndex); unauthenticated non-loopback visitors are redirected to /rgate-login, a self-contained login page.
- Complete
/api gating — modern Harness releases authenticate the /api RPC surface themselves (no credentials → 401), so rgate no longer proxies or shadows those routes. It registers only its own /api/remote-auth.* endpoints plus /rgate-login; loopback hosts pass straight through, and non-loopback visitors need a session cookie or the injected gate script redirects them to the login wall.
- Cookie sessions —
rgate_session, HttpOnly + SameSite=Strict, 7-day in-memory sessions; logout and password change invalidate all sessions.
- No more
?token= URLs — the stock harness (dsh-client-connection) only accepts the cookie minted by its process token: any address without ?token=<launchToken> returns 401, so every visit starts by hunting for that printed URL. After the login wall is passed, rgate also mints an HMAC-signed cookie in the same format (rgate_auth, key ~/.dsh/.rgate-signing.key) and patches the harness isAuthenticated to verify it and authorizeIndex to serve the index — so visiting the plain host lands on the login page, and ?token= is never needed again. /api still requires the signature, so anonymous requests stay 401.
- Login throttling — 5 failed attempts per client → exponential backoff (30s doubling, capped at 16 min). Behind Cloudflare Tunnel the client key is
Cf-Connecting-Ip (fallback X-Forwarded-For, then socket address), so one attacker cannot lock everyone out.
- Audit logging — login success/failure/lockout and password changes go to the harness log (journald) without passwords.
- Hashed password storage — scrypt (N=16384, r=8, p=1) with a random salt and constant-time comparison in
~/.dsh/remote-auth.json (mode 0600). Legacy plaintext files are migrated automatically. A forgotten password is recovered by deleting the file and restarting: the fresh password is printed once in the service log.
- Remote Access settings section — a
settings.section entry showing gate status, login/logout, and password change. Password display is hashed-only by design.
- Origin validation on login/logout/password endpoints (cross-site form posts are refused).
Install
From GitHub (plain ESM, no build step and no install scripts — nothing runs at install time):
dsh plugin --profile web add github:raomaiping-hash/dsh-rgate
Pin a commit sha for reproducibility: later pushes cannot silently change what runs on your machine (dsh plugin --profile web add github:raomaiping-hash/dsh-rgate#<commit-sha>).
From npm or a tarball:
dsh plugin --profile web add dsh-rgate # npm
dsh plugin --profile web add ./dsh-rgate-0.1.0.tgz # tarball
Then restart the web profile. The plugin prints [rgate] 门禁已启用 … (or [rgate] gate enabled …) when it activates, and creates ~/.dsh/remote-auth.json with a random password on first boot:
journalctl -u deepseek-harness | grep rgate
Configuration
There is no config file for the gate itself. Two behaviors are worth knowing:
- Loopback is always trusted.
127.0.0.1 / localhost / ::1 never see the wall — that is the admin path.
- All other Hosts require login (LAN, Tailscale, public domain alike). If you want a friction-free host, protect it upstream instead (see below).
The password file lives at $DSH_HOME/remote-auth.json (default ~/.dsh/remote-auth.json — the harness convention, beside settings.yaml):
| field | meaning |
|---|
version: 2 | scrypt-hashed storage |
salt, N, r, p, hash | scrypt parameters and derived key |
createdAt, updatedAt | bookkeeping |
HTTP endpoints added
| Endpoint | Method | Purpose |
|---|
/rgate-login | GET | Self-contained login page (redirects to / when already allowed) |
/api/remote-auth.login | POST {password} | Verify password, set session cookie |
/api/remote-auth.logout | POST | Drop session + clear cookie |
/api/remote-auth.status | GET | {configured, authenticated, loopback} |
/api/remote-auth.secret | GET | Loopback only: {mode, path, createdAt, updatedAt} — never the password |
/api/remote-auth.password | POST {current?, next} | Change password (authenticated session, or loopback + current password) |
Known limitations
- WebSocket event streams are not gated.
/api/events.mux and /api/events.host upgrades are owned by the shipped dsh-client-connection plugin; registering the same upgrade path throws, and pre-registering breaks boot. A fence-passing client can still open them and receive live session event frames. The robust fix is upstream: enable Cloudflare Access (Zero Trust) on your public domain, or put an authenticating reverse proxy (e.g. nginx auth_request) in front. That closes UI, API and WebSockets before traffic reaches the Harness.
- The
/api method table is not owned here. Harness-native /api authentication (no credentials → 401) covers new RPCs as they are added; rgate never shadows that table.
- Sessions are in-memory. A Harness restart signs everyone out (7-day cookie otherwise).
- Static assets are still served to unauthenticated visitors (they are public code); all data lives behind the API gate.
Threat model
The gate is an authentication layer for a single-password, personal/small-team deployment. It assumes the Harness process and its host filesystem are trusted; anyone who can read remote-auth.json or the process memory already owns the host. It is not a substitute for OS/network hygiene, HTTPS termination, or upstream access control on the public entry point.
Test
tests/smoke.mjs runs the plugin's real route handlers against a stubbed context in an isolated HOME (no real credentials touched):
node tests/smoke.mjs
License
MIT
Settings plane note
Harness 0.1.2-rc.2+ serves the settings plane (model providers, credentials,
preset authoring) to loopback pages only, pending a real authentication layer.
Since rgate is that layer, at every start it reapplies a one-line client patch
that lets logged-in remote browsers use settings normally; anonymous
visitors remain blocked by the wall. The anchor expression
(ctx.remote.$host.isLoopback ? "host" : "memory" in
@deepseek-ai/dsh-client-ui-settings/lib/client.js) was re-verified against
Harness 0.1.5-rc.2. The original file is backed up next to the target
(client.js.rgate-backup) and the patch reapplies automatically after each
Harness upgrade.
