Preface

The extension philosophy of DeepSeek Harness is “everything is a plugin”; the plugins directory is an independent site and is not equivalent to the DeepSeek or Huanfeng official app store.

A common scenario is: DSH Web is supposed to run on the local loopback, but operations personnel want to access it via HTTPS from a browser, without exposing pages, APIs, downloads, SSE, or WebSockets directly without login. dsh-auth is an unofficial community plugin for DeepSeek Harness, used to add administrator login to DSH Web. It is maintained by hxy91819. The core approach is to keep Harness on loopback and install a project-owned Caddy forward_auth edge to uniformly handle login verification.

What is this

dsh-auth is a community plugin for DeepSeek Harness, used to add a secure administrator login to the DSH Web app.

  • GitHub Repository: https://github.com/hxy91819/dsh-auth
  • Version in package.json: 0.2.3
  • README provides precise version installation: dsh-auth@0.2.3
  • License type not confirmed in this material; only the LICENSE file and license badge appear in the material.

Core Capabilities

The following introduces the verified dsh-auth capabilities:

  • Keep Harness on loopback and install a project-owned Caddy forward_auth edge, covering pages, APIs, downloads, SSE, and WebSockets.
  • Provide interactive setup, plan preview, and non-interactive JSON setup.
  • Support administrator initialization via password or login-token.
  • Password sources are hashed with Argon2id and are not stored in plaintext.
  • Support HTTPS and support automatic or manual TLS; automatic TLS is the HTTPS default.
  • Copy checksum-verified bundled Caddy binary and enable the independent dsh-auth-caddy.service.
  • Support optional Chinese and English token-failure page copy.
  • Support --behind-tls-proxy, used to keep the managed HTTP edge on loopback, require trusted HTTPS forwarding headers, and issue Secure cookies.

Installation and Enablement

Plugin Pre-installation is Not Equivalent to Enabling Authentication

First execute the following command to add the dsh-auth bundle to the DSH Web profile:

dsh plugin --profile web add dsh-auth

This step only adds the bundle and does not mean authentication is enabled. The plugin command does not create secrets, install Caddy, or protect anything. Enabling authentication still requires global CLI installation and running sudo dsh-auth setup.

Install CLI

Install the current stable version CLI:

sudo npm install -g dsh-auth

If you need to lock the version according to supply chain policies, you can install the precise version given in the README:

sudo npm install -g dsh-auth@0.2.3

Run Setup

Normal deployment requires Linux x64 or ARM64, systemd, Node.js 24.7 or higher, and DSH Web 0.1.0-rc.7.

Run the interactive setup:

sudo dsh-auth setup

The interactive installation will ask for confirmation of the DSH service, administrator initialization method, HTTPS hostname, and TLS mode; it will first display the secret-free plan and only modify the system after you enter confirmation values. Setup will install the pinned bundle, copy the checksum-verified Caddy binary, write permission-restricted authentication state, and enable dsh-auth-caddy.service. It does not store plaintext passwords, nor does it download Caddy during setup.

View Plan First

Before running setup, you can use plan to view the same typed plan. It does not read passwords and does not change the file system:

sudo dsh-auth plan

View Help and Version

You can print usage and CLI version:

dsh-auth --help
dsh-auth --version

Typical Usage

Interactive Password Initialization

After installing the CLI, start setup from an existing DSH Web systemd service. Example:

sudo npm install -g dsh-auth
sudo dsh-auth setup

The following is the interactive example from the README, with actual password input omitted:

$ sudo dsh-auth setup
Existing DSH Web systemd unit: dsh-web.service
Administrator initialization (password/login-token): password
Login tokens (enabled/disabled) [disabled]: enabled
Administrator username: operator
Edge mode (https/http) [https]:
TLS (automatic/manual) [automatic]:
Public HTTPS hostname: harness.example.com
...
Type install to apply this exact plan: install
dsh-auth setup completed successfully.

Non-interactive JSON + Password Initialization

Non-interactive mode requires explicitly providing the administrator initialization method. When using password initialization, the plaintext password needs to be mounted as a platform-provided temporary 0600 secret file; dsh-auth reads it only once to create the Argon2id hash and does not copy the plaintext.

The following example is a complete HTTPS system install, using password initialization and automatic TLS:

sudo dsh-auth setup \
  --non-interactive \
  --json \
  --dsh-service dsh-web.service \
  --dsh-home /var/lib/dsh \
  --dsh-executable /usr/local/bin/dsh \
  --profile web \
  --admin-bootstrap password \
  --admin-username operator \
  --login-token enabled \
  --password-file /run/secrets/dsh-auth-password \
  --mode https \
  --tls automatic \
  --upstream 127.0.0.1:3080 \
  --listen-address 0.0.0.0 \
  --server-name harness.example.com

Non-interactive JSON + Login-token Initialization

When using login-token initialization, do not pass password and username; the first authorized user can be set in the browser or choose Later:

sudo dsh-auth setup \
  --non-interactive \
  --json \
  --dsh-service dsh-web.service \
  --admin-bootstrap login-token \
  --login-token enabled \
  --mode https \
  --tls automatic \
  --server-name harness.example.com

Common Parameters

The following parameters are from the README examples and descriptions; for complete parameters, please refer to the repository documentation.

  • --mode: Choose https or http, default https.
  • --tls: Choose automatic or manual, default automatic.
  • --server-name: Public HTTPS hostname, required when --mode https.
  • --admin-bootstrap: Choose password or login-token when non-interactive.
  • --admin-username: Initial administrator login name when using password setup.
  • --login-token: Choose enabled or disabled when non-interactive; token initialization requires enabled.
  • --listen-address: Literal IP bind address; HTTP still requires an explicit private or loopback address.
  • --behind-tls-proxy: Keep managed HTTP edge on loopback, require trusted HTTPS forwarding headers, and issue Secure cookies.
  • --login-token-error-message-zh / --login-token-error-message-en: Optional token-failure page copy, requires --login-token enabled.
  • --certificate / --certificate-key: Absolute paths to certificate and private key used when using manual TLS.

Upgrade, Idempotency, and Limitations

  • Version 0.2.0 is a breaking upgrade from legacy v1 deployments; previous installer flags, Nginx-managed installations, and old sessions will not be migrated.
  • According to the breaking upgrade path described in the README, you need to first uninstall the previous installation and then run setup.
  • Repeating the same command is idempotent; if the existing managed installation has non-secret configurations that are the same, it will report unchanged.
  • Different settings, or files without an ownership record, will be rejected rather than overwritten.
  • When some configuration is missing, the system will fail loudly, rather than booting with incomplete configuration.
  • HTTP mode still requires an explicit private or loopback address.

Use Cases and Considerations

dsh-auth is suitable for this type of deployment:

  • Existing DSH Web systemd service, such as dsh-web.service.
  • DSH Web upstream listens only on loopback.
  • Need to expose Web via HTTPS and add administrator login.
  • Need Caddy forward_auth edge to simultaneously cover pages, APIs, downloads, SSE, and WebSockets.
  • Want to initialize administrator via password or login-token and want to avoid long-term storage of plaintext passwords.

Things to note before enabling:

  • dsh plugin --profile web add dsh-auth is just pre-installing the bundle, not enabling authentication.
  • sudo dsh-auth setup will modify the host system, including installing the pinned bundle, copying the Caddy binary, writing the authentication state, and enabling dsh-auth-caddy.service.
  • Plugin content runs with the current dsh process permissions; check the source code and license before installing.
  • License type is not confirmed in this material; only the LICENSE file and license badge are seen; please confirm yourself before deploying.
  • This article does not adopt unconfirmed information, such as directory page URL, category, star count, fork count, revocable sessions, bilingual UI, etc.

Links

  • GitHub: https://github.com/hxy91819/dsh-auth
  • Directory Page: The verified information in this article does not provide a confirmable directory page URL; please refer to the actual publishing address of the plugin directory site.