dsh-plugin-auth 0.1.2

package/src/index.js

@@ -0,0 +1,267 @@
+// @ts-check
+/**
+ * dsh-plugin-auth — the authentication gate for the dsh Web UI.
+ *
+ * Strategy: subclass-and-reprovide. This module's default export subclasses the
+ * stock WebServer and becomes the SOLE provider of the `webServer` service (the
+ * bundle patch disables the stock row and inserts this one). Every route a
+ * consumer registers — the SPA fallback, /api, /plugins, WebSocket upgrades, and
+ * anything added later — is wrapped in an auth gate, so there is one choke point.
+ *
+ * The plugin's own /__auth/* surface is registered via `super.register`, which
+ * bypasses the override and stays UNGATED, so the login page is reachable while
+ * logged out. This is the only module that imports the webserver peer.
+ */
+
+import { readFileSync } from 'node:fs'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { resolvePolicy } from './policy.js'
+import { createSessionStore } from './sessions.js'
+import { createLockout } from './lockout.js'
+import { createUserStore } from './users.js'
+import { verifyPassword, DUMMY_RECORD } from './passwords.js'
+import {
+  evaluate,
+  deny,
+  isSameOrigin,
+  readSessionToken,
+  serializeSessionCookie,
+  serializeClearCookie,
+} from './gate.js'
+import { renderLoginPage, sanitizeNext } from './login-page.js'
+import { usersFile, configFile } from './paths.js'
+
+const AUTH_PREFIX = '/__auth'
+const MAX_FORM_BYTES = 64 * 1024
+
+// NOTE: helper methods below use an underscore-prefixed PLAIN convention rather
+// than #private fields. Cordis hands consumers this service through a tracking
+// Proxy, and a JS #private brand check throws when `this` is that Proxy; plain
+// members resolve through it (this is why the parent WebServer avoids #private).
+
+/** Best-effort client IP from the raw socket. */
+function clientIp(req) {
+  return req.socket?.remoteAddress || req.connection?.remoteAddress || 'unknown'
+}
+
+/** Read and parse a small login form body (urlencoded or JSON). */
+async function readForm(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > MAX_FORM_BYTES) throw new Error('payload too large')
+    chunks.push(chunk)
+  }
+  const body = Buffer.concat(chunks).toString('utf8')
+  const ct = String(req.headers['content-type'] || '')
+  if (ct.includes('application/json')) {
+    const obj = JSON.parse(body || '{}')
+    return new Map(Object.entries(obj).map(([k, v]) => [k, v == null ? '' : String(v)]))
+  }
+  return new URLSearchParams(body)
+}
+
+export class AuthWebServer extends WebServer {
+  constructor(ctx, config) {
+    super(ctx, config)
+
+    // Load optional policy overrides ($DSH_HOME/auth/config.json). ENOENT is the
+    // normal case; a malformed file is logged and ignored (defaults hold).
+    let overrides = {}
+    try {
+      overrides = JSON.parse(readFileSync(configFile(), 'utf8'))
+    } catch (err) {
+      if (err && /** @type {any} */ (err).code !== 'ENOENT') {
+        this.ctx.logger?.warn?.(`auth: ignoring invalid config.json (${/** @type {any} */ (err).message})`)
+      }
+    }
+
+    this.authPolicy = resolvePolicy(overrides)
+    this.sessions = createSessionStore({ policy: this.authPolicy })
+    this.lockout = createLockout({ policy: this.authPolicy })
+    this.users = createUserStore({ path: usersFile() })
+
+    // Register the ungated auth surface directly on the parent. super.register
+    // bypasses the gate the register() override below installs.
+    super.register({ kind: 'prefix', path: AUTH_PREFIX, handler: (req, res) => this._handleAuth(req, res) })
+
+    // Background sweep of expired sessions; unref so it never holds the process.
+    this.ctx.effect(() => {
+      const timer = setInterval(() => {
+        try {
+          this.sessions.sweep()
+        } catch {
+          /* sweep must never throw into the timer */
+        }
+      }, this.authPolicy.sweepIntervalMs)
+      timer.unref?.()
+      return () => clearInterval(timer)
+    }, 'authWebServer.sessionSweep')
+
+    this.ctx.logger?.info?.('auth: web authentication gate active (login required)')
+  }
+
+  // ── gate wrappers: every consumer registration is guarded ──────────────────
+
+  register(route) {
+    return super.register({ ...route, handler: this._guard(route.handler) })
+  }
+
+  registerFallback(handler) {
+    return super.registerFallback(this._guard(handler))
+  }
+
+  registerUpgrade(route) {
+    const inner = route.handler
+    return super.registerUpgrade({
+      ...route,
+      handler: (req, socket, head) => {
+        const decision = evaluate(req, this.sessions, this.authPolicy)
+        if (decision.authenticated) return inner(req, socket, head)
+        this.ctx.logger?.info?.(`auth: rejected unauthenticated upgrade ${req.url}`)
+        socket.destroy()
+      },
+    })
+  }
+
+  /** Wrap an HTTP handler so it runs only for authenticated requests. */
+  _guard(handler) {
+    return (req, res) => {
+      const decision = evaluate(req, this.sessions, this.authPolicy)
+      if (decision.authenticated) return handler(req, res)
+      return deny(req, res, this.authPolicy)
+    }
+  }
+  // ── the ungated /__auth/* surface ──────────────────────────────────────────
+
+  /** Route the /__auth/* requests. Unknown sub-paths → 404 JSON. */
+  async _handleAuth(req, res) {
+    const url = new URL(req.url ?? '/', 'http://x')
+    const path = url.pathname
+    const method = (req.method || 'GET').toUpperCase()
+    if (path === `${AUTH_PREFIX}/login` && method === 'GET') return this._loginPage(req, res, url)
+    if (path === `${AUTH_PREFIX}/login` && method === 'POST') return this._login(req, res)
+    if (path === `${AUTH_PREFIX}/logout` && method === 'POST') return this._logout(req, res)
+    if (path === `${AUTH_PREFIX}/status` && method === 'GET') return this._status(req, res)
+    return this._json(res, 404, { error: 'not_found' })
+  }
+
+  /** GET /__auth/login — serve the page, or bounce to '/' if already signed in. */
+  _loginPage(req, res, url) {
+    if (evaluate(req, this.sessions, this.authPolicy).authenticated) {
+      res.writeHead(302, { Location: '/', 'Cache-Control': 'no-store' })
+      res.end()
+      return
+    }
+    const next = sanitizeNext(url.searchParams.get('next') || '/')
+    res.writeHead(200, {
+      'content-type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff',
+      'Referrer-Policy': 'same-origin',
+    })
+    res.end(renderLoginPage({ next }))
+  }
+
+  /** POST /__auth/login — validate credentials, set the session cookie. */
+  async _login(req, res) {
+    if (!isSameOrigin(req, this.authPolicy)) {
+      this._audit('login-denied-origin', req)
+      return this._json(res, 403, { error: 'bad_origin' })
+    }
+    const ip = clientIp(req)
+    let form
+    try {
+      form = await readForm(req)
+    } catch {
+      return this._json(res, 400, { error: 'bad_request' })
+    }
+    const username = String(form.get('username') ?? '').trim()
+    const password = String(form.get('password') ?? '')
+    const next = sanitizeNext(String(form.get('next') ?? '/'))
+    const wantsJson = String(req.headers['accept'] || '').includes('application/json')
+
+    const lock = this.lockout.check(username, ip)
+    if (lock.locked) {
+      this._audit('login-locked', req, username)
+      return this._loginFail(
+        res,
+        wantsJson,
+        next,
+        429,
+        'Too many attempts. Try again later.',
+        '尝试次数过多，请稍后再试。',
+        Math.ceil(lock.retryAfterMs / 1000),
+      )
+    }
+
+    const user = await this.users.getUser(username).catch(() => undefined)
+    const record = user && !user.disabled ? user.password : undefined
+    // Always run a scrypt verification (dummy record when unknown/disabled) so
+    // timing stays flat and there is no user-enumeration oracle.
+    const ok = await verifyPassword(password, record ?? DUMMY_RECORD)
+    if (!record || !ok) {
+      this.lockout.recordFailure(username, ip)
+      this._audit('login-failure', req, username)
+      return this._loginFail(
+        res,
+        wantsJson,
+        next,
+        401,
+        'Invalid username or password.',
+        '用户名或密码错误。',
+      )
+    }
+
+    this.lockout.recordSuccess(username, ip)
+    const token = this.sessions.rotate(readSessionToken(req, this.authPolicy), username, { ip })
+    this._audit('login-success', req, username)
+    res.setHeader('Set-Cookie', serializeSessionCookie(token, this.authPolicy))
+    if (wantsJson) return this._json(res, 200, { ok: true, next })
+    res.writeHead(303, { Location: next, 'Cache-Control': 'no-store' })
+    res.end()
+  }
+
+  /** Render (or return as JSON) a login failure with the right status. */
+  _loginFail(res, wantsJson, next, status, apiError, pageError, retryAfterSec) {
+    if (retryAfterSec) res.setHeader('Retry-After', String(retryAfterSec))
+    if (wantsJson) return this._json(res, status, { error: apiError })
+    res.writeHead(status, {
+      'content-type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff',
+    })
+    res.end(renderLoginPage({ next, error: pageError }))
+  }
+
+  /** POST /__auth/logout — revoke the session and clear the cookie. */
+  async _logout(req, res) {
+    if (!isSameOrigin(req, this.authPolicy)) return this._json(res, 403, { error: 'bad_origin' })
+    const token = readSessionToken(req, this.authPolicy)
+    if (token) this.sessions.revoke(token)
+    this._audit('logout', req)
+    res.setHeader('Set-Cookie', serializeClearCookie(this.authPolicy))
+    const wantsJson = String(req.headers['accept'] || '').includes('application/json')
+    if (wantsJson) return this._json(res, 200, { ok: true })
+    res.writeHead(303, { Location: `${AUTH_PREFIX}/login`, 'Cache-Control': 'no-store' })
+    res.end()
+  }
+
+  /** GET /__auth/status — report the current auth state as JSON. */
+  _status(req, res) {
+    const decision = evaluate(req, this.sessions, this.authPolicy)
+    this._json(res, 200, { authenticated: decision.authenticated, user: decision.session?.username ?? null })
+  }
+
+  _json(res, status, obj) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
+    res.end(JSON.stringify(obj))
+  }
+
+  _audit(event, req, username) {
+    this.ctx.logger?.info?.(`auth: ${event} user=${username ?? '-'} ip=${clientIp(req)}`)
+  }
+}
+
+export default AuthWebServer

package/src/lockout.js

@@ -0,0 +1,79 @@
+// @ts-check
+/**
+ * Per-(username, IP) failed-login lockout with exponential backoff. In-memory,
+ * injectable clock. Pure module. Keying on username+IP throttles both targeted
+ * password guessing against one account and spraying from one source, while a
+ * legitimate user on a different IP is unaffected by an attacker's failures.
+ */
+
+/**
+ * @param {object} opts
+ * @param {import('./policy.js').AuthPolicy} opts.policy
+ * @param {() => number} [opts.now]
+ */
+export function createLockout({ policy, now = Date.now } = /** @type {any} */ ({})) {
+  if (!policy) throw new Error('createLockout: policy required')
+  /** @type {Map<string, {fails: number, lockedUntil: number, last: number}>} */
+  const state = new Map()
+
+  /** @param {string} username @param {string} ip */
+  function keyOf(username, ip) {
+    return `${username ?? ''}\n${ip ?? ''}`
+  }
+
+  /** Exponential backoff once the threshold is crossed, capped at lockoutMaxMs. */
+  function backoff(fails) {
+    const over = Math.max(0, fails - policy.lockoutThreshold)
+    const ms = policy.lockoutBaseMs * 2 ** over
+    return Math.min(ms, policy.lockoutMaxMs)
+  }
+
+  /**
+   * @param {string} username @param {string} ip
+   * @returns {{locked: boolean, retryAfterMs: number}}
+   */
+  function check(username, ip) {
+    const k = keyOf(username, ip)
+    const e = state.get(k)
+    if (!e) return { locked: false, retryAfterMs: 0 }
+    const t = now()
+    // A quiet window past any active lock resets the record entirely.
+    if (e.lockedUntil <= t && t - e.last > policy.lockoutWindowMs) {
+      state.delete(k)
+      return { locked: false, retryAfterMs: 0 }
+    }
+    if (e.lockedUntil > t) return { locked: true, retryAfterMs: e.lockedUntil - t }
+    return { locked: false, retryAfterMs: 0 }
+  }
+
+  /**
+   * Record one failed attempt; returns the updated counter and any lock.
+   * @param {string} username @param {string} ip
+   */
+  function recordFailure(username, ip) {
+    const k = keyOf(username, ip)
+    const t = now()
+    const e = state.get(k) ?? { fails: 0, lockedUntil: 0, last: t }
+    // A fresh window (no active lock, long idle) starts the count over.
+    if (t - e.last > policy.lockoutWindowMs && e.lockedUntil <= t) e.fails = 0
+    e.fails += 1
+    e.last = t
+    if (e.fails >= policy.lockoutThreshold) e.lockedUntil = t + backoff(e.fails)
+    state.set(k, e)
+    return { fails: e.fails, lockedUntil: e.lockedUntil, retryAfterMs: Math.max(0, e.lockedUntil - t) }
+  }
+
+  /** Clear the record on a successful login. */
+  function recordSuccess(username, ip) {
+    state.delete(keyOf(username, ip))
+  }
+
+  return {
+    check,
+    recordFailure,
+    recordSuccess,
+    get size() {
+      return state.size
+    },
+  }
+}

package/src/login-page.js

@@ -0,0 +1,180 @@
+// @ts-check
+/**
+ * Self-contained login page: inline CSS/JS and a data-URI favicon, so it is
+ * fully reachable before authentication and never depends on a gated asset.
+ * Pure module (no peer imports). The form POSTs same-origin to /__auth/login.
+ */
+
+/** True if the string contains an ASCII control character (U+0000–U+001F, U+007F). */
+function hasControlChar(s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c < 0x20 || c === 0x7f) return true
+  }
+  return false
+}
+
+/**
+ * Reduce a caller-supplied `next` target to a safe local path, defeating open
+ * redirects. Only single-slash absolute paths pass; protocol-relative (`//`),
+ * backslash, control-char, and auth-namespace targets collapse to '/'.
+ * @param {unknown} next
+ * @returns {string}
+ */
+export function sanitizeNext(next) {
+  if (typeof next !== 'string' || next.length === 0) return '/'
+  if (!next.startsWith('/')) return '/'
+  if (next.startsWith('//') || next.startsWith('/\\')) return '/'
+  if (hasControlChar(next)) return '/'
+  if (next === '/__auth' || next.startsWith('/__auth/')) return '/'
+  return next
+}
+
+/** HTML-escape for safe interpolation into text/attribute contexts. */
+function esc(value) {
+  return String(value).replace(/[&<>"']/g, (c) => {
+    switch (c) {
+      case '&': return '&amp;'
+      case '<': return '&lt;'
+      case '>': return '&gt;'
+      case '"': return '&quot;'
+      default: return '&#39;'
+    }
+  })
+}
+
+// A tiny lock glyph as a data-URI favicon keeps the page free of gated assets.
+const FAVICON =
+  'data:image/svg+xml,' +
+  encodeURIComponent(
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">' +
+      '<path fill="#444" d="M4 7V5a4 4 0 1 1 8 0v2h1v8H3V7h1zm2 0h4V5a2 2 0 1 0-4 0v2z"/></svg>',
+  )
+
+/**
+ * Render the full login document.
+ * @param {{next?: string, error?: string}} [opts]
+ * @returns {string}
+ */
+export function renderLoginPage({ next = '/', error = '' } = {}) {
+  const safeNext = esc(sanitizeNext(next))
+  const errorHtml = error
+    ? `<p class="error" role="alert" aria-live="assertive">${esc(error)}</p>`
+    : '<p class="error" role="alert" aria-live="assertive" hidden></p>'
+  return PAGE.replaceAll('%%FAVICON%%', FAVICON).replace('%%NEXT%%', safeNext).replace('%%ERROR%%', errorHtml)
+}
+
+// PAGE template. Placeholders (%%FAVICON%%, %%NEXT%%, %%ERROR%%) are filled by
+// renderLoginPage; %%NEXT%% and the error text are HTML-escaped before insertion.
+const PAGE = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<meta name="referrer" content="same-origin">
+<meta name="color-scheme" content="light dark">
+<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
+<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#151517">
+<title>登录 · dsh</title>
+<link rel="icon" href="%%FAVICON%%">
+<style>
+  :root {
+    color-scheme: light dark;
+    --dsh-bg-base: rgb(255, 255, 255);
+    --dsh-bg-layer-2: rgb(255, 255, 255);
+    --dsh-input-bg: rgb(249, 250, 251);
+    --dsh-label-primary: rgb(15, 17, 21);
+    --dsh-label-secondary: rgb(97, 102, 107);
+    --dsh-label-tertiary: rgb(129, 133, 140);
+    --dsh-border-l2: rgba(0, 0, 0, .1);
+    --dsh-border-inverted: rgba(0, 0, 0, 0);
+    --dsh-button-fill: rgb(15, 17, 21);
+    --dsh-button-hover: rgb(67, 69, 74);
+    --dsh-button-label: rgb(255, 255, 255);
+    --dsh-error-label: rgb(236, 19, 19);
+    --dsh-error-fill: rgb(254, 242, 242);
+    --dsh-error-border: rgba(236, 19, 19, .18);
+    --dsh-shadow-lv3: 0 0 1px 0 rgba(0, 0, 0, .2),
+      0 0 4px 0 rgba(0, 0, 0, .02), 0 12px 32px 0 rgba(0, 0, 0, .08);
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --dsh-bg-base: rgb(21, 21, 23);
+      --dsh-bg-layer-2: rgb(44, 44, 46);
+      --dsh-input-bg: rgb(27, 27, 28);
+      --dsh-label-primary: rgb(249, 250, 251);
+      --dsh-label-secondary: rgb(207, 211, 214);
+      --dsh-label-tertiary: rgb(173, 178, 184);
+      --dsh-border-l2: rgba(255, 255, 255, .12);
+      --dsh-border-inverted: rgba(255, 255, 255, .06);
+      --dsh-button-fill: rgb(249, 250, 251);
+      --dsh-button-hover: rgb(235, 238, 242);
+      --dsh-button-label: rgb(15, 17, 21);
+      --dsh-error-label: rgb(242, 90, 90);
+      --dsh-error-fill: rgba(242, 90, 90, .12);
+      --dsh-error-border: rgba(242, 90, 90, .22);
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { min-height: 100%; margin: 0; }
+  body { min-height: 100vh; min-height: 100dvh; display: grid; place-items: center; padding: 24px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
+      'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+    -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale;
+    background: var(--dsh-bg-base); color: var(--dsh-label-primary); }
+  .card { width: min(380px, 100%); padding: 28px 24px 24px;
+    background: var(--dsh-bg-layer-2); border: 1px solid var(--dsh-border-inverted);
+    border-radius: 24px; box-shadow: var(--dsh-shadow-lv3); }
+  h1 { margin: 0; font-size: 20px; line-height: 28px; font-weight: 500; letter-spacing: 0; }
+  .sub { margin: 4px 0 20px; color: var(--dsh-label-secondary); font-size: 14px; line-height: 22px; }
+  form { display: flex; flex-direction: column; }
+  label { display: block; margin: 0 0 6px; font-size: 14px; line-height: 22px;
+    color: var(--dsh-label-primary); }
+  label[for=password] { margin-top: 16px; }
+  input[type=text], input[type=password] { width: 100%; height: 32px; padding: 0 8px;
+    font-family: inherit; font-size: 14px; line-height: 22px; color: var(--dsh-label-primary);
+    background: var(--dsh-input-bg); border: 1px solid var(--dsh-border-l2); border-radius: 8px;
+    transition: border-color .2s ease; }
+  input:focus { outline: none; border-color: var(--dsh-label-primary); }
+  button { display: inline-flex; align-items: center; justify-content: center; width: 100%; height: 36px;
+    margin-top: 24px; padding: 0 14px; border: 0; border-radius: 18px; cursor: pointer;
+    font-family: inherit; font-size: 14px; line-height: 22px; font-weight: 400;
+    color: var(--dsh-button-label); background: var(--dsh-button-fill);
+    transition: background .2s ease; }
+  button:hover { background: var(--dsh-button-hover); }
+  button:focus-visible { outline: 2px solid var(--dsh-label-primary); outline-offset: 2px; }
+  .error { margin: 0 0 20px; padding: 9px 11px; border-radius: 8px; font-size: 14px;
+    line-height: 22px; color: var(--dsh-error-label); background: var(--dsh-error-fill);
+    border: 1px solid var(--dsh-error-border); }
+  .error[hidden] { display: none; }
+  .foot { margin: 16px 0 0; text-align: center; color: var(--dsh-label-tertiary);
+    font-size: 12px; line-height: 18px; }
+  @media (prefers-reduced-motion: reduce) {
+    input[type=text], input[type=password], button { transition: none; }
+  }
+  @media (max-width: 480px) {
+    body { padding: 16px; }
+    .card { padding: 24px; }
+  }
+</style>
+</head>
+<body>
+<main class="card" role="main" aria-labelledby="title">
+  <h1 id="title">dsh</h1>
+  <p class="sub">登录以继续</p>
+  %%ERROR%%
+  <form method="POST" action="/__auth/login" autocomplete="on">
+    <input type="hidden" name="next" value="%%NEXT%%">
+    <label for="username">用户名</label>
+    <input id="username" name="username" type="text" autocomplete="username" required
+      autofocus autocapitalize="none" spellcheck="false" enterkeyhint="next">
+    <label for="password">密码</label>
+    <input id="password" name="password" type="password" autocomplete="current-password"
+      required enterkeyhint="go">
+    <button type="submit">登录</button>
+  </form>
+  <p class="foot">仅限授权用户访问。</p>
+</main>
+</body>
+</html>`

package/src/passwords.js

@@ -0,0 +1,112 @@
+// @ts-check
+/**
+ * Password hashing and verification using node:crypto scrypt only. Pure module
+ * (no peer imports) so it runs under `node --test` standalone and is reused by
+ * both the runtime login path and the offline `dsh-auth` CLI.
+ *
+ * Anti-enumeration: an unknown user is verified against {@link DUMMY_RECORD} so
+ * the failing path still spends a full scrypt derivation — the dominant cost —
+ * leaving no timing oracle that distinguishes "no such user" from "wrong password".
+ */
+
+import { randomBytes, scrypt as scryptCb, timingSafeEqual } from 'node:crypto'
+
+/**
+ * @typedef {object} PasswordRecord
+ * @property {'scrypt'} algo
+ * @property {string} salt   base64-encoded random salt.
+ * @property {string} hash   base64-encoded derived key.
+ * @property {number} N
+ * @property {number} r
+ * @property {number} p
+ * @property {number} keylen
+ * @property {number} maxmem
+ */
+
+/** @type {import('./policy.js').ScryptParams} */
+const FALLBACK = { N: 16384, r: 8, p: 1, keylen: 64, maxmem: 64 * 1024 * 1024 }
+
+/**
+ * @param {Buffer} password
+ * @param {Buffer} salt
+ * @param {number} keylen
+ * @param {{N:number,r:number,p:number,maxmem:number}} options
+ * @returns {Promise<Buffer>}
+ */
+function scryptAsync(password, salt, keylen, options) {
+  return new Promise((resolve, reject) => {
+    scryptCb(password, salt, keylen, options, (err, dk) => (err ? reject(err) : resolve(Buffer.from(dk))))
+  })
+}
+
+/**
+ * Hash a plaintext password into a self-describing record (cost params stored
+ * per record so they can be raised later without breaking existing users).
+ * @param {string} password
+ * @param {import('./policy.js').ScryptParams} [params]
+ * @returns {Promise<PasswordRecord>}
+ */
+export async function hashPassword(password, params = FALLBACK) {
+  const salt = randomBytes(16)
+  const { N, r, p, keylen, maxmem } = params
+  const dk = await scryptAsync(Buffer.from(String(password), 'utf8'), salt, keylen, { N, r, p, maxmem })
+  return { algo: 'scrypt', salt: salt.toString('base64'), hash: dk.toString('base64'), N, r, p, keylen, maxmem }
+}
+
+/**
+ * Verify a plaintext password against a record with a constant-time compare.
+ * Callers pass {@link DUMMY_RECORD} for unknown/disabled users to keep timing flat.
+ * @param {string} password
+ * @param {PasswordRecord | undefined | null} record
+ * @returns {Promise<boolean>}
+ */
+export async function verifyPassword(password, record) {
+  if (!record || record.algo !== 'scrypt') return false
+  let expected
+  try {
+    expected = Buffer.from(record.hash, 'base64')
+  } catch {
+    return false
+  }
+  let actual
+  try {
+    const salt = Buffer.from(record.salt, 'base64')
+    actual = await scryptAsync(Buffer.from(String(password), 'utf8'), salt, record.keylen, {
+      N: record.N, r: record.r, p: record.p, maxmem: record.maxmem,
+    })
+  } catch {
+    return false
+  }
+  // timingSafeEqual requires equal lengths; the length branch is reached only
+  // after the (dominant) derivation has run, so it leaks no useful timing.
+  if (actual.length !== expected.length) return false
+  return timingSafeEqual(actual, expected)
+}
+
+/**
+ * A fixed record shaped like a real one, used for the unknown-user branch. The
+ * password will never match; the point is to pay the scrypt cost regardless.
+ * @type {PasswordRecord}
+ */
+export const DUMMY_RECORD = {
+  algo: 'scrypt',
+  salt: Buffer.alloc(16).toString('base64'),
+  hash: Buffer.alloc(FALLBACK.keylen).toString('base64'),
+  N: FALLBACK.N, r: FALLBACK.r, p: FALLBACK.p, keylen: FALLBACK.keylen, maxmem: FALLBACK.maxmem,
+}
+
+/**
+ * Basic password-strength policy: length plus character-class diversity.
+ * @param {string} password
+ * @param {{minLength?: number}} [opts]
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+export function assessPasswordStrength(password, { minLength = 12 } = {}) {
+  const pw = String(password ?? '')
+  if (pw.length < minLength) return { ok: false, reason: `Password must be at least ${minLength} characters.` }
+  const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((re) => re.test(pw)).length
+  if (classes < 3) {
+    return { ok: false, reason: 'Password must include at least 3 of: lowercase, uppercase, digit, symbol.' }
+  }
+  return { ok: true }
+}

package/src/paths.js

@@ -0,0 +1,41 @@
+// @ts-check
+/**
+ * Locates $DSH_HOME/auth/. Self-contained (no peer import): it replicates the
+ * small, stable home-resolution contract of @deepseek-ai/dsh-home-paths
+ * ($DSH_HOME env → ~/.dsh). Being peer-free means the offline `dsh-auth` CLI
+ * works from the plugin directory without the harness on the module path, and
+ * the runtime gate never depends on that package resolving through the profile
+ * module fallback.
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const DSH_HOME_ENV = 'DSH_HOME'
+const DSH_HOME_DIR_NAME = '.dsh'
+
+/**
+ * Resolve the dsh home directory: $DSH_HOME if set (and non-blank), else ~/.dsh.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function resolveDshHome(env = process.env) {
+  const configured = env[DSH_HOME_ENV]
+  if (typeof configured === 'string' && configured.trim().length > 0) return configured
+  return join(homedir(), DSH_HOME_DIR_NAME)
+}
+
+/** @param {NodeJS.ProcessEnv} [env] @returns {string} $DSH_HOME/auth */
+export function authDir(env) {
+  return join(resolveDshHome(env), 'auth')
+}
+
+/** @param {NodeJS.ProcessEnv} [env] @returns {string} $DSH_HOME/auth/users.json */
+export function usersFile(env) {
+  return join(authDir(env), 'users.json')
+}
+
+/** @param {NodeJS.ProcessEnv} [env] @returns {string} $DSH_HOME/auth/config.json */
+export function configFile(env) {
+  return join(authDir(env), 'config.json')
+}