create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/auth.service.ts

@@ -2,13 +2,14 @@ import { detectSessionTerminal } from '@/common/constants/session.constants'
 import { AppException } from '@/common/exceptions/app.exception'
 import { Injectable } from '@nestjs/common'
 import { ConfigService } from '@nestjs/config'
-import { AuthUser, LogoutResult, RegisterResult } from 'shared/types'
+import { AuthUser, ChangePasswordResult, LogoutResult, RegisterResult } from 'shared/types'
 import { normalizeAccount } from 'shared/utils'
 import { AUTH_ERRORS } from './auth.errors'
 import { AuthRepository } from './auth.repository'
 import { LoginDto } from './dto/login.dto'
 import { RegisterDto } from './dto/register.dto'
 import { PasswordService } from './password.service'
+import { ChangePasswordDto } from './password/change-password.dto'
 import { SessionStoreService } from './session/session-store.service'
 import { SessionTokenService } from './session/session-token.service'
 
@@ -24,6 +25,9 @@ const LOGIN_DUMMY_PASSWORD_HASH =
 export class AuthService {
   private readonly idleExpiresIn: number
 
+  /**
+   * 读取会话闲置时长，并换算成登录响应使用的秒数。
+   */
   constructor(
     private readonly authRepository: AuthRepository,
     private readonly passwordService: PasswordService,
@@ -34,6 +38,11 @@ export class AuthService {
     this.idleExpiresIn = Math.floor(config.getOrThrow<number>('session.idleTtlMs') / 1000)
   }
 
+  /**
+   * 标准化账号并保存 Argon2 密码摘要，返回不含密码的注册资料。
+   * @param input 用户提交的账号、名称和明文密码。
+   * @throws 账号重复时抛出账号已存在错误，认证依赖失败时返回服务不可用错误。
+   */
   async register(input: RegisterDto): Promise<RegisterResult> {
     const account = normalizeAccount(input.account)
     const passwordHash = await this.useAuthInfrastrutrue(() =>
@@ -57,6 +66,12 @@ export class AuthService {
     }
   }
 
+  /**
+   * 校验启用账号及密码，并替换该用户在当前终端的 Redis 会话。
+   * @param metadata 登录 IP 和 User-Agent，用于识别终端并记录会话来源。
+   * @returns 仅本次返回的明文 Bearer 令牌及会话过期信息。
+   * @throws 账号不可用或密码不匹配时抛出凭据无效错误；认证依赖失败时返回服务不可用。
+   */
   async login(input: LoginDto, metadata: LoginMetadata) {
     const account = normalizeAccount(input.account)
     const user = await this.useAuthInfrastrutrue(() => this.authRepository.findByAccount(account))
@@ -71,13 +86,21 @@ export class AuthService {
 
     const { rawToken, tokenDigest } = this.sessionTokenService.createToken()
 
-    const session = await this.sessionStoreService.createOrReplace({
-      tokenDigest,
-      userId: user.id,
-      terminal: detectSessionTerminal(metadata.userAgent),
-      loginIp: metadata.ip.slice(0, 64),
-      userAgent: metadata.userAgent.slice(0, 500),
-    })
+    const session = await this.useAuthInfrastrutrue(() =>
+      this.authRepository.withActiveUserLock(user.id, (lockedPasswordHash) => {
+        if (lockedPasswordHash !== passwordHash) {
+          throw new AppException(AUTH_ERRORS.INVALID_CREDENTIALS)
+        }
+        return this.sessionStoreService.createOrReplace({
+          tokenDigest,
+          userId: user.id,
+          terminal: detectSessionTerminal(metadata.userAgent),
+          loginIp: metadata.ip.slice(0, 64),
+          userAgent: metadata.userAgent.slice(0, 500),
+        })
+      }),
+    )
+    if (!session) throw new AppException(AUTH_ERRORS.INVALID_CREDENTIALS)
 
     return {
       accessToken: rawToken,
@@ -87,6 +110,10 @@ export class AuthService {
     }
   }
 
+  /**
+   * 在认证基础设施边界执行操作，保留业务异常并将未知异常转换为认证服务不可用。
+   * @returns 原操作的结果。
+   */
   private async useAuthInfrastrutrue<T>(operation: () => Promise<T>): Promise<T> {
     try {
       return await operation()
@@ -98,10 +125,12 @@ export class AuthService {
     }
   }
 
+  /**
+   * 读取仍处于启用状态的用户公开资料。
+   * @throws 用户不存在或已停用时抛出会话失效错误。
+   */
   async getCurrentUser(userId: string): Promise<AuthUser> {
-    const user = await this.useAuthInfrastrutrue(() =>
-      this.authRepository.findPublicById(userId),
-    )
+    const user = await this.useAuthInfrastrutrue(() => this.authRepository.findPublicById(userId))
 
     if (!user || user.status !== 'active') {
       throw new AppException(AUTH_ERRORS.SESSION_INVALID)
@@ -114,6 +143,35 @@ export class AuthService {
     }
   }
 
+  /**
+   * 在本人用户行排他锁内核验旧密码、写入新摘要并撤销全部终端会话。
+   * Redis 撤销失败时事务回滚，旧密码保持有效；成功后当前会话也失效。
+   */
+  async changePassword(userId: string, input: ChangePasswordDto): Promise<ChangePasswordResult> {
+    const result = await this.useAuthInfrastrutrue(() =>
+      this.authRepository.withPasswordWriteLock(userId, async (context) => {
+        const oldPasswordMatches = await this.passwordService.verify(
+          context.passwordHash,
+          input.oldPassword,
+        )
+        if (!oldPasswordMatches) throw new AppException(AUTH_ERRORS.OLD_PASSWORD_INCORRECT)
+        if (input.newPassword === input.oldPassword) {
+          throw new AppException(AUTH_ERRORS.PASSWORD_REUSE_NOT_ALLOWED)
+        }
+
+        const passwordHash = await this.passwordService.hash(input.newPassword)
+        await context.setPasswordHash(passwordHash)
+        await this.sessionStoreService.revokeAllForUser(userId)
+        return { passwordChanged: true as const }
+      }),
+    )
+    if (!result) throw new AppException(AUTH_ERRORS.SESSION_INVALID)
+    return result
+  }
+
+  /**
+   * 撤销请求令牌对应的会话；未提供有效格式的令牌时仍返回退出成功。
+   */
   async logout(authorization: string | undefined): Promise<LogoutResult> {
     const rawToken = this.sessionTokenService.extractBearerToken(authorization)
     if (!rawToken) {

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/dto/register.dto.ts

@@ -11,7 +11,7 @@ export const registerSchema = z.object({
     .min(4)
     .max(32)
     .regex(ACCOUNT_PATTERN, '账号只能包含字母、数字和下划线'),
-  password: z.string().min(8).max(128),
+  password: z.string().min(8).max(16),
 }) satisfies z.ZodType<RegisterRequest>
 
 export class RegisterDto extends createZodDto(registerSchema) {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/guards/session-auth.guard.ts

@@ -6,6 +6,7 @@ import { AUTH_ERRORS } from '../auth.errors'
 import { SessionStoreService } from '../session/session-store.service'
 import { SessionTokenService } from '../session/session-token.service'
 import { AuthenticatedRequest } from '../session/session.types'
+import { AuthRepository } from '../auth.repository'
 
 @Injectable()
 export class SessionAuthGuard implements CanActivate {
@@ -13,8 +14,13 @@ export class SessionAuthGuard implements CanActivate {
     private readonly reflector: Reflector,
     private readonly sessionTokenService: SessionTokenService,
     private readonly sessionStoreService: SessionStoreService,
+    private readonly authRepository: AuthRepository,
   ) {}
 
+  /**
+   * 放行预检和公开路由，否则校验 Bearer 会话及用户状态，并将身份写入 request.auth。
+   * @throws 令牌缺失、会话失效或用户停用时抛出相应认证错误。
+   */
   async canActivate(context: ExecutionContext) {
     const request = context.switchToHttp().getRequest<AuthenticatedRequest>()
 
@@ -44,6 +50,8 @@ export class SessionAuthGuard implements CanActivate {
     if (!auth) {
       throw new AppException(AUTH_ERRORS.SESSION_INVALID)
     }
+    const user = await this.authRepository.findPublicById(auth.userId)
+    if (!user || user.status !== 'active') throw new AppException(AUTH_ERRORS.SESSION_INVALID)
     request.auth = auth
     return true
   }

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/password/change-password.dto.ts

@@ -0,0 +1,17 @@
+import { createZodDto } from 'nestjs-zod'
+import type { ChangePasswordRequest } from 'shared/types'
+import z from 'zod'
+
+/** 本人改密的服务端校验，保持密码原值并检查确认密码一致。 */
+export const changePasswordSchema = z
+  .object({
+    oldPassword: z.string().min(1).max(128),
+    newPassword: z.string().min(8).max(16),
+    confirmPassword: z.string(),
+  })
+  .refine((input) => input.newPassword === input.confirmPassword, {
+    path: ['confirmPassword'],
+    message: '两次密码不一致',
+  }) satisfies z.ZodType<ChangePasswordRequest>
+
+export class ChangePasswordDto extends createZodDto(changePasswordSchema) {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/password.service.ts

@@ -10,10 +10,16 @@ export const PASSWORD_HASH_OPTIONS = {
 
 @Injectable()
 export class PasswordService {
+  /**
+   * 使用统一的 Argon2id 参数对明文密码加盐哈希，返回可用于后续校验的摘要。
+   */
   hash(password: string) {
     return argon2.hash(password, PASSWORD_HASH_OPTIONS)
   }
 
+  /**
+   * 校验明文密码与 Argon2 摘要是否匹配；摘要损坏或校验失败时返回 false。
+   */
   async verify(passswordHash: string, password: string) {
     try {
       return await argon2.verify(passswordHash, password)

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/session/session-store.service.ts

@@ -23,14 +23,29 @@ import { CreatedSession, CreateSessionInput, CurrentAuthType } from './session.t
 const INVALID_SESSION_CODES = new Set(['NOT_FOUND', 'REPLACED', 'ABSOLUTE_EXPIRED'])
 
 type SessionRedis = Redis & {
+  /**
+   * 执行创建或替换会话的 Lua 命令，参数依次包含键、摘要、身份、有效期和登录来源。
+   */
   authCreateOrReplaceSession(...args: string[]): Promise<unknown>
+  /**
+   * 执行会话验证和闲置续期 Lua 命令，返回脚本协议数组供服务层校验。
+   */
   authValidateAndTouchSession(...args: string[]): Promise<unknown>
+  /**
+   * 执行原子退出 Lua 命令，避免删除已被新会话替换的终端槽位。
+   */
   authLogoutSession(...args: string[]): Promise<unknown>
+  /**
+   * 执行用户所有终端会话撤销 Lua 命令，键列表对应各终端槽位。
+   */
   authRevokeUserSessions(...args: string[]): Promise<unknown>
 }
 
 const SCRIPT_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,79}$/
 
+/**
+ * 只保留符合白名单格式的 Lua 返回码，构造不包含原始 Redis 数据的协议错误。
+ */
 function createScriptProtocolError(operation: string, value: string | undefined): Error {
   const code = SCRIPT_CODE_PATTERN.test(value ?? '') ? value : 'UNKNOWN'
   return new Error(`Redis ${operation} script returned ${code}`)
@@ -43,6 +58,9 @@ export class SessionStoreService {
   private readonly idleTtlMs: number
   private readonly absoluteTtlMs: number
 
+  /**
+   * 读取会话时限并注册 Lua 命令，使会话和终端槽位的变更在 Redis 中原子执行。
+   */
   constructor(@InjectRedis() redis: Redis, config: ConfigService) {
     this.redis = redis as SessionRedis
     this.idleTtlMs = config.getOrThrow<number>('session.idleTtlMs')
@@ -69,6 +87,10 @@ export class SessionStoreService {
     })
   }
 
+  /**
+   * 执行会话 Lua 命令并规范化数组结果。
+   * @throws Redis 调用失败或返回格式异常时抛出认证服务不可用错误。
+   */
   private async execute(command: () => Promise<unknown>) {
     try {
       const result = await command()
@@ -82,6 +104,11 @@ export class SessionStoreService {
     }
   }
 
+  /**
+   * 原子创建会话并替换该用户同一终端的旧会话。
+   * @param input 令牌摘要、用户终端及登录来源信息。
+   * @returns 初始闲置过期时间与不可延长的绝对过期时间，单位为毫秒。
+   */
   async createOrReplace(input: CreateSessionInput): Promise<CreatedSession> {
     const result = await this.execute(() =>
       this.redis.authCreateOrReplaceSession(
@@ -105,6 +132,15 @@ export class SessionStoreService {
 
     const initialExpiresAtMs = Number(result[2])
     const absoluteExpiresAtMs = Number(result[3])
+    if (
+      result[0] !== '1' ||
+      !Number.isFinite(initialExpiresAtMs) ||
+      !Number.isFinite(absoluteExpiresAtMs)
+    ) {
+      throw new AppException(AUTH_ERRORS.SERVICE_UNAVAILABLE, {
+        cause: createScriptProtocolError('createOrReplace', result[1]),
+      })
+    }
 
     // if (!Number.isFinite(initialExpiresAtMs) || !Number.isFinite(absoluteExpiresAtMs)) {
     //   throw new ServiceUnavailableException('登录状态数据异常')
@@ -116,6 +152,10 @@ export class SessionStoreService {
     }
   }
 
+  /**
+   * 校验令牌对应会话并刷新闲置有效期，刷新不会超过绝对有效期。
+   * @returns 用户及终端身份；会话缺失、被替换或过期时返回 null。
+   */
   async validateAndTouch(tokenDigest: string): Promise<CurrentAuthType | null> {
     const result = await this.execute(() =>
       this.redis.authValidateAndTouchSession(
@@ -160,6 +200,9 @@ export class SessionStoreService {
     }
   }
 
+  /**
+   * 原子撤销令牌对应会话，并仅在槽位仍指向该令牌时清理终端槽位。
+   */
   async logout(tokenDigest: string) {
     const result = await this.execute(() =>
       this.redis.authLogoutSession(createSessionKey(tokenDigest), tokenDigest, SESSION_SLOT_PREFIX),
@@ -177,6 +220,9 @@ export class SessionStoreService {
     }
   }
 
+  /**
+   * 原子撤销用户在所有支持终端上的会话，供停用用户等操作使用。
+   */
   async revokeAllForUser(userId: string) {
     const slotKeys = SESSION_TERMINALS.map((terminal) => createSessionSlotKey(userId, terminal))
     const result = await this.execute(() =>

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/session/session-token.service.ts

@@ -6,14 +6,23 @@ import { createHmac, randomBytes } from 'node:crypto'
 export class SessionTokenService {
   private readonly tokenPepper: string
 
+  /**
+   * 读取用于令牌摘要计算的服务端密钥。
+   */
   constructor(config: ConfigService) {
     this.tokenPepper = config.getOrThrow<string>('session.tokenPepper')
   }
 
+  /**
+   * 使用服务端密钥计算令牌的 HMAC-SHA256 摘要，供 Redis 存储和查询使用。
+   */
   digest(rawToken: string) {
     return createHmac('sha256', this.tokenPepper).update(rawToken).digest('hex')
   }
 
+  /**
+   * 生成 32 字节随机不透明令牌及其摘要，明文令牌仅交给客户端。
+   */
   createToken() {
     const rawToken = randomBytes(32).toString('base64url')
     return {
@@ -22,6 +31,9 @@ export class SessionTokenService {
     }
   }
 
+  /**
+   * 严格提取大小写匹配、长度为 43 的 base64url Bearer 令牌；格式不合法时返回 null。
+   */
   extractBearerToken(authorization: string | undefined) {
     const matched = /^Bearer\s+([A-Za-z0-9_-]{43})$/.exec(authorization ?? '')
     return matched?.[1] ?? null

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/session/session.script.ts

@@ -86,6 +86,12 @@ return {
 `
 
 export const VALIDATE_AND_TOUCH_SESSION_SCRIPT = String.raw`
+local function isValidDigest(value)
+  return value
+    and string.len(value) == 64
+    and string.match(value, '^[0-9a-f]+$') ~= nil
+end
+
 local function isValidTerminal(value)
   return value == 'web' or value == 'desktop' or value == 'mobile'
 end
@@ -204,7 +210,7 @@ export const REVOKE_USER_SESSIONS_SCRIPT = String.raw`
 local sessionKeyPrefix = ARGV[1]
 local revokedCount = 0
 
-for index = 1, #KEYS DO
+for index = 1, #KEYS do
   local digest = redis.call('GET', KEYS[index])
 
   if digest

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/companies/companies.controller.ts

@@ -0,0 +1,105 @@
+import { Body, Controller, Get, HttpCode, Patch, Post, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor, ids } from '@/modules/access/access-http'
+import { entityListSchema, parse, statusSchema } from '@/modules/access/access.validation'
+import {
+  createCompanySchema,
+  profileSchema,
+} from '@/modules/access/workspaces/workspaces.validation'
+import { administratorSchema } from '@/modules/members/administrators/administrators.validation'
+import { updateCompanyHierarchySchema } from 'shared/utils'
+import { CompaniesService } from './companies.service'
+
+@Controller()
+export class CompaniesController {
+  constructor(private readonly companiesService: CompaniesService) {}
+  /** 校验分页筛选参数，从平台入口查询公司列表。 */
+  @Get('platform/companies')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.companies.read' })
+  companies(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.companiesService.listCompanies({
+      actor: actor(req),
+      query: parse(entityListSchema, query),
+    })
+  }
+  /** 返回平台当前可见企业的完整父子层级树，并按同级排序稳定组装。 */
+  @Get('platform/companies/tree')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.companies.read' })
+  companyTree(@Req() req: FastifyRequest) {
+    return this.companiesService.hierarchyTree({ actor: actor(req) })
+  }
+  /** 校验公司标识，从平台入口读取公司资料及管理员详情。 */
+  @Get('platform/companies/:companyId')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.companies.read' })
+  companyDetail(@Req() req: FastifyRequest) {
+    return this.companiesService.get({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      platform: true,
+    })
+  }
+  /** 校验公司资料、层级字段和初始管理员 userId，提交平台管理员创建公司操作。 */
+  @Post('platform/companies')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.companies.create', adminOnly: true })
+  createCompany(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.companiesService.create({
+      actor: actor(req),
+      body: parse(createCompanySchema, body),
+    })
+  }
+  /** 校验公司标识、预期版本及状态，提交平台侧公司启停操作。 */
+  @Patch('platform/companies/:companyId/status')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.companies.status' })
+  companyStatus(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.companiesService.status({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      body: parse(statusSchema, body),
+    })
+  }
+  /** 校验目标父企业、循环、同级名称和版本后调整企业层级资料。 */
+  @Patch('platform/companies/:companyId/hierarchy')
+  @AccessPolicy({
+    scope: 'platform',
+    permission: 'platform.companies.hierarchy',
+  })
+  companyHierarchy(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.companiesService.updateHierarchy({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      body: parse(updateCompanyHierarchySchema, body),
+    })
+  }
+  /** 校验公司标识及管理员 userId，提交平台管理员追加或替换公司管理员操作。 */
+  @Post('platform/companies/:companyId/administrator')
+  @HttpCode(200)
+  @AccessPolicy({
+    scope: 'platform',
+    permission: 'platform.companies.administrator',
+    adminOnly: true,
+  })
+  companyAdministrator(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.companiesService.setAdministrator({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      body: parse(administratorSchema, body),
+    })
+  }
+  /** 校验公司标识，在公司作用域中读取当前公司资料和管理员详情。 */
+  @Get('companies/:companyId')
+  @AccessPolicy({ scope: 'company', permission: 'company.profile.read' })
+  profile(@Req() req: FastifyRequest) {
+    return this.companiesService.get({ actor: actor(req), companyId: ids(req).companyId! })
+  }
+  /** 校验公司标识、预期版本与资料字段，提交当前公司的资料更新。 */
+  @Patch('companies/:companyId')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.profile.update' })
+  updateProfile(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.companiesService.profile({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      body: parse(profileSchema, body),
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/companies/companies.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common'
+import { AccessModule } from '../access/access.module'
+import { MembersModule } from '../members/members.module'
+import { CompaniesController } from './companies.controller'
+import { CompaniesService } from './companies.service'
+
+@Module({
+  imports: [AccessModule, MembersModule],
+  controllers: [CompaniesController],
+  providers: [CompaniesService],
+})
+export class CompaniesModule {}