dsh-plugin-auth 0.1.2

package/README.md

@@ -0,0 +1,205 @@
+# dsh-plugin-auth
+
+Enterprise username/password authentication gate for the **dsh** (DeepSeek Harness) Web UI.
+
+Out-of-tree plugin — **no core changes**. Once installed into the `web` profile, every page, API
+route, `/plugins` asset, and WebSocket upgrade requires a logged-in session. Unauthenticated
+navigations are redirected to a self-contained login page; unauthenticated API/XHR calls get `401`.
+The login page uses Simplified Chinese (`zh-CN`) and follows the operating system's light/dark
+preference with the same palette and control geometry as the dsh Web UI; CLI and JSON API output
+remain compatible.
+
+> The stock Web UI ships only a DNS-rebinding "browser trust fence" (`isTrustedApiRequest`), which the
+> source explicitly notes **is not an authentication layer**. This plugin adds the missing gate.
+
+## How it works
+
+The plugin's default export is `class AuthWebServer extends WebServer`. A bundle composition patch
+(`cordis.patch.yml`) **disables** the stock `webserver` row and **inserts** a row that re-provides the
+`webServer` service from this subclass — so the plugin becomes the *sole* provider and every consumer
+registration flows through it:
+
+- `register` / `registerFallback` / `registerUpgrade` are overridden to wrap each handler in an auth
+  gate, then delegate to `super.*`. One choke point covers the SPA fallback, `/api`, `/plugins`,
+  upgrades, and any route added later.
+- The plugin's own `/__auth/*` surface (login page, login/logout, status) is registered with
+  `super.register` in the constructor, so it stays **ungated** and reachable while logged out.
+- The subclass truly re-provides `webServer` (`super(ctx, 'webServer')` is inherited) and the insert row
+  keeps `inject: [webStartup]` and the `{host, port}` config, so downstream `web-runtime` and
+  `connection` rows still resolve.
+
+## Requirements
+
+- Node `^22.19 || >=24` (matches dsh).
+- A dsh checkout/profile where the peers resolve: `@deepseek-ai/cordis` and
+  `@deepseek-ai/dsh-host-webserver`. Both are in the `web` profile's dependency closure already,
+  and the profile's module fallback (`healProfilesModuleFallback`) links them next to the plugin.
+- The plugin **deliberately does not declare these as `peerDependencies`**. It subclasses the
+  harness's *own* `WebServer` (the `webServer`-service provider) and must share the harness's exact
+  `WebServer` **and** `cordis` module instances. Declaring `"*"` peers makes pnpm fetch a stale
+  published copy from the registry, install it inside the plugin's dependency closure, and *shadow*
+  the profile fallback — the subclass then extends the wrong build (an older one that provides
+  `httpServer`, not `webServer`, bound to a different `cordis`), so boot fails with every web
+  consumer "pending (waiting for service: webServer)". Leaving the peers undeclared lets Node's
+  parent-walk resolve them to the fallback — the same instances the loader uses.
+
+
+## Install from npm
+
+The public npm package is the recommended installation path once a release is published. dsh forwards
+the package spec to pnpm and automatically adds the package to the profile layer list because this package
+declares `dsh.bundle`:
+
+```bash
+# install the exact release into the web profile
+dsh plugin --profile web add -w dsh-plugin-auth@0.1.2
+
+# create the first admin before first boot (writes $DSH_HOME/auth/users.json)
+dsh plugin --profile web exec dsh-auth add-user admin
+
+# confirm the auth-webserver layer resolved and the stock webserver is disabled
+dsh --profile web --dump-config
+```
+
+`dsh-plugin-auth` deliberately has no `peerDependencies`: the dsh profile supplies the exact
+`@deepseek-ai/cordis` and `@deepseek-ai/dsh-host-webserver` instances required by the subclass.
+
+## Install from a tarball
+
+Use a tarball for local development or when the package is not available from a registry. The tarball's
+realpath lands inside the profile tree, which lets its peer imports resolve through the profile module
+fallback; a `link:` to an external directory would put the realpath outside the tree and fail to resolve:
+
+```bash
+# from the plugin directory
+npm pack                       # → dsh-plugin-auth-<version>.tgz
+
+# create the first admin BEFORE first boot (writes $DSH_HOME/auth/users.json)
+node bin/dsh-auth.js add-user admin
+
+# install into the web profile.
+# -w is REQUIRED: a dsh profile is a pnpm workspace root (packages: - .), and
+# adding a dependency to a workspace root without -w fails ERR_PNPM_ADDING_TO_ROOT.
+pnpm dsh plugin --profile web add -w ./dsh-plugin-auth-<version>.tgz
+```
+
+### Pre-flight (go / no-go)
+
+Before starting the server, confirm the composition resolved and the peer imports work:
+
+```bash
+dsh --profile web --dump-config
+```
+
+The dump must show the `webserver` row with `disabled: true` and exactly one inserted `auth-webserver`
+row — with no "module resolution failed" errors. A resolution failure here fails loud; fix the install
+(use a tarball, not a directory link) before booting.
+
+### Start
+
+```bash
+pnpm dsh web            # binds 127.0.0.1:3080 by default
+pnpm dsh web --port 8080  # if 3080 is taken (e.g. a stale dsh still running)
+```
+
+Open `http://127.0.0.1:3080` → you are redirected to `/__auth/login`. After signing in you reach the
+app; `/api` and `/plugins` work as normal.
+
+> If boot fails with `EADDRINUSE ... 127.0.0.1:3080`, another process (often a stale `dsh web` from a
+> previous run) already holds the port. Stop it, or start on a different `--port`. This is a distinct
+> failure from the composition error below — it means the gate *did* activate and tried to bind.
+
+
+## CLI: `dsh-auth`
+
+Credentials live in `$DSH_HOME/auth/users.json` (atomic write, mode `0600` where POSIX modes apply) and
+are managed **offline** — never through the Web settings UI. Passwords are read from the TTY with echo
+masked, or from bootstrap env vars for non-interactive provisioning.
+
+```
+dsh-auth add-user <username>   Create a user (prompts for a password).
+dsh-auth passwd <username>     Change a user's password.
+dsh-auth list                  List users (with disabled flag + last-updated).
+dsh-auth remove <username>     Delete a user.
+dsh-auth disable <username>    Disable a user (keeps the record; blocks login).
+dsh-auth enable <username>     Re-enable a disabled user.
+```
+
+Environment:
+
+- `DSH_HOME` — auth data root (default `~/.dsh`); data in `$DSH_HOME/auth`.
+- `DSH_AUTH_BOOTSTRAP_USER` — username for non-interactive `add-user`.
+- `DSH_AUTH_BOOTSTRAP_PASSWORD` — password for non-interactive `add-user` / `passwd`.
+
+Passwords must be at least 12 characters and include at least 3 of: lowercase, uppercase, digit, symbol.
+
+## Configuration (`$DSH_HOME/auth/config.json`, optional)
+
+All keys are optional; out-of-range or wrong-typed values silently fall back to the secure default, so a
+malformed file can never weaken the gate past sane bounds.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `sessionAbsoluteTtlMs` | `43200000` (12h) | Hard session lifetime cap. |
+| `sessionIdleTtlMs` | `7200000` (2h) | Sliding idle window. |
+| `sweepIntervalMs` | `300000` (5m) | Background expired-session sweep cadence. |
+| `lockoutThreshold` | `5` | Consecutive failures (per username+IP) before lockout. |
+| `lockoutBaseMs` | `30000` | First lockout duration. |
+| `lockoutMaxMs` | `900000` (15m) | Exponential-backoff cap. |
+| `lockoutWindowMs` | `900000` (15m) | Idle time after which the failure counter resets. |
+| `minPasswordLength` | `12` | Minimum password length (floor 8). |
+| `secure` | `false` | `true` behind TLS: sets `Secure` + `__Host-` cookie, forces `Path=/`. |
+| `sameSite` | `"Strict"` | Cookie `SameSite` (`Strict` or `Lax`). |
+| `cookiePath` | `"/"` | Cookie `Path`. |
+| `trustedOrigins` | `[]` | Extra `Origin` values accepted on state-changing POSTs. |
+| `scrypt` | `{N:16384,r:8,p:1,keylen:64,maxmem:64MiB}` | Password hashing cost. |
+
+> **Behind a TLS reverse proxy**, set `"secure": true` so the session cookie gets `Secure` and the
+> `__Host-` prefix. On plain loopback HTTP the cookie cannot be `Secure` (browsers would drop it).
+
+## Security notes
+
+- **Passwords:** scrypt with a per-user random salt, self-describing cost params, constant-time compare.
+  Unknown/disabled users are verified against a fixed dummy record so there is no timing/enumeration
+  oracle.
+- **Sessions:** 256-bit random tokens, `HttpOnly; SameSite=Strict; Path=/` cookies, absolute + sliding
+  expiry, login-time token rotation (anti-fixation), logout revocation, background sweep.
+- **Brute force:** per-(username, IP) lockout with exponential backoff; a legit user on another IP is
+  unaffected by an attacker's failures.
+- **CSRF:** state-changing POSTs require a same-origin `Origin`/`Referer` (or a `trustedOrigins` entry);
+  default-deny when both are absent. This backs up `SameSite=Strict`.
+- **Open redirect:** the post-login `next` target is reduced to a safe single-slash local path.
+- **Audit:** login success/failure/lockout/logout are logged via `ctx.logger` with username + IP (never
+  the password).
+
+## Scope & tradeoffs (by design)
+
+- Local username/password only — no SSO, no 2FA.
+- Sessions are **in-memory**: a dsh restart requires everyone to log in again.
+- No separate CSRF token — `SameSite=Strict` + Origin check is the chosen defense.
+- `src/paths.js` is **self-contained** (it re-implements the `$DSH_HOME` → `~/.dsh` resolution rather
+  than importing `@deepseek-ai/dsh-home-paths`). This keeps the offline CLI working without the harness
+  on the module path and removes that package from the runtime peer set; only
+  `@deepseek-ai/dsh-host-webserver` is imported at runtime.
+
+## Composition ordering caveat
+
+This bundle disables the stock `webserver` row. Any *later* composition layer (the profile's own
+`cordis.patch.yml`, `$DSH_HOME/cordis.patch.yml`, or `--patch`) that flips `webserver` back to
+`disabled: false` would create two providers of `webServer` and boot fails **loud** (duplicate service),
+not silently. Don't re-enable the stock row while this plugin is installed.
+
+## Development / tests
+
+```bash
+node --test
+```
+
+The unit suites (policy, passwords, sessions, lockout, gate, login-page, users) are pure and run
+standalone. `tests/integration.test.js` needs the runtime peers (`@deepseek-ai/cordis`,
+`@deepseek-ai/dsh-host-webserver`); when they are not installed it **skips** with a reason. Run it inside
+a built harness checkout to exercise the real subclass over HTTP.
+
+## License
+
+MIT

package/bin/dsh-auth.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * dsh-auth — offline credential management for dsh-plugin-auth.
+ *
+ * Commands: add-user, passwd, list, remove, disable, enable.
+ * Writes $DSH_HOME/auth/users.json (atomic, mode 0600). Passwords are read from
+ * the TTY with echo masked, or from DSH_AUTH_BOOTSTRAP_USER/PASSWORD for
+ * non-interactive provisioning. Credentials never touch the Web settings UI.
+ */
+
+import process from 'node:process'
+import { readFileSync } from 'node:fs'
+import { createInterface } from 'node:readline'
+import { createUserStore } from '../src/users.js'
+import { hashPassword, assessPasswordStrength } from '../src/passwords.js'
+import { resolvePolicy } from '../src/policy.js'
+import { usersFile, configFile } from '../src/paths.js'
+
+const CTRL_C = String.fromCharCode(3)
+const CTRL_D = String.fromCharCode(4)
+const DEL = String.fromCharCode(127)
+
+function loadPolicy() {
+  try {
+    return resolvePolicy(JSON.parse(readFileSync(configFile(), 'utf8')))
+  } catch {
+    return resolvePolicy({})
+  }
+}
+
+/** Read one visible line (used for the username). */
+function prompt(query) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(query, (ans) => {
+      rl.close()
+      resolve(ans.trim())
+    })
+  })
+}
+
+/** Read one line with echo masked (raw mode on a TTY; plain read otherwise). */
+function promptHidden(query) {
+  return new Promise((resolve) => {
+    const { stdin, stdout } = process
+    stdout.write(query)
+    const wasRaw = Boolean(stdin.isRaw)
+    if (stdin.isTTY) stdin.setRawMode(true)
+    stdin.resume()
+    let input = ''
+    const onData = (buf) => {
+      for (const ch of buf.toString('utf8')) {
+        if (ch === '\n' || ch === '\r' || ch === CTRL_D) {
+          if (stdin.isTTY) stdin.setRawMode(wasRaw)
+          stdin.pause()
+          stdin.removeListener('data', onData)
+          stdout.write('\n')
+          resolve(input)
+          return
+        } else if (ch === CTRL_C) {
+          if (stdin.isTTY) stdin.setRawMode(wasRaw)
+          stdout.write('\n')
+          process.exit(130)
+        } else if (ch === DEL || ch === '\b') {
+          input = input.slice(0, -1)
+        } else if (ch >= ' ') {
+          input += ch
+        }
+      }
+    }
+    stdin.on('data', onData)
+  })
+}
+
+function fail(message) {
+  console.error(`dsh-auth: ${message}`)
+  process.exit(1)
+}
+
+/** Resolve and validate a new password from the TTY (or bootstrap env). */
+async function readNewPassword(policy) {
+  const bootstrap = process.env.DSH_AUTH_BOOTSTRAP_PASSWORD
+  let pw
+  if (bootstrap) {
+    pw = bootstrap
+  } else {
+    pw = await promptHidden('Password: ')
+    const confirm = await promptHidden('Confirm password: ')
+    if (pw !== confirm) fail('passwords do not match')
+  }
+  const strength = assessPasswordStrength(pw, { minLength: policy.minPasswordLength })
+  if (!strength.ok) fail(strength.reason)
+  return pw
+}
+const USAGE = `Usage: dsh-auth <command> [username]
+
+Commands:
+  add-user <username>   Create a user (prompts for a password).
+  passwd <username>     Change a user's password.
+  list                  List users.
+  remove <username>     Delete a user.
+  disable <username>    Disable a user (keeps the record; blocks login).
+  enable <username>     Re-enable a disabled user.
+
+Environment:
+  DSH_HOME                      Auth data root (default ~/.dsh); data in $DSH_HOME/auth.
+  DSH_AUTH_BOOTSTRAP_USER       Username for non-interactive add-user.
+  DSH_AUTH_BOOTSTRAP_PASSWORD   Password for non-interactive add-user/passwd.
+`
+
+async function main() {
+  const [cmd, argUser] = process.argv.slice(2)
+  const store = createUserStore({ path: usersFile() })
+  const policy = loadPolicy()
+
+  switch (cmd) {
+    case 'add-user': {
+      const username = (argUser || process.env.DSH_AUTH_BOOTSTRAP_USER || '').trim() || (await prompt('Username: '))
+      if (!username) fail('username required')
+      if (await store.getUser(username)) fail(`user "${username}" already exists (use passwd to change it)`)
+      const password = await readNewPassword(policy)
+      const record = await hashPassword(password, policy.scrypt)
+      await store.upsertUser(username, { password: record, disabled: false })
+      console.log(`Created user "${username}" in ${usersFile()}`)
+      break
+    }
+    case 'passwd': {
+      const username = (argUser || '').trim()
+      if (!username) fail('username required')
+      if (!(await store.getUser(username))) fail(`no such user "${username}"`)
+      const password = await readNewPassword(policy)
+      const record = await hashPassword(password, policy.scrypt)
+      await store.upsertUser(username, { password: record })
+      console.log(`Updated password for "${username}"`)
+      break
+    }
+    case 'list': {
+      const users = await store.listUsers()
+      if (users.length === 0) {
+        console.log(`No users yet (${usersFile()})`)
+        break
+      }
+      users.sort((a, b) => a.username.localeCompare(b.username))
+      for (const u of users) {
+        const when = u.updatedAt ? new Date(u.updatedAt).toISOString() : '-'
+        console.log(`${u.disabled ? '[disabled] ' : ''}${u.username}\t${when}`)
+      }
+      break
+    }
+    case 'remove': {
+      const username = (argUser || '').trim()
+      if (!username) fail('username required')
+      const ok = await store.removeUser(username)
+      if (!ok) fail(`no such user "${username}"`)
+      console.log(`Removed "${username}"`)
+      break
+    }
+    case 'disable':
+    case 'enable': {
+      const username = (argUser || '').trim()
+      if (!username) fail('username required')
+      const ok = await store.setDisabled(username, cmd === 'disable')
+      if (!ok) fail(`no such user "${username}"`)
+      console.log(`${cmd === 'disable' ? 'Disabled' : 'Enabled'} "${username}"`)
+      break
+    }
+    case undefined:
+    case '-h':
+    case '--help':
+      process.stdout.write(USAGE)
+      break
+    default:
+      process.stderr.write(USAGE)
+      process.exit(2)
+  }
+}
+
+main().catch((err) => fail(err?.message || String(err)))

package/cordis.patch.yml

@@ -0,0 +1,26 @@
+# dsh-plugin-auth composition patch.
+#
+# Applied as a bundle layer AFTER @deepseek-ai/dsh-web-app. It makes this plugin
+# the SOLE provider of the `webServer` service by:
+#   1. disabling the stock webserver row (no fiber, no provide), and
+#   2. inserting an auth-webserver row that RE-PROVIDES `webServer` via a
+#      subclass of the stock WebServer (src/index.js default export).
+#
+# Hard contract (do not drop): the insert row MUST keep `inject: [webStartup]`
+# and the {host,port} config. Downstream rows — web-runtime (@deepseek-ai/dsh-web-app)
+# and connection — depend on `webServer` being provided and bound; a row that
+# fails to re-provide it leaves them PENDING and boot fails loud.
+#
+# The row `name` is the installed package name and must resolve as a module
+# specifier from the profile (install via tarball; see README "Install").
+
+- id: webserver
+  disabled: true
+
+- insert:
+    - id: auth-webserver
+      name: dsh-plugin-auth
+      inject: [webStartup]
+      config:
+        host: !!js ctx.webStartup.host ?? '127.0.0.1'
+        port: !!js ctx.webStartup.port ?? 3080

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "dsh-plugin-auth",
+  "version": "0.1.2",
+  "description": "Enterprise username/password authentication gate for the dsh Web UI. Out-of-tree plugin — no core changes; requires login before any page or API is reachable.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-auth": "./bin/dsh-auth.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/src/gate.js

@@ -0,0 +1,127 @@
+// @ts-check
+/**
+ * The authentication gate: cookie parsing, the allow/deny decision tree, POST
+ * same-origin validation, and session-cookie serialization. Pure module (no
+ * peer imports) — it operates on plain {method, url, headers} request shapes and
+ * node:http-style response objects, so it is fully unit-testable with fakes.
+ */
+
+import { cookieName } from './policy.js'
+import { sanitizeNext } from './login-page.js'
+
+/**
+ * Parse a Cookie header into a name→value map.
+ * @param {unknown} header
+ * @returns {Record<string, string>}
+ */
+export function parseCookies(header) {
+  /** @type {Record<string, string>} */
+  const out = {}
+  if (typeof header !== 'string') return out
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const key = part.slice(0, eq).trim()
+    if (!key) continue
+    let val = part.slice(eq + 1).trim()
+    if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1)
+    try {
+      out[key] = decodeURIComponent(val)
+    } catch {
+      out[key] = val
+    }
+  }
+  return out
+}
+
+/** Read the session token from the request cookies. */
+export function readSessionToken(req, policy) {
+  const cookies = parseCookies(req.headers?.['cookie'])
+  return cookies[cookieName(policy)]
+}
+
+/**
+ * Resolve the session for a request.
+ * @returns {{authenticated: boolean, token?: string, session?: import('./sessions.js').SessionRecord}}
+ */
+export function evaluate(req, sessions, policy) {
+  const token = readSessionToken(req, policy)
+  if (!token) return { authenticated: false }
+  const session = sessions.validate(token)
+  if (!session) return { authenticated: false, token }
+  return { authenticated: true, token, session }
+}
+
+/** A navigation-type GET/HEAD wants an HTML page, so denial should redirect. */
+export function isNavigationGet(req) {
+  const method = (req.method || 'GET').toUpperCase()
+  if (method !== 'GET' && method !== 'HEAD') return false
+  const mode = req.headers?.['sec-fetch-mode']
+  if (typeof mode === 'string' && mode.length) return mode === 'navigate'
+  const accept = String(req.headers?.['accept'] || '')
+  return accept.includes('text/html')
+}
+
+/**
+ * Deny an unauthenticated HTTP request: 302 to the login page for navigations
+ * (preserving the target as ?next), 401 JSON for everything else (API/XHR/POST).
+ */
+export function deny(req, res, policy) {
+  if (isNavigationGet(req)) {
+    const next = sanitizeNext(req.url)
+    const location = `/__auth/login?next=${encodeURIComponent(next)}`
+    res.writeHead(302, { Location: location, 'Cache-Control': 'no-store' })
+    res.end()
+    return
+  }
+  const body = JSON.stringify({ error: 'unauthenticated', login: '/__auth/login' })
+  res.writeHead(401, {
+    'content-type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+    'WWW-Authenticate': 'Session realm="dsh"',
+  })
+  res.end(body)
+}
+
+/**
+ * Same-origin check for state-changing POSTs. Requires Origin (or, failing
+ * that, Referer) to match the request Host, or to be in policy.trustedOrigins.
+ * Absent both headers, it denies (default-deny). This backs up SameSite=Strict.
+ */
+export function isSameOrigin(req, policy) {
+  const host = req.headers?.['host']
+  const origin = req.headers?.['origin']
+  if (typeof origin === 'string' && origin.length) {
+    if (Array.isArray(policy.trustedOrigins) && policy.trustedOrigins.includes(origin)) return true
+    try {
+      if (host && new URL(origin).host === host) return true
+    } catch {
+      /* malformed Origin → fall through to deny */
+    }
+    return false
+  }
+  const referer = req.headers?.['referer']
+  if (typeof referer === 'string' && referer.length) {
+    try {
+      if (host && new URL(referer).host === host) return true
+    } catch {
+      /* malformed Referer → deny */
+    }
+    return false
+  }
+  return false
+}
+
+/** Serialize the Set-Cookie value that establishes a session. */
+export function serializeSessionCookie(token, policy) {
+  const parts = [`${cookieName(policy)}=${token}`, `Path=${policy.cookiePath}`, 'HttpOnly', `SameSite=${policy.sameSite}`]
+  if (policy.secure) parts.push('Secure')
+  return parts.join('; ')
+}
+
+/** Serialize the Set-Cookie value that clears the session cookie. */
+export function serializeClearCookie(policy) {
+  const parts = [`${cookieName(policy)}=`, `Path=${policy.cookiePath}`, 'HttpOnly', `SameSite=${policy.sameSite}`, 'Max-Age=0']
+  if (policy.secure) parts.push('Secure')
+  return parts.join('; ')
+}