zclaw_openfang/docs/features/00-architecture/03-security-auth.md

安全认证 (Security & Authentication)

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

---

一、功能概述

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 核心接口

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 降级策略

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 已实现功能

• Ed25519 密钥生成
• OS Keyring 集成
• JWT Token 管理
• 设备注册和审批
• 跨平台支持
• localStorage 降级 (AES-GCM 加密)

5.1.1 安全渗透测试 V1 修复 (2026-03-31)

整体评级: B+ (良好) | 5 HIGH + 10 MEDIUM 全部已修复 | 12 个安全控制项全部 PASS

SaaS 后端安全修复:

• JWT password_version 机制 — 密码修改自动使所有已签发 JWT 失效
• 账户锁定 — 5 次登录失败后锁定 15 分钟
• 邮箱验证 — RFC 5322 正则 + 254 字符长度限制
• JWT 密钥保护 — #[cfg(debug_assertions)] 保护的 fallback，release 模式拒绝启动
• TOTP 加密密钥独立化 — 生产环境强制 ZCLAW_TOTP_ENCRYPTION_KEY (64 hex)
• TOTP/API Key 加密 — AES-256-GCM + 随机 Nonce
• 密码存储 — Argon2id + OsRng 随机盐
• Refresh Token 轮换 — 单次使用 + 撤销校验

网络安全:

• Cookie 安全 — HttpOnly + Secure + SameSite=Strict + 路径作用域
• CORS 白名单 — 生产强制白名单，缺失拒绝启动
• 限流持久化 — PostgreSQL 滑动窗口，重启不丢失
• XFF 信任链 — 仅信任配置的代理 IP

前端安全:

• CSP 加固 — 移除 unsafe-inline script
• Admin Token — HttpOnly Cookie 传递，JS 不存储 token
• Pipeline 日志脱敏 — Debug 日志截断 + 仅记录 keys

详细报告: SECURITY_PENETRATION_TEST_V1.md

5.2 测试覆盖

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

5.3 已知问题

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

5.4 用户反馈

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

---

六、演化路线

6.1 已完成

• TOTP 双因素认证 (AES-256-GCM 加密存储)
• JWT password_version 密码修改使旧 token 失效
• 账户锁定机制 (5 次失败 → 锁 15 分钟)
• HttpOnly Cookie 认证模式
• CSP 加固 (移除 unsafe-inline)
• CORS 白名单强制
• 限流持久化 (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 兼容性问题
• 缓解措施: 完善的降级策略