8898bb399e
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
Update audit tracker, roadmap, architecture docs, add admin-v2 Roles page + Billing tests, sync CLAUDE.md, Cargo.toml, docker-compose.yml, add deep-research / frontend-design / chart-visualization skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
258 lines
6.8 KiB
Markdown
258 lines
6.8 KiB
Markdown
# 安全认证 (Security & Authentication)
|
||
|
||
> **分类**: 架构层
|
||
> **优先级**: P0 - 决定性
|
||
> **成熟度**: L4 - 生产
|
||
> **最后更新**: 2026-04-01
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
### 1.1 基本信息
|
||
|
||
安全认证模块负责 ZCLAW 的身份验证和凭证安全存储，支持 Ed25519 设备认证、JWT 会话令牌、TOTP 2FA、HttpOnly Cookie 等多种安全机制。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 分类 | 架构层 |
|
||
| 优先级 | P0 |
|
||
| 成熟度 | L4 |
|
||
| 依赖 | 通信层 |
|
||
|
||
### 1.2 相关文件
|
||
|
||
| 文件 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| 安全存储 | `desktop/src/lib/secure-storage.ts` | OS Keyring 集成 |
|
||
| 设备认证 | `desktop/src/lib/gateway-client.ts` | Ed25519 认证 |
|
||
| Tauri 后端 | `desktop/src-tauri/src/secure_storage.rs` | Rust 安全存储 |
|
||
|
||
---
|
||
|
||
## 二、设计初衷
|
||
|
||
### 2.1 问题背景
|
||
|
||
**用户痛点**:
|
||
1. API Key 明文存储存在安全风险
|
||
2. 多设备认证流程复杂
|
||
3. ZCLAW 有 16 层安全架构，需要适配
|
||
|
||
**系统缺失能力**:
|
||
- 缺乏安全的凭证存储
|
||
- 缺乏设备级别的身份认证
|
||
- 缺乏权限管理
|
||
|
||
**为什么需要**:
|
||
ZCLAW 采用 Ed25519 设备认证 + JWT 会话令牌的双重认证机制，需要安全的密钥存储和管理。
|
||
|
||
### 2.2 设计目标
|
||
|
||
1. **密钥安全**: 使用 OS Keyring 存储私钥
|
||
2. **设备认证**: Ed25519 签名验证设备身份
|
||
3. **会话管理**: JWT Token 自动刷新
|
||
4. **跨平台**: Windows/macOS/Linux 统一接口
|
||
|
||
### 2.3 竞品参考
|
||
|
||
| 项目 | 参考点 |
|
||
|------|--------|
|
||
| ZCLAW | 简单 Token 认证 |
|
||
| ZCLAW | 16 层安全架构 |
|
||
|
||
### 2.4 设计约束
|
||
|
||
- **安全约束**: 私钥不能离开安全存储
|
||
- **平台约束**: Windows DPAPI, macOS Keychain, Linux Secret Service
|
||
- **兼容性约束**: 无 Keyring 时降级到 localStorage
|
||
|
||
---
|
||
|
||
## 三、技术设计
|
||
|
||
### 3.1 核心接口
|
||
|
||
```typescript
|
||
interface SecureStorage {
|
||
// 设备密钥
|
||
storeDeviceKeys(publicKey: string, privateKey: string): Promise<void>;
|
||
getDeviceKeys(): Promise<{ publicKey: string; privateKey: string } | null>;
|
||
deleteDeviceKeys(): Promise<void>;
|
||
|
||
// API Key
|
||
storeApiKey(provider: string, apiKey: string): Promise<void>;
|
||
getApiKey(provider: string): Promise<string | null>;
|
||
deleteApiKey(provider: string): Promise<void>;
|
||
}
|
||
```
|
||
|
||
### 3.2 认证流程
|
||
|
||
```
|
||
1. 首次连接
|
||
│
|
||
├─► 检查本地设备密钥
|
||
│ │
|
||
│ ├─► 存在 → 使用现有密钥
|
||
│ └─► 不存在 → 生成 Ed25519 密钥对
|
||
│
|
||
├─► 向 ZCLAW 注册设备
|
||
│ │
|
||
│ ├─► 成功 → 获得 JWT Token
|
||
│ └─► 需要审批 → 等待用户确认
|
||
│
|
||
└─► 存储 JWT Token
|
||
|
||
2. 后续连接
|
||
│
|
||
├─► 使用设备私钥签名挑战
|
||
│
|
||
└─► 获取新的 JWT Token
|
||
```
|
||
|
||
### 3.3 平台实现
|
||
|
||
| 平台 | 存储后端 | Tauri 命令 |
|
||
|------|---------|-----------|
|
||
| Windows | DPAPI | `keyring_set` / `keyring_get` |
|
||
| macOS | Keychain | 同上 |
|
||
| Linux | Secret Service | 同上 |
|
||
|
||
### 3.4 降级策略
|
||
|
||
```typescript
|
||
async function storeDeviceKeys(publicKey: string, privateKey: string) {
|
||
try {
|
||
// 优先使用 OS Keyring
|
||
await invoke('keyring_set', { key: 'device_keys', value: JSON.stringify({ publicKey, privateKey }) });
|
||
} catch {
|
||
// 降级到 localStorage (加密)
|
||
const encrypted = await encrypt(privateKey);
|
||
localStorage.setItem('device_keys', JSON.stringify({ publicKey, encrypted }));
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、预期作用
|
||
|
||
### 4.1 用户价值
|
||
|
||
| 价值类型 | 描述 |
|
||
|---------|------|
|
||
| 安全保障 | 私钥不会泄露 |
|
||
| 便捷体验 | 自动认证，无需重复登录 |
|
||
| 多设备 | 支持设备级别的身份管理 |
|
||
|
||
### 4.2 系统价值
|
||
|
||
| 价值类型 | 描述 |
|
||
|---------|------|
|
||
| 架构收益 | 认证逻辑集中管理 |
|
||
| 可维护性 | 平台差异封装在后端 |
|
||
| 可扩展性 | 支持新的认证方式 |
|
||
|
||
### 4.3 成功指标
|
||
|
||
| 指标 | 基线 | 目标 | 当前 |
|
||
|------|------|------|------|
|
||
| 认证成功率 | 80% | 99% | 98% |
|
||
| 密钥泄露风险 | 高 | 零 | 零 |
|
||
|
||
---
|
||
|
||
## 五、实际效果
|
||
|
||
### 5.1 已实现功能
|
||
|
||
- [x] Ed25519 密钥生成
|
||
- [x] OS Keyring 集成
|
||
- [x] JWT Token 管理
|
||
- [x] 设备注册和审批
|
||
- [x] 跨平台支持
|
||
- [x] localStorage 降级 (AES-GCM 加密)
|
||
|
||
### 5.1.1 安全渗透测试 V1 修复 (2026-03-31)
|
||
|
||
> 整体评级: **B+** (良好) | 5 HIGH + 10 MEDIUM 全部已修复 | 12 个安全控制项全部 PASS
|
||
|
||
**SaaS 后端安全修复:**
|
||
- [x] JWT `password_version` 机制 — 密码修改自动使所有已签发 JWT 失效
|
||
- [x] 账户锁定 — 5 次登录失败后锁定 15 分钟
|
||
- [x] 邮箱验证 — RFC 5322 正则 + 254 字符长度限制
|
||
- [x] JWT 密钥保护 — `#[cfg(debug_assertions)]` 保护的 fallback，release 模式拒绝启动
|
||
- [x] TOTP 加密密钥独立化 — 生产环境强制 `ZCLAW_TOTP_ENCRYPTION_KEY` (64 hex)
|
||
- [x] TOTP/API Key 加密 — AES-256-GCM + 随机 Nonce
|
||
- [x] 密码存储 — Argon2id + OsRng 随机盐
|
||
- [x] Refresh Token 轮换 — 单次使用 + 撤销校验
|
||
|
||
**网络安全:**
|
||
- [x] Cookie 安全 — HttpOnly + Secure + SameSite=Strict + 路径作用域
|
||
- [x] CORS 白名单 — 生产强制白名单，缺失拒绝启动
|
||
- [x] 限流持久化 — PostgreSQL 滑动窗口，重启不丢失
|
||
- [x] XFF 信任链 — 仅信任配置的代理 IP
|
||
|
||
**前端安全:**
|
||
- [x] CSP 加固 — 移除 `unsafe-inline` script
|
||
- [x] Admin Token — HttpOnly Cookie 传递，JS 不存储 token
|
||
- [x] Pipeline 日志脱敏 — Debug 日志截断 + 仅记录 keys
|
||
|
||
**详细报告**: [SECURITY_PENETRATION_TEST_V1.md](../SECURITY_PENETRATION_TEST_V1.md)
|
||
|
||
### 5.2 测试覆盖
|
||
|
||
- **单元测试**: 10+ 项
|
||
- **集成测试**: 包含在 gatewayStore.test.ts
|
||
- **覆盖率**: ~80%
|
||
|
||
### 5.3 已知问题
|
||
|
||
| 问题 | 严重程度 | 状态 | 计划解决 |
|
||
|------|---------|------|---------|
|
||
| Linux 无 Keyring 时降级 | 低 | 已处理 | - |
|
||
|
||
### 5.4 用户反馈
|
||
|
||
认证流程顺畅，安全性高。
|
||
|
||
---
|
||
|
||
## 六、演化路线
|
||
|
||
### 6.1 已完成
|
||
- [x] TOTP 双因素认证 (AES-256-GCM 加密存储)
|
||
- [x] JWT password_version 密码修改使旧 token 失效
|
||
- [x] 账户锁定机制 (5 次失败 → 锁 15 分钟)
|
||
- [x] HttpOnly Cookie 认证模式
|
||
- [x] CSP 加固 (移除 unsafe-inline)
|
||
- [x] CORS 白名单强制
|
||
- [x] 限流持久化 (PostgreSQL)
|
||
|
||
### 6.2 短期计划（1-2 周）
|
||
- [ ] 添加生物识别支持 (Touch ID / Windows Hello)
|
||
|
||
### 6.3 中期计划（1-2 月）
|
||
- [ ] 支持 FIDO2 硬件密钥
|
||
- [ ] 速率限制从 DashMap 迁移到 Redis (多实例部署)
|
||
|
||
### 6.3 长期愿景
|
||
- [ ] 去中心化身份 (DID)
|
||
|
||
---
|
||
|
||
## 七、头脑风暴笔记
|
||
|
||
### 7.1 待讨论问题
|
||
1. 是否需要支持多因素认证 (MFA)？
|
||
2. 如何处理设备丢失的情况？
|
||
|
||
### 7.2 创意想法
|
||
- 设备信任链：建立可信设备网络
|
||
- 零知识证明：不暴露私钥完成认证
|
||
|
||
### 7.3 风险与挑战
|
||
- **技术风险**: Keyring API 兼容性问题
|
||
- **缓解措施**: 完善的降级策略
|