create-bubbles 0.1.25 → 0.1.27

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

@@ -0,0 +1,74 @@
+import { Injectable } from '@nestjs/common'
+import { and, count, desc, eq, gte, lte } from 'drizzle-orm'
+import type { AccessScope, AuditQuery, AuditRecord, PageResult } from 'shared/types'
+import { auditLogs } from '@/database/schema'
+import { AccessService, type AccessActor } from '@/modules/access/access.service'
+import { pageWindow, searchSql, toScope } from '@/modules/access/access.store'
+
+@Injectable()
+export class AuditService {
+  constructor(private readonly access: AccessService) {}
+
+  /**
+   * 按当前作用域审计权限分页查询日志，支持操作、操作者、时间范围和关键词筛选。
+   *
+   * 平台仅查询平台日志，公司包含本公司及所属项目日志，项目仅查询该项目日志。
+   * @returns 按时间倒序排列的审计记录及分页信息。
+   */
+  list(input: {
+    actor: AccessActor
+    scope: AccessScope
+    query: AuditQuery
+  }): Promise<PageResult<AuditRecord>> {
+    const { actor, scope, query } = input
+    return this.access.read(
+      { actor, scope, permission: `${scope.type}.audit.read` },
+      /** 按平台、公司或项目构造日志范围，在同一快照内完成筛选、计数和分页。 */
+      async (tx) => {
+        const scopeCondition =
+          scope.type === 'platform'
+            ? eq(auditLogs.scopeType, 'platform')
+            : scope.type === 'company'
+              ? eq(auditLogs.companyId, scope.companyId)
+              : and(
+                  eq(auditLogs.companyId, scope.companyId),
+                  eq(auditLogs.projectId, scope.projectId),
+                  eq(auditLogs.scopeType, 'project'),
+                )
+        const { page, pageSize, offset } = pageWindow(query)
+        const condition = and(
+          scopeCondition,
+          query.action ? eq(auditLogs.action, query.action) : undefined,
+          query.actorId ? eq(auditLogs.actorUserId, query.actorId) : undefined,
+          query.from ? gte(auditLogs.createdAt, new Date(query.from)) : undefined,
+          query.to ? lte(auditLogs.createdAt, new Date(query.to)) : undefined,
+          searchSql([auditLogs.action, auditLogs.objectType, auditLogs.objectId], query.query),
+        )
+        const [total] = await tx.select({ value: count() }).from(auditLogs).where(condition)
+        const rows = await tx
+          .select()
+          .from(auditLogs)
+          .where(condition)
+          .orderBy(desc(auditLogs.createdAt), desc(auditLogs.id))
+          .limit(pageSize)
+          .offset(offset)
+        return {
+          page,
+          pageSize,
+          total: total!.value,
+          items: rows.map((r) => ({
+            id: r.id,
+            actor: { id: r.actorUserId, name: r.actorName, account: r.actorAccount },
+            scope: toScope(r),
+            action: r.action,
+            objectType: r.objectType,
+            objectId: r.objectId,
+            summary: r.summary,
+            requestId: r.requestId,
+            createdAt: r.createdAt.toISOString(),
+          })),
+        }
+      },
+    )
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.validation.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+import { idSchema, pageSchema } from '@/modules/access/access.validation'
+
+export const auditSchema = pageSchema
+  .extend({
+    action: z.string().max(120).optional(),
+    actorId: idSchema.optional(),
+    from: z.iso.datetime().optional(),
+    to: z.iso.datetime().optional(),
+  })
+  .refine((v) => !v.from || !v.to || v.from <= v.to)

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

@@ -1,4 +1,5 @@
 import { CurrentAuth } from '@/common/decorators/current-auth.decorator'
+import { Authenticated } from '@/common/decorators/access-policy.decorator'
 import { Public } from '@/common/decorators/public.decorator'
 import { Body, Controller, Get, Headers, HttpCode, HttpStatus, Post, Req } from '@nestjs/common'
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger'
@@ -6,6 +7,7 @@ import type { FastifyRequest } from 'fastify'
 import { CurrentUser } from 'shared/types'
 import { AuthService } from './auth.service'
 import { LoginDto } from './dto/login.dto'
+import { ChangePasswordDto } from './password/change-password.dto'
 import { RegisterDto } from './dto/register.dto'
 import type { CurrentAuthType } from './session/session.types'
 
@@ -14,6 +16,9 @@ import type { CurrentAuthType } from './session/session.types'
 export class AuthController {
   constructor(private readonly authService: AuthService) {}
 
+  /**
+   * 接收注册资料，返回新账号的公开信息。
+   */
   @Public()
   @ApiOperation({ summary: '注册' })
   @Post('register')
@@ -21,6 +26,9 @@ export class AuthController {
     return this.authService.register(body)
   }
 
+  /**
+   * 从 HTTP 请求提取登录来源，并创建或替换当前终端会话。
+   */
   @Public()
   @ApiOperation({ summary: '登录并创建 Redis Session' })
   @HttpCode(HttpStatus.OK)
@@ -32,6 +40,9 @@ export class AuthController {
     })
   }
 
+  /**
+   * 按 Authorization 请求头撤销当前终端的会话。
+   */
   @ApiBearerAuth('session')
   @ApiOperation({ summary: '退出当前端' })
   @Public()
@@ -41,9 +52,13 @@ export class AuthController {
     return this.authService.logout(authorization)
   }
 
+  /**
+   * 结合认证上下文与最新用户资料，返回当前用户及登录终端。
+   */
   @ApiBearerAuth('session')
   @ApiOperation({ summary: '使用 Session Token 获取当前用户资料' })
   @Get('me')
+  @Authenticated()
   async me(@CurrentAuth() auth: CurrentAuthType): Promise<CurrentUser> {
     const user = await this.authService.getCurrentUser(auth.userId)
 
@@ -52,4 +67,14 @@ export class AuthController {
       terminal: auth.terminal,
     }
   }
+
+  /** 根据当前会话身份修改本人密码，成功后该用户全部终端会话失效。 */
+  @ApiBearerAuth('session')
+  @ApiOperation({ summary: '修改本人密码并撤销全部终端会话' })
+  @Post('change-password')
+  @HttpCode(HttpStatus.OK)
+  @Authenticated()
+  changePassword(@CurrentAuth() auth: CurrentAuthType, @Body() body: ChangePasswordDto) {
+    return this.authService.changePassword(auth.userId, body)
+  }
 }

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

@@ -29,6 +29,16 @@ export const AUTH_ERRORS = {
     publicMessage: '账号已存在',
     status: HttpStatus.CONFLICT,
   },
+  OLD_PASSWORD_INCORRECT: {
+    code: 'AUTH.OLD_PASSWORD_INCORRECT',
+    publicMessage: '旧密码错误',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
+  PASSWORD_REUSE_NOT_ALLOWED: {
+    code: 'AUTH.PASSWORD_REUSE_NOT_ALLOWED',
+    publicMessage: '新密码不能与旧密码相同',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
   FORBIDDEN: {
     code: 'AUTH.FORBIDDEN',
     publicMessage: '没有权限执行此操作',

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

@@ -21,6 +21,6 @@ import { SessionTokenService } from './session/session-token.service'
       useClass: SessionAuthGuard,
     },
   ],
-  exports: [SessionStoreService],
+  exports: [PasswordService, SessionStoreService],
 })
 export class AuthModule {}

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

@@ -5,15 +5,27 @@ import { eq } from 'drizzle-orm'
 
 type CreateUserInput = Pick<typeof users.$inferInsert, 'name' | 'account' | 'passwordHash'>
 
+interface PasswordWriteContext {
+  passwordHash: string
+  /** 在当前用户行锁和事务中写入新摘要。 */
+  setPasswordHash: (passwordHash: string) => Promise<void>
+}
+
 @Injectable()
 export class AuthRepository {
   constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
 
+  /**
+   * 按标准化账号查找完整用户记录，供密码校验使用；不存在时返回 null。
+   */
   async findByAccount(account: string) {
     const [user] = await this.db.select().from(users).where(eq(users.account, account)).limit(1)
     return user ?? null
   }
 
+  /**
+   * 按用户 ID 读取身份与状态字段，避免查询结果携带密码摘要。
+   */
   async findPublicById(userId: string) {
     const [user] = await this.db
       .select({
@@ -28,6 +40,9 @@ export class AuthRepository {
     return user ?? null
   }
 
+  /**
+   * 插入用户并返回记录；账号唯一键冲突时不写入并返回 null。
+   */
   async createUser(input: CreateUserInput) {
     const [user] = await this.db
       .insert(users)
@@ -37,4 +52,49 @@ export class AuthRepository {
       .returning()
     return user ?? null
   }
+
+  /**
+   * 在事务中对启用用户持有共享行锁，并把锁内的最新密码摘要交给回调。
+   * 登录须复核该摘要，避免在并发改密撤销后凭旧密码建立新会话。
+   * @returns 操作结果；用户不存在或已停用时返回 null。
+   */
+  withActiveUserLock<T>(userId: string, operation: (passwordHash: string) => Promise<T>) {
+    /** 在事务结束前保留共享行锁，保证回调执行期间账号状态及摘要不再变化。 */
+    return this.db.transaction(async (tx) => {
+      const [user] = await tx
+        .select({ status: users.status, passwordHash: users.passwordHash })
+        .from(users)
+        .where(eq(users.id, userId))
+        .for('share')
+      if (!user || user.status !== 'active') return null
+      return operation(user.passwordHash)
+    })
+  }
+
+  /**
+   * 以排他行锁读取本人账号的最新摘要，并在同一事务中执行密码更新及会话撤销。
+   * 回调抛错时数据库更新回滚；已成功的 Redis 撤销不会恢复。
+   */
+  withPasswordWriteLock<T>(
+    userId: string,
+    operation: (context: PasswordWriteContext) => Promise<T>,
+  ) {
+    return this.db.transaction(async (tx) => {
+      const [user] = await tx
+        .select({ status: users.status, passwordHash: users.passwordHash })
+        .from(users)
+        .where(eq(users.id, userId))
+        .for('update')
+      if (!user || user.status !== 'active') return null
+      return operation({
+        passwordHash: user.passwordHash,
+        setPasswordHash: async (passwordHash) => {
+          await tx
+            .update(users)
+            .set({ passwordHash, updatedAt: new Date() })
+            .where(eq(users.id, userId))
+        },
+      })
+    })
+  }
 }

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,12 +125,12 @@ export class AuthService {
     }
   }
 
+  /**
+   * 读取仍处于启用状态的用户公开资料。
+   * @throws 用户不存在或已停用时抛出会话失效错误。
+   */
   async getCurrentUser(userId: string): Promise<AuthUser> {
-    const user = await this.useAuthInfrastrutrue(() =>
-      this.authRepository.findPublicById(userId).catch((cause: unknown) => {
-        throw new AppException(AUTH_ERRORS.SERVICE_UNAVAILABLE, { cause })
-      }),
-    )
+    const user = await this.useAuthInfrastrutrue(() => this.authRepository.findPublicById(userId))
 
     if (!user || user.status !== 'active') {
       throw new AppException(AUTH_ERRORS.SESSION_INVALID)
@@ -116,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/auth-repsponse.dto.ts

@@ -2,7 +2,7 @@ import { createZodDto } from 'nestjs-zod'
 import z from 'zod'
 
 const authUserSchema = z.object({
-  id: z.string().uuid(),
+  id: z.uuid(),
   account: z.string(),
   name: z.string(),
 })
@@ -14,7 +14,7 @@ export class LoginResultDto extends createZodDto(
     accessToken: z.string().min(1),
     tokenType: z.literal('Bearer'),
     idleExpiresIn: z.number().int().positive(),
-    absoluteExpiresAt: z.string().datetime(),
+    absoluteExpiresAt: z.iso.datetime(),
   }),
 ) {}
 

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