# AdminCore 管理员核心认证模块

AdminCore 是应用的管理员认证核心模块，提供完整的管理员身份验证、Token管理和权限控制技术实现。作为Core层的业务支撑模块，专注于为Business层提供安全可靠的管理员认证技术能力。

## 管理员认证功能

### login()
管理员登录认证，支持用户名/邮箱/手机号多种标识符，验证管理员权限并生成签名Token。

### verifyToken()
Token验证和解析，使用HMAC-SHA256验证签名有效性，返回管理员认证载荷信息。

### resetUserPassword()
管理员重置用户密码，支持密码强度验证和安全哈希处理。

## 模块初始化功能

### onModuleInit()
模块初始化时的管理员引导创建功能，支持通过环境变量配置自动创建管理员账户。

## 使用的项目内部依赖

### ConfigService (来自 @nestjs/config)
环境变量和配置管理服务，用于获取Token密钥、有效期和引导配置参数。

### UsersService (来自 ../db/users)
用户数据访问和管理服务，提供用户查询、创建和更新功能支持。

### AdminLoginRequest (本模块)
管理员登录请求数据传输对象，定义登录所需的标识符和密码字段。

### AdminAuthPayload (本模块)
管理员认证载荷数据结构，包含管理员ID、用户名、角色和Token时间信息。

### AdminLoginResult (本模块)
管理员登录结果数据结构，包含管理员信息、访问令牌和过期时间。

## 核心特性

### 安全认证机制
- HMAC-SHA256签名Token生成和验证，确保Token不可伪造
- bcrypt密码哈希和安全验证，使用12轮salt保护密码
- 时间安全比较防止时序攻击，使用crypto.timingSafeEqual
- 密码强度验证和约束检查，要求8-128位包含字母和数字

### 多标识符支持
- 支持用户名、邮箱、手机号多种登录方式
- 智能标识符识别和路由，自动判断标识符类型
- 统一的认证流程处理，简化业务层调用

### 配置驱动设计
- 环境变量驱动的Token密钥配置，支持生产环境安全部署
- 可配置的Token有效期设置，默认8小时可自定义
- 可选的管理员引导创建功能，支持开发环境快速启动

### 权限控制机制
- 严格的管理员权限验证，仅role=9用户可获得管理员权限
- Token载荷包含完整的权限信息，支持细粒度权限控制
- 管理员操作与普通用户操作完全隔离

## 潜在风险

### 配置安全风险
- Token密钥配置不当可能导致安全漏洞，密钥长度必须至少16字符
- 生产环境必须使用强随机密钥，避免使用默认或简单密钥
- 建议定期轮换Token密钥，并实施密钥管理策略

### 权限控制风险
- 仅role=9用户可获得管理员权限，需要确保用户角色分配的准确性
- 管理员权限过高，建议实施管理员操作审计日志
- Token泄露可能导致管理员权限被滥用，建议设置合理的Token有效期

### 引导创建风险
- 引导功能可能在生产环境意外创建管理员，建议生产环境禁用
- 引导密码通过环境变量传递，需要确保环境变量安全性
- 引导创建的管理员具有最高权限，建议首次登录后立即修改密码

### 依赖服务风险
- 依赖UsersService的可用性，服务不可用时管理员无法登录
- 依赖ConfigService的配置正确性，配置错误可能导致认证失败
- 内存模式下数据重启丢失，不适用于生产环境持久化需求

## 使用建议

### 生产环境配置
```bash
# 必须配置强随机密钥（至少32字符）
ADMIN_TOKEN_SECRET=your-super-secure-random-secret-key-here

# 建议设置较短的Token有效期（单位：秒）
ADMIN_TOKEN_TTL_SECONDS=14400  # 4小时

# 生产环境禁用引导功能
ADMIN_BOOTSTRAP_ENABLED=false
```

### 开发环境配置
```bash
# 开发环境可使用简单密钥
ADMIN_TOKEN_SECRET=dev-secret-key-0123456789

# 开发环境可设置较长有效期
ADMIN_TOKEN_TTL_SECONDS=28800  # 8小时

# 开发环境可启用引导功能
ADMIN_BOOTSTRAP_ENABLED=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=Admin123456
ADMIN_NICKNAME=开发管理员
```

### 安全最佳实践
- 定期审计管理员操作日志
- 实施管理员账户的双因素认证
- 设置管理员密码复杂度策略
- 监控异常的管理员登录行为
- 建立管理员权限分级管理机制

---

**版本信息**
- 版本: 1.0.1
- 作者: jianuo
- 创建时间: 2025-12-19
- 最后修改: 2026-01-07