agentworkshop 0.8.6 → 0.8.8

package/server/services/user.service.ts

@@ -1,258 +1,277 @@
-import { userRepository, findByToken, verifyPassword } from '../repositories/user.repository'
-import type { UserListInput, UserListQuery, UserToken, AuthResult } from '../types/user'
-import type { UserCreate, UserUpdate, UserLogin, UserRegister } from '../schemas/user.schema'
-import { AppError, ErrorCodes } from '../utils/errors'
-import { useServerConfig } from '../utils/config'
-import { randomBytes } from 'node:crypto'
-import { recordOps } from './workshop/ops/ops'
-/**
- * 用户业务逻辑层（Service）
- * 职责：领域规则、认证（注册/登录/token 签发）、token 隔离（仅本人可 CRUD）、
- * 默认值解析（config 驱动）、跨仓库编排。
- * 不感知 HTTP 细节（h3），不直接触碰数据源。
- */
-
-/** 经 token 解析的用户档案（附带当前 tokenId，可识别会话 token） */
-export type UserProfile = AuthResult['user'] & { tokenId: string }
-
-/** 从 Authorization 头解析用户（供 workshop 等跨模块认证共用）：token → 用户档案或 null */
-export function resolveUserByToken(token: string): UserProfile | null {
-  const user = findByToken(token)
-  return user
-    ? {
-        id: user.id, name: user.name, email: user.email, role: user.role, createdAt: user.createdAt,
-        // findByToken 返回原生行(别名列为 0/1,非布尔):这里统一归一
-        mustChangePassword: Number((user as unknown as { mustChangePassword?: number | boolean }).mustChangePassword ?? 0) === 1,
-        tokenId: user.tokenId,
-      }
-    : null
-}
-
-export const userService = {
-  /**
-   * 登录防爆破:同 IP+邮箱在 15 分钟窗口内累计失败 ≥5 次 → 锁到窗口结束(429)。
-   * 内存态,重启即清;多实例部署由反代层限流补齐。计数表封顶 5000 条防内存滥用。
-   */
-  _loginFails: new Map<string, { count: number, firstAt: number }>(),
-
-  // ===== 管理面（与既有契约一致）=====
-
-  list(input: UserListInput) {
-    const { api } = useServerConfig()
-    const query: UserListQuery = {
-      page: input.page,
-      pageSize: Math.min(input.pageSize ?? api.pageSize, api.maxPageSize),
-      keyword: input.keyword,
-    }
-    return userRepository.list(query)
-  },
-
-  getById(id: string) {
-    const user = userRepository.findById(id)
-    if (!user) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
-    }
-    return user
-  },
-
-  create(input: UserCreate) {
-    if (userRepository.findByEmail(input.email)) {
-      throw new AppError(409, ErrorCodes.CONFLICT, '邮箱已被注册')
-    }
-    const password = input.password ?? randomPassword()
-    // 管理面建号一律首登强制改密:口令经管理员之手(或随机生成),不属于用户本人秘密
-    return userRepository.create({ ...input, password, mustChangePassword: true })
-  },
-
-  update(id: string, input: UserUpdate) {
-    if (input.email) {
-      const exists = userRepository.findByEmail(input.email)
-      if (exists && exists.id !== id) {
-        throw new AppError(409, ErrorCodes.CONFLICT, '邮箱已被占用')
-      }
-    }
-    // 管理面经 PUT 改密等同重置:置首登强制改密 + 吊销全部旧会话(旧 token 即死,
-    // 与 resetPassword 同语义;e2e M8 实证此前漏吊销)
-    const passwordChanged = input.password !== undefined
-    const patch = passwordChanged ? { ...input, mustChangePassword: true } : input
-    const user = userRepository.update(id, patch)
-    if (!user) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
-    }
-    if (passwordChanged) userRepository.revokeAllTokens(id)
-    return user
-  },
-
-  remove(id: string) {
-    if (!userRepository.remove(id)) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
-    }
-    return { id }
-  },
-
-  /** 管理面：重置指定用户密码 → 首登强制改密 + 吊销全部旧会话(旧 token 即死) */
-  resetPassword(id: string, password: string) {
-    const user = userRepository.update(id, { password, mustChangePassword: true })
-    if (!user) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
-    }
-    const revoked = userRepository.revokeAllTokens(id)
-    return { id, revokedSessions: revoked, mustChangePassword: true }
-  },
-
-  /** 本人修改密码(首登强制改密同一入口):当前密码验证 → 更新哈希并清除强制标记 */
-  changePassword(userId: string, currentPassword: string, newPassword: string) {
-    const user = userRepository.findById(userId)
-    if (!user) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
-    }
-    const { hash } = userRepository.getPasswordHash(user.email) ?? {}
-    if (!hash || !verifyPassword(currentPassword, hash)) {
-      throw new AppError(401, 'UNAUTHORIZED', '当前密码不正确')
-    }
-    userRepository.update(userId, { password: newPassword, mustChangePassword: false })
-    recordOps({
-      actor: userId, actorName: user.name, actorKind: 'user',
-      action: 'auth.password.change', kind: 'system', targetKind: 'user', targetId: userId,
-      summary: `用户 ${user.name}(${user.email})修改了密码${user.mustChangePassword ? '(完成首登强制改密)' : ''}`,
-    })
-    return { ok: true, mustChangePassword: false }
-  },
-
-  // ===== 认证（公开端点）=====
-
-  /** 注册：创建账号 + 签发首个 token（邮箱/用户名占用 → 409）。
-   * 首启初始化:原子事务内判定「尚无活跃管理员」→ 首个注册账号授予 admin
-   * (并发注册不会产生第二个 bootstrap admin) */
-  register(input: UserRegister): AuthResult {
-    if (userRepository.findByEmail(input.email)) {
-      throw new AppError(409, ErrorCodes.CONFLICT, '邮箱已被注册')
-    }
-    if (userRepository.findByName(input.name)) {
-      throw new AppError(409, 'USER_EXISTS', `用户名已存在: ${input.name}`)
-    }
-    const { user, bootstrap: needsBootstrap } = userRepository.createWithRoleBootstrap({
-      ...input, role: 'user', status: 'active',
-    })
-    if (needsBootstrap) {
-      console.log(`[users] 初始化:尚无管理员账号,首个注册账号授予管理员角色(${input.email})`)
-    }
-    const { raw } = userRepository.createToken(user.id, needsBootstrap ? 'bootstrap-admin' : 'default')
-    return { user: this.publicProfile(user), token: raw }
-  },
-
-  /** 登录：密码校验通过后签发新 token（每次登录生成一个可独立吊销的会话 token） */
-  login(input: UserLogin, opts: { ip?: string } = {}): AuthResult {
-    const FAIL_WINDOW_MS = 15 * 60_000
-    const LOCK_THRESHOLD = 5
-    const lockKey = `${opts.ip ?? 'local'}|${input.email.toLowerCase()}`
-    const fails = this._loginFails
-    if (fails.size > 5000) {
-      const oldest = fails.keys().next().value
-      if (oldest) fails.delete(oldest)
-    }
-    const rec = fails.get(lockKey)
-    // 已达阈值且窗口未过 → 锁定;偶发失败(1-4 次)不锁,窗口滑过即重置
-    if (rec && rec.count >= LOCK_THRESHOLD && Date.now() - rec.firstAt < FAIL_WINDOW_MS) {
-      const waitMin = Math.ceil((FAIL_WINDOW_MS - (Date.now() - rec.firstAt)) / 60_000)
-      recordOps({
-        actor: input.email, actorName: input.email, actorKind: 'user',
-        action: 'auth.login.locked', kind: 'system', targetKind: 'user', targetId: input.email,
-        summary: `登录锁定:账号 ${input.email} 连续失败过多,已临时锁定(约 ${waitMin} 分钟,来源 IP ${opts.ip ?? 'local'})`,
-      })
-      throw new AppError(429, 'LOGIN_LOCKED', `失败次数过多,账号已临时锁定,请约 ${waitMin} 分钟后再试`)
-    }
-    const { id, hash } = userRepository.getPasswordHash(input.email) ?? {}
-    if (!id || !hash || !verifyPassword(input.password, hash)) {
-      if (!rec || Date.now() - rec.firstAt >= FAIL_WINDOW_MS) fails.set(lockKey, { count: 1, firstAt: Date.now() })
-      else rec.count += 1
-      throw new AppError(401, 'UNAUTHORIZED', '邮箱或密码错误')
-    }
-    const user = userRepository.findById(id)
-    if (!user) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
-    }
-    if (user.status !== 'active') {
-      throw new AppError(403, 'FORBIDDEN', '账号已禁用')
-    }
-    fails.delete(lockKey)
-    const { raw } = userRepository.createToken(id, `session-${Date.now()}`)
-    recordOps({
-      actor: id, actorName: user.name, actorKind: 'user',
-      action: 'auth.login', kind: 'system', targetKind: 'user', targetId: id,
-      summary: `用户 ${user.name}(${user.email})登录成功(IP ${opts.ip ?? 'local'})`,
-    })
-    return { user: this.publicProfile(user), token: raw }
-  },
-
-  /** 登出：吊销当前 token（仅该 token 失效，其余会话不受影响） */
-  logout(token: string): { ok: boolean } {
-    return { ok: userRepository.revokeTokenByValue(token) }
-  },
-
-  // ===== 当前用户（Bearer token 身份）=====
-
-  me(token: string): AuthResult['user'] {
-    const profile = resolveUserByToken(token)
-    if (!profile) {
-      throw new AppError(401, 'UNAUTHORIZED', 'token 无效或已吊销')
-    }
-    return profile
-  },
-
-  // ===== Token CRUD（仅本人可操作自己的 token）=====
-
-  listTokens(userId: string): UserToken[] {
-    return userRepository.listTokens(userId)
-  },
-
-  /** 创建 token；返回明文一次（label 缺省空串） */
-  createToken(userId: string, label: string): { id: string, label: string, token: string, createdAt: string } {
-    const { raw, row } = userRepository.createToken(userId, label)
-    return { id: row.id, label: row.label, token: raw, createdAt: row.createdAt }
-  },
-
-  updateToken(userId: string, tokenId: string, label: string): UserToken {
-    if (!userRepository.updateTokenLabel(userId, tokenId, label)) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在或不属于当前用户')
-    }
-    const token = userRepository.findTokenById(userId, tokenId)
-    if (!token) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在')
-    }
-    return token
-  },
-
-  revokeToken(userId: string, tokenId: string): { id: string } {
-    if (!userRepository.revokeToken(userId, tokenId)) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在或不属于当前用户')
-    }
-    return { id: tokenId }
-  },
-
-  /** 查看存档明文（仅本人）；undefined=token 不存在，null=旧数据未存档 */
-  revealToken(userId: string, tokenId: string): string | null {
-    const plain = userRepository.findTokenPlain(userId, tokenId)
-    if (plain === undefined) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在或不属于当前用户')
-    }
-    if (plain === null) {
-      throw new AppError(410, 'TOKEN_PLAIN_GONE', '该 token 创建于旧版本（仅存哈希），无法查看明文；请重新签发')
-    }
-    return plain
-  },
-
-  /** 公开档案（不含敏感字段） */
-  publicProfile(u: { id: string, name: string, email: string, role: string, createdAt: string, mustChangePassword?: boolean }): AuthResult['user'] {
-    return { id: u.id, name: u.name, email: u.email, role: u.role, createdAt: u.createdAt, mustChangePassword: u.mustChangePassword === true }
-  },
-}
-
-/** 20 位随机口令（管理面创建用户未给密码时使用） */
-function randomPassword(): string {
-  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
-  const bytes = randomBytes(20)
-  let out = ''
-  for (const b of bytes) out += chars[b % chars.length]
-  return out
-}
+import { userRepository, findByToken, verifyPassword } from '../repositories/user.repository'
+import type { UserListInput, UserListQuery, UserToken, AuthResult } from '../types/user'
+import type { UserCreate, UserUpdate, UserLogin, UserRegister } from '../schemas/user.schema'
+import { AppError, ErrorCodes } from '../utils/errors'
+import { useServerConfig } from '../utils/config'
+import { randomBytes } from 'node:crypto'
+import { recordOps } from './workshop/ops/ops'
+/**
+ * 用户业务逻辑层（Service）
+ * 职责：领域规则、认证（注册/登录/token 签发）、token 隔离（仅本人可 CRUD）、
+ * 默认值解析（config 驱动）、跨仓库编排。
+ * 不感知 HTTP 细节（h3），不直接触碰数据源。
+ */
+
+/** 经 token 解析的用户档案（附带当前 tokenId，可识别会话 token） */
+export type UserProfile = AuthResult['user'] & { tokenId: string }
+
+/** 从 Authorization 头解析用户（供 workshop 等跨模块认证共用）：token → 用户档案或 null */
+export function resolveUserByToken(token: string): UserProfile | null {
+  const user = findByToken(token)
+  return user
+    ? {
+        id: user.id, name: user.name, email: user.email, role: user.role, createdAt: user.createdAt,
+        // findByToken 返回原生行(别名列为 0/1,非布尔):这里统一归一
+        mustChangePassword: Number((user as unknown as { mustChangePassword?: number | boolean }).mustChangePassword ?? 0) === 1,
+        tokenId: user.tokenId,
+      }
+    : null
+}
+
+export const userService = {
+  /**
+   * 登录防爆破:同 IP+邮箱在 15 分钟窗口内累计失败 ≥5 次 → 锁到窗口结束(429)。
+   * 内存态,重启即清;多实例部署由反代层限流补齐。计数表封顶 5000 条防内存滥用。
+   */
+  _loginFails: new Map<string, { count: number, firstAt: number }>(),
+
+  // ===== 管理面（与既有契约一致）=====
+
+  list(input: UserListInput) {
+    const { api } = useServerConfig()
+    const query: UserListQuery = {
+      page: input.page,
+      pageSize: Math.min(input.pageSize ?? api.pageSize, api.maxPageSize),
+      keyword: input.keyword,
+    }
+    return userRepository.list(query)
+  },
+
+  getById(id: string) {
+    const user = userRepository.findById(id)
+    if (!user) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
+    }
+    return user
+  },
+
+  create(input: UserCreate) {
+    if (userRepository.findByEmail(input.email)) {
+      throw new AppError(409, ErrorCodes.CONFLICT, '邮箱已被注册')
+    }
+    const password = input.password ?? randomPassword()
+    // 管理面建号一律首登强制改密:口令经管理员之手(或随机生成),不属于用户本人秘密
+    return userRepository.create({ ...input, password, mustChangePassword: true })
+  },
+
+  update(id: string, input: UserUpdate) {
+    if (input.email) {
+      const exists = userRepository.findByEmail(input.email)
+      if (exists && exists.id !== id) {
+        throw new AppError(409, ErrorCodes.CONFLICT, '邮箱已被占用')
+      }
+    }
+    // 管理面经 PUT 改密等同重置:置首登强制改密 + 吊销全部旧会话(旧 token 即死,
+    // 与 resetPassword 同语义;e2e M8 实证此前漏吊销)
+    const passwordChanged = input.password !== undefined
+    const patch = passwordChanged ? { ...input, mustChangePassword: true } : input
+    const user = userRepository.update(id, patch)
+    if (!user) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
+    }
+    if (passwordChanged) userRepository.revokeAllTokens(id)
+    return user
+  },
+
+  remove(id: string) {
+    if (!userRepository.remove(id)) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
+    }
+    return { id }
+  },
+
+  /** 管理面：重置指定用户密码 → 首登强制改密 + 吊销全部旧会话(旧 token 即死) */
+  resetPassword(id: string, password: string) {
+    const user = userRepository.update(id, { password, mustChangePassword: true })
+    if (!user) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
+    }
+    const revoked = userRepository.revokeAllTokens(id)
+    return { id, revokedSessions: revoked, mustChangePassword: true }
+  },
+
+  /** 本人修改密码(首登强制改密同一入口):当前密码验证 → 更新哈希并清除强制标记 */
+  changePassword(userId: string, currentPassword: string, newPassword: string) {
+    const user = userRepository.findById(userId)
+    if (!user) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
+    }
+    const { hash } = userRepository.getPasswordHash(user.email) ?? {}
+    if (!hash || !verifyPassword(currentPassword, hash)) {
+      throw new AppError(401, 'UNAUTHORIZED', '当前密码不正确')
+    }
+    userRepository.update(userId, { password: newPassword, mustChangePassword: false })
+    recordOps({
+      actor: userId, actorName: user.name, actorKind: 'user',
+      action: 'auth.password.change', kind: 'system', targetKind: 'user', targetId: userId,
+      summary: `用户 ${user.name}(${user.email})修改了密码${user.mustChangePassword ? '(完成首登强制改密)' : ''}`,
+    })
+    return { ok: true, mustChangePassword: false }
+  },
+
+  // ===== 认证（公开端点）=====
+
+  /** 注册：创建账号 + 签发首个 token（邮箱/用户名占用 → 409）。
+   * 首启初始化:原子事务内判定「尚无活跃管理员」→ 首个注册账号授予 admin
+   * (并发注册不会产生第二个 bootstrap admin) */
+  register(input: UserRegister): AuthResult {
+    if (userRepository.findByEmail(input.email)) {
+      throw new AppError(409, ErrorCodes.CONFLICT, '邮箱已被注册')
+    }
+    if (userRepository.findByName(input.name)) {
+      throw new AppError(409, 'USER_EXISTS', `用户名已存在: ${input.name}`)
+    }
+    const { user, bootstrap: needsBootstrap } = userRepository.createWithRoleBootstrap({
+      ...input, role: 'user', status: 'active',
+    })
+    if (needsBootstrap) {
+      console.log(`[users] 初始化:尚无管理员账号,首个注册账号授予管理员角色(${input.email})`)
+    }
+    const { raw } = userRepository.createToken(user.id, needsBootstrap ? 'bootstrap-admin' : 'default')
+    return { user: this.publicProfile(user), token: raw }
+  },
+
+  /**
+   * 登录：密码校验通过后签发新 token（每次登录生成一个可独立吊销的会话 token）。
+   *
+   * 失败锁定(2026-10-30 P2-7 重构):
+   *  - 锁键**只按账号**(此前是 `ip|email`,叠加 XFF 伪造即可把任意受害者锁死);
+   *  - 先验密码再判锁:密码正确一律放行 —— 攻击者狂刷错误密码无法把真实用户挡在门外;
+   *  - 密码错误时累计,达阈值返回 429 统一文案(不泄露"账号是否存在");
+   *  - IP 只入审计(来源可追溯),不参与判定。
+   */
+  login(input: UserLogin, opts: { ip?: string } = {}): AuthResult {
+    const FAIL_WINDOW_MS = 15 * 60_000
+    const LOCK_THRESHOLD = 5
+    const accountKey = input.email.trim().toLowerCase()
+    const fails = this._loginFails
+    if (fails.size > 5000) {
+      const oldest = fails.keys().next().value
+      if (oldest) fails.delete(oldest)
+    }
+    const rec = fails.get(accountKey)
+    const locked = Boolean(rec && rec.count >= LOCK_THRESHOLD && Date.now() - rec.firstAt < FAIL_WINDOW_MS)
+
+    const { id, hash } = userRepository.getPasswordHash(input.email) ?? {}
+    const passwordOk = Boolean(id && hash && verifyPassword(input.password, hash))
+    if (!passwordOk) {
+      if (!rec || Date.now() - rec.firstAt >= FAIL_WINDOW_MS) fails.set(accountKey, { count: 1, firstAt: Date.now() })
+      else rec.count += 1
+      const now = fails.get(accountKey)!
+      if (now.count >= LOCK_THRESHOLD) {
+        const waitMin = Math.max(1, Math.ceil((FAIL_WINDOW_MS - (Date.now() - now.firstAt)) / 60_000))
+        recordOps({
+          actor: input.email, actorName: input.email, actorKind: 'user',
+          action: 'auth.login.locked', kind: 'system', targetKind: 'user', targetId: input.email,
+          summary: `登录失败达阈值:账号 ${input.email} 暂缓签发(约 ${waitMin} 分钟,来源 IP ${opts.ip ?? 'local'})`,
+        })
+        throw new AppError(429, 'LOGIN_LOCKED', `失败次数过多,请约 ${waitMin} 分钟后再试`)
+      }
+      throw new AppError(401, 'UNAUTHORIZED', '邮箱或密码错误')
+    }
+    if (locked) {
+      // 密码正确但此前处于锁定期:放行,并记一条审计(说明确有攻击面在发生)
+      recordOps({
+        actor: input.email, actorName: input.email, actorKind: 'user',
+        action: 'auth.login.lock_bypassed', kind: 'system', targetKind: 'user', targetId: input.email,
+        summary: `账号 ${input.email} 处于失败锁定期,凭正确密码正常登录(来源 IP ${opts.ip ?? 'local'})`,
+      })
+    }
+    const user = userRepository.findById(id!)
+    if (!user) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, '用户不存在')
+    }
+    if (user.status !== 'active') {
+      throw new AppError(403, 'FORBIDDEN', '账号已禁用')
+    }
+    fails.delete(accountKey)
+    const { raw } = userRepository.createToken(id!, `session-${Date.now()}`)
+    recordOps({
+      actor: id!, actorName: user.name, actorKind: 'user',
+      action: 'auth.login', kind: 'system', targetKind: 'user', targetId: id!,
+      summary: `用户 ${user.name}(${user.email})登录成功(IP ${opts.ip ?? 'local'})`,
+    })
+    return { user: this.publicProfile(user), token: raw }
+  },
+
+  /** 登出：吊销当前 token（仅该 token 失效，其余会话不受影响） */
+  logout(token: string): { ok: boolean } {
+    return { ok: userRepository.revokeTokenByValue(token) }
+  },
+
+  // ===== 当前用户（Bearer token 身份）=====
+
+  me(token: string): AuthResult['user'] {
+    const profile = resolveUserByToken(token)
+    if (!profile) {
+      throw new AppError(401, 'UNAUTHORIZED', 'token 无效或已吊销')
+    }
+    return profile
+  },
+
+  // ===== Token CRUD（仅本人可操作自己的 token）=====
+
+  listTokens(userId: string): UserToken[] {
+    return userRepository.listTokens(userId)
+  },
+
+  /** 创建 token；返回明文一次（label 缺省空串） */
+  createToken(userId: string, label: string): { id: string, label: string, token: string, createdAt: string } {
+    const { raw, row } = userRepository.createToken(userId, label)
+    return { id: row.id, label: row.label, token: raw, createdAt: row.createdAt }
+  },
+
+  updateToken(userId: string, tokenId: string, label: string): UserToken {
+    if (!userRepository.updateTokenLabel(userId, tokenId, label)) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在或不属于当前用户')
+    }
+    const token = userRepository.findTokenById(userId, tokenId)
+    if (!token) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在')
+    }
+    return token
+  },
+
+  revokeToken(userId: string, tokenId: string): { id: string } {
+    if (!userRepository.revokeToken(userId, tokenId)) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在或不属于当前用户')
+    }
+    return { id: tokenId }
+  },
+
+  /** 查看存档明文（仅本人）；undefined=token 不存在，null=旧数据未存档 */
+  revealToken(userId: string, tokenId: string): string | null {
+    const plain = userRepository.findTokenPlain(userId, tokenId)
+    if (plain === undefined) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, 'token 不存在或不属于当前用户')
+    }
+    if (plain === null) {
+      throw new AppError(410, 'TOKEN_PLAIN_GONE', '该 token 创建于旧版本（仅存哈希），无法查看明文；请重新签发')
+    }
+    return plain
+  },
+
+  /** 公开档案（不含敏感字段） */
+  publicProfile(u: { id: string, name: string, email: string, role: string, createdAt: string, mustChangePassword?: boolean }): AuthResult['user'] {
+    return { id: u.id, name: u.name, email: u.email, role: u.role, createdAt: u.createdAt, mustChangePassword: u.mustChangePassword === true }
+  },
+}
+
+/** 20 位随机口令（管理面创建用户未给密码时使用） */
+function randomPassword(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+  const bytes = randomBytes(20)
+  let out = ''
+  for (const b of bytes) out += chars[b % chars.length]
+  return out
+}