# coffer

**Repository Path**: bigant/coffer

## Basic Information

- **Project Name**: coffer
- **Description**: 密码保存器
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Coffer

私有、零知识的多端密码管理器。

网站、系统、桌面软件、邮箱的密码越来越多，且各不相同 —— 浏览器能记一部分，
桌面软件和手机上只能靠脑子或明文便签。Coffer 用一个自托管的私密库统一管理，
并陆续支持浏览器与手机端的自动填充。

**核心取舍：服务端只存密文。** 加解密全在客户端，服务端永远接触不到密钥 ——
即使它被入侵、被托管方窥探或被依法调取，泄露的也只是无法解读的字节。

---

## 快速开始

**需要**：Rust（stable）、Node.js 20+、npm

```bash
git clone --recursive https://gitee.com/bigant/coffer.git
cd coffer/coffer-desktop
npm install
npm run tauri dev
```

> ⚠️ **必须加 `--recursive`** —— 本仓库包含 `vds-rust-sdk` 子模块，
> 漏掉会导致 Rust 构建因找不到依赖而失败。
>
> 已 clone 过的仓库补一句：
> ```bash
> git submodule update --init --recursive
> ```

首次启动会引导创建密码库。**请务必保存好恢复码** —— 零知识架构下，
忘记主密码意味着数据永久丢失，没有任何找回途径。

---

## 当前状态

已完成：创建库、解锁、增删改查、搜索、按域名归集密码、密码生成器、
从 Chrome 导入、加密备份导出、多端同步，以及 Chrome 扩展的自动填充。

**尚未实现**：手机端、扩展的跨设备场景。
详见[路线图](docs/plans/roadmap.md)。

各平台支持情况：

| 平台 | 状态 |
|---|---|
| Windows / macOS / Linux | 可用 |
| Android | 开发中 |
| 浏览器扩展 | 可用（需桌面应用同时运行） |

扩展是**不含密码学的瘦客户端**：它把当前页面的网址发给桌面应用，
由后者判断站点、解密、返回结果。因此**桌面应用不运行时扩展无法工作** ——
这是为了「加解密只有一份实现、扩展被攻破也拿不到库」而有意付出的代价，
见 [ADR-005](docs/design/ADR-005-chrome-extension-bridge.md)。

---

## 它是怎么工作的

```
主密码 ──Argon2id──> 主密钥 ──HKDF──> 包裹密钥
                                        │
随机库密钥(VK) ──被包裹密钥加密──> 存库元数据 ◄─┘
               └─被恢复码加密──> 存库元数据
               └─被设备密钥加密──> 系统凭据库（生物识别解锁用）

每条记录: XChaCha20-Poly1305(VK, 随机 nonce, AAD = 条目ID || 版本号)
```

分两层是因为**改主密码时只需重新包裹库密钥，不用重新加密所有条目**。

加密算法选用 XChaCha20-Poly1305 而非 AES-GCM：前者的 192 位随机 nonce
永不重复，多设备并发写入时没有 nonce 重用风险（一旦重用会彻底泄露密钥）。
理由与取舍见 [ADR-002](docs/design/ADR-002-crypto-primitives.md)。

---

## 项目结构

```
coffer/
├── coffer-core/       # Rust 核心库：加解密、密钥体系、存储抽象
├── coffer-desktop/    # Tauri v2 + Svelte 5 应用（桌面，也是 Android 端的工程）
├── coffer-server/     # Go 服务端：只存密文，不做搜索
├── coffer-extension/  # Chrome MV3 扩展：不含密码学的瘦客户端
├── vds-rust-sdk/      # 子模块：VDS 数据库的 Rust 客户端
├── docs/              # 设计文档、缺陷记录、路线图
└── vds-sql-dialect.md # VDS SQL 方言约束（改后端 SQL 前必读）
```

---

## 开发

```bash
# 全部构建
cargo build

# 运行测试
cargo test -p coffer-core

# 桌面应用开发模式
cd coffer-desktop && npm run tauri dev

# 仅构建前端
cd coffer-desktop && npm run build
```

后端存储用 [VDS](https://gitee.com/bigant/vds)。客户端通过子进程连接它，
所需二进制已随仓库分发，无需额外准备。

---

## 文档

| 位置 | 内容 |
|---|---|
| [docs/plans/roadmap.md](docs/plans/roadmap.md) | 各阶段要做什么 |
| [docs/design/](docs/design/) | 架构决策（ADR）、系统设计、UI 设计稿 |
| [docs/bugfix/](docs/bugfix/) | 缺陷记录：症状、根因、修复 |
| [docs/optimizations/](docs/optimizations/) | 性能优化记录 |
| [CLAUDE.md](CLAUDE.md) | 面向 AI 辅助开发的仓库说明 |

设计决策采用 ADR 形式，一条决策一个文件。要改变已确认的决定时**新写一条**
并标注取代关系，而不是就地修改 —— 决策的演变过程本身有价值。
索引见 [docs/design/README.md](docs/design/README.md)。

---

## 安全说明

**没有后门，也没有找回途径。** 这是零知识架构的必然代价，
换来的是「服务端被攻破也不会泄露密码」。

因此：

- 创建库时会强制你保存**恢复码**，请与主密码同等保管
- 目前**没有经过第三方安全审计**，请自行评估是否用于关键账号
- 数据库文件与备份都应妥善保管 —— 它们虽是密文，
  但配合弱主密码仍可能被暴力破解

安全缺陷请勿公开提交 issue。