kczx-user-management 1.0.0

package/src/store.js

@@ -0,0 +1,1072 @@
+'use strict'
+
+/**
+ * user-management store — users / sessions / activity ledger.
+ *
+ * Everything lives under `$DSH_HOME/user-management/`:
+ * - users.json     accounts (scrypt password hashes), mode 0600, atomic writes
+ * - sessions.json  issued session tokens (survive restarts), same protection
+ * - activity.jsonl append-only event ledger (logins, admin actions, page
+ *                  accesses), rolled over to the tail MAX_LEDGER_LINES
+ *
+ * No third-party dependencies: hashing is crypto.scrypt, tokens are
+ * crypto.randomBytes. All mutation paths are async and serialize through
+ * per-file write chains so concurrent requests cannot interleave writes.
+ */
+
+import fsP from 'node:fs/promises'
+import net from 'node:net'
+import { randomBytes, scrypt as scryptCb, scryptSync, timingSafeEqual, createHash } from 'node:crypto'
+import { promisify } from 'node:util'
+import { join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { generateSecret, verifyTotp } from './totp.js'
+import { DENY_ALL_WORKSPACES, isWorkspaceRestricted, normalizePath } from './permissions.js'
+// Only used to verify hashes imported from dsh-passwords: its accounts are
+// bcrypt and a hash cannot be converted, so the record keeps its algorithm
+// marker and is transparently re-hashed to scrypt on the next sign-in.
+import bcrypt from 'bcryptjs'
+
+const scrypt = promisify(scryptCb)
+
+const USERS_FILE = 'users.json'
+const SESSIONS_FILE = 'sessions.json'
+const ACTIVITY_FILE = 'activity.jsonl'
+const AUDIT_FILE = 'audit.jsonl'
+const BANS_FILE = 'bans.json'
+const USAGE_FILE = 'usage.json'
+const WORKSPACES_FILE = 'workspaces.json'
+
+/** scrypt key length / cost — modest defaults, login is not a hot path. */
+const KEY_LEN = 32
+const SCRYPT_COST = 16384
+/** Token quota window: tokens are counted per rolling hour. */
+const HOURLY_WINDOW_MS = 60 * 60 * 1000
+
+/** Session lifetime; sliding — each authenticated check past half-life renews. */
+const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000
+const SESSION_RENEW_MS = SESSION_TTL_MS / 2
+/** Ledger rollover: trim to the tail once the file grows past 2× the cap. */
+const MAX_LEDGER_LINES = 2000
+
+// ── per-user permissions & quotas ───────────────────────────────────────────
+//
+// Ported from dsh-passwords' user_permissions row so this plugin can own
+// accounts, workspace scope and usage limits on its own. Defaults are
+// permissive: an empty folder list means "every workspace" (the same reading
+// dsh-passwords gives it), a null limit means "no cap". A record written
+// before this model existed has no permissions block and reads exactly as
+// these defaults, so migration is a no-op for existing users.
+
+/** Sandbox floors the gateway may pin an account to (dsh-passwords' ranking). */
+const SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access']
+
+/** Marker for a hash imported from dsh-passwords (bcrypt, not convertible). */
+const BCRYPT_ALGO = 'bcrypt'
+
+/** A broken bcrypt dependency is reported once, not once per login attempt. */
+let bcryptFailureReported = false
+
+const DEFAULT_PERMISSIONS = Object.freeze({
+  /** Absolute folders this account may touch; empty = unrestricted. */
+  allowedFolders: [],
+  /** Tokens per rolling hour; null = unlimited. */
+  hourlyTokenLimit: null,
+  /** Minutes of agent time per day; null = unlimited. */
+  dailyMinuteLimit: null,
+  /** Floor this account's sandbox to a mode; null = leave the choice to it. */
+  sandboxMode: null,
+  /** Allow uploads / git operations through the gateway. dsh-passwords ships
+   *  these asymmetric (upload on, git download off) and that asymmetry is kept:
+   *  a git clone can pull an entire repository out of the host. */
+  allowUpload: true,
+  allowGit: false,
+  /** Allow creating new workspaces, not just using existing ones (dp default:
+   *  off — a workspace is a place an agent may write to). */
+  allowWorkspaceCreate: false,
+  /** Gate-level deny (sessions dropped, sign-in refused): unlike `disabled`
+   *  this is a policy state the enforcement layer reads on every request. */
+  banned: false,
+  /** Free-form admin note. */
+  note: '',
+})
+
+function normalizeFolders(raw) {
+  if (!Array.isArray(raw)) return []
+  const out = []
+  for (const entry of raw) {
+    const value = String(entry ?? '').trim()
+    if (value !== '' && !out.includes(value)) out.push(value)
+  }
+  return out
+}
+
+/** Accept only a non-negative finite number; anything else means "no cap". */
+function normalizeLimit(raw) {
+  if (raw === null || raw === undefined || raw === '') return null
+  const value = Number(raw)
+  if (!Number.isFinite(value) || value < 0) return null
+  return Math.floor(value)
+}
+
+/**
+ * Coerce anything (a fresh record, an old record, an API patch) into a
+ * complete, valid permissions block. Every field is validated here rather than
+ * at each call site: an invalid sandbox mode or a negative limit must never
+ * reach the enforcement layer.
+ */
+function normalizePermissions(raw) {
+  const source = raw && typeof raw === 'object' ? raw : {}
+  return {
+    allowedFolders: normalizeFolders(source.allowedFolders),
+    hourlyTokenLimit: normalizeLimit(source.hourlyTokenLimit),
+    dailyMinuteLimit: normalizeLimit(source.dailyMinuteLimit),
+    sandboxMode: SANDBOX_MODES.includes(source.sandboxMode) ? source.sandboxMode : null,
+    // Only an explicit true enables these: absent means the safe default, both
+    // for a fresh record and for one written before a field existed.
+    allowUpload: source.allowUpload !== false,
+    allowGit: source.allowGit === true,
+    allowWorkspaceCreate: source.allowWorkspaceCreate === true,
+    banned: source.banned === true,
+    note: typeof source.note === 'string' ? source.note.slice(0, 200) : '',
+  }
+}
+
+// Workspace-scope semantics live in ./permissions.js and are re-exported here:
+// one implementation for the store, the API and the enforcement layer.
+/** Operation audit ledger (separate file — must not be rolled away by
+ *  security events or vice versa). Same 2× trim rule. */
+const MAX_AUDIT_LINES = 5000
+
+const USERNAME_RE = /^[a-zA-Z0-9_-]{2,32}$/
+const MIN_PASSWORD_LEN = 6
+const ACTIVITY_LIMIT_DEFAULT = 200
+
+class StoreError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+/** dsh data root — mirrors the host ($DSH_HOME, default ~/.dsh). */
+function dshHome() {
+  return process.env.DSH_HOME ? resolve(process.env.DSH_HOME) : join(homedir(), '.dsh')
+}
+
+function isValidUsername(name) {
+  return typeof name === 'string' && USERNAME_RE.test(name)
+}
+
+function isValidPassword(pw) {
+  return typeof pw === 'string' && pw.length >= MIN_PASSWORD_LEN && pw.length <= 256
+}
+
+async function hashPassword(password, salt) {
+  const useSalt = salt || randomBytes(16).toString('hex')
+  const derived = await scrypt(password, useSalt, KEY_LEN, { N: SCRYPT_COST, r: 8, p: 1 })
+  return { salt: useSalt, passHash: derived.toString('hex') }
+}
+
+/**
+ * Constant-time password check against a stored record.
+ *
+ * Native records are scrypt ({ salt, passHash }). Records imported from
+ * dsh-passwords carry { algo: 'bcrypt', passHash } instead: a bcrypt hash
+ * cannot be converted, so it is verified as-is and upgraded on the next
+ * successful sign-in (see checkLogin).
+ */
+function verifyPassword(record, password) {
+  if (!record || !record.passHash || typeof password !== 'string') return false
+  if (record.algo === BCRYPT_ALGO) {
+    if (typeof record.passHash !== 'string' || record.passHash === '') return false
+    try {
+      return bcrypt.compareSync(password, record.passHash)
+    } catch (error) {
+      // Swallowing this silently would make "the dependency is missing or the
+      // hash is malformed" indistinguishable from "wrong password" — the account
+      // would simply never be able to sign in, with nothing said about it.
+      if (!bcryptFailureReported) {
+        bcryptFailureReported = true
+        console.error('[user-management] bcrypt verification failed; imported accounts cannot sign in:', error && error.message)
+      }
+      return false
+    }
+  }
+  if (!record.salt) return false
+  const derived = scryptSync(password, record.salt, KEY_LEN, { N: SCRYPT_COST, r: 8, p: 1 })
+  const expected = Buffer.from(record.passHash, 'hex')
+  if (derived.length !== expected.length) return false
+  return timingSafeEqual(derived, expected)
+}
+
+/** Random URL-safe token (session ids, one-time reset passwords). */
+function randomToken(bytes = 32) {
+  return randomBytes(bytes).toString('base64url')
+}
+
+/** Temps are 12 chars but human-typeable: groups of 4. */
+function tempPassword() {
+  const raw = randomToken(9) // 12 base64url chars
+  return raw.slice(0, 4) + '-' + raw.slice(4, 8) + '-' + raw.slice(8, 12)
+}
+
+/** Stable token fingerprint for ledger entries — never log the token itself. */
+function tokenFingerprint(token) {
+  return createHash('sha256').update(String(token)).digest('hex').slice(0, 12)
+}
+
+function normalizeIp(raw) {
+  if (!raw) return ''
+  let ip = String(raw)
+  if (ip.startsWith('::ffff:')) ip = ip.slice(7)
+  if (ip === '::1') ip = '127.0.0.1'
+  return ip
+}
+
+/**
+ * Create a store rooted at `<home>/user-management`. All state is cached in
+ * memory after load; writes persist through serialized atomic replacements.
+ */
+function createStore({ home, now = () => Date.now() } = {}) {
+  const dir = join(home, 'user-management')
+  const usersFile = join(dir, USERS_FILE)
+  const sessionsFile = join(dir, SESSIONS_FILE)
+  const activityFile = join(dir, ACTIVITY_FILE)
+  const auditFile = join(dir, AUDIT_FILE)
+  const bansFile = join(dir, BANS_FILE)
+  const usageFile = join(dir, USAGE_FILE)
+  const workspacesFile = join(dir, WORKSPACES_FILE)
+
+  /** @type {{seq:number, users:Array}} */
+  let usersDoc = { seq: 0, users: [] }
+  /** @type {{tokens:Object<string,{userId,username,createdAt,expiresAt}>}} */
+  let sessionsDoc = { tokens: {} }
+  /** @type {{bans:Array<{ip,note,createdAt,createdBy}>}} */
+  let bansDoc = { bans: [] }
+  /**
+   * Per-account quota counters, keyed by lower-cased username.
+   *
+   * Keyed by username rather than user id so the same accounting works for a
+   * store session and for a signed identity arriving from a login gateway
+   * (whose id is synthetic). A rename therefore starts a fresh window — an
+   * acceptable trade for a quota, which is a rate limit rather than an audit
+   * record.
+   *
+   * @type {Record<string, {day:string, activeSeconds:number, firstSeenAt:number, lastActiveAt:number, hourlyWindowStart:number, hourlyTokens:number}>}
+   */
+  let usageDoc = { users: {} }
+  /**
+   * Workspace ownership: normalized path → owning username.
+   *
+   * Ported from dsh-passwords' user_workspaces table. It answers one question
+   * the permission switches cannot: this folder is inside your allow-list, but
+   * it is somebody else's workspace — so it is not yours to see, rename or
+   * delete. The owning account is exempt, and so is an administrator.
+   *
+   * @type {{owners: Record<string, string>}}
+   */
+  let workspacesDoc = { owners: {} }
+
+  /** Lookup used during load, before the public helpers are meaningful. */
+  function findUserByUsernameRaw(username) {
+    const needle = String(username || '').toLowerCase()
+    return usersDoc.users.find((u) => String(u.username).toLowerCase() === needle) || null
+  }
+
+  /** Local-time day key, matching how "daily" is understood by a human. */
+  function todayKey(ts) {
+    const d = new Date(ts)
+    const month = String(d.getMonth() + 1).padStart(2, '0')
+    const day = String(d.getDate()).padStart(2, '0')
+    return `${d.getFullYear()}-${month}-${day}`
+  }
+
+  /** Roll a record over when the local day changed. */
+  function rollDay(entry, ts) {
+    const day = todayKey(ts)
+    if (entry.day !== day) {
+      entry.day = day
+      entry.activeSeconds = 0
+      entry.hourlyTokens = 0
+      entry.hourlyWindowStart = ts
+    }
+    return entry
+  }
+  let ledgerLines = 0
+  let auditLines = 0
+  let auditSeq = 0
+  const writeChain = { users: Promise.resolve(), sessions: Promise.resolve(), ledger: Promise.resolve(), audit: Promise.resolve() }
+
+  function atomicWrite(file, content) {
+    return fsP.mkdir(dir, { recursive: true }).then(() => {
+      const temp = join(dir, `.${randomBytes(6).toString('hex')}.tmp`)
+      return fsP.writeFile(temp, content, { encoding: 'utf8', mode: 0o600 })
+        .then(() => fsP.rename(temp, file))
+    })
+  }
+
+  function persistUsers() {
+    const run = writeChain.users.then(() => atomicWrite(usersFile, JSON.stringify(usersDoc, null, 2)))
+    writeChain.users = run.catch(() => {})
+    return run
+  }
+
+  function persistWorkspaces() {
+    const run = writeChain.users.then(() => atomicWrite(workspacesFile, JSON.stringify(workspacesDoc, null, 2)))
+    writeChain.users = run.catch(() => {})
+    return run
+  }
+
+  function persistUsage() {
+    const run = writeChain.users.then(() => atomicWrite(usageFile, JSON.stringify(usageDoc, null, 2)))
+    writeChain.users = run.catch(() => {})
+    return run
+  }
+
+  function persistBans() {
+    const run = writeChain.users.then(() => atomicWrite(bansFile, JSON.stringify(bansDoc, null, 2)))
+    writeChain.users = run.catch(() => {})
+    return run
+  }
+
+  function persistSessions() {
+    const run = writeChain.sessions.then(() => atomicWrite(sessionsFile, JSON.stringify(sessionsDoc)))
+    writeChain.sessions = run.catch(() => {})
+    return run
+  }
+
+  async function load() {
+    await fsP.mkdir(dir, { recursive: true })
+    for (const [file, assign] of [
+      [usersFile, (data) => { usersDoc = data }],
+      [sessionsFile, (data) => { sessionsDoc = data }],
+      [bansFile, (data) => { bansDoc = data }],
+      [usageFile, (data) => { usageDoc = data }],
+      [workspacesFile, (data) => { workspacesDoc = data }],
+    ]) {
+      try {
+        const raw = await fsP.readFile(file, 'utf8')
+        const parsed = JSON.parse(raw)
+        if (parsed && typeof parsed === 'object') assign(parsed)
+      } catch (e) {
+        if (e && e.code !== 'ENOENT') throw e
+      }
+    }
+    if (!Array.isArray(usersDoc.users)) usersDoc.users = []
+    if (!Number.isFinite(usersDoc.seq)) usersDoc.seq = usersDoc.users.length
+    // Records written before the permission model existed carry no block: fill
+    // in the defaults in place so every reader sees one shape.
+    for (const user of usersDoc.users) user.permissions = normalizePermissions(user.permissions)
+    if (!sessionsDoc.tokens || typeof sessionsDoc.tokens !== 'object') sessionsDoc.tokens = {}
+    if (!Array.isArray(bansDoc.bans)) bansDoc.bans = []
+    if (!usageDoc || typeof usageDoc.users !== 'object' || usageDoc.users === null) usageDoc = { users: {} }
+    if (!workspacesDoc || typeof workspacesDoc.owners !== 'object' || workspacesDoc.owners === null) workspacesDoc = { owners: {} }
+    // A claim whose account no longer exists would hide that folder from
+    // everyone but an administrator, so drop those on load.
+    for (const [path, owner] of Object.entries(workspacesDoc.owners)) {
+      if (findUserByUsernameRaw(owner) === null) delete workspacesDoc.owners[path]
+    }
+    // Usage is a rolling counter, not a ledger: anything older than a couple of
+    // days can never affect a quota again, so it is dropped rather than kept
+    // forever in a file that gets rewritten on every touch.
+    for (const [name, entry] of Object.entries(usageDoc.users)) {
+      if (!entry || typeof entry !== 'object' || entry.day !== todayKey(now()) || entry.day !== todayKey(entry.lastActiveAt || 0)) {
+        delete usageDoc.users[name]
+      }
+    }
+    // expired tokens are dropped on boot; ledger line count for rollover
+    const ts = now()
+    for (const token of Object.keys(sessionsDoc.tokens)) {
+      if (!sessionsDoc.tokens[token] || sessionsDoc.tokens[token].expiresAt <= ts) delete sessionsDoc.tokens[token]
+    }
+    try { ledgerLines = (await fsP.readFile(activityFile, 'utf8')).split('\n').filter((l) => l.trim() !== '').length } catch { ledgerLines = 0 }
+    try {
+      const raw = await fsP.readFile(auditFile, 'utf8')
+      const lines = raw.split('\n').filter((l) => l.trim() !== '')
+      auditLines = lines.length
+      for (const line of lines) {
+        try {
+          const id = JSON.parse(line).id
+          const match = typeof id === 'string' ? /^a(\d+)$/.exec(id) : null
+          if (match) auditSeq = Math.max(auditSeq, Number(match[1]))
+        } catch { /* skip malformed line */ }
+      }
+    } catch { auditLines = 0 }
+    return { users: usersDoc.users.length, sessions: Object.keys(sessionsDoc.tokens).length }
+  }
+
+  // ── users ────────────────────────────────────────────────────────────────
+
+  function publicUser(user) {
+    if (!user) return null
+    return {
+      id: user.id, username: user.username, role: user.role,
+      disabled: !!user.disabled,
+      totpEnabled: !!user.totpSecret,
+      createdAt: user.createdAt, lastLoginAt: user.lastLoginAt || null,
+      permissions: normalizePermissions(user.permissions),
+    }
+  }
+
+  function findUser(id) {
+    return usersDoc.users.find((u) => u.id === id) || null
+  }
+
+  function findUserByUsername(username) {
+    const needle = String(username || '').toLowerCase()
+    return usersDoc.users.find((u) => u.username.toLowerCase() === needle) || null
+  }
+
+  function countAdmins() {
+    return usersDoc.users.filter((u) => u.role === 'admin').length
+  }
+
+  async function createUser({ username, password, role = 'user', disabled = false, permissions }) {
+    if (!isValidUsername(username)) throw new StoreError('bad_username', '用户名需 2-32 位，仅限字母/数字/下划线/连字符')
+    if (!isValidPassword(password)) throw new StoreError('bad_password', `密码至少 ${MIN_PASSWORD_LEN} 位`)
+    if (findUserByUsername(username)) throw new StoreError('duplicate', '用户名已存在')
+    if (role !== 'admin' && role !== 'user') throw new StoreError('bad_role', 'role 必须是 admin 或 user')
+    const { salt, passHash } = await hashPassword(password)
+    const user = {
+      id: `u_${++usersDoc.seq}_${randomToken(6)}`,
+      username: String(username),
+      role,
+      salt,
+      passHash,
+      createdAt: now(),
+      lastLoginAt: null,
+      permissions: normalizePermissions(permissions),
+    }
+    // Approval-mode registrations land disabled (the admin enable button is
+    // the approval action); admin-created accounts are always active.
+    if (disabled) user.disabled = true
+    usersDoc.users.push(user)
+    await persistUsers()
+    return publicUser(user)
+  }
+
+  /**
+   * Merge a partial permissions patch onto a user (admin action). Absent keys
+   * keep their current value; an explicit null clears a limit. Everything goes
+   * through normalizePermissions, so the stored shape is always complete.
+   */
+  async function setPermissions(user, patch) {
+    if (!user) throw new StoreError('not_found', '用户不存在')
+    const next = { ...normalizePermissions(user.permissions) }
+    for (const [key, value] of Object.entries(patch || {})) {
+      if (value !== undefined) next[key] = value
+    }
+    user.permissions = normalizePermissions(next)
+    await persistUsers()
+    return publicUser(user)
+  }
+
+  /**
+   * Create an account from an exported record, preserving its existing password
+   * hash verbatim (see verifyPassword for how a foreign algorithm is handled).
+   *
+   * Used by the dsh-passwords migration: re-hashing is impossible without the
+   * plaintext password, and asking every user to reset would make the move
+   * disruptive enough that nobody does it.
+   *
+   * @param options.replaceCredentials - also adopt the imported password hash
+   *        when the username already exists here (see the collision note below).
+   * @returns {{ user: object, created: boolean, credentialsReplaced?: boolean }}
+   *          whether the account was newly created; an existing username keeps
+   *          its own hash unless `replaceCredentials` asks otherwise, so
+   *          re-running a migration is safe by default.
+   */
+  async function importUser({ username, role = 'user', passHash, algo, salt, createdAt, lastLoginAt, disabled = false, permissions, replaceCredentials = false }) {
+    if (!isValidUsername(username)) throw new StoreError('bad_username', '用户名需 2-32 位，仅限字母/数字/下划线/连字符')
+    if (typeof passHash !== 'string' || passHash === '') throw new StoreError('bad_password', '导入记录缺少密码哈希')
+    if (role !== 'admin' && role !== 'user') throw new StoreError('bad_role', 'role 必须是 admin 或 user')
+
+    const existing = findUserByUsername(username)
+    if (existing) {
+      existing.permissions = normalizePermissions(permissions)
+      if (typeof role === 'string') existing.role = role
+      // A name collision means the two systems each had an account under this
+      // username with unrelated password hashes. The caller decides which side
+      // wins: replacing is the right call when the imported system is the one
+      // people actually sign in to today, but it must be asked for explicitly
+      // (silently swapping someone's credentials is not a migration's job).
+      let credentialsReplaced = false
+      if (replaceCredentials) {
+        existing.passHash = passHash
+        if (typeof algo === 'string' && algo !== '') existing.algo = algo
+        else delete existing.algo
+        if (typeof salt === 'string' && salt !== '') existing.salt = salt
+        else delete existing.salt
+        credentialsReplaced = true
+      }
+      await persistUsers()
+      return { user: publicUser(existing), created: false, credentialsReplaced }
+    }
+
+    const user = {
+      id: `u_${++usersDoc.seq}_${randomToken(6)}`,
+      username: String(username),
+      role,
+      passHash,
+      createdAt: Number.isFinite(createdAt) ? createdAt : now(),
+      lastLoginAt: Number.isFinite(lastLoginAt) ? lastLoginAt : null,
+      permissions: normalizePermissions(permissions),
+    }
+    // A native (scrypt) hash keeps its salt; an imported foreign hash keeps its
+    // algorithm marker so verification knows which path to take.
+    if (typeof salt === 'string' && salt !== '') user.salt = salt
+    if (typeof algo === 'string' && algo !== '') user.algo = algo
+    if (disabled) user.disabled = true
+    usersDoc.users.push(user)
+    await persistUsers()
+    return { user: publicUser(user), created: true }
+  }
+
+  // ── workspace ownership ──────────────────────────────────────────────────
+
+  /** path → owner map (a copy; callers must not mutate store state). */
+  function workspaceOwners() {
+    return { ...workspacesDoc.owners }
+  }
+
+  /** Who owns this folder, or null when nobody has claimed it. */
+  function workspaceOwnerOf(path) {
+    return workspacesDoc.owners[normalizePath(path)] || null
+  }
+
+  /** Claim a folder for an account (a no-op when someone already owns it). */
+  async function claimWorkspace(path, username) {
+    const key = normalizePath(path)
+    if (key === '' || key === '.' || key === '/') return null
+    if (workspacesDoc.owners[key] !== undefined) return workspacesDoc.owners[key]
+    workspacesDoc.owners[key] = String(username)
+    await persistWorkspaces()
+    return workspacesDoc.owners[key]
+  }
+
+  /** Release a claim (the folder is gone). */
+  async function releaseWorkspace(path) {
+    const key = normalizePath(path)
+    if (workspacesDoc.owners[key] === undefined) return false
+    delete workspacesDoc.owners[key]
+    await persistWorkspaces()
+    return true
+  }
+
+  /** Move a claim with its folder. */
+  async function renameWorkspace(oldPath, newPath) {
+    const from = normalizePath(oldPath)
+    const to = normalizePath(newPath)
+    if (workspacesDoc.owners[from] === undefined) return false
+    workspacesDoc.owners[to] = workspacesDoc.owners[from]
+    delete workspacesDoc.owners[from]
+    await persistWorkspaces()
+    return true
+  }
+
+  // ── usage / quota counters ───────────────────────────────────────────────
+
+  /** Counters for an account, or null when it has no record for today. */
+  function getUsage(username) {
+    const key = String(username || '').toLowerCase()
+    if (key === '') return null
+    const entry = usageDoc.users[key]
+    if (!entry) return null
+    rollDay(entry, now())
+    return { ...entry }
+  }
+
+  /**
+   * Record activity against an account's daily allowance.
+   *
+   * Called from the request path, so it stays cheap: the caller throttles by
+   * wall clock (a request every few seconds must not become a file write every
+   * few seconds), and this only persists when the caller passed real time.
+   */
+  async function touchUsage(username, seconds = 0) {
+    const key = String(username || '').toLowerCase()
+    if (key === '') return null
+    const ts = now()
+    const entry = rollDay(usageDoc.users[key] || {
+      day: todayKey(ts),
+      activeSeconds: 0,
+      firstSeenAt: ts,
+      lastActiveAt: ts,
+      hourlyWindowStart: ts,
+      hourlyTokens: 0,
+    }, ts)
+    entry.lastActiveAt = ts
+    if (Number.isFinite(seconds) && seconds > 0) entry.activeSeconds += Math.round(seconds)
+    usageDoc.users[key] = entry
+    await persistUsage()
+    return { ...entry }
+  }
+
+  /**
+   * Add reported tokens to the rolling hourly window.
+   *
+   * The client reports deltas of dsh's own token projection: the gateway cannot
+   * see provider accounting, and reconstructing it from response bodies was
+   * abandoned upstream as unreliable.
+   */
+  async function addTokens(username, tokens) {
+    const key = String(username || '').toLowerCase()
+    const amount = Math.round(Number(tokens))
+    if (key === '' || !Number.isFinite(amount) || amount <= 0) return getUsage(username)
+    const ts = now()
+    const entry = rollDay(usageDoc.users[key] || {
+      day: todayKey(ts),
+      activeSeconds: 0,
+      firstSeenAt: ts,
+      lastActiveAt: ts,
+      hourlyWindowStart: ts,
+      hourlyTokens: 0,
+    }, ts)
+    if (ts - entry.hourlyWindowStart >= HOURLY_WINDOW_MS) {
+      entry.hourlyWindowStart = ts
+      entry.hourlyTokens = 0
+    }
+    entry.hourlyTokens += amount
+    entry.lastActiveAt = ts
+    usageDoc.users[key] = entry
+    await persistUsage()
+    return { ...entry }
+  }
+
+  /** First account in an empty system becomes admin (see README). */
+  function roleForNextRegistration() {
+    return usersDoc.users.length === 0 ? 'admin' : 'user'
+  }
+
+  async function verifyLogin(username, password) {
+    const outcome = await checkLogin(username, password)
+    return outcome.result === 'ok' || outcome.result === 'disabled' ? outcome.user : null
+  }
+
+  /**
+   * Full login outcome: 'ok' | 'invalid' | 'disabled' (correct credentials
+   * but the account is disabled). The invalid path burns hash time so
+   * missing users are not distinguishable; the disabled path only exists
+   * behind correct credentials, so revealing it is safe.
+   */
+  async function checkLogin(username, password) {
+    const user = findUserByUsername(username)
+    if (!user) {
+      await hashPassword(password || '', '00000000000000000000000000000000')
+      return { result: 'invalid' }
+    }
+    if (!verifyPassword(user, password)) return { result: 'invalid' }
+    // Migrated accounts: the bcrypt hash verified, so this is the moment to move
+    // them onto the native scheme. Best effort — a failed re-hash must not fail
+    // a correct sign-in (the old hash still works next time).
+    if (user.algo === BCRYPT_ALGO) {
+      try {
+        const { salt, passHash } = await hashPassword(password)
+        user.salt = salt
+        user.passHash = passHash
+        delete user.algo
+        await persistUsers()
+      } catch { /* keep the imported hash */ }
+    }
+    return { result: user.disabled ? 'disabled' : 'ok', user }
+  }
+
+  /** Disable / enable an account. Disabled users fail login and lose all
+   *  live sessions (resolveSession also re-checks the flag defensively). */
+  async function setDisabled(user, disabled) {
+    if (typeof disabled !== 'boolean') throw new StoreError('bad_request', 'disabled 必须是布尔值')
+    if (disabled && user.role === 'admin' && countAdmins() <= 1) {
+      throw new StoreError('last_admin', '不能禁用最后一个管理员')
+    }
+    if (disabled) user.disabled = true
+    else delete user.disabled
+    await persistUsers()
+  }
+
+  async function setPassword(user, password) {
+    if (!isValidPassword(password)) throw new StoreError('bad_password', `密码至少 ${MIN_PASSWORD_LEN} 位`)
+    const { salt, passHash } = await hashPassword(password)
+    user.salt = salt
+    user.passHash = passHash
+    await persistUsers()
+  }
+
+  async function setRole(user, role) {
+    if (role !== 'admin' && role !== 'user') throw new StoreError('bad_role', 'role 必须是 admin 或 user')
+    if (user.role === 'admin' && role !== 'admin' && countAdmins() <= 1) {
+      throw new StoreError('last_admin', '不能降级最后一个管理员')
+    }
+    user.role = role
+    await persistUsers()
+  }
+
+  // ── TOTP two-step verification ───────────────────────────────────────────
+  //
+  // Enrollment is two-phase so a typo in the secret can never lock the user
+  // out: startTotpSetup parks the fresh secret in totpPendingSecret, and only
+  // activateTotp — which demands a code the authenticator generated FROM that
+  // secret — promotes it to totpSecret (the enabled flag is `totpSecret`
+  // itself). verifyLoginOtp enforces single use by persisting the matched
+  // step counter; older/equal counters are rejected as replays.
+
+  /** Generate a pending secret; the API layer builds the otpauth URI + QR. */
+  async function startTotpSetup(user) {
+    if (user.totpSecret) throw new StoreError('totp_enabled', '两步验证已开启，请先关闭再重新绑定')
+    user.totpPendingSecret = generateSecret()
+    await persistUsers()
+    return { secret: user.totpPendingSecret }
+  }
+
+  /** Promote the pending secret to enabled after the user proves possession. */
+  async function activateTotp(user, code) {
+    if (!user.totpPendingSecret) throw new StoreError('no_pending_totp', '请先开始两步验证绑定')
+    const verdict = verifyTotp(user.totpPendingSecret, code, { nowMs: now() })
+    if (!verdict.ok) return false
+    user.totpSecret = user.totpPendingSecret
+    user.totpLastCounter = verdict.counter
+    user.totpEnabledAt = now()
+    delete user.totpPendingSecret
+    await persistUsers()
+    return true
+  }
+
+  /** Drop every TOTP field (self-service disable and admin reset share this). */
+  async function disableTotp(user) {
+    if (!user.totpSecret) throw new StoreError('totp_not_enabled', '该账号未开启两步验证')
+    delete user.totpSecret
+    delete user.totpPendingSecret
+    delete user.totpLastCounter
+    delete user.totpEnabledAt
+    await persistUsers()
+  }
+
+  /**
+   * Login-time OTP check. `notEnabled` lets the caller skip the OTP branch
+   * entirely; a successful check persists the matched counter so the same
+   * code can never be accepted twice.
+   */
+  async function verifyLoginOtp(user, code) {
+    if (!user.totpSecret) return { ok: false, notEnabled: true }
+    const verdict = verifyTotp(user.totpSecret, code, { nowMs: now(), lastCounter: user.totpLastCounter || 0 })
+    if (verdict.ok) {
+      user.totpLastCounter = verdict.counter
+      await persistUsers()
+    }
+    return verdict
+  }
+
+  async function removeUser(user) {
+    const index = usersDoc.users.indexOf(user)
+    if (index === -1) throw new StoreError('not_found', '用户不存在')
+    if (user.role === 'admin' && countAdmins() <= 1) {
+      throw new StoreError('last_admin', '不能删除最后一个管理员')
+    }
+    usersDoc.users.splice(index, 1)
+    for (const token of Object.keys(sessionsDoc.tokens)) {
+      if (sessionsDoc.tokens[token].userId === user.id) delete sessionsDoc.tokens[token]
+    }
+    await persistUsers()
+    return persistSessions()
+  }
+
+  async function touchLogin(user) {
+    user.lastLoginAt = now()
+    await persistUsers()
+  }
+
+  function listUsers() {
+    return usersDoc.users.map(publicUser)
+  }
+
+  // ── sessions ─────────────────────────────────────────────────────────────
+
+  async function createSession(user) {
+    const token = randomToken()
+    const ts = now()
+    sessionsDoc.tokens[token] = { userId: user.id, username: user.username, createdAt: ts, expiresAt: ts + SESSION_TTL_MS }
+    await pruneSessions()
+    return { token, expiresAt: ts + SESSION_TTL_MS }
+  }
+
+  async function pruneSessions() {
+    const ts = now()
+    for (const token of Object.keys(sessionsDoc.tokens)) {
+      const session = sessionsDoc.tokens[token]
+      if (!session || session.expiresAt <= ts) delete sessionsDoc.tokens[token]
+    }
+    return persistSessions()
+  }
+
+  /** Resolve a token → {user, session, token}. Sliding renewal past half-life. */
+  async function resolveSession(token) {
+    if (!token || typeof token !== 'string') return null
+    const session = sessionsDoc.tokens[token]
+    if (!session) return null
+    const ts = now()
+    if (session.expiresAt <= ts) {
+      delete sessionsDoc.tokens[token]
+      await persistSessions()
+      return null
+    }
+    const user = findUser(session.userId)
+    if (!user) {
+      delete sessionsDoc.tokens[token]
+      await persistSessions()
+      return null
+    }
+    if (user.disabled) {
+      delete sessionsDoc.tokens[token]
+      await persistSessions()
+      return null
+    }
+    if (session.expiresAt - ts < SESSION_RENEW_MS) {
+      session.expiresAt = ts + SESSION_TTL_MS
+      await persistSessions()
+    }
+    return { user, session, token }
+  }
+
+  async function dropSession(token) {
+    if (token && sessionsDoc.tokens[token]) {
+      delete sessionsDoc.tokens[token]
+      await persistSessions()
+    }
+  }
+
+  /** Kill every session of a user (password reset / role change / delete). */
+  async function dropUserSessions(userId, exceptToken) {
+    let dropped = false
+    for (const token of Object.keys(sessionsDoc.tokens)) {
+      if (sessionsDoc.tokens[token].userId !== userId) continue
+      if (token === exceptToken) continue
+      delete sessionsDoc.tokens[token]
+      dropped = true
+    }
+    if (dropped) await persistSessions()
+  }
+
+  // ── IP bans ──────────────────────────────────────────────────────────────
+
+  function isBanned(ip) {
+    if (!ip) return false
+    return bansDoc.bans.some((b) => b.ip === ip)
+  }
+
+  function listBans() {
+    return bansDoc.bans.slice().sort((a, b) => b.createdAt - a.createdAt)
+  }
+
+  /** Ban an IP (validated). Loopback addresses are rejected outright and
+   *  the self-lockout guard lives in the API layer — it needs the
+   *  requester's live IP, the store does not. */
+  async function banIp(ip, { note = '', by = null } = {}) {
+    const normalized = String(ip || '').trim()
+    if (net.isIP(normalized) === 0) throw new StoreError('bad_ip', '不是合法的 IP 地址')
+    if (/^127\./.test(normalized) || normalized === '::1') throw new StoreError('protected_ip', '不能封禁回环地址')
+    if (isBanned(normalized)) throw new StoreError('duplicate', '该 IP 已在封禁列表')
+    bansDoc.bans.push({ ip: normalized, note: String(note || '').slice(0, 140), createdAt: now(), createdBy: by })
+    return persistBans()
+  }
+
+  async function unbanIp(ip) {
+    const before = bansDoc.bans.length
+    bansDoc.bans = bansDoc.bans.filter((b) => b.ip !== ip)
+    if (bansDoc.bans.length === before) throw new StoreError('not_found', '该 IP 不在封禁列表')
+    return persistBans()
+  }
+
+  // ── activity + audit ledgers ─────────────────────────────────────────────
+
+  function ledgerLine(entry) {
+    return JSON.stringify({
+      ts: now(),
+      type: entry.type,
+      username: entry.username || null,
+      userId: entry.userId || null,
+      ip: entry.ip || '',
+      detail: entry.detail || '',
+    })
+  }
+
+  /** Serialized append to a JSONL ledger with 2×-cap tail rollover. */
+  function appendJsonl({ file, line, getLines, setLines, cap }) {
+    const run = writeChain.ledger
+      .then(() => fsP.appendFile(file, line + '\n', { encoding: 'utf8', mode: 0o600 }))
+      .then(async () => {
+        setLines(getLines() + 1)
+        if (getLines() > cap * 2) {
+          const raw = await fsP.readFile(file, 'utf8')
+          const lines = raw.split('\n').filter((l) => l.trim() !== '')
+          const keep = lines.slice(-cap)
+          setLines(keep.length)
+          await atomicWrite(file, keep.join('\n') + '\n')
+        }
+      })
+    writeChain.ledger = run.catch(() => {})
+    return run
+  }
+
+  async function appendActivity(entry) {
+    return appendJsonl({
+      file: activityFile,
+      line: ledgerLine(entry),
+      getLines: () => ledgerLines,
+      setLines: (n) => { ledgerLines = n },
+      cap: MAX_LEDGER_LINES,
+    })
+  }
+
+  /** Operation audit: every gated API/WebSocket action of a signed-in user. */
+  async function appendAudit(entry) {
+    const id = `a${++auditSeq}`
+    return appendJsonl({
+      file: auditFile,
+      line: JSON.stringify({
+        id,
+        ts: now(),
+        type: entry.type || 'api',
+        username: entry.username || null,
+        userId: entry.userId || null,
+        ip: entry.ip || '',
+        method: entry.method || '',
+        path: entry.path || '',
+        status: entry.status || null,
+      }),
+      getLines: () => auditLines,
+      setLines: (n) => { auditLines = n },
+      cap: MAX_AUDIT_LINES,
+    })
+  }
+
+  /** Remove one audit entry by id (admin manual cleanup). */
+  async function removeAuditEntry(id) {
+    const run = writeChain.ledger.then(async () => {
+      let raw = ''
+      try { raw = await fsP.readFile(auditFile, 'utf8') } catch { return false }
+      const lines = raw.split('\n').filter((l) => l.trim() !== '')
+      const kept = []
+      let removed = false
+      for (const line of lines) {
+        try {
+          if (JSON.parse(line).id === id) { removed = true; continue }
+        } catch { /* keep malformed lines as-is */ }
+        kept.push(line)
+      }
+      if (!removed) return false
+      auditLines = kept.length
+      await atomicWrite(auditFile, kept.length === 0 ? '' : kept.join('\n') + '\n')
+      return true
+    })
+    writeChain.ledger = run.catch(() => {})
+    return run
+  }
+
+  /** Drop the entire audit ledger (admin manual cleanup). */
+  async function clearAudit() {
+    const run = writeChain.ledger.then(async () => {
+      auditLines = 0
+      await atomicWrite(auditFile, '')
+    })
+    writeChain.ledger = run.catch(() => {})
+    return run
+  }
+
+  /**
+   * Read ledger entries newest-first. Filters: type (exact), userId, and a
+   * set of types (`types`). `limit` caps the scan window from the tail.
+   */
+  async function listActivity({ type, types, userId, limit = ACTIVITY_LIMIT_DEFAULT } = {}) {
+    return listJsonl(activityFile, (entry) => {
+      if (type && entry.type !== type) return false
+      if (types) {
+        const set = Array.isArray(types) ? new Set(types) : types
+        if (!set.has(entry.type)) return false
+      }
+      if (userId && entry.userId !== userId) return false
+      return true
+    }, limit)
+  }
+
+  /**
+   * Read the operation audit newest-first. Filters: username, method
+   * (exact), path substring, and a response-status class ('2'|'3'|'4'|'5').
+   */
+  async function listAudit({ username, method, path, statusClass, limit = ACTIVITY_LIMIT_DEFAULT } = {}) {
+    return listJsonl(auditFile, (entry) => {
+      if (username && entry.username !== username) return false
+      if (method && entry.method !== method) return false
+      if (path && !String(entry.path || '').includes(path)) return false
+      if (statusClass && String(entry.status || '').charAt(0) !== statusClass) return false
+      return true
+    }, limit)
+  }
+
+  async function listJsonl(file, predicate, limit) {
+    let raw = ''
+    try { raw = await fsP.readFile(file, 'utf8') } catch { return [] }
+    const lines = raw.split('\n').filter((l) => l.trim() !== '')
+    const cap = Math.max(1, Math.min(Number(limit) || ACTIVITY_LIMIT_DEFAULT, MAX_AUDIT_LINES))
+    const out = []
+    for (let i = lines.length - 1; i >= 0 && out.length < cap; i -= 1) {
+      let entry
+      try { entry = JSON.parse(lines[i]) } catch { continue }
+      if (predicate(entry)) out.push(entry)
+    }
+    return out
+  }
+
+  return {
+    // lifecycle
+    load,
+    // users
+    createUser, verifyLogin, checkLogin, setPassword, setRole, setDisabled, removeUser, touchLogin,
+    listUsers, findUser, findUserByUsername, countAdmins, roleForNextRegistration, publicUser,
+    setPermissions, normalizePermissions, isWorkspaceRestricted, DENY_ALL_WORKSPACES, importUser,
+    // totp
+    startTotpSetup, activateTotp, disableTotp, verifyLoginOtp,
+    // sessions
+    createSession, resolveSession, dropSession, dropUserSessions, pruneSessions,
+    // ip bans
+    isBanned, listBans, banIp, unbanIp,
+    // usage / quotas
+    getUsage, touchUsage, addTokens,
+    // workspace ownership
+    workspaceOwners, workspaceOwnerOf, claimWorkspace, releaseWorkspace, renameWorkspace,
+    // ledger
+    appendActivity, listActivity, appendAudit, listAudit, removeAuditEntry, clearAudit,
+    // internals for tests
+    DEFAULT_PERMISSIONS,
+    SANDBOX_MODES,
+    HOURLY_WINDOW_MS,
+    __files: { dir, usersFile, sessionsFile, activityFile, auditFile, bansFile, usageFile, workspacesFile },
+    __state: () => ({ users: usersDoc.users, sessions: sessionsDoc.tokens, ledgerLines, auditLines, bans: bansDoc.bans, usage: usageDoc.users }),
+    StoreError,
+  }
+}
+
+export {
+  createStore,
+  normalizePermissions,
+  isWorkspaceRestricted,
+  DENY_ALL_WORKSPACES,
+  DEFAULT_PERMISSIONS,
+  SANDBOX_MODES,
+  dshHome,
+  isValidUsername,
+  isValidPassword,
+  verifyPassword,
+  hashPassword,
+  randomToken,
+  tempPassword,
+  tokenFingerprint,
+  normalizeIp,
+  StoreError,
+  SESSION_TTL_MS,
+  SESSION_RENEW_MS,
+  MAX_LEDGER_LINES,
+  MAX_AUDIT_LINES,
+  USERNAME_RE,
+  MIN_PASSWORD_LEN,
+  ACTIVITY_LIMIT_DEFAULT,
+}