Preface

DeepSeek Harness (DSH) uses a plugin-based architecture, and the Web GUI is served by default on the loopback address. When direct external exposure or sharing across multiple environments on an internal network is required, direct access lacks an authentication mechanism. This plugin adds a static-token login wall in front of the DSH Web interface, enabling token validation and access control for the Web service without modifying the DSH source code.

What It Is

dsh-auth-proxy is a plugin maintained by wxyzh. It listens on a local address (default 127.0.0.1:8443). Unauthenticated access displays the built-in login page. After validating the token, it issues an HttpOnly session cookie, then forwards HTTP and WebSocket traffic to the loopback DSH web server (default 127.0.0.1:3080).

Installation and Activation

Installing the plugin requires pnpm to be available in PATH. The plugin is automatically added to the web profile roster.

dsh plugin --profile web add @wxyzh/dsh-auth-proxy

Core Features

  1. Token-authenticated reverse proxy: Provides a built-in login page and validates the token using SHA-256 + timingSafeEqual to avoid timing side-channel attacks.
  2. HttpOnly session cookie: The session is a signed cookie with HttpOnly and SameSite=Lax; Max-Age is set to 10 years. The server does not store sessions, so cookies remain valid after a restart; however, changing the token immediately invalidates all logged-in sessions.
  3. IP allowlist and failure lockout: Supports IPv4 allowlists in CIDR format, with configurable failure thresholds and lockout durations.
  4. Live configuration updates: Managed through the Host’s settings section; configuration can be changed without restarting the process.
  5. Branding override: Supports rewriting the page title, favicon, and PWA manifest at the proxy layer, as well as injecting sidebar visuals.
  6. web-all compatibility: Compatible with the web-all plugin; restores the /remote prefix and adapts to the responsive layout of the mobile settings panel.

Configuration

The plugin manages configuration through the Host’s settings and supports hot updates.

Combined entry configuration example:

enabled: true
host: 127.0.0.1
port: 8443
targetHost: 127.0.0.1
targetPort: 3080
# 推荐使用环境变量
token: !!js process.env.DSH_AUTH_TOKEN
brand.enabled: true
brand.title: 'MyApp'
accessUrls: ['https://my-app.example.com']
allowedIps: ['127.0.0.1', '10.0.0.0/8']
maxFailures: 0
lockoutMinutes: 15

Configuration options:
* token: Shared access token. For security, the default is empty or the placeholder change-me; in that case, the proxy remains disabled and never listens.
* brand: When enabled, performs branding-layer overrides, supporting custom titles, icons, and sidebar visuals.
* accessUrls: For display only; declares the external access entry addresses and may include HTTPS domains.
* allowedIps: IP allowlist. If empty, a token is always required.

Notes and Limitations

  1. No TLS: The plugin itself does not handle TLS. Binding to a wildcard or public IP (such as 0.0.0.0 or a public IP) is prohibited. For external access, place a TLS reverse proxy (such as nginx/Caddy) in front to terminate encryption, then point it back to this listening address.
  2. No single-session revocation: Sessions are stateless signed cookies. Restarting does not invalidate them, but changing the token immediately logs everyone out. Logout only clears the client-side cookie.
  3. Mobile coupling: The collapse behavior and width optimization of the mobile settings panel are coupled to the structure of web-all. A semantic-level refactoring of web-all may affect compatibility.
  4. Configuration scope: Configuration is written only through the Host’s settings; no standalone configuration file is provided.

Summary

dsh-auth-proxy provides a lightweight token authentication layer. By listening on a local port and forwarding traffic, it implements secure access control for the DSH Web GUI. It is suitable for scenarios that require adding authentication to a local DSH instance without modifying the source code.