跳到正文
AIPass

安全架构

AIPass 如何加密保险库——Argon2id、XChaCha20-Poly1305、纪元轮换、恢复与导出。

AIPass 是本地优先的：保险库是你机器上一个由加密文件组成的目录（macOS 上为 ~/Library/Application Support/dev.aipass.desktop/vault），明文凭据永远不会被写入磁盘、同步或记录日志。

密钥层级

Text
master password ──Argon2id──> master key ──┐                                           ├─> wraps ──> vault root key ──> vault epoch key ──> per-record data keysrecovery key ───HKDF-SHA256──> wrap key ───┘
  • 主密钥（master key） —— 由主密码经 Argon2id（0x13 版本）派生。新保险库使用 64 MiB 内存、2 轮迭代、并行度 1 和随机 128 位盐。KDF 参数存储在保险库清单中，因此日后可以加强参数而不破坏旧保险库。
  • 保险库根密钥 —— 创建保险库时生成的随机 256 位密钥。它被存储两份：由主密钥包裹一份，由恢复密钥包裹一份。修改主密码只是重新包裹根密钥，根密钥本身不变。
  • 保险库纪元密钥（epoch key） —— 包裹每条记录数据密钥的随机 256 位密钥。轮换它不需要修改密码。
  • 每记录数据密钥 —— 每条服务商记录、授权、设备记录都有自己随机的 256 位数据密钥，由当前纪元密钥包裹。

静态加密

每个保险库对象——服务商记录、授权、设备记录——都是一个完整的加密信封：

  • XChaCha20-Poly1305 认证加密，256 位密钥，每次写入使用随机 192 位随机数。
  • 记录 ID 作为关联数据绑定，信封无法在记录之间互换。
  • 标题、域名、端点、认证方式、备注和 API 密钥全部在信封内部。磁盘上唯一的明文元数据是保险库清单（KDF 参数、包裹后的根密钥、当前纪元）和对象 ID。

API 密钥搜索通过存储在信封内的 HMAC-SHA256 指纹（截断至 96 位，base64）实现——密钥本身不会出现在任何索引中。界面和 CLI 输出中密钥默认掩码显示（形如 sk-ant…xyz9），除非显式要求显示。

恢复密钥

创建保险库时你会得到唯一一个恢复密钥：AIPASS- 后接 32 字节大写十六进制，按四位一组用连字符分隔。它通过 HKDF-SHA256 派生包裹密钥，可以独立于密码解开根密钥。输入是宽容的——大小写、连字符和空白都会被规范化。

恢复是一次性的：使用它会设置新主密码、生成新的恢复密钥（同样只显示一次），并轮换保险库纪元。请将当前恢复密钥离线妥善保存；AIPass 无法再次显示它。

纪元轮换与设备

轮换纪元（aipass vault rotate，或设置 → Rotate keys）会用新鲜随机数通过 HKDF-SHA256 将纪元密钥向前棘轮推进，并重新包裹每条记录的数据密钥。旧纪元密钥无法解密轮换后写入的记录——这为保险库提供了前向保密。

每台打开过保险库的机器都会注册为一条加密的设备记录。吊销设备（aipass vault revoke-device <id>）会将其标记为不受信任并轮换纪元，因此失去同步权限的设备无法再利用过期的密钥材料。

浏览器填充授权

浏览器填充从不直接复用存储的密钥。代理会签发授权——一个独立的加密信封，保存密钥副本、绑定来源、120 秒过期。授权过期时，其包裹的数据密钥会被剥离，文件被标记为墓碑：这是加密擦除，而不仅是一个标志位。已消费或过期的授权无法重放。流程见扩展指南。

锁定

锁定会从代理内存中丢弃解密后的密钥材料。保险库会因空闲超时（默认 60 分钟）、系统睡眠、锁屏、应用退出或代理重启而锁定——可配置项均可调整。锁定后，每个客户端（桌面、CLI、扩展）都必须用主密码重新解锁。

加密导出与导入

aipass vault export 生成 aipass-encrypted-vault-export（版本 1）文件：保险库文件被打包并在独立的导出密码下用新的 Argon2id 参数加密——导出的保护不依赖主密码，因此请选择强导出密码。aipass vault import 将其恢复到不存在保险库的目录中，并在完成后锁定会话。

同样的加密备份机制也保护工具配置：aipass configure 会把旧配置文件快照保存为 .aipbackup 文件，用保险库派生密钥加密并绑定操作 ID，aipass rollback 负责恢复。

同步

同步只把三类加密对象——objects/*.aipobj、grants/*.aipgrant、devices/*.aipdevice——复制到本地文件夹、iCloud Drive、OneDrive 或 WebDAV 端点。对象携带 Lamport 时间戳用于排序；当同一对象两侧不一致时，失败方会被隔离，由你在桌面应用的同步设置中逐个解决（接受或丢弃）。同步目标从不持有明文：流水线有测试确认明文密钥不会落到远端。