dsh-plugin-auth

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