kczx-user-management 1.0.0

package/src/gateway-core.js

@@ -0,0 +1,769 @@
+'use strict'
+
+/**
+ * The user-management gateway server: one listener that terminates TLS
+ * (SNI-selected per-site certificates, self-signed where none are supplied),
+ * enforces a Host allow-list, runs the user-management store-backed auth gate,
+ * serves /login + /user-management/api/* locally, and reverse-proxies
+ * everything else — WebSocket upgrades included — to the loopback dsh
+ * webserver.
+ *
+ * Two listener modes share that whole pipeline:
+ *   - default (node:https) — the standalone deployment, where this gateway IS
+ *     the login door;
+ *   - `plaintext: true` (node:http, loopback only) — the merged deployment,
+ *     where dsh-passwords is the only door and this listener is the ledger
+ *     observer it proxies through.
+ *
+ * Adapted from dsh-gateway (clarknu/dsh-gateway) lib/gateway-core.js. The
+ * dsh-gateway flat-users HMAC auth is replaced by user-management's store:
+ * the routing defers to a `decider` (see src/gate.js createDecider) for the
+ * allow/redirect/401/403 decision, and to `handleApi` for the local API.
+ *
+ * Cordis-free by design: the plugin wrapper (src/index.js) owns config
+ * resolution + lifecycle + hot-reload + self-heal; this module is testable
+ * standalone.
+ */
+
+import { createServer as createHttpServer } from 'node:http'
+import { createServer as createHttpsServer } from 'node:https'
+import { createSecureContext } from 'node:tls'
+import { X509Certificate } from 'node:crypto'
+import { createProxy } from './proxy.js'
+import {
+  clampSessionHistorySandbox,
+  collectIdPathPairs,
+  extractWorkspaceRenamePaths,
+  isWorkspaceCreate,
+  isWorkspaceDeleteOrRename,
+  normalizePath,
+  sanitizeHiddenUnicodeJson,
+  extractPathFromBody,
+  extractWorkspaceId,
+  filterByPathField,
+  findStringField,
+  folderAllowed,
+  forceRejectApproval,
+  isAdminOnlyPluginEndpoint,
+  isGitRequest,
+  isUploadRequest,
+  isWorkspaceRestricted,
+  filterByPathFieldWithPredicate,
+  permissionPresetFromCommand,
+  presetFromSettingsMutate,
+  sandboxPresetRank,
+} from './permissions.js'
+import { loadOrCreateSiteCert } from './certs.js'
+import {
+  SESSION_COOKIE,
+  LOGIN_PAGE_PATH,
+  API_PREFIX,
+  parseCookies,
+  isAuditableRequest,
+  sendUnauthorized,
+  sendForbidden,
+} from './gate.js'
+
+/**
+ * Create a gateway from resolved options. Returns { start, stop, port }.
+ *
+ * options: {
+ *   listenHost, port, upstream, sites, certsDir, title,
+ *   decider,           // async (req) => { action, session?, path? }
+ *   handleApi,         // async (req, res, deps)
+ *   renderLoginPage,   // ({ hasUsers, title }) => html
+ *   deps,              // { store, clientIp } for handleApi
+ *   clearedCookie,     // () => string  (for /logout)
+ *   auditHooks,        // { onApiRequest(req, session, path, status), onWsOpen(req, session, path) }
+ *   log(msg), warn(msg), onError(err)
+ * }
+ */
+function createGateway(options) {
+  // Plaintext mode: the merged deployment's observer listener. See the option
+  // doc in index.js — loopback only, no certificate, reached solely by the
+  // co-located dsh-passwords gateway (which tunnels WS as raw TCP and so
+  // cannot speak TLS on this hop).
+  const plaintext = options.plaintext === true
+  const log = typeof options.log === 'function' ? options.log : () => {}
+  const warn = typeof options.warn === 'function' ? options.warn : log
+  const proxy = createProxy(options.upstream, options.getAuthenticatedUrl, { rewriteResponse: rewritePlanFor })
+
+  /** dsh's workspace-list RPC — the one response this layer rewrites. */
+  const WORKSPACE_LIST_RE = /^\/api\/workspace[.\/]list$/
+  /** dsh's session-creating RPC — the one request this layer inspects. */
+  const SESSION_CREATE_RE = /^\/api\/session[.\/]create([.\/]|$)/
+  /** The paths through which a sandbox preset can be widened. */
+  const SANDBOX_SETTINGS_RE = /^\/api\/settings[.\/]/
+  const SANDBOX_COMMAND_RE = /^\/api\/commands[.\/]execute$/
+  const SANDBOX_RESPOND_RE = /^\/api\/respond$/
+  /** Session history replay — clamped and sanitized for every account. */
+  const SESSION_HISTORY_RE = /^\/api\/session[.\/]history$/
+  /** Hard cap on an inspected request body; over it the request is refused. */
+  const MAX_GATE_BODY = 64 * 1024
+  /** workspaceId → path, harvested from workspace-list responses (see below). */
+  const workspacePathById = new Map()
+
+  function requestPath(req) {
+    try { return new URL(req.url || '/', 'http://dsh.local').pathname } catch { return '' }
+  }
+
+  /**
+   * Ask the host half for an account's permissions. Kept behind deps so this
+   * module stays cordis-free and testable: no store, no policy, just a lookup.
+   */
+  /** Owner map (path → username) as the host half sees it. */
+  function ownerMap() {
+    const read = options.deps && options.deps.workspaceOwners
+    if (typeof read !== 'function') return {}
+    try { return read() || {} } catch { return {} }
+  }
+
+  function sessionUsername(session) {
+    return session && session.user && typeof session.user.username === 'string' ? session.user.username : ''
+  }
+
+  function sessionIsAdmin(session) {
+    return !!(session && session.user && session.user.role === 'admin')
+  }
+
+  function applyWorkspaceChange(method, path) {
+    const change = options.deps && options.deps[method]
+    if (typeof change !== 'function') return
+    try {
+      const result = change.apply(null, path)
+      if (result && typeof result.catch === 'function') result.catch(() => {})
+    } catch { /* ownership bookkeeping must never break a request */ }
+  }
+
+  function permissionsFor(session) {
+    const lookup = options.deps && options.deps.permissionsFor
+    if (typeof lookup !== 'function' || !session) return null
+    try { return lookup(session) } catch { return null }
+  }
+
+  /**
+   * Decide whether a response must be rewritten before the client sees it.
+   *
+   * Today only the workspace list qualifies: an account with a folder allow-list
+   * must not receive entries outside it. The unrestricted case (empty list, or
+   * no account match) returns null and streams through untouched, so the common
+   * path pays nothing.
+   */
+  function rewritePlanFor(req) {
+    if ((req.method || '').toUpperCase() !== 'POST') return null
+    const path = requestPath(req)
+    const perms = permissionsFor(req.umSession)
+
+    if (WORKSPACE_LIST_RE.test(path)) {
+      const session = req.umSession
+      const folderScoped = perms !== null && perms !== undefined && isWorkspaceRestricted(perms.allowedFolders)
+      const ownerScoped = !sessionIsAdmin(session)
+      // An administrator with an unrestricted list has nothing to hide; anyone
+      // else either has a folder allow-list, or must not see other people's
+      // workspaces, or both.
+      if (!folderScoped && !ownerScoped) return null
+      const mine = sessionUsername(session)
+      const isAdmin = sessionIsAdmin(session)
+      return {
+        transform: (parsed) => {
+          // Harvest BEFORE filtering: the cache must also hold workspaces this
+          // account cannot see, so a create aimed at one resolves to a path and
+          // is then correctly refused (rather than looking unidentifiable).
+          collectIdPathPairs(parsed, workspacePathById)
+          const owners = ownerMap()
+          const visible = (candidate) => {
+            if (folderScoped && !folderAllowed(candidate, perms.allowedFolders)) return false
+            if (isAdmin) return true
+            const owner = owners[normalizePath(candidate)]
+            return owner === undefined || owner === mine
+          }
+          const filtered = filterByPathFieldWithPredicate(parsed, 'path', visible)
+          return sanitizeHiddenUnicodeJson(filtered)
+        },
+      }
+    }
+
+    if (SESSION_HISTORY_RE.test(path)) {
+      const allowedMode = perms && typeof perms.sandboxMode === 'string' ? perms.sandboxMode : null
+      return {
+        transform: (parsed) => {
+          // Clamp first (it rewrites values in place), then sanitize: a hidden
+          // character smuggled into a preset name must not survive the rewrite.
+          if (allowedMode !== null) clampSessionHistorySandbox(parsed, allowedMode)
+          return sanitizeHiddenUnicodeJson(parsed)
+        },
+      }
+    }
+
+    return null
+  }
+
+  const sites = (options.sites || [{ hosts: ['localhost'] }]).map((site) => ({
+    hosts: (site.hosts || []).map((h) => String(h).toLowerCase()),
+    cert: site.cert || '',
+    key: site.key || '',
+  }))
+  if (sites.length === 0) sites.push({ hosts: [], cert: '', key: '' })
+
+  const allowList = new Set(sites.flatMap((s) => s.hosts))
+  if (plaintext) {
+    // The signing gateway dials this listener as http://127.0.0.1:<port>, and
+    // a loopback literal is exactly what the auto site list omits (it skips
+    // internal addresses on purpose). Without these the observer would answer
+    // 421 to its only legitimate caller.
+    for (const host of ['127.0.0.1', 'localhost', '::1']) allowList.add(host)
+  }
+  const allowAll = allowList.size === 0
+  if (allowAll) {
+    warn('user-management: no hosts configured — accepting every Host header (set sites[].hosts to restrict)')
+  }
+
+  // Plaintext carries no certificate at all: no TLS context is built, and
+  // certMaterial below stays null so the cert-download endpoints answer 404
+  // and the client's certificate card hides itself (the single door owns TLS).
+  const contexts = plaintext ? [] : sites.map((site) => {
+    const { cert, key } = loadOrCreateSiteCert(site, options.certsDir, log)
+    return {
+      hosts: site.hosts,
+      context: createSecureContext({ cert, key }),
+      certPem: cert,
+      keyPem: key,
+    }
+  })
+  const defaultSite = contexts[0] ?? null
+
+  // Certificate material for the download endpoints. The certificate is
+  // public by nature (broadcast in every TLS handshake) — serving it
+  // unauthenticated is the whole point: a first-time visitor fetches it,
+  // imports it into their trust store, and the self-signed warning goes
+  // away for good. Computed once per gateway instance.
+  let certMaterial = null
+  try {
+    if (defaultSite === null) throw new Error('plaintext listener: no certificate material')
+    const x509 = new X509Certificate(defaultSite.certPem)
+    certMaterial = {
+      pem: defaultSite.certPem,
+      der: x509.raw,
+      fingerprint: x509.fingerprint256,
+      notBefore: x509.validFrom,
+      notAfter: x509.validTo,
+      subject: x509.subject,
+    }
+  } catch { /* malformed cert — the endpoints answer 404 */ }
+  const allHosts = [...new Set(sites.flatMap((s) => s.hosts))]
+
+  /** Host matching: exact, bare wildcard, or *.example.com wildcard. */
+  function hostMatches(pattern, host) {
+    if (pattern === host || pattern === '*') return true
+    if (pattern.startsWith('*.')) {
+      const suffix = pattern.slice(1)
+      return host.endsWith(suffix) && host.length > suffix.length
+    }
+    return false
+  }
+
+  /** Strip port and brackets from a Host header value; lowercase. */
+  function normalizeHost(header) {
+    if (!header) return ''
+    let host = String(header).trim().toLowerCase()
+    if (host.startsWith('[')) {
+      const end = host.indexOf(']')
+      return end === -1 ? host : host.slice(1, end)
+    }
+    const colon = host.lastIndexOf(':')
+    return colon === -1 ? host : host.slice(0, colon)
+  }
+
+  function selectContext(servername) {
+    if (defaultSite === null) return null // plaintext listener: never consulted
+    const name = (servername || '').toLowerCase()
+    for (const entry of contexts) {
+      if (entry.hosts.some((h) => hostMatches(h, name))) return entry.context
+    }
+    return defaultSite.context
+  }
+
+  function hostAllowed(host) {
+    if (allowAll) return true
+    for (const pattern of allowList) {
+      if (hostMatches(pattern, host)) return true
+    }
+    return false
+  }
+
+  const send = (res, status, headers, body) => {
+    res.writeHead(status, headers)
+    res.end(body)
+  }
+  const redirect = (res, location, extraHeaders) =>
+    send(res, 302, Object.assign({ Location: location, 'cache-control': 'no-store' }, extraHeaders || {}), '')
+
+  /** Buffer a request body with a hard cap; null means "could not read it". */
+  function readRequestBody(req, limit) {
+    return new Promise((resolve) => {
+      const chunks = []
+      let size = 0
+      let done = false
+      const finish = (value) => {
+        if (done) return
+        done = true
+        resolve(value)
+      }
+      req.on('data', (chunk) => {
+        size += chunk.length
+        if (size > limit) {
+          finish(null)
+          req.destroy()
+          return
+        }
+        chunks.push(chunk)
+      })
+      req.on('end', () => finish(Buffer.concat(chunks)))
+      req.on('error', () => finish(null))
+      req.on('aborted', () => finish(null))
+    })
+  }
+
+  /**
+   * Path-level gates — no body needed, because the decision is purely
+   * (method, path).
+   *
+   * Two rules, in this order:
+   *   1. The third-party ops surfaces are admin-only for EVERYONE (they sit
+   *      outside the permission model, so no account setting can open them);
+   *   2. otherwise the owning account (role 'admin') is unrestricted — the
+   *      upload/git switches are for the accounts it hands out, exactly how
+   *      dsh-passwords scopes them to sub-users.
+   *
+   * @returns {string|null} a refusal reason, or null to proceed.
+   */
+  function pathGateFor(req) {
+    const session = req.umSession
+    const perms = permissionsFor(session)
+    if (perms === null || perms === undefined) return null
+    const method = (req.method || 'GET').toUpperCase()
+    const path = requestPath(req)
+    const isAdmin = !!(session && session.user && session.user.role === 'admin')
+
+    if (isAdminOnlyPluginEndpoint(method, path)) {
+      return isAdmin ? null : 'this endpoint is available to the owning account only'
+    }
+    if (isAdmin) return null
+    if (perms.allowUpload !== true && isUploadRequest(method, path)) {
+      return 'uploads are disabled for this account'
+    }
+    if (perms.allowGit !== true && isGitRequest(path)) {
+      return 'git and download operations are disabled for this account'
+    }
+    return null
+  }
+
+  /**
+   * Ask the host half whether this account has spent its allowance.
+   *
+   * The host owns the counters (it owns the store); the gateway only asks, so
+   * this module stays free of persistence and policy. A refusal is a plain 403
+   * with the reason, and a broken counter never blocks traffic — an exception
+   * reads as "allowed", because a quota bug must not lock everyone out.
+   */
+  function quotaGateFor(req) {
+    const refuse = options.deps && options.deps.quotaRefusal
+    if (typeof refuse !== 'function') return null
+    const method = (req.method || 'GET').toUpperCase()
+    if (method === 'OPTIONS' || method === 'HEAD') return null
+    try {
+      return refuse(req.umSession, requestPath(req))
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Which inspection, if any, this request needs — and whose rules apply.
+   *
+   * `kind` is the inspection to run: 'folder' guards where a session may be
+   * created, 'settings'/'command' guard against widening the sandbox, 'respond'
+   * forces escalation approvals to a denial.
+   */
+  function gateFor(req) {
+    const method = (req.method || '').toUpperCase()
+    if (method !== 'POST' && method !== 'PUT') return null
+    const perms = permissionsFor(req.umSession)
+    if (perms === null || perms === undefined) return null
+    const path = requestPath(req)
+    const folderScope = isWorkspaceRestricted(perms.allowedFolders)
+    const sandboxScope = typeof perms.sandboxMode === 'string' && perms.sandboxMode !== ''
+    if (folderScope && SESSION_CREATE_RE.test(path)) return { kind: 'folder', perms }
+    // Workspace management is judged for every non-admin: the ownership map and
+    // the creation switch apply even to an account with no folder allow-list.
+    if (!sessionIsAdmin(req.umSession) && (isWorkspaceCreate(path) || isWorkspaceDeleteOrRename(path))) {
+      return { kind: 'workspace', perms, path }
+    }
+    if (sandboxScope && SANDBOX_SETTINGS_RE.test(path)) return { kind: 'settings', perms }
+    if (sandboxScope && SANDBOX_COMMAND_RE.test(path)) return { kind: 'command', perms }
+    if (sandboxScope && SANDBOX_RESPOND_RE.test(path)) return { kind: 'respond', perms }
+    return null
+  }
+
+  /**
+   * Folder gate for session-creating requests.
+   *
+   * A restricted account may only start a session inside a folder it is allowed
+   * to touch. Finding that folder means reading the body, so the body is
+   * buffered and replayed upstream (proxy.sendRequestBody).
+   *
+   * @returns {string|null} null when the request may proceed, else a short
+   *          reason it must be refused. Anything unverifiable is refused:
+   *          an unreadable body is an unknown target, not a permission.
+   */
+  async function inspectGatedRequest(req, gate) {
+    const raw = await readRequestBody(req, MAX_GATE_BODY)
+    if (raw === null) return 'request body unreadable'
+    let parsed = null
+    if (raw.length > 0) {
+      try {
+        parsed = JSON.parse(raw.toString('utf8'))
+      } catch {
+        return 'request body unparseable'
+      }
+    }
+
+    if (gate.kind === 'folder') {
+      let target = extractPathFromBody(parsed)
+      if (target === null) {
+        const id = extractWorkspaceId(parsed)
+        if (id !== null) target = workspacePathById.get(id) ?? null
+        if (target === null) return 'target workspace not identifiable'
+      }
+      if (!folderAllowed(target, gate.perms.allowedFolders)) return 'folder outside the allowed workspace scope'
+    }
+
+    if (gate.kind === 'workspace') {
+      if (gate.perms.allowWorkspaceCreate !== true) {
+        return 'workspace creation and management are disabled for this account'
+      }
+      // A rename carries oldPath/newPath — keys the generic path walker does not
+      // know — so the dedicated extractor goes first. Ordering it the other way
+      // round (as dsh-passwords did) makes every rename look unidentifiable and
+      // fails it closed.
+      const isRename = /(?:rename|update)(?:[.\/]|$)/.test(gate.path)
+      const renamePaths = isRename ? extractWorkspaceRenamePaths(parsed) : null
+      let target = renamePaths !== null ? renamePaths.oldPath : extractPathFromBody(parsed)
+      if (target === null) {
+        const id = extractWorkspaceId(parsed)
+        if (id !== null) target = workspacePathById.get(id) ?? null
+        if (target === null) return 'target workspace not identifiable'
+      }
+      if (isWorkspaceRestricted(gate.perms.allowedFolders) && !folderAllowed(target, gate.perms.allowedFolders)) {
+        return 'folder outside the allowed workspace scope'
+      }
+      const owners = ownerMap()
+      const me = sessionUsername(req.umSession)
+      const existing = owners[normalizePath(target)] === undefined ? null : owners[normalizePath(target)]
+      // Somebody else's workspace is not yours to touch, whatever the switches say.
+      if (existing !== null && existing !== me) return 'this workspace belongs to another account'
+
+      if (isWorkspaceCreate(gate.path)) {
+        if (existing === null) applyWorkspaceChange('claimWorkspace', [target, me])
+      } else {
+        // A rename whose two paths cannot both be read is not authorizable, so it
+        // is refused rather than guessed at.
+        if (isRename && renamePaths === null) return 'rename target not identifiable'
+        if (isRename && renamePaths !== null) {
+          if (isWorkspaceRestricted(gate.perms.allowedFolders) && !folderAllowed(renamePaths.newPath, gate.perms.allowedFolders)) {
+            return 'folder outside the allowed workspace scope'
+          }
+          applyWorkspaceChange('renameWorkspace', [target, renamePaths.newPath])
+        } else if (existing !== null) {
+          // The folder is going away: stop claiming it, or the path would stay
+          // hidden from everyone but an administrator forever.
+          applyWorkspaceChange('releaseWorkspace', [target])
+        }
+      }
+    }
+
+    if (gate.kind === 'settings') {
+      const preset = presetFromSettingsMutate(parsed)
+      const assigned = sandboxPresetRank(gate.perms.sandboxMode)
+      if (preset !== null && sandboxPresetRank(preset) > assigned) {
+        return `sandbox preset "${preset}" is wider than the account's allowance`
+      }
+    }
+
+    if (gate.kind === 'command') {
+      const line = findStringField(parsed, 'line')
+      const preset = line === null ? null : permissionPresetFromCommand(line)
+      if (preset !== null && sandboxPresetRank(preset) > sandboxPresetRank(gate.perms.sandboxMode)) {
+        return `sandbox preset "${preset}" is wider than the account's allowance`
+      }
+    }
+
+    if (gate.kind === 'respond') {
+      // The body is rewritten rather than refused: the answer still has to reach
+      // the host, it just cannot be an escalation granted to a restricted agent.
+      if (parsed !== null && typeof parsed === 'object' && forceRejectApproval(parsed)) {
+        const rewritten = Buffer.from(JSON.stringify(parsed), 'utf8')
+        req.umReplayBody = rewritten
+        req.headers['content-length'] = String(rewritten.length)
+        return null
+      }
+    }
+
+    // The upstream still has to receive the body: hand it back for replay.
+    req.umReplayBody = raw
+    req.headers['content-length'] = String(raw.length)
+    return null
+  }
+
+  /** Wire the operation-audit hook to fire when the response completes. */
+  function wireAudit(req, res, session, path) {
+    const method = (req.method || 'GET').toUpperCase()
+    if (typeof options.auditHooks.onApiRequest === 'function' && isAuditableRequest(method, req.headers && req.headers.accept, path)) {
+      res.on('finish', () => {
+        try { options.auditHooks.onApiRequest(req, session, path, res.statusCode) } catch { /* audit must never break the gate */ }
+      })
+    }
+  }
+
+  async function handleRequest(req, res) {
+    const host = normalizeHost(req.headers.host)
+    if (!hostAllowed(host)) {
+      return send(res, 421, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' }, 'user-management: unknown host')
+    }
+
+    const url = new URL(req.url || '/', `https://${req.headers.host || 'localhost'}`)
+    const path = url.pathname
+    const method = (req.method || 'GET').toUpperCase()
+
+    // The decider runs for every request: it checks IP bans first (403,
+    // login page included), resolves the session, and returns the gate
+    // decision. /login + /logout stay public but are still subject to bans.
+    let decision
+    try {
+      decision = await options.decider(req)
+    } catch {
+      return sendUnauthorized(res)
+    }
+    if (decision.action === 'forbidden') return sendForbidden(res)
+    // Stashed for the response-rewrite hook: the proxy runs after routing and
+    // has no other way to learn whose permissions apply.
+    req.umSession = decision.session || null
+
+    // /user-management/api/cert[?format=der] + /cert-info — public material,
+    // served before the auth gate so a first-time (still untrusted) visitor
+    // can download the cert and bootstrap trust. IP bans still apply (the
+    // decider above ran already).
+    if (certMaterial && method === 'GET' && path === `${API_PREFIX}/cert`) {
+      const wantDer = url.searchParams.get('format') === 'der'
+      return send(res, 200, {
+        'content-type': wantDer ? 'application/x-x509-ca-cert' : 'application/x-pem-file',
+        'content-disposition': `attachment; filename="user-management-gateway.${wantDer ? 'cer' : 'crt'}"`,
+        'cache-control': 'no-store',
+      }, wantDer ? certMaterial.der : certMaterial.pem)
+    }
+    if (certMaterial && method === 'GET' && path === `${API_PREFIX}/cert-info`) {
+      return send(res, 200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }, JSON.stringify({
+        fingerprint: certMaterial.fingerprint,
+        notBefore: certMaterial.notBefore,
+        notAfter: certMaterial.notAfter,
+        subject: certMaterial.subject,
+        hosts: allHosts,
+      }))
+    }
+
+    // /login — standalone login/register page (register tab is default on a
+    // fresh system; first registrant becomes admin). Authed users bounce to /.
+    if (path === LOGIN_PAGE_PATH) {
+      if (method !== 'GET' && method !== 'HEAD') {
+        return send(res, 405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET, HEAD' }, 'method not allowed')
+      }
+      if (decision.session) return redirect(res, '/')
+      const html = options.renderLoginPage({
+        hasUsers: options.deps.store.listUsers().length > 0,
+        title: options.title || 'DSH 控制台',
+      })
+      return send(res, 200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }, html)
+    }
+
+    // /logout — clear the cookie + drop the server session, back to /login.
+    if (path === '/logout') {
+      const cookies = parseCookies(req.headers && req.headers.cookie)
+      const token = cookies[SESSION_COOKIE]
+      if (token) {
+        try { await options.deps.store.dropSession(token) } catch { /* best effort */ }
+      }
+      return redirect(res, LOGIN_PAGE_PATH, { 'Set-Cookie': options.clearedCookie() })
+    }
+
+    // /user-management/api/* — handled locally by the existing API (login,
+    // register, session, self-service, admin user-mgmt, audit, bans). The
+    // decider already gated non-public sub-paths (401 anonymous); handleApi
+    // re-checks authority too.
+    if (path === API_PREFIX || path.startsWith(`${API_PREFIX}/`)) {
+      if (decision.action !== 'allow') {
+        if (decision.action === 'redirect') return redirect(res, decision.location || LOGIN_PAGE_PATH)
+        return sendUnauthorized(res)
+      }
+      wireAudit(req, res, decision.session, path)
+      try {
+        await options.handleApi(req, res, options.deps)
+      } catch (error) {
+        // The host half maps its own error types to status codes (a malformed
+        // request body is a 400, not a server fault); anything it does not name
+        // stays a 500.
+        const toStatus = options.deps && options.deps.statusForError
+        let status = 500
+        if (typeof toStatus === 'function') {
+          try {
+            const mapped = toStatus(error)
+            if (typeof mapped === 'number' && mapped >= 400 && mapped <= 599) status = mapped
+          } catch { /* fall back to 500 */ }
+        }
+        if (!res.headersSent) send(res, status, { 'content-type': 'application/json; charset=utf-8' }, JSON.stringify({ error: String((error && error.message) || error) }))
+        else res.end()
+      }
+      return
+    }
+
+    // /plugins/* — dsh web SPA client-plugin bundles. The SPA's client-modules
+    // loader fetches these WITHOUT the session cookie (crossorigin), so the
+    // auth gate (401 anonymous) breaks plugin loading ("Failed to load
+    // plugins"). They are static SPA assets (no secrets) — proxy publicly to
+    // the loopback dsh web. IP bans already enforced above (the decider ran).
+    if (path.startsWith('/plugins/')) {
+      return proxy.handleRequest(req, res)
+    }
+
+    // /manifest.webmanifest + /favicon.svg — PWA metadata referenced by the
+    // SPA's index.html <link rel="manifest">. Chrome fetches the manifest
+    // WITHOUT credentials (the link carries no crossorigin="use-credentials"),
+    // so the auth gate 401s it even for logged-in users ("Manifest fetch from
+    // ... failed, code 401"). Static, no secrets — proxy publicly. IP bans
+    // already enforced above (the decider ran).
+    if (path === '/manifest.webmanifest' || path === '/favicon.svg') {
+      return proxy.handleRequest(req, res)
+    }
+
+    // Everything else (the SPA, dsh /api, static) is proxied to the loopback
+    // dsh webserver — but only past the auth gate.
+    if (decision.action === 'allow') {
+      const quotaRefusal = quotaGateFor(req)
+      if (quotaRefusal !== null) {
+        return send(res, 403, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+          JSON.stringify({ error: 'usage allowance exhausted', reason: quotaRefusal }))
+      }
+      const pathRefusal = pathGateFor(req)
+      if (pathRefusal !== null) {
+        return send(res, 403, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+          JSON.stringify({ error: 'request not allowed for this account', reason: pathRefusal }))
+      }
+      const gate = gateFor(req)
+      if (gate !== null) {
+        const reason = await inspectGatedRequest(req, gate)
+        if (reason !== null) {
+          return send(res, 403, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+            JSON.stringify({ error: 'request not allowed for this account', reason }))
+        }
+      }
+      wireAudit(req, res, decision.session, path)
+      return proxy.handleRequest(req, res)
+    }
+    if (decision.action === 'redirect') return redirect(res, decision.location || LOGIN_PAGE_PATH)
+    return sendUnauthorized(res)
+  }
+
+  function handleUpgrade(req, socket, head) {
+    const host = normalizeHost(req.headers.host)
+    if (!hostAllowed(host)) {
+      socket.end('HTTP/1.1 421 Misdirected Request\r\nConnection: close\r\n\r\n')
+      return
+    }
+    Promise.resolve()
+      .then(() => options.decider(req))
+      .then((decision) => {
+        if (decision.action === 'allow') {
+          if (typeof options.auditHooks.onWsOpen === 'function') {
+            try { options.auditHooks.onWsOpen(req, decision.session, decision.path) } catch { /* audit must never break the gate */ }
+          }
+          return proxy.handleUpgrade(req, socket, head)
+        }
+        try {
+          socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n')
+        } catch { /* socket may already be gone */ }
+        socket.destroy()
+      })
+      .catch(() => {
+        try { socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch {}
+        socket.destroy()
+      })
+  }
+
+  let server = null
+  let boundPort = null
+
+  async function start() {
+    // The default site's cert/key are passed directly: a server created
+    // with only a SecureContext (no cert/key) sends handshake_failure to
+    // clients that omit SNI — which is every browser connecting to an IP
+    // literal (https://192.168.x.x). cert/key keeps the no-SNI default
+    // context alive; SNICallback then selects per-host contexts.
+    const onRequest = (req, res) => {
+      handleRequest(req, res).catch(() => {
+        if (!res.headersSent) sendUnauthorized(res)
+      })
+    }
+    server = plaintext
+      ? createHttpServer(onRequest)
+      : createHttpsServer(
+        {
+          cert: defaultSite.certPem,
+          key: defaultSite.keyPem,
+          SNICallback: (servername, callback) => callback(null, selectContext(servername)),
+        },
+        onRequest,
+      )
+    server.on('upgrade', handleUpgrade)
+    // TLS-only event: an HTTP listener can never emit it.
+    if (!plaintext) server.on('tlsClientError', (_err, tlsSocket) => tlsSocket && tlsSocket.destroy())
+    await new Promise((resolve, reject) => {
+      const onListening = () => { server.removeListener('error', onError); resolve() }
+      const onError = (err) => { server.removeListener('listening', onListening); reject(err) }
+      server.once('listening', onListening)
+      server.once('error', onError)
+      server.listen({ host: options.listenHost || '0.0.0.0', port: options.port != null ? options.port : 19843 })
+    })
+    boundPort = server.address().port
+    server.on('error', (err) => {
+      warn(`user-management: listener error — ${err.code || err.message}`)
+      if (server !== null && typeof options.onError === 'function') options.onError(err)
+    })
+    log(
+      `user-management: https://${options.listenHost === '0.0.0.0' ? '0.0.0.0' : options.listenHost}:${boundPort} ` +
+        `-> ${options.upstream} (hosts: ${allowAll ? '*' : [...allowList].join(',')})`,
+    )
+    return boundPort
+  }
+
+  function stop() {
+    try { proxy.close() } catch { /* agent teardown must never take the listener down */ }
+    const old = server
+    server = null
+    boundPort = null
+    if (old) {
+      try { old.close() } catch { /* already closed */ }
+      old.closeAllConnections && old.closeAllConnections()
+    }
+  }
+
+  return {
+    start,
+    stop,
+    get port() { return boundPort },
+    /** SHA-256 fingerprint of the certificate presented when no SNI name matches. */
+    defaultCertFingerprint() {
+      try { return new X509Certificate(defaultSite.certPem).fingerprint256 } catch { return '' }
+    },
+  }
+}
+
+export { createGateway }