kczx-user-management 1.0.0

package/client/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# user-management bundle patch: contributes the plugin row into the
+# host composition when this package is installed via `dsh plugin add`.
+#
+# The plugin is HOST-PLANE: it spins up its own node:https gateway listener
+# (TLS + self-signed certs + Host allow-list) that reverse-proxies to the
+# loopback dsh webserver, with its own user store as the auth (login/register
+# page + /user-management/api/* served locally; everything else proxied). It
+# also serves a settings-page management UI from its client half. It must land
+# in the host composition (this insert), never inside an agent preset.
+
+- insert:
+    - id: user-management
+      name: 'kczx-user-management'

package/docs/FAQ.md

@@ -0,0 +1,95 @@
+# 常见问题（FAQ）
+
+> 所有文件级操作的第一原则：**先停 dsh web 再改文件**。user-management 把数据整份缓存在内存里，插件运行期间任何一次写盘（哪怕只是某人登录了一次）都会用内存副本覆盖你手改的文件。停法：`kill -9 $(lsof -tiTCP:19080 -sTCP:LISTEN)`（launchd 会自动拉起新进程），改完文件即已完成——新进程启动时读取的就是你改过的版本。
+
+## 忘记管理员密码 / 用户名怎么办
+
+按代价从小到大三级处理：
+
+### 情况 A：还有一个可用的管理员
+
+让 TA 在 **设置 → 用户管理 → 用户** 里对你「重置密码」——生成随机临时密码（仅展示一次，立即保存），你用临时密码登录后尽快改成自己的密码。忘记的只是用户名的话，问 TA 在用户列表里看一眼即可（用户名是明文存的）。
+
+### 情况 B：只有一个管理员（就是你），账号还能登录但忘了密码
+
+无法找回（密码是 scrypt 加盐哈希，不可逆），只能"重建账号"：
+
+```bash
+# 1. 停 dsh web（见顶部原则）
+kill -9 $(lsof -tiTCP:19080 -sTCP:LISTEN)
+# 2. 编辑 ~/.dsh/user-management/users.json，删掉你这个用户的整个 { ... } 条目
+#    （先看清 username 字段确认删的是自己）
+# 3. 启动后用原用户名重新注册
+```
+
+注意：**重建后角色是普通用户**——继续情况 C 把 role 改回 admin。
+
+### 情况 C：把某个账号（重新）提升为管理员
+
+```bash
+kill -9 $(lsof -tiTCP:19080 -sTCP:LISTEN)
+# 编辑 ~/.dsh/user-management/users.json，找到目标用户，把
+#   "role": "user"
+# 改成
+#   "role": "admin"
+# 保存，重启完成
+```
+
+### 情况 D：什么都不记得了，推倒重来（清空所有用户）
+
+```bash
+kill -9 $(lsof -tiTCP:19080 -sTCP:LISTEN)
+rm ~/.dsh/user-management/users.json ~/.dsh/user-management/sessions.json
+# 重启后系统回到零用户状态，第一个注册的账号成为管理员
+```
+
+副作用：所有用户消失、所有人被登出；封禁列表、审计记录不受影响。
+
+## 把 IP 封错了 / 需要解封
+
+- 界面路径：**设置 → 用户管理 → IP 封禁** → 该行「解封」。
+- 完全进不来时的兜底：停 dsh web → 编辑（或直接删除）`~/.dsh/user-management/bans.json` → 重启。
+- 插件自带两道防误封：回环地址（127.x、::1）服务端直接拒绝；封禁"你当前请求所用的 IP"会被拒绝。所以正常操作不会把自己锁死。
+
+## 浏览器一直弹证书警告
+
+自签证书的警告**只能靠导入信任链消除**，SAN 再全也一样弹。路径：**设置 → 用户管理 → HTTPS 证书** → 下载 PEM（Windows 用 DER）→ 核对指纹 → 复制对应系统的导入命令执行。导入一次永久有效。临时用可以 `curl -k` 跳过校验。公网 IP 部署想要零警告，可用 Let's Encrypt 给 `<ip>.sslip.io` 签真证书（配置 `sites[].cert/key`）；Tailscale 用户优先 `tailscale cert` + ts.net 域名。
+
+## 为什么直连 dsh web 端口（19080/3080）没有登录墙
+
+v0.4 起门禁由本插件**自带的 HTTPS 网关**（默认 `https://<IP>:19843`）承担，不是宿主的 19080。直连 19080 等于绕过网关——**请保证 dsh web 只监听 loopback**（127.0.0.1），对外只暴露 19843。本机 `dsh web` 若被改绑到 0.0.0.0:19080，等于没有认证裸奔。
+
+## 登录后很快又被要求登录
+
+- 必须通过网关的 HTTPS 地址访问（cookie 带 `Secure` 标志，浏览器只在 HTTPS 下收发）——用 `http://` 访问根本登录不上
+- 改密码、被重置密码、被降级角色都会踢掉你的**其他**会话（当前浏览器不受影响）
+- 会话 7 天滑动过期；dsh 重启不掉线（会话落盘在 `sessions.json`）
+
+## 重置密码的临时密码没记下来
+
+临时密码只在弹窗里显示一次，丢了就再点一次「重置密码」生成新的——每次重置都会作废该用户全部旧会话，旧临时密码同时失效。
+
+## 其他插件怎么知道当前请求是哪个用户
+
+消费 cordis 服务 `user-management`（`resolveRequest(req)` / `resolveToken(token)`），浏览器端直接 `fetch('/user-management/api/session')`。完整示例见 README 的「给其他插件：解析请求的用户身份」章节。
+
+## 操作日志 / 审计文件太大了
+
+自动滚动：登录记录保留最近 2000 条、操作日志 5000 条，超限自动裁掉最旧的。手动清空：管理员在「操作日志」页点「清空」（或逐条删除），该操作本身也会留痕。紧急瘦身可停 dsh web 后删除 `activity.jsonl` / `audit.jsonl`。
+
+## 网关没起来 / 端口被占用
+
+```bash
+# 谁占着 19843：
+lsof -iTCP:19843
+# 启动日志（用户管理所有 [user-management] 前缀的输出都在这里）：
+grep user-management ~/.dsh/logs/web.out.log ~/.dsh/logs/web.err.log
+```
+
+- `EADDRINUSE`：19843 被别的进程（或另一个 dsh 实例）占了——杀掉占用者，或在 `~/.dsh/settings.yaml` 的 `user-management:` 段改 `port`
+- 配置了 `enabled: false` 网关不会启动
+- 改了 hosts/证书配置不生效：删除 `~/.dsh/user-management/certs/` 下的旧证书文件再重启（旧证书按指纹稳定复用，不会自动重签）
+
+## 升级 dsh 后网关行为异常
+
+网关是独立监听器，不依赖宿主内部结构，升级宿主一般无感。若异常：先看 `~/.dsh/logs/web.err.log` 里 `[user-management]` 的报错，再到 [GitHub Issues](https://github.com/weibaohui/user-management/issues) 反馈（附日志）。

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "kczx-user-management",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "dsh 插件 · 登录门 + 账号 / 权限 / 配额 / 审计台账（dsh-passwords 的功能已并入）：HTTPS 登录网关与自签证书、用户增删改查、工作区白名单与归属跟踪、每小时 token 与每日时长配额、沙盒档位下限、上传/git 开关、三本审计台账（登录/访问/操作）、IP 封禁、TOTP 两步验证。",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "auth",
+    "login",
+    "gateway",
+    "user-management",
+    "permissions",
+    "quota",
+    "audit",
+    "dsh-plugin"
+  ],
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./client/bundle.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "files": [
+    "src",
+    "client",
+    "scripts",
+    "docs",
+    "cordis.patch.yml",
+    "README.md",
+    "MERGED-DEPLOYMENT.md",
+    "CUTOVER-RUNBOOK.md"
+  ],
+  "scripts": {
+    "check": "node --check src/index.js && node --check src/gate.js && node --check src/store.js && node --check src/totp.js && node --check src/login-page.js && node --check src/proxy.js && node --check src/certs.js && node --check src/gateway-core.js && node --check src/permissions.js && node --check src/trusted-identity.js && node --check client/index.js",
+    "pack:tgz": "npm run build:client && npm pack",
+    "test": "node --test test/*.test.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "ensure:deps": "node scripts/ensure-deps.mjs",
+    "prepublishOnly": "npm run build:client && npm run check && npm test",
+    "prepack": "npm run build:client"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "bcryptjs": "^3.0.3",
+    "selfsigned": "^2.4.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weibaohui/user-management.git"
+  },
+  "homepage": "https://github.com/weibaohui/user-management#readme",
+  "bugs": {
+    "url": "https://github.com/weibaohui/user-management/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build-client.mjs

@@ -0,0 +1,42 @@
+'use strict'
+
+/**
+ * Generate client/bundle.js from client/index.js.
+ *
+ * The upstream package shipped this generated file but not the generator, which
+ * made the browser half unbuildable from source. This reproduces the wrapper
+ * exactly (verified byte-for-byte against the upstream artifact): the source
+ * indented four spaces inside a window.__ModuleLoader__.load({...}) factory,
+ * with the module's package name as the loader id.
+ *
+ * Usage: node scripts/build-client.mjs   (or npm run build:client)
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const sourcePath = join(root, 'client', 'index.js')
+const outputPath = join(root, 'client', 'bundle.js')
+
+const source = readFileSync(sourcePath, 'utf8').replace(/\r\n/g, '\n').replace(/\n$/, '')
+const body = source.split('\n').map((line) => (line.length === 0 ? line : '    ' + line)).join('\n')
+
+const header = [
+  '/* Generated from client/index.js by scripts/build-client.mjs — do not edit by hand.',
+  ' * Regenerate with: npm run build:client',
+  ' */',
+  'window.__ModuleLoader__.load({',
+  `  id: ${JSON.stringify(manifest.name)},`,
+  '  factory: (require) => {',
+  '    var module = { exports: {} }',
+  '    var exports = module.exports',
+  '    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" })',
+  '    var React = require("react")',
+  '',
+].join('\n')
+
+const footer = '\n\n    return module.exports\n  }\n})\n'
+writeFileSync(outputPath, header + body + footer, 'utf8')
+console.log('client/bundle.js written from client/index.js')

package/scripts/ensure-deps.mjs

@@ -0,0 +1,50 @@
+'use strict'
+
+/**
+ * Ensure the one dsh-provided library this plugin needs is present.
+ *
+ * @deepseek-ai/schemastery is part of the harness, not of npm's public graph for
+ * this package: npm either skips it or prunes it on the next install (it is also
+ * declared as a peer of the harness), which would leave the plugin unable to
+ * load at all. Rather than depend on a hand-copied folder surviving, this runs
+ * after install and restores it from the dsh installation that will host the
+ * plugin — the same source the harness itself resolves it from.
+ *
+ * Idempotent: it does nothing when the import already resolves.
+ */
+import { existsSync, mkdirSync, cpSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+const target = join(root, 'node_modules', '@deepseek-ai', 'schemastery')
+if (existsSync(join(target, 'package.json'))) {
+  console.log('[ensure-deps] @deepseek-ai/schemastery already present')
+  process.exit(0)
+}
+
+const home = homedir()
+const candidates = [
+  // dsh's shared package anchor: every profile resolves from here.
+  join(home, '.dsh', 'profiles', 'node_modules', '@deepseek-ai', 'schemastery'),
+  // a checkout's own copy (development machines)
+  'E:/code/dsh/deepseek-harness-master_1/node_modules/@deepseek-ai/schemastery',
+  join(process.env.APPDATA || '', 'npm', 'node_modules', '@deepseek-ai', 'dsh', 'node_modules', '@deepseek-ai', 'schemastery'),
+]
+
+const source = candidates.find((candidate) => candidate && existsSync(join(candidate, 'package.json')))
+if (source === undefined) {
+  console.error('[ensure-deps] could not find @deepseek-ai/schemastery.')
+  console.error('[ensure-deps] Looked in:')
+  for (const candidate of candidates) console.error('  ' + candidate)
+  console.error('[ensure-deps] Install or copy it next to this plugin; without it the plugin cannot load.')
+  process.exit(1)
+}
+
+mkdirSync(dirname(target), { recursive: true })
+// dereference: the source is a pnpm install full of symlinks, and creating
+// symlinks on Windows needs privileges this script must not assume.
+cpSync(source, target, { recursive: true, dereference: true })
+console.log('[ensure-deps] restored @deepseek-ai/schemastery from ' + source)

package/scripts/import-from-dsh-passwords.mjs

@@ -0,0 +1,111 @@
+'use strict'
+
+/**
+ * One-shot account migration: dsh-passwords → this plugin.
+ *
+ * Reads the source with dsh-passwords' OWN modules. Its username column is
+ * AES-256-GCM ciphertext with a separate HMAC index for lookups, so decoding it
+ * here by hand would be a second implementation of that format — one that drifts
+ * the moment dsh-passwords changes it. Reusing its reader keeps the migration
+ * correct by construction.
+ *
+ * Password hashes are carried over verbatim (bcrypt) and NOT re-hashed: the
+ * plaintext is unavailable. The store verifies them as-is and upgrades each
+ * account to the native scrypt scheme on its next successful sign-in.
+ *
+ * Usage:
+ *   node scripts/import-from-dsh-passwords.mjs --from <dsh-passwords dir> [--dry-run]
+ *
+ * Run it with dsh stopped if you can: the running plugin caches users in memory,
+ * so it will not see imported accounts until it reloads (restart dsh afterwards).
+ */
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createStore, dshHome } from '../src/store.js'
+
+const argv = process.argv.slice(2)
+const fromIndex = argv.indexOf('--from')
+const source = fromIndex >= 0 ? argv[fromIndex + 1] : ''
+const dryRun = argv.includes('--dry-run')
+// A username that exists in BOTH systems has two unrelated password hashes.
+// Without this flag the imported one is ignored and the existing account keeps
+// the password it already had here — which is wrong when the point of the move
+// is that people keep signing in with the credentials they use today.
+const replaceCredentials = argv.includes('--overwrite-credentials')
+if (!source) {
+  console.error('usage: node scripts/import-from-dsh-passwords.mjs --from <dsh-passwords dir> [--dry-run]')
+  process.exit(2)
+}
+
+// dsh-passwords reads its .env through this variable.
+process.env.DSH_PASSWORDS_ENV_FILE = join(source, '.env')
+const load = (name) => import(pathToFileURL(join(source, 'dist', name)).href)
+const [{ loadConfig }, { Database }, { createFieldCrypto }] = await Promise.all([
+  load('config.js'),
+  load('db.js'),
+  load('encrypt.js'),
+])
+
+const config = loadConfig()
+const db = new Database(config.dbPath, createFieldCrypto(config.dbEncKey, config.setupKey))
+
+/** SQLite datetime → epoch ms (the source stores 'YYYY-MM-DD HH:MM:SS' in UTC). */
+function toMs(value) {
+  if (typeof value !== 'string' || value === '') return undefined
+  const iso = value.includes('T') ? value : value.replace(' ', 'T') + 'Z'
+  const t = Date.parse(iso)
+  return Number.isFinite(t) ? t : undefined
+}
+
+const store = createStore({ home: dshHome() })
+await store.load()
+
+const rows = db.listUsers()
+let imported = 0
+let updated = 0
+let skipped = 0
+
+for (const row of rows) {
+  const full = db.getUserById(row.id)
+  if (!full || typeof full.password_hash !== 'string' || full.password_hash === '') {
+    skipped += 1
+    console.log('  skip ' + row.username + ': no password hash')
+    continue
+  }
+  const p = db.getPermissions(row.id)
+  const permissions = p ? {
+    allowedFolders: p.allowed_folders,
+    hourlyTokenLimit: p.hourly_token_limit,
+    dailyMinuteLimit: p.daily_minutes_limit,
+    allowUpload: p.allow_upload,
+    allowGit: p.allow_git_download,
+    allowWorkspaceCreate: p.allow_workspace_create,
+    banned: p.banned,
+    sandboxMode: p.sandbox_mode,
+  } : undefined
+  const clash = store.findUserByUsername(row.username) !== null
+  if (dryRun) {
+    const mark = clash ? (replaceCredentials ? ' [exists here → credentials REPLACED]' : ' [exists here → keeps its current password]') : ''
+    console.log('  would import ' + row.username + ' (' + row.role + ')' + (p ? ' — folders=' + JSON.stringify(p.allowed_folders) + ' tokens=' + String(p.hourly_token_limit) + ' sandbox=' + String(p.sandbox_mode) : ' — default permissions') + mark)
+    continue
+  }
+  const result = await store.importUser({
+    username: row.username,
+    role: row.role,
+    passHash: full.password_hash,
+    algo: 'bcrypt',
+    createdAt: toMs(row.created_at),
+    lastLoginAt: toMs(row.last_login_at),
+    permissions,
+    replaceCredentials,
+  })
+  if (result.created) imported += 1
+  else updated += 1
+  const note = result.credentialsReplaced === true ? ' — credentials replaced' : clash && !replaceCredentials ? ' — kept its existing password' : ''
+  console.log('  ' + (result.created ? 'imported' : 'updated ') + ' ' + row.username + ' (' + row.role + ')' + note)
+}
+
+console.log('')
+console.log((dryRun ? '[dry run] ' : '') + 'source users: ' + rows.length + '  imported: ' + imported + '  updated: ' + updated + '  skipped: ' + skipped)
+if (!dryRun) console.log('Now restart dsh so the running plugin reloads the store.')
+db.close()

package/src/certs.js

@@ -0,0 +1,89 @@
+'use strict'
+
+/**
+ * TLS material for one gateway site: loads a supplied certificate pair, or
+ * generates a self-signed one (persisted under the certs dir so the
+ * fingerprint stays stable across restarts — regenerating every boot would
+ * break any client that pinned or trusted the previous cert). Self-signed
+ * certs are issued for 100 years (days 36500). Persisted certs are NOT
+ * regenerated automatically: to pick up a new expiry or a changed SAN set,
+ * delete the cert/key files under the certs dir and restart.
+ *
+ * Ported from dsh-gateway (clarknu/dsh-gateway) lib/certs.js, adapted to
+ * CommonJS. SANs cover every host the site declares, as DNS or IP entries
+ * (IPv4 + IPv6), so modern browsers (which validate against the SAN list,
+ * not the CN) accept the self-signed certificate for each configured name.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import selfsigned from 'selfsigned'
+
+const IPV4_RE = /^\d{1,3}(?:\.\d{1,3}){3}$/
+// IPv6 literal: hex digits + colons only, and must contain at least one colon
+// (so a hex-only hostname like "cafe" is not misread as an IPv6 address).
+const IPV6_RE = /^[0-9a-fA-F:]+$/
+
+/** Load the configured PEM pair, or generate + persist a self-signed one. */
+function loadOrCreateSiteCert({ cert, key, hosts }, certsDir, log) {
+  if (cert && key) {
+    const crt = readFileSync(cert, 'utf8')
+    const prv = readFileSync(key, 'utf8')
+    return { cert: crt, key: prv, auto: false }
+  }
+  if (!certsDir) {
+    throw new Error('user-management: certsDir is required to generate self-signed certificates')
+  }
+  const primary = (hosts || []).find((h) => h && h !== '*') || 'localhost'
+  const safe = primary.replace(/[^A-Za-z0-9._-]/g, '_')
+  mkdirSync(certsDir, { recursive: true })
+  const crtPath = join(certsDir, `${safe}.crt`)
+  const keyPath = join(certsDir, `${safe}.key`)
+  if (existsSync(crtPath) && existsSync(keyPath)) {
+    return {
+      cert: readFileSync(crtPath, 'utf8'),
+      key: readFileSync(keyPath, 'utf8'),
+      auto: true,
+      certPath: crtPath,
+      keyPath: keyPath,
+    }
+  }
+  const pems = selfsigned.generate(
+    [{ name: 'commonName', value: primary }],
+    {
+      days: 36500,
+      keySize: 2048,
+      algorithm: 'sha256',
+      extensions: [
+        {
+          name: 'subjectAltName',
+          altNames: sanEntries(hosts, primary),
+        },
+        { name: 'basicConstraints', cA: false },
+        { name: 'keyUsage', digitalSignature: true, keyEncipherment: true },
+        { name: 'extKeyUsage', serverAuth: true },
+      ],
+    },
+  )
+  writeFileSync(crtPath, pems.cert, 'utf8')
+  writeFileSync(keyPath, pems.private, { encoding: 'utf8', mode: 0o600 })
+  if (typeof log === 'function') {
+    log(
+      `user-management: generated a self-signed certificate for ${JSON.stringify(hosts || [primary])} ` +
+        `(${crtPath}) — point cert/key at a CA-signed pair in settings for public hostnames`,
+    )
+  }
+  return { cert: pems.cert, key: pems.private, auto: true, certPath: crtPath, keyPath: keyPath }
+}
+
+/** node-forge SAN entries: type 2 = DNS, type 7 = iPAddress (IPv4 or IPv6 literal). */
+function sanEntries(hosts, primary) {
+  const names = [...new Set([...(hosts || []), primary].filter((h) => h && h !== '*'))]
+  return names.map((h) => {
+    if (IPV4_RE.test(h)) return { type: 7, ip: h }
+    if (IPV6_RE.test(h) && h.includes(':')) return { type: 7, ip: h }
+    return { type: 2, value: h }
+  })
+}
+
+export { loadOrCreateSiteCert, sanEntries }

package/src/gate.js

@@ -0,0 +1,162 @@
+'use strict'
+
+/**
+ * Pure auth-gate decision core for the user-management gateway.
+ *
+ * The gateway listener (src/gateway-core.js) calls `createDecider(...)` on
+ * every request: it checks IP bans first (403, login page included), resolves
+ * the um_session cookie against the store, and returns the gate decision
+ * (allow / redirect-to-login / unauthorized / forbidden). The gateway then
+ * routes accordingly (local API/login page vs. reverse-proxy) and wires the
+ * audit hooks on response completion.
+ *
+ * Previously this module also installed a gate by re-ordering listeners on the
+ * shared dsh node:http server (attachGate / installFallbackGate / installGate).
+ * That shared-server gate is gone — the gateway listener IS the gate now, so
+ * the auth cannot be bypassed by hitting the loopback dsh web directly. Only
+ * the pure, testable decision core remains here.
+ */
+
+const LOGIN_PAGE_PATH = '/login'
+const API_PREFIX = '/user-management/api'
+/** Paths reachable without a session (login page + auth API itself). */
+const PUBLIC_PATHS = [
+  LOGIN_PAGE_PATH,
+  `${API_PREFIX}/login`,
+  `${API_PREFIX}/register`,
+  `${API_PREFIX}/session`,
+  `${API_PREFIX}/logout`,
+  // Signing-gateway session events carry no browser session by definition: the
+  // handler authenticates them with the identity signature instead of a cookie.
+  `${API_PREFIX}/internal/session-event`,
+]
+
+function isPublicPath(path) {
+  return PUBLIC_PATHS.some((entry) => path === entry || path.startsWith(`${entry}/`) || path.startsWith(`${entry}?`))
+}
+
+/** Document request = a browser navigation (GET/HEAD asking for text/html). */
+function isDocumentRequest(method, acceptHeader) {
+  if (method !== 'GET' && method !== 'HEAD') return false
+  const accept = String(acceptHeader || '')
+  return accept.includes('text/html')
+}
+
+const STATIC_SUFFIX_RE = /\.(?:js|mjs|css|map|woff2?|ttf|otf|png|jpe?g|gif|svg|ico|webp|avif|mp4|webmanifest|txt)$/i
+
+/** Static asset (bundle files, fonts, images) — never audit-logged. */
+function isStaticAsset(path) {
+  return STATIC_SUFFIX_RE.test(String(path || ''))
+}
+
+/** API-ish request worth auditing: neither a page navigation nor an asset. */
+function isAuditableRequest(method, acceptHeader, path) {
+  return !isDocumentRequest(method, acceptHeader) && !isStaticAsset(path)
+}
+
+function parseCookies(header) {
+  const out = {}
+  const raw = String(header || '')
+  if (raw === '') return out
+  for (const pair of raw.split(';')) {
+    const eq = pair.indexOf('=')
+    if (eq === -1) continue
+    const key = pair.slice(0, eq).trim()
+    if (key === '') continue
+    out[key] = decodeURIComponent(pair.slice(eq + 1).trim())
+  }
+  return out
+}
+
+/**
+ * Pure gate decision.
+ * @param {object} input
+ * @param {string} input.method
+ * @param {string} input.path          pathname only (no query)
+ * @param {string} input.accept        raw Accept header
+ * @param {boolean} input.sessionValid whether the session cookie resolves
+ * @returns {{action:'allow'} | {action:'redirect', location:string} | {action:'unauthorized'}}
+ */
+function gateDecision({ method, path, accept, sessionValid }) {
+  if (sessionValid) return { action: 'allow' }
+  if (isPublicPath(path)) return { action: 'allow' }
+  if (isDocumentRequest(method, accept)) return { action: 'redirect', location: LOGIN_PAGE_PATH }
+  return { action: 'unauthorized' }
+}
+
+/**
+ * Decide from a live request. `resolveSession(req)` → truthy when the
+ * request carries a valid session. `isBanned(ip)` runs BEFORE any session
+ * work: a banned source IP is denied everything (403), login page included.
+ * Two audit hooks:
+ * - `onAccess(req, session, path)` fires for document navigations that pass
+ *   the gate (the "access ledger");
+ * - allow decisions carry `{ session, path }` so the gateway can record the
+ *   operation audit (API/WebSocket) once the response completes.
+ *
+ * `resolveTrusted(req)` is consulted FIRST when present: in the merged
+ * deployment the co-located dsh-passwords gateway is the only login door and
+ * signs the authenticated user onto every request (see trusted-identity.js),
+ * so this layer lets those requests through without a second login of its own
+ * — while still running the ban check and feeding both ledgers.
+ */
+function createDecider({ resolveSession, resolveTrusted, onAccess, getClientIp, isBanned }) {
+  return async function decide(req) {
+    let url
+    try {
+      url = new URL(req.url || '/', 'http://dsh.local')
+    } catch {
+      return { action: 'unauthorized' }
+    }
+    const method = (req.method || 'GET').toUpperCase()
+    const ip = getClientIp ? getClientIp(req) : ''
+    if (isBanned && ip && isBanned(ip)) return { action: 'forbidden', path: url.pathname }
+    const cookies = parseCookies(req.headers && req.headers.cookie)
+    // Signature first: a trusted request carries no um_session cookie and must
+    // never be bounced to the local login page.
+    const trusted = typeof resolveTrusted === 'function' ? resolveTrusted(req) : null
+    const resolved = trusted || await resolveSession(cookies[SESSION_COOKIE])
+    const decision = gateDecision({
+      method,
+      path: url.pathname,
+      accept: req.headers && req.headers.accept,
+      sessionValid: !!resolved,
+    })
+    if (decision.action === 'allow') {
+      decision.session = resolved
+      decision.path = url.pathname
+      if (onAccess && isDocumentRequest(method, req.headers && req.headers.accept) && !isPublicPath(url.pathname)) {
+        try { onAccess(req, resolved, url.pathname) } catch { /* ledger must never break the gate */ }
+      }
+    }
+    return decision
+  }
+}
+
+const SESSION_COOKIE = 'um_session'
+
+function sendUnauthorized(res) {
+  res.writeHead(401, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify({ error: 'unauthorized' }))
+}
+
+function sendForbidden(res, message) {
+  res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify({ error: message || 'forbidden' }))
+}
+
+export {
+  SESSION_COOKIE,
+  LOGIN_PAGE_PATH,
+  API_PREFIX,
+  PUBLIC_PATHS,
+  gateDecision,
+  createDecider,
+  parseCookies,
+  isDocumentRequest,
+  isStaticAsset,
+  isAuditableRequest,
+  isPublicPath,
+  sendUnauthorized,
+  sendForbidden,
+}