hxy91819/dsh-auth ↗★ 7

dsh-auth

Caddy-fronted administrator authentication bundle for DeepSeek Harness

包名
dsh-auth
兼容性
待验证
Harness 依赖范围
>=0.2.0-rc.2 <0.3.0
Cordis 依赖范围
~4.0.4
版本
0.3.1
许可证
MIT
最近更新
2026年11月9日

同名包的其他仓库

安装

$npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-auth

dsh-auth

English | 简体中文

npm version CI license

Unofficial community plugin for DeepSeek Harness. Add a secure administrator login to the DeepSeek Harness Web app. dsh-auth keeps Harness on loopback and installs a project-owned Caddy forward_auth edge for pages, APIs, downloads, SSE, and WebSockets.

Version 0.2.0 is a breaking upgrade from legacy v1 deployments. Previous installer flags, Nginx-managed installations, and old sessions are not migrated. Uninstall the previous installation, then run setup again.

Quick start

Interactive setup

Install the published CLI, then start from an existing DSH Web systemd service whose upstream listens only on loopback:

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

npm install -g dsh-auth installs the current stable CLI, and the installer pins that same version in the selected DSH profile. For controlled production rollout, install the exact version approved by your supply-chain policy:

sudo npm install -g dsh-auth@0.3.0

Plugin pre-install is not enabled authentication

dsh plugin --profile web add dsh-auth (or a local tarball) only adds the bundle to the Web profile. With both core environment variables absent the bundle stays dormant: Web keeps booting with its native authentication, and no dsh-auth routes or settings UI appear. A partially supplied configuration produces an activation error and does not enable dsh-auth; Harness may keep running with its native authentication. Enabling authentication always requires the globally installed CLI and sudo dsh-auth setup; the plugin command never creates secrets, installs Caddy, or protects anything.

When setup finds a pre-installed bundle whose package name, version, and build content exactly match the running CLI, it adopts it: no package is reinstalled, and the bundle keeps external ownership. Any other pre-installed build is refused before the host changes. Rollback and uninstall leave an adopted bundle in place; without managed configuration it simply returns to dormancy.

The interactive installer asks for the exact DSH service, administrator initialization method, HTTPS hostname, and TLS mode; shows a secret-free plan; and changes the system only after you type the exact confirmation. It installs the pinned bundle into the selected DSH profile, copies a checksum-verified Caddy binary bundled in the same package, writes permission-restricted authentication state, and enables an independent dsh-auth-caddy.service. It never stores a plaintext password and never downloads Caddy at setup time.

Normal deployment requires Linux x64 or ARM64, systemd, Node.js 24.7 or newer, and DSH Web 0.2.0-rc.2. Automatic TLS is the HTTPS default. Manual TLS requires an existing certificate and key. --server-name accepts either a DNS name or a public literal IP address.

The standalone installer explicitly enables DSH_AUTH_NATIVE_AUTH_BRIDGE=true: a valid, revocable dsh-auth session can then act as the native Harness operator while native Host and Origin checks remain enforced. The plugin defaults this option to false. Multi-user gateways such as Chatroom must leave it disabled and enforce their own resource authorization. Revoking a dsh-auth session does not revoke separately issued native Harness credentials.

$ 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
Password:
Confirm password:
dsh-auth setup completed successfully.

Rerunning the same command is idempotent. An existing managed installation with identical non-secret settings is reported unchanged; different settings or files without an ownership record are rejected instead of overwritten.

Use plan before setup to inspect the same typed plan without reading a password or changing the filesystem:

sudo dsh-auth plan

CLI setup (non-interactive)

Non-interactive mode requires stable flags and an explicit administrator initialization method. For password initialization, mount the plaintext password as a temporary 0600 secret file supplied by the platform; dsh-auth reads it once to create an Argon2id hash and does not copy the plaintext.

These command names, flag names, --name value or --name=value syntax, JSON schema version 2, and exit codes are the public automation contract. Global flags may precede the command. New flags and diagnostic codes may be added. Renaming, removing, or changing the meaning of an existing flag, JSON field, or exit code is a breaking change.

Print the frozen usage text:

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

-h is an alias for --help. dsh-auth setup --help prints the same usage text. The example below is a complete HTTPS system install with password initialization and automatic TLS.

Prompts run only when stdin and stdout are both TTYs and --non-interactive is not set. --json is output format only and does not disable prompts.

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

Token initialization omits the password and username. The first authorized user sets them in the browser, or chooses 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
FlagRequiredDefaultDescription
--help, -hnoPrint usage and exit.
--versionnoPrint the CLI version and exit.
--non-interactiveon a TTYDisable prompts.
--jsonnoEmit one JSON document. Does not disable prompts.
--modenohttpshttps or http.
--behind-tls-proxynodisabledKeep the managed HTTP edge on loopback, require trusted HTTPS forwarding headers, and issue Secure cookies.
--admin-bootstrapwhen not promptingpassword or login-token.
--admin-usernamepassword setupInitial administrator login name.
--login-tokenwhen not promptingenabled or disabled. Token initialization requires enabled.
--login-token-error-message-zhnobuilt-in Chinese copyOptional 1–500 character Chinese token-failure page text. Requires --login-token enabled.
--login-token-error-message-ennobuilt-in English copyOptional 1–500 character English token-failure page text. Requires --login-token enabled.
--listen-addressHTTP0.0.0.0 for HTTPSLiteral IP bind address. HTTP still requires an explicit private or loopback address.
--dsh-servicesystem setupExact existing DSH Web systemd unit. Omit only with --output-dir.
--password-file or --password-stdinready password setupPassword source. Not used by plan or token initialization. Unchanged reruns skip it.
--server-name--mode httpsPublic HTTPS hostname.
--tlsHTTPSautomaticautomatic or manual.
--certificate--tls manualAbsolute TLS certificate path.
--certificate-key--tls manualAbsolute TLS private-key path.
--dry-runnoOn setup, alias for plan. On uninstall, list owned removals without changing the host.
--dsh-homenodiscoveredHarness home when the unit does not infer it.
--dsh-executablenodiscoveredDSH executable file when the unit does not infer it. Not a directory.
--profilenowebDSH profile name.
--upstreamno127.0.0.1:3080Loopback DSH listener (127.0.0.1 or [::1]).
--packagenodsh-auth@Pinned registry spec or absolute .tgz.
--http-portno80 (8080 for HTTP)HTTP or HTTPS-redirect port.
--https-portno443HTTPS listen port.
--output-dirnoOffline or container render directory. Skips systemd.

Free certificates for a public IP

When --server-name is a publicly routable IPv4 or IPv6 address and --tls automatic is selected, the managed Caddy requests a free Let’s Encrypt IP address certificate with the shortlived profile and renews it automatically. Let’s Encrypt requires these certificates to be valid for about six days, so the host must keep Caddy’s persistent state and outbound ACME access available. The HTTP challenge port must be reachable from the Internet (normally TCP 80); the certificate authenticates the IP, not a port, so the HTTPS listener may use another port after issuance.

For the public address 9.135.102.192 on the normal HTTPS port:

sudo dsh-auth setup \
  --non-interactive \
  --dsh-service dsh-web.service \
  --admin-bootstrap login-token \
  --login-token enabled \
  --mode https \
  --tls automatic \
  --server-name 9.135.102.192 \
  --http-port 80 \
  --https-port 443

If ACME validation cannot reach the machine, setup does not turn that into a trusted certificate: use a DNS name, restore public access to the challenge port, or provide an existing certificate with --tls manual. tls internal remains an explicit local/evaluation fallback and is not a publicly trusted certificate.

Removed without aliases: --nginx, --authorize-nginx-install, --user-id, --username, --roles, and --dsh-bin.

Other commands accept a smaller frozen flag set:

CommandRequired when not promptingOptional
planSame setup flags, without a password source--json, --non-interactive
doctor--json
upgrade--authorize-upgrade--package, --json, --non-interactive, --dry-run
reset-password--password-file or --password-stdin; --authorize-password-reset--json, --non-interactive
uninstall--authorize-uninstall--json, --non-interactive, --dry-run
issue-login-token--authorize-login-token-issue when not prompting--ttl-seconds, --public-origin, --auth-state-file with --public-origin, --json
hash--password-stdin
secret

Passwords are accepted only through hidden interactive input, --password-stdin, or --password-file. There is no inline password flag. Command output, JSON, plans, subprocess argv, and installer errors never contain password or session-secret values. issue-login-token is the only command whose successful stdout or JSON may contain a bearer login token.

Issue a one-time login link

When setup enabled login tokens, a cloud control plane or operator can mint a single-use URL. The raw token appears only in the successful human URL line or the JSON success document:

sudo dsh-auth issue-login-token --non-interactive --authorize-login-token-issue

The URL uses a fragment (/auth/token#token=…). Opening it establishes the same 72-hour rolling session as a password login. If the administrator password has not been set, the browser first offers a setup page; Later skips only that login.

Container and image layouts pass explicit paths instead of reading the systemd ownership record:

dsh-auth issue-login-token \
  --non-interactive \
  --authorize-login-token-issue \
  --json \
  --auth-state-file /export/dsh-auth/state/auth-state.json \
  --public-origin https://harness.example.com

A system installation created with --behind-tls-proxy also takes the current public HTTPS origin at issue time. The value is not stored by setup, so changing an outer proxy address or port does not require reinstalling dsh-auth:

sudo dsh-auth issue-login-token \
  --non-interactive \
  --authorize-login-token-issue \
  --public-origin https://203.0.113.10:49152

Setup can replace the built-in failure page text. Configure Chinese and English independently; an omitted language keeps its built-in copy. Each value is 1–500 Unicode characters of plain text. Control characters are rejected, and HTML is shown as text rather than markup. The installer refuses these flags when --login-token is disabled.

Malformed, expired, already-used, and unknown tokens all return the same HTTP 401 page with that text. The page does not identify which of those cases occurred. A token POST that fails the Origin or CSRF check returns a different HTTP 403 page: it asks the user to reopen the latest console link or check the public access address, does not use the 401 text, and does not consume the token.

sudo dsh-auth setup \
  --login-token enabled \
  --login-token-error-message-zh '登录链接不可用,请向管理员重新申请。' \
  --login-token-error-message-en 'This sign-in link is unavailable. Request a new one from your administrator.'

External identity providers

dsh-auth exposes a provider-neutral authorization-code interface. The built-in ioa provider adapts Tencent IOA/Taihu's signed AccessToken exchange while the session, CSRF, state, and authorization policy remain provider-independent.

Enable it through the Cordis bundle configuration (the provider is disabled by default):

externalIdentity:
  enabled: true
  paasId: ${TAIHU_PAAS_ID}
  tokenFile: /run/secrets/taihu-token
  baseUrl: https://api.woa.com
  callbackUrl: https://lightpilot.woa.com/auth/callback
  allowedUsers: [masonxhuang, yuehuali]
  allowedDepartmentIds: []
  allowedDepartmentPrefixes: []

Users start the flow at /auth/login/ioa. The callback validates a short-lived state value, exchanges the one-time code server-side, applies the configured user/department allowlist, and creates the same revocable opaque session used by password login. The Taihu token is read only from the permission-restricted tokenFile; it is never accepted in a URL or persisted authentication state.

Set allowedUsers: ['*'] to accept every authenticated identity from the configured provider or gateway. This delegates admission to that identity provider; signatures, encrypted assertions, expiry, and session verification still apply. An empty allowlist continues to deny access. The same policy applies to gatewayIdentity.allowedUsers and its DSH_AUTH_GATEWAY_ALLOWED_USERS environment setting.

Verified identity headers

An authenticated GET or HEAD request to /auth/verify still returns 204 and the legacy X-Dsh-Auth-User-Id: admin, username, and edge-role headers. For an external (IOA) session it also returns URL-encoded, validated profile headers: X-Dsh-Auth-Subject, X-Dsh-Auth-Username, X-Dsh-Auth-Display-Name, and optional X-Dsh-Auth-Picture. Subject is the stable external account key; X-Dsh-Auth-Roles describes only the dsh-auth edge and must not be used as an application role. The managed Caddy removes client-supplied values before forward_auth and copies only verifier output to the upstream. Profile fields are bounded to 512 UTF-8 bytes and reject control characters; picture URLs must be HTTPS without credentials or fragments.

Reset the password

Signed-in administrators can open Settings → General → Reset password, enter the current password, and set a new one.