dsh-auth-gate

English | 简体中文

A login door for your DeepSeek Harness (dsh) web instance. Put it in front of a public dsh deployment and nobody can reach your agents, your chat sessions, or your LLM credentials without signing in first.

What it does

• Everything needs a login. Every page, API call, and WebSocket connection is checked. Visitors without a valid session are sent to a simple login page (or rejected with 401 for API/script requests).

• Two ways to sign in (pick one in the configuration):

  • Password (recommended): each admin gets a username and password.
  • Token: one shared secret token for the whole instance.

• Works for browsers and scripts. Browsers use the login page; scripts and curl can pass Authorization: Bearer <token> and skip the page entirely.

• Safe by default. Passwords are stored hashed, logins are rate-limited (repeated wrong attempts temporarily lock the address), session cookies are secure, and any missing or broken configuration blocks access instead of silently opening the door.

• A small command-line tool for managing users:

  dsh-auth user add admin --password-stdin   # add a user
  dsh-auth user list                          # list users
  dsh-auth user disable admin                 # block a user's future logins
  

Quick start

# 1. Install the plugin from npm into your dsh profile.
#    Since 0.4.1 the package declares a `dsh.bundle` manifest, so `dsh plugin add`
#    also registers the mount (dsh.profile.bundles) automatically:
dsh plugin --profile web add dsh-auth-gate

# 2. Create an admin account
printf '%s\n' 'choose-a-strong-password' | dsh-auth user add admin --password-stdin

# 3. Turn on password login: override the plugin config in $DSH_HOME/cordis.patch.yml
#    (a ready-to-use config-override template ships in deploy/cordis.patch.yml;
#    see Configuration below — the mount itself needs no manual patch row)

# 4. Restart dsh. Open your site — you will be asked to sign in.

See it in action

Visitors without a session are sent to the login page:

After signing in, they land on your instance:

A prominent Sign out / 退出登录 button sits inside the Settings panel (the Settings → General page, below the last preference row). It's a centered, danger-styled filled button (16px door icon + localized label, theme tokens for light/dark), and its label follows the GUI language through the same locale mechanism the Settings language switch uses. Clicking it runs the same native POST /auth/logout?next=/ flow as before.

Configuration

The bundle mount (id dsh-auth-gate, inserted by dsh plugin add) uses the default config: mode: "token" backed by the DSH_AUTH_TOKEN environment variable. To change it, override the config in $DSH_HOME/cordis.patch.yml (or the profile's cordis.patch.yml — a ready-to-use override template ships in deploy/cordis.patch.yml). The override targets the mounted row by id (no insert — adding one would double-mount the plugin):

- id: dsh-auth-gate
  config:
    mode: "password" # "password" (recommended) or "token"
    cookieSecure: true # keep true when you use https

Deployment

• Reverse-proxy deployment guide — Caddy/nginx setups, the browser-trust fence gotcha (Settings-page 403s behind a proxy, and why auth alone doesn't fix them), and the recommended semi-shell topology.
• docs/deployment.md — ops checklist, acceptance steps (A–I) and troubleshooting. Chinese version: docs/deployment_zh.md.

Requirements

• Node ≥ 22.19 and pnpm on the server.
• The dsh web profile running (dsh --profile web).
• If cookieSecure is true, your site must be served over https (browsers refuse secure cookies on plain http).

License

MIT

Notes & limitations

• Disabling a user only stops new logins; already-signed-in sessions stay valid until they expire.
• Login rate limiting resets when the server restarts.
• Behind a reverse proxy, rate limiting counts by the proxy's address.
• Sign out from the GUI: a prominent "Sign out / 退出登录" button sits in the Settings panel (Settings → General, bottom) — client half, requires the web app's client bundle (dsh 0.1.0-rc.6+); the direct /auth/logout?next=/ URL always works as a fallback.
• The plugin only protects dsh's web surface. It is not a replacement for server-level security: keep the server OS user locked down and the config files private (.credentials.yaml and auth/users.yaml are created with 0600 permissions).