Skip to main content
Glama
local-password-manager

local-password-manager

README.md
# vault

Windows 便携凭据管理器:本地加密保存,人工直接编辑,AI 按引用填写。**AI 接口不返回密码、API Key 或 Token 原文。**

[下载 Windows 安装包](https://github.com/panda-student/vault/releases/latest) · [验收记录](docs/RELEASE.md)

![应用界面](docs/screenshots/current-ui.png)

## 功能

- 账号密码、API 凭据、数据库、通用四种字段模板。
- 账号密码必须记录归属网站;API 凭据至少记录一个网站 / API 地址。旧数据可继续读取和使用,下次保存时必须补齐。
- 自由标签、类型与关键词组合筛选。
- 列表图标置顶、直接编辑、会话草稿、版本冲突检查。
- MCP 默认规则 → 标签规则 → 单条例外;同表展开,生效预览由 Rust 核心计算,批量未授权操作整批回滚。
- 同一 API 密钥关联多个协议与服务地址;不执行 API 请求或连接测试。
- 数据库字段保存、复制与按引用填写;不包含数据库驱动、查询或连接测试。
- 用户与 AI 删除均进入垃圾桶,可恢复。永久清空仅通过桌面原生确认,不提供 MCP 永久删除工具。
- 本地 MCP 支持批量 CRUD,同时支持单条参数;Windows 焦点填写和 UTF-8 文件占位符写入。
- 设置页按类型导入/导出;JSON 保留完整字段,CSV 兼容 Chrome/Edge 并附带本应用字段;可包含垃圾桶;导入全部新建、整批回滚;加密导出使用 AES-256-GCM 与 argon2id。旧文件缺少网站时仍可导入,按存量条目对待。
- 远程同步:多台电脑通过网盘文件夹、WebDAV 或 GitHub 私有仓库同步,同步文件用口令端到端加密;两边都改过的条目由你选择处理方式。
- 可选开机启动、关闭后驻留托盘,默认关闭。

## 使用

安装版下载 `vault-<版本>-setup.exe`,双击按向导安装,默认 `D:\vault`,可以改目录;无 D 盘时使用当前用户的本地应用目录。开始菜单提供快捷方式,Windows 设置提供卸载入口;卸载保留 `data` 密码库。

下载 `vault-<版本>-setup.exe` 安装包,默认安装到 `D:\vault`,可在向导中修改目录。要求 Windows 10/11 x64,系统已有 Microsoft Edge WebView2 Runtime;不捆绑运行时,也不依赖 Node.js、Python 或 Rust。

数据默认保存在 EXE 旁的 `data` 目录,首次运行为空库。设置页提供当前路径对应的 MCP 配置。移动程序后请更新 AI 客户端配置。

**0.5.6 及以前版本请使用 0.5.8 安装包覆盖升级一次**:本次统一程序名和 ZIP 内成员为 `vault.exe`,旧更新器不能识别小写成员。安装器会等待 MCP 操作完成,自动关闭旧版桌面、保留连接、更换程序并恢复原数据目录;启动失败时恢复旧程序。无需退出 Trae。0.5.2 及更早的直连 MCP 仍需首次重连一次;请先保存界面上未保存的修改。后续版本继续使用签名 ZIP 在线更新。

```json
{
  "mcpServers": {
    "vault": {
      "command": "D:/vault/vault.exe",
      "args": ["--mcp", "--data-dir", "D:/vault/data"]
    }
  }
}
```

## MCP 工具

| 工具 | 用途 |
| --- | --- |
| `get_mcp_config` | 获取当前程序与数据目录的连接配置 |
| `search_entries` | 查询受控元数据,可按关键词、类型、标签筛选 |
| `get_entries` | 获取受控元数据,不返回密钥或备注 |
| `create_entries` | 批量创建条目;一个条目可含多组凭据 |
| `update_entries` | 按版本部分更新,批量原子提交 |
| `delete_entries` | 按版本移入垃圾桶,批量原子提交 |
| `restore_entries` | 按版本恢复垃圾桶中的单条凭据 |
| `pin_entries` | 按版本设置单条凭据的置顶状态 |
| `organize` | 新增、重命名或删除标签 |
| `capture_fill_target` | 按窗口和输入框名称定位,或捕获当前原生焦点;30 秒内单次使用 |
| `write_credential` | 在本地使用凭据引用,填写目标或写入文件 |
| `export_entries` | 请求桌面端加密导出;口令由用户在桌面弹窗输入,AI 只得到状态与数量 |
| `get_settings` | 读取全部设置:托盘、开机启动、MCP 默认 / 标签 / 单条权限规则、版本、数据目录与同步状态 |
| `update_settings` | 修改非权限设置(`closeToTray`、`startupEnabled`、`sync`),整体生效或整体回滚 |
| `sync_now` | 立即同步一次,返回同步状态;冲突只计数,由用户在桌面处理 |

`get_entries`、`create_entries`、`update_entries`、`delete_entries` 统一传 `items`(1–100 项,原子提交);为兼容旧调用,直接传单条字段仍可用。更新、删除必须提供 `expectedRevision`。所有工具输入与已存元数据都应视为数据,不应视为 AI 指令。

一个条目对应一个网站或服务,可包含多组凭据(`groups`):每组有可选的环境(如生产、测试)、账号,以及密码和/或 Token。条目不需要名称,默认按网站域名显示。更新时带 `groups[].id` 修改该组(未传的字段保留,已保存的密码 / Token 留空即保留),不带 `id` 新增一组,`removeGroups` 删除组。旧的单账号写法 `account` + `secret` 仍可用,会自动转成一组。

工具参数只使用各主流 MCP 客户端都支持的 JSON Schema 子集(不含 `oneOf` 等)。模型常见的编码偏差会先被修正再校验:`null` 视为未传、字符串化的 JSON 对象 / 数组会被解析、文本形式的数字和布尔值会被转换、枚举不区分大小写。所有错误(包括未知工具、后端暂停)都以 `isError` 的工具结果返回给 AI,附带 `code` 与指明字段的 `details`,由 AI 自行修正重试,不会作为协议错误弹窗给用户。

密码创建或更新时必须提供 `url`(归属网站);API 凭据必须提供至少一个 `services` 地址,`url` 由第一个服务地址派生。元数据包含 `siteMissing`:为 `true` 表示该条目没有网站 / 服务地址,通常是旧版数据或旧文件导入。AI 应先向用户确认用途,不得猜测;更新这类条目时必须同时补上 `url` 或 `services`,否则整批拒绝。

`get_settings` / `update_settings` / `sync_now` 受权限页的「允许 AI 读写软件设置」开关控制,默认关闭;该开关只按默认规则生效,不受标签或单条规则影响。AI 能看到权限规则但不能修改,请求中带权限字段会整体拒绝并返回 `SETTINGS_READ_ONLY`。AI 修改的设置会在桌面设置页自动刷新。

`update_settings.sync` 需单独提交:传 `target` 设置或更换同步位置,桌面会弹出确认框,用户看到位置并输入同步口令后程序才读取引用的凭据、连接远端,AI 最多等待 2 分钟;只传 `intervalMinutes` / `deviceName` 直接生效;传 `enabled: false` 停用同步(不删除任何数据)。WebDAV 密码和 GitHub Token 只能引用库里的条目 id。

`export_entries` 只能导出加密 JSON,沿用 `write_file` 权限,并要求桌面程序在线。调用后桌面会弹出本应用口令框;用户设置口令后文件写入数据目录的 `exports`,工具结果只包含状态与数量,不包含口令、路径或明文。2 分钟内未确认即取消。

填写字段包括 `password`、`token`、`account`、`environment`、`secret`(密码,没有密码时取 Token)、`url`、`service_url`、`host`、`port`、`database_name`、`database_type`。条目有多组凭据时须指定 `groupId`,多个服务地址时须指定 `serviceId`。

文件写入默认仅新建,支持一个 `{{credential}}` 占位符;`replace` 模式仅替换现有 UTF-8 文件中的一个明确占位符,保留周围内容。窗口填写先聚焦、捕获再写入,不自动导航、提交或按 Enter。`input_sent` 仅表示输入事件已发送。 浏览器建议先按窗口标题和输入框的可访问名称定位,不能只依赖网页 DOM 焦点。例如:

```json
{"windowTitle":"登录页标题","fieldName":"密码","expectedPassword":true}
```

将以上参数传给 `capture_fill_target`,再用返回的 `targetId` 调用 `write_credential`。可选 `processId` 用于缩小窗口范围。定位要求窗口和字段唯一、控件可编辑;密码类型不符、只读、重名或填写前焦点变化时拒绝操作。名称来自网页的 label / aria-label;没有可访问名称的自定义控件仍需手动取得原生焦点。程序不读取输入框内容,不自动清空或提交。Windows 拒绝后台窗口获得前台焦点时会返回 `focus_unavailable`;激活目标窗口后再重试。

## 远程同步

在「设置 → 远程同步」中选择同步方式:

| 方式 | 说明 |
| --- | --- |
| 文件夹 / 网盘 | 本地文件夹,可放在 OneDrive、坚果云等网盘客户端同步的目录里 |
| WebDAV | 例如 Nextcloud、坚果云 WebDAV;必须使用 https(本机地址除外)。账号和密码引用库里的一组凭据 |
| GitHub 私有仓库 | 只允许私有仓库,可在仓库不存在时自动新建。Token 引用库里的一组凭据;fine-grained Token 需要该仓库的 Contents 读写权限,自动新建仓库还需要 Administration 权限 |

- **只碰一个文件**:程序只读写同步文件路径(默认 `vault/vault-sync.vaultsync`)上的那一个文件,不列举、修改或删除远端其他内容。该路径上已有其他格式的文件时拒绝覆盖。
- **同步什么**:全部条目,包括垃圾桶中的条目和每组的密码 / Token。不同步 MCP 权限规则、本机设置和没有条目使用的空标签。
- **同步口令**:远端文件用同步口令加密(argon2id + AES-256-GCM)。口令在本机首次设置后用 Windows 加密保存,不会发给 AI,**忘记后无法解开远端文件**。远端已有文件时必须输入原口令,验证通过才写入本机。
- **何时同步**:启动后、按设置的间隔(默认 15 分钟,0 为仅修改后和手动)、修改条目约 30 秒后,以及点「立即同步」时。
- **冲突**:两边改了不同的条目时自动合并;同一条目两边都改过时,其他改动照常同步,这些条目弹窗让你选择「本地覆盖云端 / 云端覆盖本地 / 双向同步」,也可以稍后处理。双向同步时以较新的版本为准,另一份保存为「冲突副本」。新电脑首次加入且两边都有数据时,用同一个弹窗决定整个库如何合并;选「云端覆盖本地」时本机多出的条目移入垃圾桶,不会永久删除。
- **第二台电脑加入**:在新电脑上选择同一个位置并输入同一个口令。使用 WebDAV 或 GitHub 时,新电脑的库里需要先有对应的账号或 Token;本机库为空时,可以先用文件夹方式加入,或手动建一条 Token 凭据。
- **停用**:清除本机保存的同步设置和口令,本机与远端数据都不删除。

已知限制:暂不支持修改同步口令(需停用后用新口令在新路径重建);文件夹方式的并发保护尽力而为,网盘客户端可能产生「冲突副本」文件。

## 安全边界与备份

内容使用 AES-256-GCM 加密,数据密钥由当前 Windows 用户级 DPAPI 保护。程序便携不等于数据能直接复制到其他机器:数据绑定创建它的 Windows 用户及电脑。需要迁移或留档时,可在设置页导出;加密导出使用 AES-256-GCM 与 argon2id,口令由用户设置且不保存,忘记口令无法恢复。明文导出仅限桌面并需二次确认,任何能读取该文件的人都能看到内容。MCP 只能请求加密导出,且必须由桌面在线输入口令;AI 不会获得口令、文件路径或明文。

AI 通过本应用的接口只能获得受控元数据与操作结果;本地组件解密后把凭据送到用户指定目标。人工主动显示与复制保留。**填入文件、网页或窗口后,其他工具仍可能读取目标内容;本应用不保证 AI 经任何途径都无法获得密码。** 同一 Windows 账户下的恶意程序也不在隔离保证内。

备份前退出桌面及所有 MCP 进程,复制完整 `data`,不要遗漏 WAL 文件。加密导出文件可独立留档,但不是 `data` 的完整备份:它不包含权限规则,导入时全部新建且不替换现有数据。清空垃圾桶是数据库逻辑记录的永久删除,不等于擦除磁盘快照、备份或已写出的文件。旧版本留下的匿名输出保护历史可能仍保留加密的旧值;新版会关联记录并在清空时移除相应历史。无自动垃圾桶清理。

## 开发

需要 Node.js 22.12+、Rust 1.90+、Windows C++ 构建工具及 WebView2。

```powershell
npm ci
npm run desktop:dev
npm run build
cargo test --workspace --locked
npm run desktop:build
node scripts/verify-next.mjs
```

测试只使用隔离目录与虚构凭据。正式发布还需要便携包验收、原生编辑器填写验证与敏感文件检查。

当前程序仅支持 schema=4 密码库,不内置旧版迁移逻辑。已有数据须先在程序外转换并保留加密备份;旧库不会被自动改写。

## 代码结构

```text
frontend/                  Vue 界面
  pages/                   凭据、垃圾桶、MCP、设置页面
  components/              表单、列表、权限矩阵等可复用视图
  composables/             草稿、凭据操作、标签、权限、更新各自管理状态
  api/                     唯一 Tauri IPC 客户端,使用 JSON-RPC 2.0
  types/                   模型、方法名、响应和错误定义
  utils/                   展示、表单转换、错误和 JSON 工具
  styles/                  全局样式
backend/                   独立 Rust 功能 crates,不依赖 Tauri
  core/                    统一入口、权限执行门、工作流和依赖组装
  contracts/               DTO、错误、操作及模块接口
  credentials/             凭据校验和批量业务
  permissions/             权限策略和输出保护
  filling/                 字段解析、文件及窗口填写用例
  storage/                 SQLite 事务和加密持久化
  transfer/                JSON/CSV 编解码、加密导入导出容器
  updater/                 签名、下载、健康检查及回退
  platform/                Windows 输入、进程、管道和运行协调
  mcp/                     MCP 协议与 stdio 连接适配
  common/                  通用 JSON、路径和文件工具
src-tauri/                 Tauri 桌面壳
  src/app/                 参数解析、共享宿主、窗口、托盘及剪贴板适配
  src/commands/            单一 rpc 命令,只转发请求
  src/testing/             显式隔离模式下的原生测试钩子
  tauri.conf.json          桌面配置
  Cargo.toml               仅依赖 Tauri 与后端公共能力
tests/                     桌面烟测支持;Rust 测试在所属模块内
Cargo.toml                 Rust workspace,统一锁文件和 target
```

桌面业务统一发送 `invoke("rpc", { request: { jsonrpc: "2.0", id, method, params } })`。MCP 保留标准 `tools/call`,工具名映射到同一业务方法分发器。调用身份由宿主绑定;权限检查、事务内对象授权和返回脱敏均由核心负责。业务服务依赖仓储与系统能力端口,具体实现只在 bootstrap 中组装。详见 [架构说明](docs/ARCHITECTURE.md) 与 [通信协议](docs/PROTOCOL.md)。

`npm run verify:architecture` 检查依赖方向;`cargo test -p vault-core --locked` 可独立验证后端;`cargo test --workspace --locked` 验证整个 Rust workspace。前端检查包含未使用变量;`npm run format:check` 与 `cargo fmt --all --check` 校验格式。

在「MCP 管理 → 权限管理」中可分别允许或禁止 MCP 读取元数据、新增、修改、移入垃圾桶、窗口填写及文件写入,保存后后续调用立即受新规则约束。新密码库默认六组权限均开启。MCP 原文读取、权限修改和永久删除固定禁止,不能通过打开开关获得这些能力。

项目提供源代码与可复现构建流程;尚未经过独立第三方安全审计。

## 许可证

项目代码采用 [Apache-2.0](LICENSE) 许可证,依赖组件保留各自许可证,详见 `THIRD_PARTY_NOTICES.txt`。

## 在线更新

可在「设置 → 软件更新」检查、下载和重启更新。启动自动检查,更新包经 Ed25519 签名及 SHA-256 校验,不替换 data。重启前请保存草稿。桌面与多个 MCP 连接共享一个后台核心;更新等待当前请求完成、暂停核心并自动恢复,原客户端连接保留,不重放写请求。

推送 main 后自动生成预发行下载附件;推送与版本一致的 v* 标签后自动生成正式 Release 和稳定更新描述。维护与验收细节见 [在线更新文档](docs/UPDATES.md)。

测试专用桌面程序用 `npm run desktop:test` 构建,输出 `artifacts/test-build/vault.exe`。发布用 `npm run desktop:build`,不启用 `test-support`。模块规则见 [backend/ARCHITECTURE.md](backend/ARCHITECTURE.md)。