dsh-auth-gate

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.

Maintained until dsh ships authentication natively. dsh has no built-in login
yet, and this repository is how we close that gap: new dsh releases are tracked
(mount-point changes, supported version ranges, Linux/Windows CI), regressions are
fixed, and releases keep shipping. When official authentication lands we will publish
the migration path and keep supporting the dsh versions still in use, so nobody is left
on an abandoned fork.

Contents

• What it does
• What it does not do
• Quick start
• See it in action
• Configuration
• Command-line tool
• Admin tools: list users and reset a password
• Bundled configuration skill
• Troubleshooting
• Deployment
• Authenticated local proxy (optional)
• Requirements
• Notes & limitations
• Development
• License

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). The one exception is
  GET /manifest.webmanifest: browsers fetch the Web App Manifest without
  credentials, so that exact path is public (name / icons / display mode only).
• 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.
• Admin tools. In password mode an administrator can list users and reset another user's
  password, either from the Account security section of the Settings panel or over HTTP
  (GET /auth/users, POST /auth/users/password); a reset revokes that user's sessions and
  forces a new password at their next sign-in before they can reach anything else. Only an
  administrator on a full session sees the panel block, and the admin plane refuses to reset your
  own account (use the self-service form above it, or the CLI when you have forgotten your
  password).
• Optional two-factor authentication (TOTP). In password mode, a user with
  a TOTP secret added to their account signs in with password plus a 6-digit
  code from an authenticator app (RFC 6238, configurable off/optional/required).
• 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 wrong username or password makes the login card
  re-render with an inline Invalid username or password.: the username is kept, the
  password must be retyped. A lockout (HTTP 429 + retry-after) shows the same card
  with the retry seconds and a message saying the lockout applies to "this network".
  The number of remaining attempts is deliberately never shown, and with JavaScript a
  page refresh no longer consumes another failed attempt.

What it does not do

Honest boundaries, so you can gauge the risk before installing (the full list with
mechanisms is in docs/deployed/known-limitations.md):

• Not server-level security. Keep the OS user locked down and the config files
  private (auth/users.yaml and .credentials.yaml are created 0600); this plugin
  guards dsh's web surface only.
• Not every way of changing a password evicts sessions. dsh-auth user disable
  blocks future logins and revokes the sessions that user was issued (within
  revokeSweepMs, 5 s by default); the Settings panel's self-service change revokes every
  session of that user, and so does an administrator's reset of someone else's password;
  the CLI's dsh-auth user passwd only rewrites the stored hash.
• Not a replacement for HTTPS. With cookieSecure: true you must serve the site
  over https.
• Not a full identity provider. No OAuth/OIDC, no self-registration, no e-mail
  reset; users are created and managed by an administrator through the CLI.

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.
#    `dsh plugin add` installs the plugin into the profile's node_modules
#    ($DSH_HOME/profiles/web, default ~/.dsh/...) — the CLI is NOT added to your
#    PATH, so call it through the profile. `dsh plugin` already requires pnpm:
printf '%s\n' 'choose-a-strong-password' | \
  pnpm --dir "$DSH_HOME/profiles/web" exec 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

Every screenshot below uses the English UI, and both READMEs share the same set of
images (the plugin's own panels follow the GUI language; the server-rendered pages are
English in every locale).

Visitors without a session are sent to the login page (the card is rendered by the plugin
server-side in English, so this shot is the same in every locale):

When TOTP is enabled for your account, signing in continues with a second step — a
6-digit code from your authenticator app (password first, then the code):

After signing in, they land on your instance:

On dsh 0.1.2-alpha+ (which guards pages with a launch token), signing in
auto-bridges the token gate: the login redirect takes a short relative
/?token=… hop that sets the dsh cookie, then lands on / (details in
docs/implemented/impl-launch-token-bridge.md).

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.

A signed-in user can also change their own password from the Account security
section of the Settings panel (password mode only): current password, the new
password typed twice, and a TOTP code whenever the account has a secret. The panel
title carries the plugin's own mark (a shield + keyhole outlined at 16px).

The mark next to the section name in the nav is the plugin's too: the host has no
per-section icon option yet (settings.section carries only id/order/label,
and nav icons come from the host's hard-coded navIcon(id), which falls back to
the default gear for third-party sections), so a temporary DOM stopgap replaces
our own row and nothing else (if it cannot find the row it silently falls back to
the gear). Once dsh offers an icon option, the stopgap and its code are removed
(see ADR D24.1 for the migration conditions).

The panel posts to POST /auth/password (current / password / code,
form-urlencoded) and, on success, every session of that user is revoked,
including the one making the change. The client immediately sends the device
back to the login page with a reason, and the card explains why (the success panel
only stays on screen when the environment refuses to navigate; its "Sign in again"
button is then the fallback way out):

Passwords must be at least 14 characters, contain four character classes and
differ from the current one. With TOTP on, a code already spent in the current
30-second window is rejected as a replay: wait for the next code.

An administrator on a full session also gets a user management block below that form (the
panel screenshot above shows it): a read-only list (name, role, a mutually exclusive
disabled / must-change-password / normal badge and a two-factor badge, with "You" on their own
row) plus a reset form for another user. A reset forces the target to pick a new password at the
next sign-in and revokes every session that user had, while the acting administrator's own
session is untouched. When the administrator's own account has TOTP enabled, the reset asks for a
current code as well. The block renders only for role === "admin" on a full (not forced-change)
session, and a non-admin client never requests the user list at all. Resetting your own
account is not possible: the server refuses it and the dropdown excludes you, so an administrator
who has forgotten their own password must reset it on the server with
dsh-auth user passwd <name>.

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"
    totp: "optional" # "off" (default), "optional", or "required"
    cookieSecure: true # keep true when you use https

Option	Default	What it does
mode	"token"	"password" = username/password login; "token" = one shared secret
totp	"off"	Password mode only. "optional": users with a TOTP secret sign in with password + code; "required": all users must have a secret (users without one get the uniform 401 at the password stage, same body as a wrong password — anti-enumeration)
sessionTtl	604800	How long a login lasts (seconds) before you must sign in again
cookieName	dsh_auth	Name of the session cookie (rarely needs changing)
tokenRef	"DSH_AUTH_TOKEN"	Token mode only: which environment variable holds the shared secret
cookieSecure	true	Set to false only if you are testing over plain http
usersFile	""	Password mode: where your user list lives. Defaults to $DSH_HOME/auth/users.yaml
publicHost	""	Host rendered in the login page identity block (the anti-phishing "which instance is this" line). Empty = use the request Host header. Set it when a reverse proxy rewrites Host (e.g. Caddy header_up Host 127.0.0.1:3080), otherwise the card shows a loopback address instead of your public domain. With D25 it also lets the admin and password-change endpoints validate an Origin header: with publicHost empty they accept only Sec-Fetch-Site: same-origin, so production deployments should set it, and write it with the scheme (https://host) when TLS terminates at a reverse proxy
revokeSweepMs	5000	Password mode: how fast (ms) a user disabled with dsh-auth user disable loses already issued sessions. 0 = never sweep (disabling only blocks new logins)
clientIpHeader	""	Header carrying the real client address for rate limiting (x-forwarded-for, or cf-connecting-ip behind Cloudflare). Empty = read no header at all. Only read when the request's peer is inside trustedProxyCidrs; without it a same-host reverse proxy makes every client share one lockout bucket (issue #74)
trustedProxyCidrs	["127.0.0.0/8", "::1/128"]	Which peers may supply clientIpHeader (default: loopback only; a peer without an address, i.e. a Unix socket, counts as local). Invalid entries are dropped with an error log and trust narrows to loopback, an explicit [] means "trust nobody", and 0.0.0.0/0 / ::/0 are always rejected
logoutOrder	1000	Slot order of the "Sign out" button in Settings → General (higher = lower on the page). Raise it if another plugin registers a bigger order

To enable TOTP for a user, run dsh-auth user totp enable <name> and add the
printed secret (or scan the otpauth:// URI) into an authenticator app (Google
Authenticator, 1Password, etc.). The code changes every 30 seconds; a code from
the previous or next window is also accepted (drift tolerance).

Command-line tool

dsh-auth manages users from the shell:

dsh-auth user add admin --password-stdin   # add a user (--admin creates an administrator)
dsh-auth user list                          # list users
dsh-auth user passwd admin                  # change a password (read twice; there is no --password flag)
dsh-auth user role admin user               # grant/revoke the admin role: user role <name> <admin|user>
dsh-auth user disable admin                 # block future logins + revoke that user's live sessions
dsh-auth user enable admin                  # re-enable a disabled user (a reset alone does not let them in)
dsh-auth user totp enable admin             # generate a TOTP secret (prints an otpauth:// URI)
dsh-auth user totp disable admin            # remove the TOTP secret

dsh-auth is directly on your PATH when the package is installed globally. After
dsh plugin add the binary lives inside the profile and must be called through it -
see Quick start.

dsh-auth user passwd only rewrites the stored hash: it does not revoke that user's
live sessions. Use the Settings panel change when sessions must be evicted right away;
dsh-auth user disable also blocks future logins, but the sessions already issued are
dropped by the periodic sweep (revokeSweepMs, ~5 s by default).

Admin tools: list users and reset a password

In password mode an administrator can list users and reset another user's password from the
Account security section of the Settings panel, or over HTTP for scripts
(/auth/users is a field-whitelisted list, /auth/users/password is the reset). Both routes
behave identically, and every authenticated state-changing POST is checked against its Origin,
so a script must send one (there is no exemption):

# List users (admin session cookie in jar).
curl -s -H "Origin: https://dsh.example.com" -b jar https://dsh.example.com/auth/users

# Reset someone's password. `code` is required only when YOUR own account has TOTP enabled.
curl -s -H "Origin: https://dsh.example.com" -b jar \
  -d "target=alice&password=<new>&confirm=<new>&code=<your-totp>" \
  https://dsh.example.com/auth/users/password

A request without an Origin, or with one that does not match the instance, is rejected with
403 (fail-closed); the only other accepted signal is the browser's own
Sec-Fetch-Site: same-origin. Configure publicHost when a reverse proxy rewrites Host:
without it the server cannot derive its own origin, and the change/reset endpoints then accept
Sec-Fetch-Site: same-origin alone, which the commands above do not send. Write it with the
scheme (https://dsh.example.com) when TLS terminates at the proxy: with a bare host:port the
scheme is inferred from whether the incoming connection itself is TLS, so an http hop from the
proxy makes script Origin checks fail (browsers are unaffected).

The reset marks the target account as "must change password" and revokes every session that
user had (the acting admin's own session is untouched). At the target's next sign-in they get a
restricted session (15 minutes, never renewed): it can reach only the plugin's own password
form at GET /auth/password and nothing else, not even the host UI. That form is
server-rendered and works without JavaScript (no external assets, no script); submitting it
still requires the current password, and success clears the mark and signs the user out so they
can sign in normally. A reset does not touch the target's TOTP secret, and resetting a
disabled account does not let it sign in: the login path rejects disabled users, so run
dsh-auth user enable <name> first. The full contract is in
D25.

Bundled configuration skill

The package ships a configuration quick-reference skill at
.agents/skills/dsh-auth-gate-config/ (this page). Install it into the
user-level dsh skill root so agents on the deployment side can answer
"what configuration does auth-gate support?" directly:

pnpm --dir "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>" exec dsh-auth skill install [--force]

It copies the skill to $DSH_HOME/skills/dsh-auth-gate-config/, which
dsh's skill discovery picks up automatically. Re-running without
--force keeps any local edits to the skill; use --force to refresh it
from the package.

The skill is a user-only skill (disable-model-invocation: true in its
frontmatter): it stays out of the model's auto-invocable skill catalog so it is
not injected into every agent turn, and you open it explicitly from the skill
panel whenever you need the config reference (the UI marks it user-only).
If you prefer the agent to answer configuration questions automatically,
remove that frontmatter field after installation.

Troubleshooting

dsh-auth: command not found

dsh plugin --profile web add dsh-auth-gate installs the package into the
profile's node_modules ($DSH_HOME/profiles/web/node_modules/dsh-auth-gate,
default ~/.dsh/...), but nothing is added to your shell's PATH, so the CLI
binary is not callable by name. This only affects the CLI — the plugin itself
runs fine. Pick one:

1. Call it through the profile (recommended). dsh plugin already requires
   pnpm, so the CLI resolves from the same place the plugin lives:

   pnpm --dir "${DSH_HOME:-$HOME/.dsh}/profiles/web" exec dsh-auth user add admin --password-stdin
   pnpm --dir "${DSH_HOME:-$HOME/.dsh}/profiles/web" exec dsh-auth user list
   

   Optionally, once per shell session:

   alias dsh-auth='pnpm --dir "${DSH_HOME:-$HOME/.dsh}/profiles/web" exec dsh-auth'
   

2. Direct node invocation (no pnpm needed at runtime):

   node "$DSH_HOME/profiles/web/node_modules/dsh-auth-gate/lib/cli.js" user add admin --password-stdin
   

3. Install the package globally, then dsh-auth is on your PATH:

   npm install -g dsh-auth-gate
   dsh-auth user add admin --password-stdin
   

Whichever way you call it, the CLI manages the same shared user list
($DSH_HOME/auth/users.yaml, fallback ~/.dsh/auth/users.yaml) that the plugin
reads — the global copy is just a launcher.

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/deployed/deployment.md — ops checklist, acceptance steps
  (A–I) and troubleshooting. Chinese version:
  docs/deployed/deployment_zh.md.

Authenticated local proxy (optional)

⚠️ Known limitation (unaffected by any auth-gate release): dsh's settings pages
("Settings -> Models", etc.) are editable only when the page origin is loopback
(localhost/127.x). This is a dsh client-side boundary (isLoopback), orthogonal to
authentication — on a domain page the settings dialog reports
"settings are unavailable in this browser" and providers/credentials cannot be edited;
upgrading dsh-auth-gate does not change that. To edit configuration, use this local proxy,
or open http://127.0.0.1:3080 on the server itself. Chatting and model selection on the
domain page are unaffected.

After the semi-shell fixed the server-side /api fence, dsh's client still requires
"page origin must be loopback"; the local proxy provides a loopback page entry on the user's
machine, used together with auth-gate so remote config editing stays authenticated
end-to-end, without touching dsh sources. Full design: docs/deployed/local-proxy.md
(Chinese: docs/deployed/local-proxy_zh.md).

• Zero-dependency Node bin (dsh-auth-proxy): strictly bound to 127.0.0.1, stateless
  pass-through for pages/API, events.mux/events.host WebSocket tunneling, and
  stripping of the Secure attribute from Set-Cookie (Safari fallback).
• Authentication reuses auth-gate (password and token modes): the login page and session
  cookies pass through untouched.
• Security boundary (deny-list, Phase 2.1): combined with --mark-proxy, the server-side
  guard answers 403 for marked requests hitting host.pickDirectory/host.openPath/
  settings.openDocument/llm.discoverModels, so a remote authenticated user cannot reach
  the host's native capabilities; unmarked traffic behaves exactly as if the proxy were not
  deployed.

dsh-auth-proxy --listen 127.0.0.1:8443 --target https://your-domain.example --mark-proxy
# Open http://127.0.0.1:8443 in the browser -> log in -> "Settings -> Models" is editable

systemd example: deploy/systemd/dsh-auth-proxy.service.example.

Requirements

• Node ≥ 22.19 and pnpm on the server.
• dsh 0.1.x / 0.2.x (declared as engines.dsh: ^0.1.0-rc.6 || ^0.1.5-rc.2 || ^0.1.7-alpha.1 || ^0.2.0-rc.1). Runtime-verified against 0.1.5-rc.2 and 0.1.7-rc.2 (production, in that
  order), plus 0.1.7-alpha.1 and 0.2.0-rc.2 (isolated instances); the full test
  suite runs on the 0.2.0-rc.2 host packages. The 0.1.6-*
  prereleases are not enumerated because no plugin version was verified against
  them (stable 0.1.6 is covered by ^0.1.5-rc.2). The plugin runs on the
  host's own @deepseek-ai/dsh-storage-domain and @deepseek-ai/cordis
  copies — both are peer dependencies, never bundled — so a profile booted from
  the dsh base bundle already provides them. dsh 0.2.0-rc.2 (already on the next line) refuses to install, and at boot silently
  skips, plugins whose @deepseek-ai/dsh* peer ranges do not cover the running host
  version; that check reads peers only - engines.dsh is not consulted - and a plugin
  declaring no such peer is not checked at all. The 0.2.0-rc.1 alternative is
  therefore declared in both engines.dsh and the storage-domain peer.
• 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).

Notes & limitations

The short list; the full version, including the mechanisms and the ADRs behind them,
is in docs/deployed/known-limitations.md.

• Disabling a user only stops new logins; sessions already issued are revoked by the
  periodic sweep (revokeSweepMs, 5 s by default - with 0 they stay valid until they
  expire).
• Login rate limiting and the TOTP replay guard reset when the server restarts.
• Behind a reverse proxy, set clientIpHeader (and trustedProxyCidrs): otherwise all
  clients share one lockout bucket, and login plus the self-service change each have their
  own, so both are affected.
• A password change reports success even if revoking the old sessions fails; the failure is
  logged at error level and the old cookie stays valid until its session TTL.
• The Origin check covers the two authenticated state-changing POSTs only: POST /auth/login
  keeps SameSite=Lax as its only cross-site defence, and a reset whose session revocation
  fails still answers 200 with sessionsRevoked:false (plus an error log), so a stale cookie
  can survive until the session TTL expires.
• A reset never touches the target's TOTP secret, and resetting a disabled account does not let
  it sign in (the login path rejects disabled users), so run dsh-auth user enable <name> first.
• An administrator without TOTP makes the admin endpoints single-factor; enable TOTP for
  administrators in production.
• The plugin protects dsh's web surface only. Keep the OS user and the config files
  private.

Development

Built on the engineering conventions of
dsh-plugin-framework: barrel-only
cross-slice imports, the npm run verify gate chain, and decision records. verify
runs format / lint / no-emdash / slice / lock / decisions / docs / readme-parity /
type-check / coverage 80% / build / bundle; tests, build and the release flow are
documented in docs/specs/development.md.

License

MIT