安全 API
安全相关接口，包括活跃会话管理、认证事件查询和登录埋点。独立于 /auth 公开路由，所有端点均需 JWT 认证。
路由前缀：/security
源码：apps/backend/src/routes/security.ts
认证
所有接口需要 JWT 认证（仅支持 JWT，不支持 API Key）：
Authorization: Bearer <JWT>端点
1. 活跃会话列表
GET /security/sessions查询当前用户的所有活跃 Session。返回设备摘要、IP 哈希、地理位置等脱敏信息，并标记当前 Session。
示例请求：
bash
curl -X GET "https://block2-api.wainao.chat/security/sessions" \
-H "Authorization: Bearer <JWT>"响应 200 OK：
json
{
"sessions": [
{
"id": "uuid",
"deviceSummary": "Chrome 120 / macOS",
"ipHash": "a1b2c3...",
"city": "Shanghai",
"country": "CN",
"createdAt": "2026-03-10T08:00:00.000Z",
"updatedAt": "2026-03-17T10:00:00.000Z",
"isCurrent": true
},
{
"id": "uuid-2",
"deviceSummary": "Safari / iOS",
"ipHash": "d4e5f6...",
"city": "Beijing",
"country": "CN",
"createdAt": "2026-03-15T12:00:00.000Z",
"updatedAt": "2026-03-16T18:00:00.000Z",
"isCurrent": false
}
],
"currentSessionId": "uuid"
}提示
ipHash 是 IP 地址的脱敏哈希值，不会暴露真实 IP。isCurrent 标记当前请求使用的 Session。
错误码：
| HTTP | 错误 | 说明 |
|---|---|---|
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式（如 API Key） |
| 500 | 查询失败 | 服务端错误 |
2. 终止指定会话
DELETE /security/sessions/:sessionId注销指定 Session（使对应设备的 Refresh Token 失效）。不允许注销当前 Session。
路径参数：
| 参数 | 说明 |
|---|---|
sessionId | 要终止的 Session ID（UUID 格式） |
示例请求：
bash
curl -X DELETE "https://block2-api.wainao.chat/security/sessions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
-H "Authorization: Bearer <JWT>"响应 200 OK：
json
{
"success": true,
"message": "该设备的 refresh token 已失效，access token 可能延迟到过期才完全失效"
}警告
注销 Session 后，目标设备的 Refresh Token 立即失效，但已签发的 Access Token 在过期前仍可使用（通常 1 小时内）。
错误码：
| HTTP | 错误 | 说明 |
|---|---|---|
| 400 | Session ID 格式无效 | sessionId 不是合法 UUID |
| 400 | 不能注销当前设备的 session，请使用登出功能 | 尝试注销当前 Session |
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式 |
| 404 | Session 不存在或无权操作 | Session 不存在或不属于当前用户 |
| 500 | 注销失败 | 服务端错误 |
3. 认证事件列表
GET /security/auth-events查询当前用户的登录事件历史（分页）。包含设备摘要、IP 哈希和地理位置。
查询参数：
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
limit | number | 否 | 20 | 每页数量（1-100） |
offset | number | 否 | 0 | 偏移量 |
示例请求：
bash
curl -X GET "https://block2-api.wainao.chat/security/auth-events?limit=10&offset=0" \
-H "Authorization: Bearer <JWT>"响应 200 OK：
json
{
"events": [
{
"id": "uuid",
"event_type": "login_success",
"ip_hash": "a1b2c3...",
"ip_country": "CN",
"ip_city": "Shanghai",
"device_summary": "Chrome 120 / macOS",
"created_at": "2026-03-17T10:00:00.000Z"
}
],
"total": 42,
"limit": 10,
"offset": 0
}错误码：
| HTTP | 错误 | 说明 |
|---|---|---|
| 400 | 分页参数无效 | limit 或 offset 不合法 |
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式 |
| 500 | 查询失败 | 服务端错误 |
4. 记录登录事件
POST /security/record-login前端登录成功后调用，记录登录事件（埋点用途）。采用 best-effort 策略，即使记录失败也返回成功。
示例请求：
bash
curl -X POST "https://block2-api.wainao.chat/security/record-login" \
-H "Authorization: Bearer <JWT>"响应 200 OK：
json
{
"success": true
}提示
此接口无请求体。服务端自动从请求头提取 IP 和 User-Agent 信息。
错误码：
| HTTP | 错误 | 说明 |
|---|---|---|
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式 |