Preface

If you want to add a login gate in front of dsh web, a common approach is to temporarily block it at the reverse proxy or outer service layer. dsh-auth-gateway is a Cordis gateway plugin maintained by xbzbing, licensed under MIT, designed for DeepSeek Harness (dsh web), providing password authentication, TOTP two-factor authentication, real request interception, session management, and login auditing.

Below, we introduce its capabilities, installation method, how to enable TOTP, as well as considerations for uninstallation and password reset.

What Is This

dsh-auth-gateway is a gateway-layer plugin: it establishes an authentication gate for dsh web and intercepts unauthenticated HTTP and WebSocket requests at the gateway layer. It doesn’t just add a login box to the page; instead, it handles authentication, sessions, rate limiting, and auditing along the request path of dsh web.

The maintainer is xbzbing, and the license is MIT. The README states that the project supports dsh 0.1.1-rc.2; package.json declares Node >= 20.

Core Capabilities

First, implement password authentication, then enable TOTP as needed. Below are the main items it covers:

  • Provides a password authentication gate for dsh web
  • Supports TOTP two-factor authentication and one-time backup codes
  • Intercepts unauthenticated HTTP and WebSocket requests at the gateway layer
  • Logs audit events for successful logins, failed logins, logouts, password changes, and brute-force alerts
  • Provides password failure lockout, global login rate limiting, and independent rate limiting for OTP/backup codes
  • Offers session management based on in-memory tokens and HttpOnly Cookies
  • Supports reverse proxy sub-path basePath and an optional authentication settings panel

Installation and Enabling

Install the plugin:

dsh plugin --profile web add dsh-auth-gateway

Start dsh web:

dsh web --port 8080

After the first deployment, a one-time initial password is generated and printed to the console. Copy the initial password first, then open the dsh web page to log in.

After logging in, you will enter the personal password setup step. Setting a personal password is mandatory, and all features are unavailable until completed. After the above steps, subsequent access to dsh web will pass through the login gate first.

Enabling TOTP

If you want to enable TOTP, after logging in, visit:

/otp/setup

On that page, enable TOTP and save the one-time backup codes. Once OTP is enabled, logging in requires a password + verification code (or backup code).

OTP keys are encrypted and stored using AES-256-GCM. The master key can come from an environment variable:

DSH_AUTH_GATEWAY_MASTER_KEY

It can also come from an automatically generated file:

auth-gateway/otp-master.key

Sessions, Rate Limiting, and Auditing

Session management uses in-memory tokens and HttpOnly Cookies.

Protection strategies include:

  • Password failure lockout
  • Global login rate limiting
  • Independent rate limiting for OTP/backup codes

Audit logs record successful logins, failed logins, logouts, password changes, and brute-force alerts. Logs are persisted to:

$DSH_HOME/auth-gateway/audit.log

They rotate daily and are retained for 90 days, without recording credentials.

Sub-path Deployment

If dsh web is not deployed at the root path but under a reverse proxy sub-path, you need to configure basePath in the deployment side’s profile patch for sub-path deployment. The plugin itself also provides an optional authentication settings panel.

Password Reset and Uninstallation

If you forget the password, you can reset it using dsh-auth-gateway-reset, and after restarting, the console will print a new initial password.

When uninstalling, first clear credentials, then remove the plugin:

~/.dsh/profiles/web/node_modules/.bin/dsh-auth-gateway-uninstall
dsh plugin --profile web remove dsh-auth-gateway

Applicable Scenarios and Considerations

Suitable for the following scenarios:

  • Need to add a password login gate to dsh web
  • Need TOTP two-factor authentication and backup codes
  • Need to intercept unauthenticated HTTP and WebSocket requests
  • Need to retain login audit and rate limiting records

Before installation, note:

  • The plugin runs with the current dsh process permissions; check the source code and license before installation
  • License is MIT
  • README states support for dsh 0.1.1-rc.2, requiring Node >= 20
  • There is one documented security exception: LAN trust provides minimal intervention for the settings page under the domain/reverse-proxy access model

Related Links

GitHub:

https://github.com/xbzbing/dsh-auth-gateway

Plugin directory hint (subject to actual directory):

https://www.skillhub.cn/plugins/xbzbing/dsh-auth-gateway