Preface¶

The DSH plugin ecosystem emphasizes “everything is a plugin”; the community directory is an independent site with no official affiliation to DeepSeek / High-Flyer. dsh-auth-gate is an authentication plugin within this ecosystem with a specific goal: to add a login gate to DSH web instances, requiring valid sessions for page access, API calls, and WebSocket connections.

It is suitable for scenarios where you need to expose a dsh web instance to browser users and scripted calls. After this plugin is applied, unauthenticated browser visits will see a login page, while script requests must explicitly carry tokens or session credentials.

What This Is¶

dsh-auth-gate is a login gate plugin for DSH web instances.

The repository is located at https://github.com/TecFancy/dsh-auth-gate. The scraped data does not include separate author / maintainer fields, so this document only treats TecFancy from the URL as a clue for the owner, not as an official maintainer declaration.

Basic information visible in the data includes:

• License: MIT.
• Runtime environment requirement: Node >=22.19.0.
• package.json declares two bins: dsh-auth and dsh-auth-proxy. The detailed user management commands documented in the verified data are for dsh-auth.

Core Capabilities¶

Unified Interception of Pages, API, and WebSocket¶

The core behavior of dsh-auth-gate is: page access, API calls, and WebSocket connections all require valid sessions. Accesses without valid sessions are blocked; browser users can use the login page, while scripts or curl requests need to use Authorization: Bearer <token> to bypass the login page.

Two Authentication Modes¶

The plugin supports two authentication modes:

1. Password authentication: uses username and password.
2. Shared token authentication: uses a shared secret.

The default mounting configuration is mode: token, with the shared secret stored in the DSH_AUTH_TOKEN environment variable.

Optional TOTP Two-Factor Authentication¶

Password mode supports optional TOTP two-factor authentication, compliant with RFC 6238. totp can be configured as off, optional, or required.

Once TOTP is enabled for a user, an additional verification code is required at login. The code changes every 30 seconds, with a tolerance window before and after the current period.

Default Security Policies¶

The default security policies listed in the verified data include:

• Passwords are stored as hashes.
• Login attempts are rate-limited.
• Session cookies use the secure setting.
• Missing or corrupted configuration blocks access rather than silently allowing it.

User Management CLI¶

The plugin provides the dsh-auth CLI for:

• Adding users.
• Listing users.
• Disabling users.
• Enabling or disabling TOTP.

Installation and Activation¶

First, install the plugin to the web profile:

dsh plugin --profile web add dsh-auth-gate

This command installs the plugin into the specified profile. After installation, the CLI is not directly added to PATH and must be invoked via the profile.

If enabling password mode, first create an administrator account. The example enters the web profile directory via pnpm --dir to execute dsh-auth:

printf '%s\n' 'choose-a-strong-password' | pnpm --dir "$DSH_HOME/profiles/web" exec dsh-auth user add admin --password-stdin

Next, override the mounting configuration in $DSH_HOME/cordis.patch.yml. The example below only overrides mode, totp, and cookieSecure:

- id: dsh-auth-gate
  config:
    mode: password
    totp: optional
    cookieSecure: true

After these steps, accessing the DSH web instance will trigger the login gate. The default cookieSecure: true is suitable for HTTPS environments; only consider setting it to false for plain http testing.

Configuration Options¶

The verified data lists the following configuration options:

Typical Usage¶

Managing Users¶

The user management commands listed in the data include:

dsh-auth user add admin --password-stdin
dsh-auth user list
dsh-auth user disable admin
dsh-auth user totp enable admin
dsh-auth user totp disable admin

If the plugin is installed to a profile via dsh plugin --profile web add dsh-auth-gate, it can be invoked per profile, for example:

pnpm --dir "$DSH_HOME/profiles/web" exec dsh-auth user list

Enabling TOTP¶

Enable TOTP for a user:

dsh-auth user totp enable admin

The command outputs a TOTP secret or an otpauth:// URI. After adding the secret or URI to an authenticator app, the user can use the verification code to log in in password mode.

Script Requests¶

Scripts or curl requests can carry a Bearer token to bypass the login page:

Authorization: Bearer <token>

Applicable Scenarios and Considerations¶

Suitable for the following scenarios:

• The DSH web instance needs to be exposed externally, but page access, APIs, and WebSocket connections all require login verification.
• Browser users use the login page, while automated scripts use Bearer tokens.
• In password mode, you need to manage multiple users and enable TOTP for some or all users.

Consider the following notes:

• This plugin runs with the permissions of the current DSH process; review the source code and license before installation. This plugin’s license is MIT.
• In shared token mode, DSH_AUTH_TOKEN is sensitive credentials and should be kept out of repositories or logs.
• cookieSecure defaults to true; only consider disabling it for plain http testing.
• Missing or corrupted configuration blocks access; this is expected behavior, not silent allowance.
• TOTP verification codes change every 30 seconds, with a tolerance window before and after the current period.

Related Links¶

GitHub repository: https://github.com/TecFancy/dsh-auth-gate

To find it in the DSH community directory, search for dsh-auth-gate on the standalone directory site.