kczx-user-management 1.0.0

package/src/index.js

@@ -0,0 +1,1358 @@
+'use strict'
+
+/**
+ * dsh-plugin-user-management — Host half
+ *
+ * An HTTPS remote-access gateway + user administration for the dsh web
+ * surface. The plugin spins up its OWN node:https listener (TLS + self-signed
+ * certs + Host allow-list) that reverse-proxies to the loopback dsh
+ * webserver, with user-management's own user store as the auth:
+ * - Standalone /login page (login + register tabs; first registrant becomes
+ *   admin). Unauthenticated page navigations redirect to /login, API/WS
+ *   traffic is answered 401.
+ * - Optional TOTP two-step verification (RFC 6238): self-service enrollment
+ *   with QR + manual entry, OTP demanded after a correct password at login,
+ *   brute-force lockout, single-use replay guard, and an admin recovery
+ *   reset. See src/totp.js and the /me/totp/* + /users/:id/reset-totp APIs.
+ * - JSON API under /user-management/api: sessions, self service, admin user
+ *   management (list / delete / reset password / role / disable), IP bans,
+ *   and the activity + audit ledgers.
+ * - Everything else (the SPA, dsh /api, /plugins, static) is proxied to the
+ *   loopback dsh web — but only past the auth gate, so the loopback dsh web
+ *   stays unreachable directly and the auth cannot be bypassed.
+ *
+ * Role model: the first account registered into an empty system becomes
+ * admin; later registrations are plain users. Admins manage everyone,
+ * plain users see/change only themselves.
+ *
+ * Data lives in `$DSH_HOME/user-management/` (0600, atomic writes) — see
+ * src/store.js. Self-signed certs live under `$DSH_HOME/user-management/certs/`.
+ *
+ * IDENTITY FOR SIBLING PLUGINS: this plugin provides the cordis service
+ * `user-management` ({ resolveRequest(req), resolveToken(token) }) so any
+ * host-plane plugin can map an incoming request's `um_session` cookie to
+ * `{ id, username, role, ... }` — e.g. to attribute scheduled items, shares
+ * or edits to a user. Consume it with RUNTIME `ctx.inject(['user-management'],
+ * cb)` only (statically injecting an optional service hangs activation);
+ * full examples in the README section 「给其他插件：解析请求的用户身份」 and
+ * on createIdentityService below.
+ *
+ * The network-access layer (gateway-core/proxy/certs + hot-reload + self-heal)
+ * is adapted from dsh-gateway (clarknu/dsh-gateway); the auth backend is
+ * user-management's store (um_session), NOT dsh-gateway's flat HMAC users.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { networkInterfaces } from 'node:os'
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import z from '@deepseek-ai/schemastery'
+import {
+  createStore,
+  dshHome,
+  normalizeIp,
+  tempPassword,
+  StoreError,
+  ACTIVITY_LIMIT_DEFAULT,
+  normalizePermissions,
+} from './store.js'
+import { createTrustedIdentity } from './trusted-identity.js'
+import { otpauthUri } from './totp.js'
+import qrCodeFactory from './vendor/qrcode-generator.js'
+import {
+  SESSION_COOKIE,
+  API_PREFIX,
+  createDecider,
+  parseCookies,
+  isAuditableRequest,
+} from './gate.js'
+import { renderLoginPage } from './login-page.js'
+import { createGateway } from './gateway-core.js'
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+const MAX_BODY_BYTES = 64 * 1024
+const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60
+/**
+ * Compact "what changed" text for a permission edit. The ledger is read by
+ * humans scanning for who loosened or tightened what — a full JSON blob would
+ * bury that, and folder lists can be long.
+ */
+function describePermissionDelta(before, after) {
+  const parts = []
+  for (const key of Object.keys(after)) {
+    const toText = (value) => (Array.isArray(value) ? value.join('|') : value === null ? '' : String(value))
+    const a = toText(after[key])
+    const b = toText(before ? before[key] : undefined)
+    if (a !== b) parts.push(`${key}=${a === '' ? '(none)' : a}`)
+  }
+  return parts.length > 0 ? parts.join(' ') : 'no change'
+}
+
+/** Ledger types a plain user may read about themselves. */
+const SELF_ACTIVITY_TYPES = ['login', 'login_failed', 'logout', 'password_change', 'totp_enabled', 'totp_disabled']
+const ADMIN_ACTIVITY_TYPES = ['login', 'login_failed', 'logout', 'password_change', 'register', 'reset_password', 'role_change', 'delete_user', 'access', 'totp_enabled', 'totp_disabled', 'totp_reset', 'user_created', 'user_disabled', 'user_enabled', 'permission_change', 'audit_clear', 'ban_ip', 'unban_ip']
+const AUDIT_LIMIT_DEFAULT = 200
+/** TOTP brute-force guard: lock an account's OTP check after this many
+ *  consecutive bad codes (the code space is only 10^6, so without this an
+ *  attacker holding the password could grind the 3-valid-codes-per-30s
+ *  window indefinitely). In-memory only — a restart clears it. */
+const OTP_FAIL_LIMIT = 5
+const OTP_LOCKOUT_MS = 60 * 1000
+
+/**
+ * Per-username lockout after consecutive TOTP failures. Deliberately simple:
+ * `fail()` counts, and reaching the limit locks for `lockoutMs` (during which
+ * even a correct code is rejected — pacing attacks defeat count-only guards).
+ */
+function createOtpGuard({ limit = OTP_FAIL_LIMIT, lockoutMs = OTP_LOCKOUT_MS, now = () => Date.now() } = {}) {
+  const state = new Map() // username(lowercased) → { fails, lockedUntil }
+  const keyOf = (username) => String(username || '').toLowerCase()
+  return {
+    fail(username) {
+      const key = keyOf(username)
+      const rec = state.get(key) || { fails: 0, lockedUntil: 0 }
+      rec.fails += 1
+      if (rec.fails >= limit) {
+        rec.lockedUntil = now() + lockoutMs
+        rec.fails = 0
+      }
+      state.set(key, rec)
+    },
+    /** Remaining lockout in ms; 0 = not locked. */
+    locked(username) {
+      const rec = state.get(keyOf(username))
+      if (!rec) return 0
+      return Math.max(0, rec.lockedUntil - now())
+    },
+    reset(username) {
+      state.delete(keyOf(username))
+    },
+  }
+}
+
+/** Self-contained QR SVG for the enrollment URI (white ground, scannable). */
+function totpQrSvg(uri) {
+  const qr = qrCodeFactory(0, 'M')
+  qr.addData(uri)
+  qr.make()
+  return qr.createSvgTag({ cellSize: 5, margin: 2 })
+}
+
+function sendJson(res, status, payload, extraHeaders) {
+  res.writeHead(status, Object.assign({ 'content-type': 'application/json; charset=utf-8' }, extraHeaders || {}))
+  res.end(JSON.stringify(payload))
+}
+
+function readJsonBody(req) {
+  return new Promise((fulfil, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) { reject(new Error('request body too large')); req.destroy(); return }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      try { fulfil(chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString('utf8'))) }
+      catch (error) { reject(new StoreError('bad_json', `invalid JSON body: ${error && error.message}`)) }
+    })
+    req.on('error', reject)
+  })
+}
+
+// Secure because the gateway is HTTPS-only now (the shared-server HTTP gate is gone).
+function sessionCookie(token) {
+  return `${SESSION_COOKIE}=${token}; Path=/; HttpOnly; SameSite=Lax; Secure; Max-Age=${SESSION_TTL_SECONDS}`
+}
+
+function clearedCookie() {
+  return `${SESSION_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Secure; Max-Age=0`
+}
+
+/** Normalize an API path: strip trailing slashes (keep the root). */
+function normalizeApiPath(pathname) {
+  const stripped = pathname.replace(/\/+$/, '')
+  return stripped === '' ? pathname : stripped
+}
+
+function statusForStoreError(error) {
+  switch (error && error.code) {
+    case 'last_admin': return 409
+    case 'not_found': return 404
+    default: return 400
+  }
+}
+
+/**
+ * The full API request handler, factored out for tests. `deps`:
+ * { store, clientIp(req) }.
+ * Anonymous (no session) → 401 on every non-public endpoint; an authenticated
+ * non-admin hitting an admin endpoint → 403. The gateway also 401s anonymous
+ * non-public paths before reaching here (defense in depth), but handleApi is
+ * self-consistent without it so it can be tested on a bare http server.
+ */
+async function handleApi(req, res, deps) {
+  const url = new URL(req.url || '/', 'http://dsh.local')
+  const path = normalizeApiPath(url.pathname)
+  const method = (req.method || 'GET').toUpperCase()
+  const { store } = deps
+  const apiPath = path.startsWith(`${API_PREFIX}/`) ? path.slice(API_PREFIX.length) : path
+
+  const authed = async () => {
+    // A signature-bearing request from the co-located login gateway has no
+    // um_session cookie (it never logged in here) — the trusted identity IS
+    // the session, so the ledgers, the user table and the admin APIs all keep
+    // working behind the single door.
+    if (typeof deps.resolveTrusted === 'function') {
+      const trusted = deps.resolveTrusted(req)
+      if (trusted) return trusted
+    }
+    const cookies = parseCookies(req.headers && req.headers.cookie)
+    return store.resolveSession(cookies[SESSION_COOKIE])
+  }
+
+  // requireAdmin: 401 anonymous, 403 authenticated non-admin, else the admin session.
+  const requireAdmin = async () => {
+    const session = await authed()
+    if (!session) return { ok: false, status: 401, message: '未登录' }
+    if (session.user.role !== 'admin') return { ok: false, status: 403, message: '需要管理员权限' }
+    return { ok: true, session }
+  }
+
+  // ── anonymous endpoints ──────────────────────────────────────────────────
+
+  if (apiPath === '/login' && method === 'POST') {
+    const body = await readJsonBody(req)
+    const username = typeof body.username === 'string' ? body.username.trim() : ''
+    const outcome = await store.checkLogin(username, body.password)
+    if (outcome.result === 'invalid') {
+      await store.appendActivity({ type: 'login_failed', username: username || null, ip: deps.clientIp(req), detail: 'wrong credentials' })
+      return sendJson(res, 401, { error: '用户名或密码错误' })
+    }
+    if (outcome.result === 'disabled') {
+      await store.appendActivity({ type: 'login_failed', username: username, userId: outcome.user.id, ip: deps.clientIp(req), detail: 'account disabled' })
+      return sendJson(res, 403, { error: '账号已被禁用，请联系管理员' })
+    }
+    const user = outcome.user
+    // TOTP step — only revealed AFTER the password is correct (otpRequired in
+    // the response tells the login page to show the code field; a missing or
+    // wrong code never discloses whether the account has TOTP to a caller who
+    // doesn't hold valid credentials).
+    if (user.totpSecret) {
+      const guard = deps.otpGuard || (deps.otpGuard = createOtpGuard())
+      const lockedFor = guard.locked(username)
+      if (lockedFor > 0) {
+        await store.appendActivity({ type: 'login_failed', username, userId: user.id, ip: deps.clientIp(req), detail: 'totp attempts locked' })
+        return sendJson(res, 429, { error: `两步验证失败次数过多，请 ${Math.ceil(lockedFor / 1000)} 秒后再试`, otpRequired: true })
+      }
+      const code = typeof body.otp === 'string' ? body.otp.trim() : ''
+      if (code === '') {
+        return sendJson(res, 401, { error: '请输入两步验证码', otpRequired: true })
+      }
+      const verdict = await store.verifyLoginOtp(user, code)
+      if (!verdict.ok) {
+        guard.fail(username)
+        await store.appendActivity({ type: 'login_failed', username, userId: user.id, ip: deps.clientIp(req), detail: 'invalid totp' })
+        return sendJson(res, 401, { error: '两步验证码错误', otpRequired: true })
+      }
+      guard.reset(username)
+    }
+    const { token } = await store.createSession(user)
+    await store.touchLogin(user)
+    await store.appendActivity({ type: 'login', username: user.username, userId: user.id, ip: deps.clientIp(req) })
+    return sendJson(res, 200, { user: store.publicUser(user) }, { 'set-cookie': sessionCookie(token) })
+  }
+
+  if (apiPath === '/register' && method === 'POST') {
+    const body = await readJsonBody(req)
+    const username = typeof body.username === 'string' ? body.username.trim() : ''
+    const role = store.roleForNextRegistration()
+    // Approval mode (autoActivate off, the default): every self-registration
+    // except the first admin starts DISABLED until an admin enables the
+    // account — the users-table enable button is the approval action. The
+    // bare-handler test harness (no deps.autoActivate) keeps classic
+    // auto-activation so old flows read unchanged.
+    const autoActivate = deps.autoActivate ? deps.autoActivate() === true : true
+    const pending = role !== 'admin' && !autoActivate
+    try {
+      const created = await store.createUser({ username, password: body.password, role, disabled: pending })
+      if (pending) {
+        await store.appendActivity({ type: 'register', username: created.username, userId: created.id, ip: deps.clientIp(req), detail: `role=${role} pending` })
+        return sendJson(res, 200, { user: created, pending: true })
+      }
+      const user = store.findUserByUsername(created.username)
+      const { token } = await store.createSession(user)
+      await store.touchLogin(user)
+      await store.appendActivity({ type: 'register', username: created.username, userId: created.id, ip: deps.clientIp(req), detail: `role=${role}` })
+      return sendJson(res, 200, { user: created }, { 'set-cookie': sessionCookie(token) })
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+  }
+
+  if (apiPath === '/session' && method === 'GET') {
+    const session = await authed()
+    return sendJson(res, 200, {
+      user: session ? store.publicUser(session.user) : null,
+      // Observer mode (merged deployment): this layer sits behind the single
+      // login door, so the client hides everything that only makes sense for a
+      // door of its own — accounts, bans, certificates, 2FA, sign-out — and
+      // shows the ledgers it exists for.
+      observer: typeof deps.observerMode === 'function' ? deps.observerMode() === true : false,
+    })
+  }
+
+  if (apiPath === '/logout' && method === 'POST') {
+    const session = await authed()
+    if (session) {
+      await store.dropSession(session.token)
+      await store.appendActivity({ type: 'logout', username: session.user.username, userId: session.user.id, ip: deps.clientIp(req) })
+    }
+    return sendJson(res, 200, { ok: true }, { 'set-cookie': clearedCookie() })
+  }
+
+  // ── authenticated self service ───────────────────────────────────────────
+
+  if (apiPath === '/me/password' && method === 'POST') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    const body = await readJsonBody(req)
+    const ok = await store.verifyLogin(session.user.username, body.oldPassword)
+    if (!ok) return sendJson(res, 400, { error: '当前密码不正确' })
+    try {
+      await store.setPassword(session.user, body.newPassword)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+    await store.dropUserSessions(session.user.id, session.token)
+    await store.appendActivity({ type: 'password_change', username: session.user.username, userId: session.user.id, ip: deps.clientIp(req) })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  // ── TOTP self-service enrollment ─────────────────────────────────────────
+
+  // Step 1: mint the (pending) secret. The QR + otpauth URI are generated
+  // here so the browser half stays bundle-light.
+  if (apiPath === '/me/totp/setup' && method === 'POST') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    try {
+      const { secret } = await store.startTotpSetup(session.user)
+      const uri = otpauthUri({ username: session.user.username, secret })
+      return sendJson(res, 200, { secret, otpauth: uri, qrSvg: totpQrSvg(uri) })
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, 409, { error: error.message })
+      throw error
+    }
+  }
+
+  // Step 2: prove possession of the secret with a live code.
+  if (apiPath === '/me/totp/activate' && method === 'POST') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    const body = await readJsonBody(req)
+    let activated = false
+    try {
+      activated = await store.activateTotp(session.user, body.code)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, 409, { error: error.message })
+      throw error
+    }
+    if (!activated) return sendJson(res, 400, { error: '动态码不正确，请确认验证器时间已同步后重试' })
+    await store.appendActivity({ type: 'totp_enabled', username: session.user.username, userId: session.user.id, ip: deps.clientIp(req) })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  // Disable: identity re-confirmed by password (a stolen session alone must
+  // not be able to weaken the account). Existing sessions are kept — they
+  // already passed the full login.
+  if (apiPath === '/me/totp/disable' && method === 'POST') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    const body = await readJsonBody(req)
+    const ok = await store.verifyLogin(session.user.username, body.password)
+    if (!ok) return sendJson(res, 400, { error: '登录密码不正确' })
+    try {
+      await store.disableTotp(session.user)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, 409, { error: error.message })
+      throw error
+    }
+    await store.appendActivity({ type: 'totp_disabled', username: session.user.username, userId: session.user.id, ip: deps.clientIp(req) })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  if (apiPath === '/users' && method === 'GET') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    // Each row carries today's consumption: an administrator setting a limit is
+    // looking at the account it applies to, and a plain user wants to see their
+    // own allowance. Null means "no activity recorded today", not zero.
+    const withUsage = (row) => ({ ...row, usage: store.getUsage(row.username) })
+    if (session.user.role === 'admin') return sendJson(res, 200, { users: store.listUsers().map(withUsage) })
+    return sendJson(res, 200, { users: [withUsage(store.publicUser(session.user))] })
+  }
+
+  // ── 内部：接收登录门（dsh-passwords）的会话事件 ──────────────────────────
+  // 合并部署下登录发生在唯一入口，这本「登录记录」只能靠它推过来。凭据就是
+  // 签名身份头本身：只有回环 + 有效 HMAC 才进得来（resolveTrusted 已校验），
+  // 路径因此列在 PUBLIC_PATHS 里（浏览器路径的会话检查对它不适用）。
+  if (apiPath === '/internal/session-event' && method === 'POST') {
+    const trusted = typeof deps.resolveTrusted === 'function' ? deps.resolveTrusted(req) : null
+    if (!trusted) return sendJson(res, 401, { error: 'untrusted' })
+    const body = await readJsonBody(req)
+    const type = typeof body.type === 'string' ? body.type : ''
+    if (!INTERNAL_SESSION_TYPES.has(type)) return sendJson(res, 400, { error: 'unknown event' })
+    await store.appendActivity({
+      type,
+      username: trusted.user.username,
+      userId: trusted.user.id,
+      ip: deps.clientIp(req),
+      detail: typeof body.detail === 'string' && body.detail !== '' ? body.detail : undefined,
+    })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  // ── token usage reporting (any signed-in account) ────────────────────────
+  // dsh's own client projection is the only reliable source of provider
+  // accounting (the gateway cannot see it, and reconstructing it from response
+  // bodies was abandoned as unreliable), so the browser reports DELTAS of that
+  // projection and this side accumulates them into the hourly window the quota
+  // is measured against. Deltas are idempotent from the client's point of view
+  // — it tracks the last cumulative value — so a duplicate report cannot inflate
+  // a quota.
+  if (apiPath === '/usage/report' && method === 'POST') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    const body = await readJsonBody(req)
+    const tokens = Number(body.tokens)
+    if (!Number.isFinite(tokens) || tokens < 0 || tokens > 100_000_000) {
+      return sendJson(res, 400, { error: 'tokens 无效' })
+    }
+    await store.addTokens(session.user.username, Math.round(tokens))
+    return sendJson(res, 200, { ok: true })
+  }
+
+  if (apiPath === '/activity' && method === 'GET') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    const isAdmin = session.user.role === 'admin'
+    const type = url.searchParams.get('type') || undefined
+    const limit = Number(url.searchParams.get('limit')) || ACTIVITY_LIMIT_DEFAULT
+    if (!isAdmin) {
+      const entries = await store.listActivity({ types: SELF_ACTIVITY_TYPES, userId: session.user.id, limit })
+      return sendJson(res, 200, { entries })
+    }
+    const username = url.searchParams.get('username')
+    const target = username ? store.findUserByUsername(username) : null
+    const entries = await store.listActivity({
+      type,
+      userId: username ? (target ? target.id : 'NoSuchUser') : undefined,
+      limit,
+    })
+    return sendJson(res, 200, { entries })
+  }
+
+  if (apiPath === '/audit' && method === 'GET') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    if (session.user.role !== 'admin') return sendJson(res, 403, { error: '需要管理员权限' })
+    const entries = await store.listAudit({
+      username: url.searchParams.get('username') || undefined,
+      method: url.searchParams.get('method') || undefined,
+      path: url.searchParams.get('path') || undefined,
+      statusClass: url.searchParams.get('statusClass') || undefined,
+      limit: Number(url.searchParams.get('limit')) || AUDIT_LIMIT_DEFAULT,
+    })
+    return sendJson(res, 200, { entries })
+  }
+
+  if (apiPath === '/audit' && method === 'DELETE') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    await store.clearAudit()
+    await store.appendActivity({ type: 'audit_clear', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req) })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  const auditDeleteMatch = /^\/audit\/([A-Za-z0-9_-]+)$/.exec(apiPath)
+  if (auditDeleteMatch && method === 'DELETE') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const removed = await store.removeAuditEntry(auditDeleteMatch[1])
+    if (!removed) return sendJson(res, 404, { error: '记录不存在' })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  // ── admin-only IP bans ───────────────────────────────────────────────────
+
+  if (apiPath === '/bans' && method === 'GET') {
+    const session = await authed()
+    if (!session) return sendJson(res, 401, { error: '未登录' })
+    if (session.user.role !== 'admin') return sendJson(res, 403, { error: '需要管理员权限' })
+    return sendJson(res, 200, { bans: store.listBans(), selfIp: deps.clientIp(req) })
+  }
+
+  if (apiPath === '/bans' && method === 'POST') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const body = await readJsonBody(req)
+    const ip = typeof body.ip === 'string' ? body.ip.trim() : ''
+    if (ip === deps.clientIp(req)) return sendJson(res, 400, { error: '不能封禁当前正在使用的 IP' })
+    try {
+      await store.banIp(ip, { note: body.note, by: admin.session.user.username })
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+    await store.appendActivity({ type: 'ban_ip', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `ip=${ip}${body.note ? ` note=${body.note}` : ''}` })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  const unbanMatch = /^\/bans\/(.+)$/.exec(apiPath)
+  if (unbanMatch && method === 'DELETE') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const ip = decodeURIComponent(unbanMatch[1])
+    try {
+      await store.unbanIp(ip)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+    await store.appendActivity({ type: 'unban_ip', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `ip=${ip}` })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  // ── admin-only user administration ───────────────────────────────────────
+
+  if (apiPath === '/users' && method === 'POST') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const body = await readJsonBody(req)
+    try {
+      const created = await store.createUser({ username: body.username, password: body.password, role: body.role || 'user' })
+      await store.appendActivity({ type: 'user_created', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `created=${created.username} role=${created.role}` })
+      return sendJson(res, 200, { user: created })
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+  }
+
+  const disableMatch = /^\/users\/([A-Za-z0-9_-]+)\/disabled$/.exec(apiPath)
+  if (disableMatch && method === 'POST') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const target = store.findUser(disableMatch[1])
+    if (!target) return sendJson(res, 404, { error: '用户不存在' })
+    if (target.id === admin.session.user.id) return sendJson(res, 403, { error: '不能禁用自己的账号' })
+    const body = await readJsonBody(req)
+    const disabled = !!body.disabled
+    try {
+      await store.setDisabled(target, disabled)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+    if (disabled) await store.dropUserSessions(target.id)
+    await store.appendActivity({
+      type: disabled ? 'user_disabled' : 'user_enabled',
+      username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req),
+      detail: `target=${target.username}`,
+    })
+    return sendJson(res, 200, { user: store.publicUser(target) })
+  }
+
+  // ── per-user permissions & quotas (admin) ────────────────────────────────
+  // The account model dsh-passwords used to own: workspace scope, hourly token
+  // cap, daily minutes, sandbox floor, upload/git switches and the policy ban.
+  // GET reads, PUT/PATCH merges a partial patch (absent keys keep their value).
+  const permissionsMatch = /^\/users\/([A-Za-z0-9_-]+)\/permissions$/.exec(apiPath)
+  if (permissionsMatch) {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const target = store.findUser(permissionsMatch[1])
+    if (!target) return sendJson(res, 404, { error: '用户不存在' })
+    if (method === 'GET') return sendJson(res, 200, { user: store.publicUser(target) })
+    if (method === 'PUT' || method === 'PATCH') {
+      const body = await readJsonBody(req)
+      const before = store.publicUser(target).permissions
+      let updated
+      try {
+        updated = await store.setPermissions(target, body)
+      } catch (error) {
+        if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+        throw error
+      }
+      await store.appendActivity({
+        type: 'permission_change',
+        username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req),
+        detail: `target=${target.username} ${describePermissionDelta(before, updated.permissions)}`,
+      })
+      // Banning is a policy action: it takes effect on live sessions at once.
+      if (updated.permissions.banned && !before.banned) await store.dropUserSessions(target.id)
+      return sendJson(res, 200, { user: updated })
+    }
+    return sendJson(res, 405, { error: 'method not allowed' })
+  }
+
+  const adminMatch = /^\/users\/([A-Za-z0-9_-]+)(?:\/(reset-password|reset-totp|role))?$/.exec(apiPath)
+
+  if (adminMatch && method === 'DELETE' && !adminMatch[2]) {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const target = store.findUser(adminMatch[1])
+    if (!target) return sendJson(res, 404, { error: '用户不存在' })
+    if (target.id === admin.session.user.id) return sendJson(res, 403, { error: '不能删除自己的账号' })
+    try {
+      await store.removeUser(target)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+    await store.appendActivity({ type: 'delete_user', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `deleted=${target.username}` })
+    return sendJson(res, 200, { ok: true })
+  }
+
+  if (adminMatch && adminMatch[2] === 'reset-password' && method === 'POST') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const target = store.findUser(adminMatch[1])
+    if (!target) return sendJson(res, 404, { error: '用户不存在' })
+    const generated = tempPassword()
+    await store.setPassword(target, generated)
+    await store.dropUserSessions(target.id)
+    await store.appendActivity({ type: 'reset_password', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `target=${target.username}` })
+    return sendJson(res, 200, { tempPassword: generated })
+  }
+
+  // Admin recovery path for a lost authenticator device: strip the target's
+  // TOTP so they can sign in with the password alone (and re-enroll). Does
+  // not touch their live sessions — this weakens FUTURE logins only, and the
+  // action itself lands in the activity ledger.
+  if (adminMatch && adminMatch[2] === 'reset-totp' && method === 'POST') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const target = store.findUser(adminMatch[1])
+    if (!target) return sendJson(res, 404, { error: '用户不存在' })
+    try {
+      await store.disableTotp(target)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, 409, { error: error.message })
+      throw error
+    }
+    await store.appendActivity({ type: 'totp_reset', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `target=${target.username}` })
+    return sendJson(res, 200, { user: store.publicUser(target) })
+  }
+
+  if (adminMatch && adminMatch[2] === 'role' && method === 'POST') {
+    const admin = await requireAdmin()
+    if (!admin.ok) return sendJson(res, admin.status, { error: admin.message })
+    const target = store.findUser(adminMatch[1])
+    if (!target) return sendJson(res, 404, { error: '用户不存在' })
+    if (target.id === admin.session.user.id) return sendJson(res, 403, { error: '不能修改自己的角色' })
+    const body = await readJsonBody(req)
+    try {
+      await store.setRole(target, body.role)
+    } catch (error) {
+      if (error instanceof StoreError) return sendJson(res, statusForStoreError(error), { error: error.message })
+      throw error
+    }
+    await store.dropUserSessions(target.id)
+    await store.appendActivity({ type: 'role_change', username: admin.session.user.username, userId: admin.session.user.id, ip: deps.clientIp(req), detail: `target=${target.username} role=${target.role}` })
+    return sendJson(res, 200, { user: store.publicUser(target) })
+  }
+
+  return sendJson(res, 404, { error: 'not found' })
+}
+
+/** How often an account's activity counter is allowed to be written. */
+const USAGE_TOUCH_INTERVAL_MS = 60_000
+
+/** Static assets never count as activity (a page load is not "using" the agent). */
+const STATIC_PATH_RE = /\.(?:js|mjs|css|map|woff2?|ttf|otf|png|jpe?g|gif|svg|ico|webp|avif|mp4|webmanifest|txt)$/i
+
+/** In-memory per-account throttle for the usage counter (not persisted). */
+const lastUsageTouch = new Map()
+
+/** Session events the signing gateway may push into the login ledger. */
+const INTERNAL_SESSION_TYPES = new Set(['login', 'login_failed', 'logout'])
+
+// ── schemastery config (the `user-management:` settings namespace) ──────────
+const Config = z.object({
+  enabled: z.boolean().default(true),
+  // Registration approval switch: false (default) puts every self-registered
+  // account (first admin excepted) into the disabled state until an admin
+  // enables it from the users table; true activates registrations immediately.
+  autoActivate: z.boolean().default(false),
+  listenHost: z.string().default('0.0.0.0'),
+  port: z.natural().min(1).max(65535).default(19843),
+  sites: z
+    .array(
+      z.object({
+        hosts: z.array(z.string()).default([]),
+        cert: z.string().default(''),
+        key: z.string().default(''),
+      }),
+    )
+    .default([]), // empty = auto-enumerate all local IPs (see allLocalIPs)
+  // ── merged deployment (dsh-passwords in front) ──────────────────────────
+  // Shared HMAC key (dsh-passwords MCP_INTERNAL_SECRET). When set, a request
+  // arriving from a loopback peer carrying a valid signature is trusted as an
+  // authenticated user: this plugin stops being a login door and becomes the
+  // ledger observer behind the single door. Empty (default) = inert, i.e. the
+  // standalone deployment where this plugin owns the login. See
+  // src/trusted-identity.js for the exact trust conditions.
+  trustedSecret: z.string().default(''),
+  // Accepted signing peers; empty = loopback only (127.0.0.1 / ::1).
+  trustedPeers: z.array(z.string()).default([]),
+  // Serve the gateway listener over plain HTTP. ONLY legal together with a
+  // loopback listenHost: the listener is then reachable by the co-located
+  // dsh-passwords gateway alone, which tunnels WebSocket upgrades as raw TCP
+  // and therefore cannot speak TLS to this hop. Never enable with 0.0.0.0.
+  plaintext: z.boolean().default(false),
+  title: z.string().default('DSH 控制台'),
+  // Reserved (accepted, not wired): the store owns session lifetime, login
+  // failure is not auto-locked (admins set IP bans instead), and handleApi
+  // owns its own body-size cap. Kept for the settings card + forward use.
+  sessionDays: z.natural().min(1).default(7),
+  loginFailLimit: z.natural().min(1).default(5),
+  lockoutSeconds: z.natural().min(1).default(60),
+  maxBodyBytes: z.natural().min(1024).default(16384),
+})
+
+/**
+ * Enumerate every non-loopback local IP (IPv4 + IPv6, including Tailscale):
+ * skips lo/Loopback + vEthernet/virtual/hyper-v interface names, internal
+ * addresses, IPv4 APIPA (169.254.), IPv6 loopback (::1) and link-local
+ * (fe80::). Accepts an optional `interfaces` arg (defaults to
+ * node:os.networkInterfaces()) so the filter is unit-testable with a stub.
+ */
+/** Loopback listener hosts — the only ones a plaintext gateway may bind. */
+function isLoopbackHost(host) {
+  const value = String(host || '').trim().toLowerCase()
+  return value === '127.0.0.1' || value === 'localhost' || value === '::1'
+}
+
+function allLocalIPs(interfaces) {
+  const ifaces = interfaces || (() => { try { return networkInterfaces() } catch { return {} } })()
+  const out = []
+  for (const [name, addrs] of Object.entries(ifaces)) {
+    if (/^(lo|Loopback)/i.test(name)) continue
+    if (/vEthernet|virtual|hyper-v/i.test(name)) continue
+    for (const a of addrs || []) {
+      if (a.internal) continue
+      const addr = a.address || ''
+      if (!addr) continue
+      if (a.family === 'IPv4') {
+        if (addr.startsWith('169.254.')) continue
+        out.push(addr)
+      } else if (a.family === 'IPv6') {
+        if (addr === '::1' || addr.startsWith('fe80:')) continue
+        out.push(addr)
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Auto-site host list: every local IP plus its sslip.io / nip.io wildcard-DNS
+ * aliases. Purely additive SAN coverage — trusting the self-signed cert once
+ * then makes IP, pretty-name and wildcard-DNS access all warning-free. (It
+ * does NOT remove the untrusted-cert warning by itself; for public IPs a real
+ * Let's Encrypt cert via these names is the zero-warning path, and on
+ * Tailscale `tailscale cert` + ts.net names remain the better choice.)
+ */
+function autoSiteHosts(ips) {
+  const list = (ips || []).map(String)
+  return ['localhost', ...list, ...list.flatMap((ip) => [`${ip}.sslip.io`, `${ip}.nip.io`])]
+}
+
+/**
+ * Resolve the effective site list from config + auto-enumerated local IPs.
+ *
+ * MERGE semantics (v0.5.4): the auto-enumerated host list — localhost, every
+ * non-loopback local IP and each IP's sslip.io / nip.io wildcard-DNS alias —
+ * ALWAYS forms the self-signed certificate site, so the gateway stays
+ * reachable on the LAN / Tailscale / loopback out of the box. Configured
+ * sites WITHOUT cert/key are folded into that self-signed site: their hosts
+ * are merged in (de-duplicated), covering names the local NICs can't see —
+ * e.g. a NAT'd public IP routed to this host that no local interface owns.
+ * Configured sites WITH cert/key are kept as independent SNI sites (real
+ * domain certs). Empty cfg.sites is the zero-config default (pure auto).
+ *
+ * Before v0.5.4 a configured sites array REPLACED the auto list entirely,
+ * dropping every local IP + alias and breaking local / LAN / Tailscale
+ * access with 421 (unknown host) the moment a user added any site.
+ */
+function resolveSites(cfg, autoIps) {
+  const configured = (cfg && cfg.sites && cfg.sites.length) ? cfg.sites : []
+  const extraHosts = configured
+    .filter((s) => !s.cert && !s.key)
+    .flatMap((s) => s.hosts || [])
+  const mergedHosts = [...new Set([...autoSiteHosts(autoIps), ...extraHosts])]
+  const domainSites = configured.filter((s) => s.cert || s.key)
+  return [{ hosts: mergedHosts, cert: '', key: '' }, ...domainSites]
+}
+
+/**
+ * The empty-user-store guard. Previously REFUSED to start a non-loopback
+ * listener with no registered users (forcing the first admin registration
+ * onto loopback). Relaxed to a no-op under the zero-config default (Option B):
+ * a non-loopback listener with no users STARTS and the first visitor
+ * registers as admin (the user-management model). The safety message moved
+ * to bootWarnings, which warns (does not refuse) in that case. Always returns
+ * null (safe to apply); kept + exported for tests + forward use.
+ */
+function emptyUsersGuard() {
+  return null
+}
+
+/**
+ * Cordis service `user-management` — lets sibling host-plane plugins resolve
+ * who is behind an incoming request. Extracted as a factory so tests can
+ * exercise it without running the full apply() (which owns the gateway
+ * lifecycle).
+ *
+ * @typedef {Object} UmUser
+ * @property {string} id            stable user id (e.g. `u_3_a1b2c3d4`)
+ * @property {string} username
+ * @property {'admin'|'user'} role
+ * @property {boolean} disabled     always false — disabled users never resolve
+ * @property {number} createdAt     epoch ms
+ * @property {number|null} lastLoginAt
+ *
+ * @example // consumer (any host-plane plugin):
+ *   module.exports = {
+ *     name: 'my-plugin',
+ *     inject: ['webServer'],            // ← do NOT list 'user-management' here;
+ *                                       //   statically injecting an optional
+ *                                       //   service hangs your activation
+ *     apply(ctx) {
+ *       ctx.inject(['user-management'], (scope) => {
+ *         const um = scope['user-management']
+ *         ctx.effect(() => ctx.webServer.register({
+ *           kind: 'prefix', path: '/my-plugin/api',
+ *           handler: async (req, res) => {
+ *             const user = await um.resolveRequest(req)
+ *             if (!user) return sendJson(res, 401, { error: '未登录' })
+ *             if (user.role !== 'admin') return sendJson(res, 403, { error: '需要管理员' })
+ *             // user.username / user.id attribute the action
+ *           },
+ *         }), 'my-plugin: api')
+ *       })
+ *     },
+ *   }
+ *
+ * Both resolvers await the store's async load internally, so the service is
+ * safe to call as soon as it is provided. Unauthenticated / expired sessions
+ * resolve to null; disabled users never resolve (the store drops their
+ * sessions on disable). Browser halves of sibling plugins don't need this
+ * service — they can simply `fetch('/user-management/api/session')`, which
+ * the gateway answers locally with `{ user: {...} | null }`.
+ *
+ * @param {{ store: object, ready: Promise<object> }} opts
+ * @returns {{ resolveRequest(req: object): Promise<UmUser|null>, resolveToken(token: string): Promise<UmUser|null> }}
+ */
+function createIdentityService({ store, ready }) {
+  const withSession = async (token) => {
+    try { await ready } catch { return null } // broken store → nobody resolves
+    const session = await store.resolveSession(token)
+    return session ? store.publicUser(session.user) : null
+  }
+  return {
+    /** Resolve the browser request's `um_session` cookie to its user. */
+    async resolveRequest(req) {
+      const cookies = parseCookies(req.headers && req.headers.cookie)
+      return withSession(cookies[SESSION_COOKIE])
+    },
+    /** Lower-level variant for callers that already extracted the token. */
+    async resolveToken(token) {
+      return withSession(token)
+    },
+  }
+}
+
+const plugin = {
+  name: 'user-management',
+  inject: ['webServer'],
+  __internals: {
+    handleApi,
+    sendJson,
+    readJsonBody,
+    normalizeApiPath,
+    statusForStoreError,
+    sessionCookie,
+    clearedCookie,
+    SELF_ACTIVITY_TYPES,
+    ADMIN_ACTIVITY_TYPES,
+    AUDIT_LIMIT_DEFAULT,
+    Config,
+    emptyUsersGuard,
+    allLocalIPs,
+    autoSiteHosts,
+    createIdentityService,
+    resolveSites,
+    createOtpGuard,
+    totpQrSvg,
+  },
+  apply(ctx, config = {}) {
+    const pluginName = 'user-management'
+    const store = createStore({ home: dshHome() })
+    const ready = store.load().catch((error) => {
+      console.error(`[${pluginName}] store load failed:`, error && error.message)
+      throw error
+    })
+    const socketIp = (req) => normalizeIp(req.socket && req.socket.remoteAddress)
+    // Merged deployment: the co-located dsh-passwords gateway signs the user —
+    // and the real client IP it saw — onto every request it proxies here.
+    // Memoized per request: the decider, both ledger hooks and the API all ask,
+    // and each ask would otherwise re-run the HMAC.
+    // Created inert and (re)built inside every rebuild: `config` here is only
+    // the composition base — the real values live in the settings namespace,
+    // which registers *after* apply() (see refreshTrustedIdentity below). The
+    // closure stays stable so deps/decider can hold it while the secret moves.
+    let trustedBase = createTrustedIdentity({ secret: '' })
+    let trustedCache = new WeakMap()
+    const resolveTrusted = (req) => {
+      if (!req || typeof req !== 'object') return null
+      if (trustedCache.has(req)) return trustedCache.get(req)
+      const session = trustedBase(req)
+      trustedCache.set(req, session)
+      return session
+    }
+    /** Rebuild the verifier from the live settings (secret/peers are hot). */
+    const refreshTrustedIdentity = (cfg) => {
+      trustedBase = createTrustedIdentity({ secret: cfg.trustedSecret, peers: cfg.trustedPeers })
+      trustedCache = new WeakMap()
+    }
+    /** True client IP: the signed upstream value when present, else the socket
+     *  peer. Behind the single door every socket peer is 127.0.0.1, so without
+     *  this the ledgers' IP column — and IP banning — would be meaningless. */
+    const clientIp = (req) => {
+      const trusted = resolveTrusted(req)
+      return (trusted && trusted.clientIp) || socketIp(req)
+    }
+    const deps = { store, clientIp, resolveTrusted }
+
+    // Identity service for sibling plugins (see createIdentityService).
+    ctx.provide('user-management', createIdentityService({ store, ready }))
+
+
+    const dataDir = join(dshHome(), 'user-management')
+    const certsDir = join(dataDir, 'certs')
+
+    const log = (msg) => console.log(`[${pluginName}] ${msg}`)
+    const warn = (msg) => console.warn(`[${pluginName}] ${msg}`)
+    log(`gateway plugin v${pkg.version} starting (pid ${process.pid})`)
+
+    /** The injected webServer service carries the real bound dsh port. */
+    const resolveUpstream = (cfg) => {
+      try {
+        const ws = ctx.webServer
+        if (ws && typeof ws.port === 'number') return `http://127.0.0.1:${ws.port}`
+      } catch { /* fall through */ }
+      warn('user-management: webServer service unavailable — assuming upstream http://127.0.0.1:3080')
+      return 'http://127.0.0.1:3080'
+    }
+
+    // dsh 0.1.2-rc.1+ gates `/` index.html behind a launchToken + signed
+    // browser cookie (dsh-client-connection BrowserAuth). The injected
+    // `connection` service exposes the PUBLIC authenticatedUrl(baseUrl)
+    // builder — the sanctioned way to obtain a token-carrying URL (reading
+    // BrowserAuth.launchToken directly would couple us to a TS-private
+    // field). We hand the gateway a builder that binds the token URL to the
+    // upstream origin at call time, so hot-reloaded upstreams stay in sync.
+    // On 0.1.1-rc.2 (no BrowserAuth) the builder stays null and the proxy
+    // falls through to a plain passthrough — backward compatible.
+    let authenticatedUrlBuilder = null
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['connection'], (fiber) => {
+        try {
+          // ctx.inject delivers a fiber whose `.connection` is the registered
+          // HostConnectionService (cf. the existing settings inject: scope.settings).
+          const conn = (fiber && fiber.connection) || fiber
+          authenticatedUrlBuilder = conn && typeof conn.authenticatedUrl === 'function'
+            ? (origin) => {
+                try { return conn.authenticatedUrl(origin) } catch { return null }
+              }
+            : null
+        } catch { authenticatedUrlBuilder = null }
+      })
+    }
+    // Binds at call time: proxy.js invokes getAuthenticatedUrl(origin) and
+    // needs the token URL string, not the builder function itself. Returning
+    // the bare builder (v0.8.0) made new URL(fn) throw inside the mint and
+    // silently skip cookie minting — masked on 0.1.1-rc.2 where the builder
+    // is null and the plain-proxy fallback was used regardless.
+    const getAuthenticatedUrl = (origin) => (authenticatedUrlBuilder ? authenticatedUrlBuilder(origin) : null)
+
+    // The decider runs on every gateway request: IP-ban check (403) → session
+    // resolve → gate decision (allow/redirect/401). onAccess feeds the activity
+    // ledger; the gateway wires onApiRequest/onWsOpen to the audit ledger.
+    const decider = createDecider({
+      resolveSession: async (token) => { await ready; return store.resolveSession(token) },
+      resolveTrusted,
+      getClientIp: clientIp,
+      isBanned: (ip) => store.isBanned(ip),
+      onAccess: (req, resolved, path) => {
+        store.appendActivity({
+          type: 'access',
+          username: resolved ? resolved.user.username : null,
+          userId: resolved ? resolved.user.id : null,
+          ip: clientIp(req),
+          detail: path,
+        }).catch(() => {})
+      },
+    })
+    const auditEntry = (session, method, path, ip, status, type) => ({
+      type,
+      username: session ? session.user.username : null,
+      userId: session ? session.user.id : null,
+      ip,
+      method,
+      path,
+      status: status === undefined ? null : status,
+    })
+    const auditHooks = {
+      onApiRequest: (req, session, path, status) => {
+        store.appendAudit(auditEntry(session, (req.method || 'GET').toUpperCase(), path, clientIp(req), status, 'api')).catch(() => {})
+      },
+      onWsOpen: (req, session, path) => {
+        store.appendAudit(auditEntry(session, 'WS', path, clientIp(req), null, 'ws')).catch(() => {})
+      },
+    }
+
+    // ── gateway lifecycle: hot-reload (bind-then-swap) + self-heal ────────
+    let settingsScope = null
+    let current = null
+    let currentOptions = null
+    let startedAt = null
+    let lastError = ''
+    let lastOnErrorAt = 0
+    let restarting = false
+    let rebuildChain = Promise.resolve()
+    const resolvedConfig = () => (settingsScope ? settingsScope.get() : config)
+    // Registration approval switch, read per request so settings hot-reload applies.
+    deps.autoActivate = () => resolvedConfig().autoActivate === true
+    // Observer mode = a signing secret is configured, i.e. dsh-passwords owns
+    // the login. Read per request so a settings change flips the UI live.
+    deps.observerMode = () => String(resolvedConfig().trustedSecret || '') !== ''
+    /**
+     * Permissions for a session — the enforcement hooks' one question for the
+     * host half.
+     *
+     * A trusted (signed) session carries no permissions of its own, so the
+     * account record here is the source of truth, matched by username. An
+     * unknown username yields null, which the gateway reads as "unrestricted":
+     * enforcement is a property of the accounts this plugin owns, and inventing
+     * restrictions for a name it has never seen would lock people out mid-migration.
+     */
+    /**
+     * Quota gate for the request path: accrue activity, then refuse once a
+     * daily-minute or hourly-token allowance is spent.
+     *
+     * Only accounts that carry a limit are tracked at all — an account with no
+     * limits must not pay a usage write for every request it makes. Accrual is
+     * throttled by wall clock, and the elapsed time since the previous touch is
+     * what gets added, so the counter tracks real activity rather than request
+     * count.
+     *
+     * @returns {string|null} a refusal reason, or null to proceed.
+     */
+    deps.quotaRefusal = (session, path) => {
+      const username = session && session.user && session.user.username
+      if (typeof username !== 'string' || username === '') return null
+      const user = store.findUserByUsername(username)
+      if (!user) return null
+      const perms = normalizePermissions(user.permissions)
+      const daily = perms.dailyMinuteLimit
+      const hourly = perms.hourlyTokenLimit
+      if (daily === null && hourly === null) return null
+      if (typeof path === 'string' && STATIC_PATH_RE.test(path)) return null
+
+      const ts = Date.now()
+      const previous = lastUsageTouch.get(username) || 0
+      if (ts - previous >= USAGE_TOUCH_INTERVAL_MS) {
+        lastUsageTouch.set(username, ts)
+        // Fire and forget: a quota counter must never add latency to a request.
+        void store.touchUsage(username, previous === 0 ? 0 : (ts - previous) / 1000).catch(() => {})
+      }
+      const usage = store.getUsage(username)
+      if (!usage) return null
+      if (daily !== null && usage.activeSeconds >= daily * 60) return '每日时长配额已用完'
+      if (hourly !== null && usage.hourlyTokens >= hourly) return '每小时 token 配额已用完'
+      return null
+    }
+
+    /**
+     * Workspace ownership, exposed to the gateway's enforcement hooks.
+     *
+     * The gateway owns no storage: it asks these four questions and applies the
+     * answers, which keeps the ownership policy testable at the store level and
+     * the HTTP mechanics testable at the proxy level.
+     */
+    // Error → status mapping lives with the store's own error types.
+    deps.statusForError = (error) => statusForStoreError(error)
+    deps.workspaceOwners = () => store.workspaceOwners()
+    deps.claimWorkspace = (path, username) => store.claimWorkspace(path, username)
+    deps.releaseWorkspace = (path) => store.releaseWorkspace(path)
+    deps.renameWorkspace = (oldPath, newPath) => store.renameWorkspace(oldPath, newPath)
+
+    deps.permissionsFor = (session) => {
+      const username = session && session.user && session.user.username
+      if (typeof username !== 'string' || username === '') return null
+      const user = store.findUserByUsername(username)
+      if (!user) return null
+      return normalizePermissions(user.permissions)
+    }
+
+    const queueRebuild = (force = false) => {
+      rebuildChain = rebuildChain
+        .then(async () => {
+          await ready
+          const cfg = resolvedConfig()
+          refreshTrustedIdentity(cfg)
+          if (cfg.enabled === false) {
+            if (current) log('user-management: disabled — listener stopped')
+            restarting = false
+            stopHealthCheck()
+            try { current && current.stop() } catch (e) { warn(`user-management: error stopping listener — ${e.message || e}`) }
+            current = null
+            currentOptions = null
+            startedAt = null
+            return
+          }
+          // Site resolution (MERGE, v0.5.4): auto-enumerated hosts (localhost
+          // + every non-loopback local IP + their sslip.io / nip.io aliases)
+          // always form the self-signed cert site, so the gateway stays
+          // reachable on the LAN/Tailscale/loopback. Configured sites WITHOUT
+          // cert/key fold their hosts into that self-signed site (covers names
+          // the local NICs can't see, e.g. a NAT'd public IP); configured
+          // sites WITH cert/key stay independent SNI sites (real domain
+          // certs). Empty cfg.sites = pure auto (zero-config default).
+          const sites = resolveSites(cfg, allLocalIPs())
+          // Plaintext is legal on loopback only: it exists so the co-located
+          // dsh-passwords gateway can reach this observer through the raw TCP
+          // tunnel it uses for WebSocket upgrades. Any other bind would expose
+          // the observer unencrypted, so it is refused rather than honoured.
+          if (cfg.plaintext && !isLoopbackHost(cfg.listenHost)) {
+            warn(`user-management: plaintext listener pinned to 127.0.0.1 (configured listenHost "${cfg.listenHost}" would serve it unencrypted)`)
+          }
+          const options = {
+            listenHost: cfg.plaintext ? '127.0.0.1' : cfg.listenHost,
+            plaintext: cfg.plaintext === true,
+            port: cfg.port,
+            upstream: resolveUpstream(cfg),
+            getAuthenticatedUrl,
+            sites,
+            certsDir,
+            title: cfg.title,
+            decider,
+            handleApi,
+            renderLoginPage,
+            deps,
+            clearedCookie,
+            auditHooks,
+            log,
+            warn,
+            onError: (error) => {
+              const now = Date.now()
+              if (now - lastOnErrorAt < 30000) {
+                warn('user-management: listener error recurring — suppressing auto-restart')
+                return
+              }
+              lastOnErrorAt = now
+              void queueRebuild(true)
+            },
+          }
+          if (current && !force) {
+            // Two-tier hot reload: request-time fields mutate in place (no gap);
+            // listener-affecting fields restart the server.
+            const restartNeeded =
+              currentOptions.listenHost !== options.listenHost ||
+              currentOptions.plaintext !== options.plaintext ||
+              currentOptions.port !== options.port ||
+              currentOptions.upstream !== options.upstream ||
+              JSON.stringify(currentOptions.sites) !== JSON.stringify(options.sites)
+            if (!restartNeeded) {
+              restarting = false
+              Object.assign(currentOptions, options)
+              currentOptions.sites = options.sites
+              return
+            }
+            log('user-management: listener settings changed — restarting')
+          }
+          // A listener swap tears down the very connection that requested it.
+          // Give the in-flight response a beat to flush before closing the old server.
+          if (current) await new Promise((resolve) => setTimeout(resolve, 120))
+          restarting = true
+          stopHealthCheck()
+          try { current && current.stop() } catch (e) { warn(`user-management: error stopping previous listener — ${e.message || e}`) }
+          current = null
+          currentOptions = null
+          startedAt = null
+          lastError = ''
+          try {
+            const next = createGateway(options)
+            const port = await next.start() // bind-then-swap: only publish `current` after a successful bind
+            current = next
+            currentOptions = options
+            startedAt = new Date().toISOString()
+            restarting = false
+            bootWarnings(cfg, sites, port)
+            startHealthCheck()
+          } catch (error) {
+            restarting = false
+            stopHealthCheck()
+            lastError = error.message || String(error)
+            warn(`user-management: failed to apply configuration, gateway is down — ${lastError}`)
+          }
+        })
+        .catch(() => {}) // a contained rebuild never poisons the chain
+      return rebuildChain
+    }
+
+    function bootWarnings(cfg, sites, port) {
+      const listenHost = String((cfg && cfg.listenHost) || '')
+      const loopbackOnly = /^(127\.0\.0\.1|::1|localhost)$/i.test(listenHost)
+      if (!loopbackOnly && store.listUsers().length === 0) {
+        warn(`user-management: non-loopback listener with no registered users — the first visitor will register as admin; ensure the network is trusted (or register the first admin on loopback 127.0.0.1:${port} first)`)
+      }
+      const hosts = (sites || []).flatMap((s) => s.hosts || [])
+      // After MERGE the self-signed site always carries localhost + every
+      // local IP, so this warning only fires when there genuinely is no
+      // non-loopback host anywhere (no local NICs + nothing configured) —
+      // i.e. the gateway is about to be exposed with no reachable name.
+      const hasNonLoopbackHost = hosts.some((h) => h && h !== 'localhost' && !/^(127\.|::1$)/.test(h))
+      if (!hasNonLoopbackHost) {
+        warn(`user-management: listening on port ${port} but no public hostname is configured — add sites[].hosts before exposing it`)
+      }
+    }
+
+    // ── self-heal: 60s HTTPS probe, rebuild only after 3 consecutive failures ─
+    let healthTimer = null
+    let checking = false
+    let healthFails = 0
+    const HEALTH_FAIL_LIMIT = 3
+
+    // Self-heal probe picks the first non-loopback IPv4 (falls back to loopback).
+    const primaryIPv4 = () => allLocalIPs().find((ip) => ip.includes('.')) || null
+
+    // Plaintext twin of probeHttps — see the call site: probing a plaintext
+    // listener with TLS would fail 3× and rebuild it in a loop forever.
+    const probeHttp = (host, port, timeoutMs = 4000) =>
+      new Promise((resolve) => {
+        let settled = false
+        const done = (ok) => { if (settled) return; settled = true; req.destroy(); resolve(ok) }
+        const req = httpRequest(
+          { host, port, path: '/', method: 'GET', timeout: timeoutMs, headers: { Host: host } },
+          (res) => { res.resume(); done(true) },
+        )
+        req.on('timeout', () => done(false))
+        req.on('error', () => done(false))
+        req.end()
+      })
+
+    const probeHttps = (host, port, timeoutMs = 4000) =>
+      new Promise((resolve) => {
+        let settled = false
+        const done = (ok) => { if (settled) return; settled = true; req.destroy(); resolve(ok) }
+        const req = httpsRequest(
+          { host, port, path: '/', method: 'GET', rejectUnauthorized: false, timeout: timeoutMs, headers: { Host: host } },
+          (res) => { res.resume(); done(true) },
+        )
+        req.on('timeout', () => done(false))
+        req.on('error', () => done(false))
+        req.end()
+      })
+
+    const startHealthCheck = () => { stopHealthCheck(); healthTimer = setInterval(() => { void checkHealth() }, 60000); healthTimer.unref && healthTimer.unref() }
+    const stopHealthCheck = () => { if (healthTimer) { clearInterval(healthTimer); healthTimer = null } }
+    const checkHealth = async () => {
+      const gw = current
+      if (!gw || typeof gw.port !== 'number' || checking) return
+      checking = true
+      try {
+        const host =
+          currentOptions && currentOptions.listenHost === '0.0.0.0'
+            ? (primaryIPv4() || '127.0.0.1')
+            : ((currentOptions && currentOptions.listenHost) || '127.0.0.1')
+        const probe = (currentOptions && currentOptions.plaintext === true) ? probeHttp : probeHttps
+        const ok = await probe(host, gw.port)
+        if (current !== gw) return
+        if (ok) { if (healthFails > 0) healthFails = 0; return }
+        healthFails += 1
+        if (healthFails >= HEALTH_FAIL_LIMIT) {
+          healthFails = 0
+          warn(`user-management: listener health check failed ${HEALTH_FAIL_LIMIT}x consecutively — not serving, restarting`)
+          await queueRebuild(true)
+        } else {
+          warn(`user-management: HTTPS health check failed (${healthFails}/${HEALTH_FAIL_LIMIT}) — will retry`)
+        }
+      } finally {
+        checking = false
+      }
+    }
+
+    // ── /user-management/panel — admin-only status (reached via the gateway proxy) ─
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'prefix',
+      path: '/user-management/panel',
+      handler: async (req, res) => {
+        const method = (req.method || 'GET').toUpperCase()
+        if (method !== 'GET' && method !== 'HEAD') return sendJson(res, 405, { error: 'method not allowed' })
+        await ready
+        const cookies = parseCookies(req.headers && req.headers.cookie)
+        const session = await store.resolveSession(cookies[SESSION_COOKIE])
+        if (!session || session.user.role !== 'admin') return sendJson(res, 403, { error: '需要管理员权限' })
+        const cfg = resolvedConfig()
+        const phase = cfg.enabled === false ? 'disabled' : restarting ? 'restarting' : current ? 'running' : lastError ? 'error' : 'stopped'
+        return sendJson(res, 200, {
+          version: pkg.version,
+          enabled: cfg.enabled !== false,
+          phase,
+          startedAt,
+          lastError,
+          listenHost: cfg.listenHost,
+          port: (current && current.port) || cfg.port,
+          sites: (cfg.sites || []).map((s) => ({ hosts: s.hosts || [], cert: s.cert ? 'file' : 'auto' })),
+          users: store.listUsers().length,
+        })
+      },
+    }), `${pluginName}: panel route`)
+
+    // ── settings namespace: hot-reload on every committed change ────────────
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['settings'], (scope) => {
+        try {
+          const registration = scope.settings.register('user-management', Config, { base: config })
+          settingsScope = registration
+          registration.watch(() => { void queueRebuild() })
+          void queueRebuild()
+        } catch (error) {
+          warn(`user-management: settings namespace unavailable, using the composition config only — ${error.message || error}`)
+          void queueRebuild()
+        }
+      })
+    }
+
+    // Profiles without a settings service still get the gateway from composition config.
+    void queueRebuild()
+
+    ctx.on('dispose', () => {
+      stopHealthCheck()
+      if (current) log('user-management: plugin disposed — stopping listener')
+      try { current && current.stop() } catch (e) { warn(`user-management: error stopping listener on dispose — ${e.message || e}`) }
+      current = null
+    })
+  },
+}
+
+export default plugin