Prefectural

DSH’s plugin-based approach is suitable for integrating extension capabilities as independent packages. For scenarios where the WebUI needs to be exposed to teams, reverse proxies, or LAN access, a common question arises: can an unauthenticated browser still read page resources, call interfaces, or establish real-time connections?

dsh-webui-auth addresses this point by providing a persistent authentication plugin: create an account and password in the settings first, and then access to the WebUI requires logging in.

What Is This

dsh-webui-auth is a WebUI authentication plugin for DeepSeek Harness (DSH), licensed under MIT, with zero dependencies.

Its functionality is focused: it adds a login gate in front of the DSH WebUI. After creating an account and password, unauthenticated browsers cannot load WebUI resources, call interfaces, or establish real-time connections. Authentication is enforced at the HTTP/transport layer.

Core Capabilities

Here are the capabilities it currently offers.

  • Four-layer protection: Covers WebUI resources, plugin bundles, /api RPC interfaces, and WebSocket.
  • No modification to DSH core package source code: Achieved by runtime wrapping of webServer routes.
  • Fail-closed: Expects to refuse enabling authentication when routes are missing or wrapping is incomplete.
  • Session persistence: Server sessions are written to sessions.jsonl, carried by HttpOnly; SameSite=Lax cookies.
  • Credential storage: Passwords are stored as scrypt hashes in dsh-webui-auth.json, with no plaintext written to disk.
  • Login rate limiting: Login failures are rate-limited per client IP, with a maximum of 5 attempts per minute.
  • Audit logs: Security events are appended to audit.jsonl, with client IP anonymized using HMAC-SHA256.
  • First-time initialization: Requires a setup token generated at each startup.
  • Security headers: The login page and API responses include strict CSP, nosniff, DENY, no-referrer, noindex, and no-store.
  • Appearance: The login page and settings page follow the DSH built-in appearance settings.
  • Zero dependencies.

Installation and Enabling

First, run the installation command:

npx @deepseek-ai/dsh plugin --profile web add dsh-webui-auth

After installation, restart DSH for it to take effect.

On first enablement, open the WebUI’s “Settings → Authentication” or visit:

/dsh-webui-auth/login

Then enter the setup token printed in the startup log to create an account and password.

After enabling:

  1. Unauthenticated access to any path will redirect to the login page.
  2. After logging in, sessions are免登录 based on session validity, defaulting to 12 hours.
  3. Modifying, disabling, or logging out requires the current password.
  4. Changing the password will revoke all other active sessions.

If you forget the password, delete the dsh-webui-auth.json file in the data directory. Authentication will automatically disable within 1 minute at most, after which you can use the new setup token to recreate the account.

Audit and Data Files

Audit logs are appended to audit.jsonl. You can view them via CLI:

node index.js audit --limit 50

The data directory varies by installation method:

  • npm / GitHub / tarball installation: The plugin package is located inside node_modules, and the data directory is .dsh-webui-auth/ in the parent directory of node_modules.
  • Local link / source installation: The data directory is the plugin source directory.
  • Fallback directory: $DSH_HOME/dsh-webui-auth/.

When upgrading from 0.3.x, runtime data is not automatically migrated. You need to manually copy the following files:

dsh-webui-auth.json
sessions.jsonl
audit-hmac-key
audit.jsonl

Usage Notes and Boundaries

It is best to confirm the following boundaries before installation and deployment.

  • The plugin runs with the current dsh process permissions. You should review the source code and license before installation.
  • WebSocket upgrades are still subject to the core isTrustedApiRequest restrictions. For reverse proxy or LAN deployments, you need to add the external domain to client-connection.trustedHosts.
  • There is an unprotected window of up to 10 seconds between runtime route wrapping and the next hot reload rescan.
  • When the reverse proxy and DSH are not on the same machine, proxy headers are not trusted, and rate limiting will aggregate by proxy IP.
  • IP anonymization in audit logs cannot prevent local attackers with file access privileges.
  • The threat model is browser/network clients. Local processes that can directly read or write the host process memory or files are not within the scope of protection.
  • SHA-256 credentials from 0.1.x are no longer verifiable from 0.2.0. You need to delete the credential file and recreate the account.

Applicable Scenarios

dsh-webui-auth is suitable for controlled access scenarios where a login gate needs to be added to the DSH WebUI: sessions can be persisted after initial account creation, authentication covers resources, interfaces, and WebSocket, audit logs can be viewed locally, and deployment does not require modifying the DSH core source code.

GitHub repository:

https://github.com/Yuuz12/dsh-webui-auth