dsh-auth-gate

see Configuration below — the mount itself needs no manual patch row)

Configuration

The bundle mount (id dsh-auth-gate, inserted by dsh plugin add) uses the default config: mode: "token" backed by the DSH_AUTH_TOKEN environment variable. To change it, override the config in $DSH_HOME/cordis.patch.yml (or the profile's cordis.patch.yml — a ready-to-use override template ships in deploy/cordis.patch.yml). The override targets the mounted row by id (no insert — adding one would double-mount the plugin):

- id: dsh-auth-gate
  config:
    mode: "password" # "password" (recommended) or "token"
    totp: "optional" # "off" (default), "optional", or "required"
    cookieSecure: true # keep true when you use https

Option	Default	What it does
mode	"token"	"password" = username/password login; "token" = one shared secret
totp	"off"	Password mode only. "optional": users with a TOTP secret sign in with password + code; "required": all users must have a secret (users without one get the uniform 401 at the password stage, same body as a wrong password — anti-enumeration)
sessionTtl	604800	How long a login lasts (seconds) before you must sign in again
cookieName	dsh_auth	Name of the session cookie (rarely needs changing)
tokenRef	"DSH_AUTH_TOKEN"	Token mode only: which environment variable holds the shared secret
cookieSecure	true	Set to false only if you are testing over plain http
usersFile	""	Password mode: where your user list lives. Defaults to $DSH_HOME/auth/users.yaml
publicHost	""	Host rendered in the login page identity block (the anti-phishing "which instance is this" line). Empty = use the request Host header. Set it when a reverse proxy rewrites Host (e.g. Caddy header_up Host 127.0.0.1:3080), otherwise the card shows a loopback address instead of your public domain. With D25 it also lets the admin and password-change endpoints validate an Origin header: with publicHost empty they accept only Sec-Fetch-Site: same-origin, so production deployments should set it, and write it with the scheme (https://host) when TLS terminates at a reverse proxy
revokeSweepMs	5000	Password mode: how fast (ms) a user disabled with dsh-auth user disable loses already issued sessions. 0 = never sweep (disabling only blocks new logins)
clientIpHeader	""	Header carrying the real client address for rate limiting (x-forwarded-for, or cf-connecting-ip behind Cloudflare). Empty = read no header at all. Only read when the request's peer is inside trustedProxyCidrs; without it a same-host reverse proxy makes every client share one lockout bucket (issue #74)
trustedProxyCidrs	["127.0.0.0/8", "::1/128"]	Which peers may supply clientIpHeader (default: loopback only; a peer without an address, i.e. a Unix socket, counts as local). Invalid entries are dropped with an error log and trust narrows to loopback, an explicit [] means "trust nobody", and 0.0.0.0/0 / ::/0 are always rejected
logoutOrder	1000	Slot order of the "Sign out" button in Settings → General (higher = lower on the page). Raise it if another plugin registers a bigger order

To enable TOTP for a user, run dsh-auth user totp enable and add the printed secret (or scan the otpauth:// URI) into an authenticator app (Google Authenticator, 1Password, etc.). The code changes every 30 seconds; a code from the previous or next window is also accepted (drift tolerance).

Bundled configuration skill

The package ships a configuration quick-reference skill at .agents/skills/dsh-auth-gate-config/ (this page). Install it into the user-level dsh skill root so agents on the deployment side can answer "what configuration does auth-gate support?" directly:

pnpm --dir "${DSH_HOME:-$HOME/.dsh}/profiles/
" exec dsh-auth skill install [--force]

It copies the skill to $DSH_HOME/skills/dsh-auth-gate-config/, which dsh's skill discovery picks up automatically. Re-running without --force keeps any local edits to the skill; use --force to refresh it from the package.

The skill is a user-only skill (disable-model-invocation: true in its frontmatter): it stays out of the model's auto-invocable skill catalog so it is not injected into every agent turn, and you open it explicitly from the skill panel whenever you need the config reference (the UI marks it user-only). If you prefer the agent to answer configuration questions automatically, remove that frontmatter field after installation.