云端只存密文！基于 Argon2id + AES-256-GCM 打造零成本端到端加密（E2EE）多端同步

摘要：桌面效率启动器中存储着用户最核心的数字资产——从高频使用的代码短语（Snippets）、内网快捷链接（Quicklinks），到自带的 AI API Key 与偏好设置。传统的云同步方案要么强迫用户一打开软件就扫码登录官方账号并将数据明文存在厂商数据库里，要么对基础同步功能按月收费。本文深度拆解 ZTools 的 @ztools/sync-crypto 端到端加密（E2EE）同步引擎，详解如何结合密码学界公认最强的 Argon2id 抗 GPU/ASIC 密钥派生算法 与 AES-256-GCM 认证加密算法，配合 HTTP ETag 乐观锁防并发覆盖机制，让用户直接用自己免费的 WebDAV（坚果云 / Nextcloud）、GitHub Gist 或对象存储 实现 100% 零知识（Zero-Knowledge）安全同步。

一、 为什么效率工具必须坚持“Local-First + 去中心化端到端加密”？

在设计 ZTools 的数据存储与同步体系时，我们首先明确了两条不可妥协的隐私底线：

1. 01
   绝不强弹登录窗，数据 100% 本地优先（Local-First）：

一个启动器软件在没有网络、不注册任何账号的情况下，必须能够 100% 发挥全部本地性能。所有个人数据默认保存在本地 SQLite 数据库中。

1. 01
   自带存储（BYOS）永久免费，云端零明文（Zero-Knowledge E2EE）：

当极客用户需要在公司的 Windows 工作站与家里的 MacBook 之间同步配置时，他完全可以使用自己已有的 GitHub Gist（私人代码片段） 或 WebDAV（如坚果云、群晖 NAS、Alist）。而且，在数据离开本机网卡之前，必须在本地完成高强度端到端加密——即使第三方网盘被黑客拖库，攻击者拿到的也只是一串在数学上不可逆的随机密文！

二、 密码学工程选型：为什么是 Argon2id + AES-256-GCM？

很多初级项目在实现“密码加密”时，会直接用 SHA-256(password) 算个哈希当作 AES 密钥，或者使用早已被淘汰的 AES-CBC 模式。这在现代密码学攻防中存在致命漏洞：

• 普通哈希（SHA-256）无法抵御显卡阵列暴力破解：一块现代消费级显卡（如 RTX 4090）每秒可以计算数百亿次 SHA-256 哈希，用户设置的 8~10 位主密码在几分钟内就会被字典彩虹表撞破；
• 缺乏完整性认证（MAC）易受填充预言机攻击（Padding Oracle Attack）：如果不校验密文的认证标签（Authentication Tag），攻击者或损坏的网络传输可以篡改密文字节而不被解密端察觉，甚至诱导解密端泄露明文信息。

在 packages/sync-crypto/ 中，我们采用了工业级密码学黄金组合：

三、 全链路加密同步架构与核心源码拆解

3.1 端到端加密封装与验证管线图

flowchart LR
    subgraph LocalClient ["本地 ZTools 客户端 (可信边界内)"]
        Plain["本地结构化数据快照<br/>(Snippets / Quicklinks / Settings)"]
        MasterPwd["用户主密码 (Master Password)<br/>(仅驻留本地内存，绝不上传)"]
        SaltGen["CSPRNG 密码学随机数发生器<br/>(16B Salt + 12B Nonce)"]
        Argon["Argon2id 密钥派生器<br/>(m=64MB, t=3, p=4) -> 32B Key"]
        AesGcm["AES-256-GCM 认证加密引擎<br/>(绑定 AAD 协议版本防降级)"]
        Envelope["标准密文信封 (SyncEnvelope v1)<br/>{ v, kdf, salt, iv, tag, ciphertext }"]

        MasterPwd & SaltGen --> Argon
        Plain & Argon & SaltGen --> AesGcm --> Envelope
    end

    subgraph UntrustedCloud ["零信任云端存储适配器 (WebDAV / GitHub Gist)"]
        CloudStore["远端密文文件 (ztools-sync.enc.json)<br/>配合 ETag 乐观锁校验"]
    end

    Envelope -->|"HTTPS + If-Match: <ETag>"| CloudStore

3.2 核心源码实现 1：Argon2id 内存硬化密钥派生与 AES-256-GCM 封装

在 packages/sync-crypto/src/crypto/ 中，我们将协议版本号与载荷元数据作为 附加认证数据（AAD, Additional Authenticated Data） 绑定进 AES-256-GCM 的计算过程中。这意味着攻击者哪怕只把信封外层的版本号 "v": 1 改成 "v": 0 企图发动协议降级攻击，解密时的 authTag 校验也会瞬间报错拦截！

import crypto from 'node:crypto';

export interface EncryptedSyncEnvelope {
  version: 1;
  kdf: {
    algorithm: 'argon2id';
    memoryCostKiB: number;
    timeCost: number;
    parallelism: number;
    saltBase64: string;
  };
  cipher: {
    algorithm: 'aes-256-gcm';
    ivBase64: string;
    authTagBase64: string;
    ciphertextBase64: string;
  };
  updatedAt: number;
}

/**
 * 使用 AES-256-GCM 加密同步载荷，并将信封元数据绑定为 AAD（附加认证数据）
 */
export async function encryptSyncPayload(
  plaintextJson: string,
  masterPassword: string,
  deriveKeyFn: (pwd: string, salt: Buffer) => Promise<Buffer>
): Promise<EncryptedSyncEnvelope> {
  // 1. 每次加密强制生成全新的 16 字节密码学安全随机盐与 12 字节 GCM 标准 IV
  const salt = crypto.randomBytes(16);
  const iv = crypto.randomBytes(12);

  // 2. 通过 Argon2id 派生 256 位 (32 字节) 对称主密钥
  const key = await deriveKeyFn(masterPassword, salt);

  try {
    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });

    // 3. 构造 AAD 附加认证数据：锁死协议版本与算法参数，防止信封头被篡改
    const aad = Buffer.from('ztools-e2ee-v1:argon2id:aes-256-gcm', 'utf8');
    cipher.setAAD(aad);

    const encrypted = Buffer.concat([
      cipher.update(Buffer.from(plaintextJson, 'utf8')),
      cipher.final(),
    ]);
    const authTag = cipher.getAuthTag();

    return {
      version: 1,
      kdf: {
        algorithm: 'argon2id',
        memoryCostKiB: 65536, // 64MB 内存硬成本
        timeCost: 3,
        parallelism: 4,
        saltBase64: salt.toString('base64'),
      },
      cipher: {
        algorithm: 'aes-256-gcm',
        ivBase64: iv.toString('base64'),
        authTagBase64: authTag.toString('base64'),
        ciphertextBase64: encrypted.toString('base64'),
      },
      updatedAt: Date.now(),
    };
  } finally {
    // 4. 安全擦除内存中的明文密钥字节，防止内存转储 (Core Dump) 泄露
    key.fill(0);
  }
}

安全细节高亮：注意 finally 块中的 key.fill(0)！用完派生出的 32 字节密钥 Buffer 后，我们立即在内存中原地覆写清零，不给 V8 堆内存留下任何长期滞留的明文密钥痕迹。

3.3 核心源码实现 2：基于 HTTP ETag 乐观锁的多端并发防覆盖机制

假设你在家里用 MacBook 添加了一条快捷短语 A，在公司用 Windows 台式机添加了另一条快捷短语 B。如果两台设备直接粗暴地执行 PUT /ztools-sync.enc.json，后推上去的那台设备就会把前一台设备的数据彻底覆盖掉！

为了在没有中心化协调服务器（Serverless / 纯 WebDAV 或 Gist）的条件下解决并发冲突，e2ee-sync-engine.ts 实现了完整的 “拉取解密 $\rightarrow$ 实体级 LWW（Last-Write-Wins with Tombstone）合并 $\rightarrow$ 携带 If-Match: <ETag> 条件写回” 乐观锁闭环：

sequenceDiagram
    participant DeviceA as 设备 A (本地同步引擎)
    participant Cloud as WebDAV / GitHub Gist 远端存储
    participant DeviceB as 设备 B (并发修改者)

    DeviceA->>Cloud: 1. GET /ztools-sync.enc.json
    Cloud-->>DeviceA: 2. 返回密文包 + Header: ETag: "v101"
    DeviceA->>DeviceA: 3. 本地解密并按条目 ID + updatedAt 合并增删改 (含墓碑标记)
    
    Note over DeviceB,Cloud: 此时设备 B 抢先完成了一次推送，远端 ETag 变为 "v102"
    
    DeviceA->>Cloud: 4. PUT 新密文包 (携带 Header: If-Match: "v101")
    Cloud-->>DeviceA: 5. 返回 HTTP 412 Precondition Failed (拦截并发覆盖！)
    DeviceA->>DeviceA: 6. 捕获冲突，自动拉取 "v102" 重新执行三方合并后再提交

通过 条目级墓碑合并（Entity-Level Merge with Tombstones） + HTTP 412 Precondition Failed 乐观锁重试，即使两台电脑在同一秒钟各自修改了不同的快捷短语并点击同步，两边的新增条目也能毫发无损地自动融合在一起！

四、 总结与下期预告

通过 @ztools/sync-crypto（Argon2id + AES-256-GCM + AAD 协议防降级 + ETag 乐观锁），ZTools 兑现了对极客用户的隐私承诺：不需要向官方交一分钱买云空间，也不需要把你的核心数据托付给任何厂商的良心，用你自己的 GitHub Gist 或 WebDAV 就能拥有银行级安全的跨端同步体验。

在接下来的第五专题（第 11~15 篇）中，我们将深入拆解 ZTools 最受欢迎的核心内置生产力套件与跨平台（Linux Wayland / macOS）底层攻坚细节：

• 下一篇（第 11 篇）：《剪贴板管理器的魔鬼细节：SQLite WAL 高性能持久化、高熵密码自动脱敏与“顺序流水粘贴”实现》（延伸阅读：《双向 MCP 网关与 BYOK 本地模型路由》 · 《快捷短语输入效率翻 10 倍指南》）

本文关联核心插件（官网详情与使用指南）

• 端到端加密密码保险箱（安全工具）：采用 Argon2id 密钥派生与 AES-256-GCM 认证加密守护核心凭据
• 超级剪贴板历史（办公效率）：本地 SQLite 存储结合可选 E2EE 端到端加密跨设备同步
• 快捷短语 Snippets（办公效率）：支持通过加密通道在多台办公电脑间安全同步个人代码片段与模板
• 2FA 动态验证码管理（安全工具）：本地离线生成 TOTP 双因素认证动态口令，密钥加密存储

官方体验与开源共建

官方网站（免费下载体验）：https://www.ztools.cn （www.ztools.cn）

⭐ GitHub 核心宿主开源仓库：https://github.com/ZToolsTeam/ZTools

Gitee 国内镜像开源仓库：https://gitee.com/hoposky/ZTools

GitHub 插件生态开源大仓：https://github.com/ZToolsTeam/ZTools-extensions

欢迎前往官网下载体验，或点击上方 GitHub / Gitee 链接为我们点亮一颗 Star ⭐，一起打造纯粹开源、免费极客的下一代跨平台效率中枢！