Introduction

DSH supports extending the web profile via plugins. When the DeepSeek Harness Web GUI needs to provide external access, HTTP routes and WebSocket / HTTP upgrade paths require clear authentication boundaries. dsh-web-auth is a DSH plugin used to complete login, session, and cookie control before requests reach the application routes.

What is it

dsh-web-auth, with the npm package name @summersec/dsh-web-auth, is the transport-level authentication gate for the DeepSeek Harness Web GUI. It disables the default webserver and inserts an auth-gated webServer service, requiring subsequent Web GUI access to go through authentication first.

The repository is located at https://github.com/SummerSec/dsh-web-auth and the license is MIT.

Core Features

  • Authenticate HTTP routes and WebSocket / HTTP upgrade paths.
  • The default auth mode is always, including 127.0.0.1.
  • Optional non-loopback mode: skips authentication only when bound to loopback.
  • Uses scrypt password hashes in the scrypt$N$r$p$salt$key format.
  • Sessions are saved as 32-byte random tokens, using an in-memory store, with a sliding TTL.
  • Sets HttpOnly and SameSite=Strict cookies, with optional Secure.
  • Provides per-client-IP login attempt limiting and returns Retry-After.
  • Includes a built-in /auth/login page, supporting light/dark themes, as well as form or JSON body.
  • Applies origin checks, open-redirect sanitization, CSP, and frame denial to auth responses.
  • Disables the default webserver and inserts an auth-gated webServer service.

Installation and Usage

The following conditions must be met before enabling:

  • Node.js >= 22
  • DeepSeek Harness with the web profile
  • Peer dependency is @deepseek-ai/cordis ^4.0.1

The following is the basic PowerShell usage process. First, generate the password and scrypt hash offline, then export the hash to the current shell, and then install it to the web profile:

npx --yes @summersec/dsh-web-auth generate

$env:WEB_AUTH_PASSWORD_HASH = 'scrypt$...'
$env:WEB_AUTH_USERNAME = 'admin'

dsh plugin --profile web add @summersec/dsh-web-auth

dsh web

generate is used to generate passwords and hashes that can be saved to an offline location. For subsequent runs, WEB_AUTH_PASSWORD_HASH should be set preferentially; WEB_AUTH_PASSWORD is only suitable for temporary / lab use.

Do not put the password or hash into a shared or committed .env. If authentication is active, and neither passwordHash nor password is configured, the plugin will throw an error at startup.

Authentication Modes

The default mode is always, which requires login even if the service is bound to 127.0.0.1.

If you need to skip authentication for local loopback access while enabling authentication when bound to a non-loopback address, you can set non-loopback:

$env:WEB_AUTH_MODE = 'non-loopback'
dsh web --host 0.0.0.0

Please note: non-loopback only skips authentication when bound to loopback; once bound to a non-loopback address like 0.0.0.0, authentication takes effect.

Use Cases and Considerations

Suitable for the following situations:

  • DSH Web GUI needs to bind to a non-loopback address.
  • Want to protect both HTTP routes and WebSocket / HTTP upgrade paths.
  • Want to replace the default webserver via a DSH plugin rather than just adding a frontend login page.

Usage considerations:

  • The plugin runs with the permissions of the current DSH process. You should check the source code and license before installing.
  • Sessions are stored in memory; after expiration or DSH process restart, the client will receive an authentication_required response.
  • Prioritize using WEB_AUTH_PASSWORD_HASH to avoid putting plaintext passwords or hashes into shared / committed .env.
  • When authentication is active, if passwordHash or password is missing, startup will fail, preventing the inadvertent opening of an unauthenticated service.

Conclusion

dsh-web-auth places the login boundary at the transport layer of the DSH Web GUI, covering HTTP routes and WebSocket / HTTP upgrade paths, and provides session management, cookies, login rate limiting, and basic security response handling. Source code can be viewed at:

https://github.com/SummerSec/dsh-web-auth