# TOTP双因素认证API

<cite>
**Referenced Files in This Document**   
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)
- [TOTPApi.md](file://src/api/generated/docs/TOTPApi.md)
- [totp.tsx](file://src/views/user-center/user-profile/components/totp.tsx)
- [kami-api-sys-user-v1-totp-image-get-res.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-image-get-res.ts)
- [kami-api-sys-user-v1-totp-set-req.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-set-req.ts)
- [kami-api-sys-user-v1-totp-reset-req.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-reset-req.ts)
- [kami-api-sys-user-v1-totp-status-get-res.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-status-get-res.ts)
- [user.ts](file://src/api/user.ts)
</cite>

## 目录

1. [简介](#简介)
2. [API端点](#api端点)
3. [请求参数和响应数据结构](#请求参数和响应数据结构)
4. [二维码生成与传输](#二维码生成与传输)
5. [TOTP与密码认证集成](#totp与密码认证集成)
6. [前端实现示例](#前端实现示例)
7. [安全最佳实践](#安全最佳实践)
8. [账户恢复流程](#账户恢复流程)

## 简介

TOTP（基于时间的一次性密码）双因素认证API为kami_frontend项目提供了增强的安全认证机制。该API允许用户通过时间同步的一次性密码来验证身份，从而在常规密码认证的基础上增加了一层安全保障。系统通过生成唯一的TOTP密钥、二维码和验证代码，实现了完整的双因素认证流程，有效防止了未经授权的账户访问。

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L1-L630)
- [TOTPApi.md](file://src/api/generated/docs/TOTPApi.md#L1-L187)

## API端点

TOTP双因素认证API提供了四个核心端点，分别用于获取TOTP密钥、生成二维码、验证TOTP代码以及管理TOTP功能的启用和禁用状态。

```mermaid
flowchart TD
A[获取TOTP状态] --> B[生成TOTP二维码]
B --> C[设置TOTP验证]
C --> D[重置TOTP验证]
E[登录验证] --> F[验证TOTP代码]
```

**Diagram sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L1-L630)

### 获取TOTP密钥和状态

`GET /api/user/totp/status` 端点用于查询当前用户的TOTP认证状态。该接口返回用户是否已启用TOTP双因素认证，以及相关的TOTP密钥和二维码信息。

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L421-L455)
- [user.ts](file://src/api/user.ts#L88-L94)

### 生成TOTP二维码

`GET /api/user/totp/image` 端点用于生成TOTP二维码图像。用户需要提供验证码作为参数，系统将返回包含TOTP配置信息的二维码，用户可以使用认证应用程序扫描该二维码来配置TOTP。

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L1-L89)
- [user.ts](file://src/api/user.ts#L106-L110)

### 验证TOTP代码

`POST /api/user/totp/set` 端点用于验证用户提供的TOTP代码并完成双因素认证的设置。用户需要提交TOTP代码、密码以及从二维码获取的密钥信息，系统将验证这些信息的正确性。

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L178-L242)
- [user.ts](file://src/api/user.ts#L96-L104)

### 启用/禁用TOTP功能

`POST /api/user/totp/reset` 端点用于重置或禁用用户的TOTP双因素认证功能。用户需要提供验证码来确认操作，系统将清除当前的TOTP配置。

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L89-L177)
- [user.ts](file://src/api/user.ts#L112-L116)

## 请求参数和响应数据结构

### 请求参数

#### 获取TOTP二维码请求参数

- `code` (string): 验证码，用于身份验证

#### 设置TOTP验证请求参数

- `code` (string): TOTP验证码
- `password` (string): 用户密码
- `otpKey` (string): OTP密钥
- `otpSecret` (string): OTP密钥

#### 重置TOTP验证请求参数

- `code` (string): 验证码，用于确认操作

**Section sources**

- [kami-api-sys-user-v1-totp-set-req.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-set-req.ts#L1-L46)
- [kami-api-sys-user-v1-totp-reset-req.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-reset-req.ts#L1-L28)

### 响应数据结构

#### 获取TOTP状态响应

```json
{
  "status": boolean,
  "image": string,
  "otpSecret": string,
  "otpKey": string
}
```

#### 生成TOTP二维码响应

```json
{
  "image": string
}
```

#### 设置TOTP验证响应

返回HTTP状态码200表示成功

#### 重置TOTP验证响应

```json
{
  "image": string
}
```

```mermaid
classDiagram
class TOTPStatusResponse {
+status : boolean
+image : string
+otpSecret : string
+otpKey : string
}
class TOTPImageResponse {
+image : string
}
class TOTPSetRequest {
+code : string
+password : string
+otpKey : string
+otpSecret : string
}
class TOTPResetRequest {
+code : string
}
TOTPStatusResponse <|-- TOTPImageResponse
TOTPSetRequest <|-- TOTPResetRequest
```

**Diagram sources**

- [kami-api-sys-user-v1-totp-status-get-res.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-status-get-res.ts#L1-L46)
- [kami-api-sys-user-v1-totp-image-get-res.ts](file://src/api/generated/models/kami-api-sys-user-v1-totp-image-get-res.ts#L1-L28)

## 二维码生成与传输

TOTP二维码的生成和传输是双因素认证流程中的关键环节。系统通过`/api/user/totp/image`端点生成包含TOTP配置信息的二维码，该二维码遵循标准的OTPAuth URI格式。

### 二维码数据格式

生成的二维码包含以下信息：

- 认证协议类型（otpauth）
- 认证方法（totp）
- 用户标识
- 密钥信息（secret）
- 发行者信息

### 传输机制

二维码数据通过Base64编码的PNG图像数据URL传输。前端接收到响应后，可以直接将`image`字段的值作为`<img>`标签的`src`属性显示二维码。

```mermaid
sequenceDiagram
participant Frontend as 前端
participant Backend as 后端
participant User as 用户
User->>Frontend : 输入验证码并请求二维码
Frontend->>Backend : GET /api/user/totp/image?code=xxx
Backend->>Backend : 生成TOTP密钥和二维码
Backend->>Frontend : 返回包含二维码图像的JSON响应
Frontend->>User : 显示二维码供扫描
```

**Diagram sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L1-L89)
- [user.ts](file://src/api/user.ts#L106-L110)

## TOTP与密码认证集成

TOTP双因素认证与常规密码认证的集成流程确保了系统的整体安全性。在用户登录过程中，系统会根据用户的TOTP设置状态决定是否需要进行额外的验证。

### 登录流程集成

当用户尝试登录时，系统执行以下步骤：

1. 验证用户名和密码
2. 检查用户是否启用了TOTP双因素认证
3. 如果已启用，则要求用户提供TOTP验证码
4. 验证TOTP代码的正确性
5. 完成登录过程

### API调用流程

```mermaid
flowchart TD
A[用户登录] --> B{检查TOTP状态}
B --> |已启用| C[请求TOTP验证码]
C --> D[验证TOTP代码]
D --> E[完成登录]
B --> |未启用| F[直接登录]
F --> E
```

**Section sources**

- [user.ts](file://src/api/user.ts#L88-L94)
- [login.ts](file://src/api/login.ts#L1-L50)

## 前端实现示例

前端通过`user.ts`文件中的封装函数与TOTP API进行交互，实现了完整的TOTP设置向导。

### TOTP设置向导组件

前端实现了一个分步的TOTP设置向导，包含两个主要步骤：

#### 第一步：显示二维码

```typescript
// 获取TOTP状态
queryTotpStatus().then(res => {
  state.totpStatus = res.data.status;
  if (!state.totpStatus) {
    state.QrImage = res.data.image;
    state.otpSecret = res.data.otpSecret;
    state.otpKey = res.data.otpKey;
  }
});
```

#### 第二步：验证和设置

```typescript
// 设置TOTP验证
setTotp({
  otpSecret: props.otpSecret,
  otpKey: props.otpKey,
  ...formData
}).then(() => {
  emit('submit');
});
```

### 组件结构

```mermaid
classDiagram
class TotpComponent {
+totpStatus : boolean
+QrImage : string
+otpSecret : string
+otpKey : string
+getTotpStatus()
}
class StepOneForm {
+QrImage : string
+otpKey : string
+otpSecret : string
+password : string
+code : string
}
class StepTwoForm {
+code : string
+showImage : boolean
+image : string
}
TotpComponent --> StepOneForm
TotpComponent --> StepTwoForm
StepOneForm --> StepTwoForm
```

**Diagram sources**

- [totp.tsx](file://src/views/user-center/user-profile/components/totp.tsx#L1-L219)

## 安全最佳实践

### TOTP密钥保护

- TOTP密钥在传输过程中使用HTTPS加密
- 密钥在服务器端安全存储，不以明文形式保存
- 每次生成新的TOTP配置时都会创建新的密钥

### 恢复代码生成

系统在用户启用TOTP双因素认证时生成恢复代码，这些代码可以用于在设备丢失或无法访问认证应用程序时恢复账户访问。

### 多重验证机制

- 在关键操作（如启用/禁用TOTP）时要求用户提供验证码
- 密码在传输前进行Base64加密
- 所有API调用都需要身份验证

**Section sources**

- [user.ts](file://src/api/user.ts#L96-L104)
- [encrypt.ts](file://src/utils/encrypt.ts#L1-L20)

## 账户恢复流程

当用户丢失设备或无法访问TOTP认证应用程序时，系统提供了安全的账户恢复流程。

### 恢复流程步骤

1. 用户选择"无法访问认证器"选项
2. 系统要求用户提供恢复代码
3. 验证恢复代码的有效性
4. 临时禁用TOTP双因素认证
5. 允许用户重新设置TOTP或使用其他验证方式

### 安全措施

- 恢复代码只能使用一次
- 每次使用恢复代码后都会生成新的恢复代码
- 恢复过程需要额外的身份验证步骤
- 系统会记录所有恢复操作以供审计

```mermaid
flowchart TD
A[设备丢失] --> B[请求账户恢复]
B --> C{提供恢复代码}
C --> |正确| D[临时禁用TOTP]
D --> E[重新设置TOTP]
E --> F[生成新恢复代码]
C --> |错误| G[拒绝恢复请求]
```

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L89-L177)
- [user.ts](file://src/api/user.ts#L112-L116)
