Introduction

When deploying DeepSeek Harness (DSH) locally, the Web port usually needs to be exposed directly. To add an access-control layer without modifying DSH core configuration or introducing an external reverse proxy (such as Nginx), you can integrate a plugin into the DSH Web process. The dsh-web-pass plugin is designed for this purpose: it runs with zero dependencies inside the DSH Web process and provides Cookie-based authentication, multi-password routing, and access-log viewing.

Plugin Overview

dsh-web-pass is an admin-security plugin developed by maintainer linz919. It is a zero-dependency Web password gate with a natively integrated settings page. It supports session authentication via Cookies and provides forced password setup, login-failure locking, and multi-password multi-upstream routing.

Core Features

The plugin mainly includes the following features:
* Cookie Session Authentication: A Cookie-based authentication mechanism, not Nginx Basic Auth.
* Forced Password Setup: The first visit must set a password (subject to complexity requirements).
* True Lockout Mechanism: After reaching the failure limit, a lockout state is entered (default 60s baseline). Exponential backoff is supported (maximum 16x). A successful login does not reset the failure count.
* Sliding Session: The session validity period is 2 days, and it is automatically renewed with daily use.
* Multi-Password Multi-Upstream: Supports “guest mode,” where one password maps to one backend service, enabling multi-entry routing.
* Automatic Delegation of Authentication: Automatically retains built-in DSH authentication on behalf of users, so users do not need to handle DSH Token/Cookie.
* Access Logs: Built-in access-log viewer that records password-validation-related requests.
* Zero Dependencies: No external dependencies, with natively integrated settings page.
* Native Settings Page: Provides a natively integrated settings interface.

Installation and Activation

Use the official command to install the plugin:

dsh plugin --profile web add dsh-web-pass

After installation, restart the DSH Web service to apply the changes.

Typical Usage

  1. Access Entry: The browser accesses the plugin listening port (default 3081) via TLS or a reverse proxy; internally it forwards to DSH or another local service.
  2. Configure Backend: After logging in, open the settings page and add an upstream directly (label + host:port); changes take effect immediately.
  3. Multi-Entry Routing: Configure multiple backend entries, each with an independent password. Enter the corresponding password when logging in to access a different backend service (for example, the owner DSH or a clean guest DSH).

Data and Configuration

  • Data Storage: All data is stored under the $DSH_HOME/dsh-web-pass/ directory, including password hashes, sessions, and logs.
  • Session Handling: The session Cookie (dws_session) generated by the plugin is not forwarded upstream, and upstreams cannot write this Cookie via response headers.
  • Logout Restriction: The logout endpoint only supports POST requests to prevent CSRF attacks.
  • First Visit: Password setup is mandatory; otherwise access is denied.

Notes

  • Upstream Response Filtering: Any dws_session in upstream responses is automatically filtered to prevent leakage of the plugin Cookie.
  • Consistency: After upgrading the plugin or adjusting configuration, it is recommended to log in again to refresh the session.

Conclusion

dsh-web-pass provides a lightweight solution for adding access control and multi-entry management to local DSH services. For more details and source code, refer to GitHub.