# 安全认证 (Security & Authentication)

> **分类**: 架构层
> **优先级**: P0 - 决定性
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-16

---

## 一、功能概述

### 1.1 基本信息

安全认证模块负责 ZCLAW 与 OpenFang 之间的身份验证和凭证安全存储，支持 Ed25519 设备认证和 JWT 会话令牌。

| 属性 | 值 |
|------|-----|
| 分类 | 架构层 |
| 优先级 | 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. OpenFang 有 16 层安全架构，需要适配

**系统缺失能力**:
- 缺乏安全的凭证存储
- 缺乏设备级别的身份认证
- 缺乏权限管理

**为什么需要**:
OpenFang 采用 Ed25519 设备认证 + JWT 会话令牌的双重认证机制，需要安全的密钥存储和管理。

### 2.2 设计目标

1. **密钥安全**: 使用 OS Keyring 存储私钥
2. **设备认证**: Ed25519 签名验证设备身份
3. **会话管理**: JWT Token 自动刷新
4. **跨平台**: Windows/macOS/Linux 统一接口

### 2.3 竞品参考

| 项目 | 参考点 |
|------|--------|
| OpenClaw | 简单 Token 认证 |
| OpenFang | 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 密钥对
   │
   ├─► 向 OpenFang 注册设备
   │       │
   │       ├─► 成功 → 获得 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 降级

### 5.2 测试覆盖

- **单元测试**: 10+ 项
- **集成测试**: 包含在 gatewayStore.test.ts
- **覆盖率**: ~80%

### 5.3 已知问题

| 问题 | 严重程度 | 状态 | 计划解决 |
|------|---------|------|---------|
| Linux 无 Keyring 时降级 | 低 | 已处理 | - |

### 5.4 用户反馈

认证流程顺畅，安全性高。

---

## 六、演化路线

### 6.1 短期计划（1-2 周）
- [ ] 添加生物识别支持 (Touch ID / Windows Hello)

### 6.2 中期计划（1-2 月）
- [ ] 支持 FIDO2 硬件密钥

### 6.3 长期愿景
- [ ] 去中心化身份 (DID)

---

## 七、头脑风暴笔记

### 7.1 待讨论问题
1. 是否需要支持多因素认证 (MFA)？
2. 如何处理设备丢失的情况？

### 7.2 创意想法
- 设备信任链：建立可信设备网络
- 零知识证明：不暴露私钥完成认证

### 7.3 风险与挑战
- **技术风险**: Keyring API 兼容性问题
- **缓解措施**: 完善的降级策略