dsh-plugin-auth

Enterprise username/password authentication gate for the dsh (DeepSeek Harness) Web UI.

Out-of-tree plugin — no core changes. Once installed into the web profile, every page, API route, /plugins asset, and WebSocket upgrade requires a logged-in session. Unauthenticated navigations are redirected to a self-contained login page; unauthenticated API/XHR calls get 401. The login page uses Simplified Chinese (zh-CN) and follows the operating system's light/dark preference with the same palette and control geometry as the dsh Web UI; CLI and JSON API output remain compatible.

The stock Web UI ships only a DNS-rebinding "browser trust fence" (isTrustedApiRequest), which the source explicitly notes is not an authentication layer. This plugin adds the missing gate.

How it works

The plugin's default export is class AuthWebServer extends WebServer. A bundle composition patch (cordis.patch.yml) disables the stock webserver row and inserts a row that re-provides the webServer service from this subclass — so the plugin becomes the sole provider and every consumer registration flows through it:

• register / registerFallback / registerUpgrade are overridden to wrap each handler in an auth gate, then delegate to super.*. One choke point covers the SPA fallback, /api, /plugins, upgrades, and any route added later.
• The plugin's own /__auth/* surface (login page, login/logout, status) is registered with super.register in the constructor, so it stays ungated and reachable while logged out.
• The subclass truly re-provides webServer (super(ctx, 'webServer') is inherited) and the insert row keeps inject: [webStartup] and the {host, port} config, so downstream web-runtime and connection rows still resolve.

Requirements

• Node ^22.19 || >=24 (matches dsh).
• A dsh checkout/profile where the peers resolve: @deepseek-ai/cordis and @deepseek-ai/dsh-host-webserver. Both are in the web profile's dependency closure already, and the profile's module fallback (healProfilesModuleFallback) links them next to the plugin.
• The plugin deliberately does not declare these as peerDependencies. It subclasses the harness's own WebServer (the webServer-service provider) and must share the harness's exact WebServer and cordis module instances. Declaring "*" peers makes pnpm fetch a stale published copy from the registry, install it inside the plugin's dependency closure, and shadow the profile fallback — the subclass then extends the wrong build (an older one that provides httpServer, not webServer, bound to a different cordis), so boot fails with every web consumer "pending (waiting for service: webServer)". Leaving the peers undeclared lets Node's parent-walk resolve them to the fallback — the same instances the loader uses.

Install from npm

The public npm package is the recommended installation path once a release is published. dsh forwards the package spec to pnpm and automatically adds the package to the profile layer list because this package declares dsh.bundle.

Use the command form that matches how dsh is installed:

• Installed dsh CLI (the dsh executable is on PATH): use dsh ....
• Source checkout (this repository): use pnpm dsh ... from the harness root.

# install the exact release into the web profile (installed CLI)
dsh plugin --profile web add -w dsh-plugin-auth@0.1.3

# from a deepseek-harness source checkout, run the equivalent command instead:
pnpm dsh plugin --profile web add -w dsh-plugin-auth@0.1.3

# create the first admin before first boot (writes $DSH_HOME/auth/users.json)
dsh plugin --profile web exec dsh-auth add-user admin
pnpm dsh plugin --profile web exec dsh-auth add-user admin  # source checkout

# confirm the auth-webserver layer resolved and the stock webserver is disabled
dsh --profile web --dump-config
pnpm dsh --profile web --dump-config  # source checkout

dsh-plugin-auth deliberately has no peerDependencies: the dsh profile supplies the exact @deepseek-ai/cordis and @deepseek-ai/dsh-host-webserver instances required by the subclass.

Install from a tarball

Use a tarball for local development or when the package is not available from a registry. The tarball's realpath lands inside the profile tree, which lets its peer imports resolve through the profile module fallback; a link: to an external directory would put the realpath outside the tree and fail to resolve:

# from the plugin directory
npm pack                       # → dsh-plugin-auth-<version>.tgz

# create the first admin BEFORE first boot (writes $DSH_HOME/auth/users.json)
node bin/dsh-auth.js add-user admin

# install into the web profile.
# -w is REQUIRED: a dsh profile is a pnpm workspace root (packages: - .), and
# adding a dependency to a workspace root without -w fails ERR_PNPM_ADDING_TO_ROOT.
pnpm dsh plugin --profile web add -w ./dsh-plugin-auth-<version>.tgz

Pre-flight (go / no-go)

Before starting the server, confirm the composition resolved and the peer imports work:

dsh --profile web --dump-config

The dump must show the webserver row with disabled: true and exactly one inserted auth-webserver row — with no "module resolution failed" errors. A resolution failure here fails loud; fix the install (use a tarball, not a directory link) before booting.

Start

pnpm dsh web            # binds 127.0.0.1:3080 by default
pnpm dsh web --port 8080  # if 3080 is taken (e.g. a stale dsh still running)

Open http://127.0.0.1:3080 → you are redirected to /__auth/login. After signing in you reach the app; /api and /plugins work as normal.

If boot fails with EADDRINUSE ... 127.0.0.1:3080, another process (often a stale dsh web from a previous run) already holds the port. Stop it, or start on a different --port. This is a distinct failure from the composition error below — it means the gate did activate and tried to bind.

CLI: dsh-auth

Credentials live in $DSH_HOME/auth/users.json (atomic write, mode 0600 where POSIX modes apply) and are managed offline — never through the Web settings UI. Passwords are read from the TTY with echo masked, or from bootstrap env vars for non-interactive provisioning.

dsh-auth add-user <username>   Create a user (prompts for a password).
dsh-auth passwd <username>     Change a user's password.
dsh-auth list                  List users (with disabled flag + last-updated).
dsh-auth remove <username>     Delete a user.
dsh-auth disable <username>    Disable a user (keeps the record; blocks login).
dsh-auth enable <username>     Re-enable a disabled user.

Environment:

• DSH_HOME — auth data root (default ~/.dsh); data in $DSH_HOME/auth.
• DSH_AUTH_BOOTSTRAP_USER — username for non-interactive add-user.
• DSH_AUTH_BOOTSTRAP_PASSWORD — password for non-interactive add-user / passwd.

Passwords must be at least 12 characters and include at least 3 of: lowercase, uppercase, digit, symbol.

Configuration ($DSH_HOME/auth/config.json, optional)

All keys are optional; out-of-range or wrong-typed values silently fall back to the secure default, so a malformed file can never weaken the gate past sane bounds.

Key	Default	Meaning
sessionAbsoluteTtlMs	43200000 (12h)	Hard session lifetime cap.
sessionIdleTtlMs	7200000 (2h)	Sliding idle window.
sweepIntervalMs	300000 (5m)	Background expired-session sweep cadence.
lockoutThreshold	5	Consecutive failures (per username+IP) before lockout.
lockoutBaseMs	30000	First lockout duration.
lockoutMaxMs	900000 (15m)	Exponential-backoff cap.
lockoutWindowMs	900000 (15m)	Idle time after which the failure counter resets.
minPasswordLength	12	Minimum password length (floor 8).
secure	false	true behind TLS: sets Secure + __Host- cookie, forces Path=/.
sameSite	"Strict"	Cookie SameSite (Strict or Lax).
cookiePath	"/"	Cookie Path.
trustedOrigins	[]	Extra Origin values accepted on state-changing POSTs.
scrypt	{N:16384,r:8,p:1,keylen:64,maxmem:64MiB}	Password hashing cost.

Behind a TLS reverse proxy, set "secure": true so the session cookie gets Secure and the __Host- prefix. On plain loopback HTTP the cookie cannot be Secure (browsers would drop it).

Security notes

• Passwords: scrypt with a per-user random salt, self-describing cost params, constant-time compare. Unknown/disabled users are verified against a fixed dummy record so there is no timing/enumeration oracle.
• Sessions: 256-bit random tokens, HttpOnly; SameSite=Strict; Path=/ cookies, absolute + sliding expiry, login-time token rotation (anti-fixation), logout revocation, background sweep.
• Brute force: per-(username, IP) lockout with exponential backoff; a legit user on another IP is unaffected by an attacker's failures.
• CSRF: state-changing POSTs require a same-origin Origin/Referer (or a trustedOrigins entry); default-deny when both are absent. This backs up SameSite=Strict.
• Open redirect: the post-login next target is reduced to a safe single-slash local path.
• Audit: login success/failure/lockout/logout are logged via ctx.logger with username + IP (never the password).

Scope & tradeoffs (by design)

• Local username/password only — no SSO, no 2FA.
• Sessions are in-memory: a dsh restart requires everyone to log in again.
• No separate CSRF token — SameSite=Strict + Origin check is the chosen defense.
• src/paths.js is self-contained (it re-implements the $DSH_HOME → ~/.dsh resolution rather than importing @deepseek-ai/dsh-home-paths). This keeps the offline CLI working without the harness on the module path and removes that package from the runtime peer set; only @deepseek-ai/dsh-host-webserver is imported at runtime.

Composition ordering caveat

This bundle disables the stock webserver row. Any later composition layer (the profile's own cordis.patch.yml, $DSH_HOME/cordis.patch.yml, or --patch) that flips webserver back to disabled: false would create two providers of webServer and boot fails loud (duplicate service), not silently. Don't re-enable the stock row while this plugin is installed.

Development / tests

node --test

The unit suites (policy, passwords, sessions, lockout, gate, login-page, users) are pure and run standalone. tests/integration.test.js needs the runtime peers (@deepseek-ai/cordis, @deepseek-ai/dsh-host-webserver); when they are not installed it skips with a reason. Run it inside a built harness checkout to exercise the real subclass over HTTP.

License

MIT