身份认证模块
身份认证模块提供基于 web3 的认证服务，使用 SIWE (Sign-In with Ethereum) 标准。用户可以通过 Ethereum 钱包进行身份认证，无需创建传统账户。
认证流程
- 用户连接钱包
- 客户端从服务器请求 nonce
- 用户使用钱包签名 SIWE 消息
- 客户端将签名消息发送到服务器进行验证
- 服务器返回包含过期时间的 token 对象用于后续认证请求
接口说明
获取 Nonce
路径: /api/auth/nonce
方法: GET
认证: 无需认证
请求字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| address | 是 | string | Ethereum 钱包地址 |
响应字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| nonce | 是 | string | 用于 SIWE 消息的随机数 |
| message | 是 | string | 预格式化的 SIWE 签名消息 |
验证签名
路径: /api/auth/verify
方法: POST
认证: 无需认证
请求字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| message | 是 | string | 已签名的 SIWE 消息 |
| signature | 是 | string | 钱包签名 |
| address | 是 | string | Ethereum 钱包地址 |
| referral_code | 否 | string | 推荐码（仅在首次验证时生效） |
响应字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | AuthToken | 用于认证请求的 JWT 信息 |
| user | 是 | User | 用户信息 |
刷新 Token
路径: /api/auth/refresh
方法: POST
认证: 需要 JWT 认证
请求字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| - | - | - | 无需请求体 |
响应字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | AuthToken | 新的 JWT 信息 |
登出
路径: /api/auth/logout
方法: POST
认证: 需要 JWT 认证
请求字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| - | - | - | 无需请求体 |
响应字段
| 字段名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| success | 是 | boolean | 登出成功状态 |
| message | 是 | string | 确认消息 |
AuthToken 对象定义
AuthToken 对象包含以下字段：
| 字段名 | 类型 | 说明 |
|---|---|---|
| token | string | 用于认证的 JWT 字符串 |
| exp | number | 过期时间戳（单位：秒） |
JWT Token 使用说明
对于需要认证的接口，请在请求头中包含最新的 token 对象中的 token 字段：
Authorization: Bearer <token.token>exp 字段表示 JWT 过期时间（Unix 时间戳，秒），当 token 过期时请调用刷新接口获取新的 token 对象。
推荐功能说明
referral_code参数仅在用户首次验证签名时记录，用于后续推荐关系建立- 推荐关系的实际建立是异步的，当被推荐人成功参与游戏时才会生效
- 老用户再次登录时，即使提供
referral_code也会被忽略