ata-sesli/rvault

# RVault RVault 是一个本地优先的密码管理器，使用 Rust 编写，提供了终端 UI、CLI 以及一个 Helium 浏览器扩展，该扩展通过 native messaging 与本地的 `rvault` 二进制文件进行通信。 当前版本：`1.2.0`。 RVault 将数据保留在本地。密码在写入 SQLite 之前会被加密，浏览器集成通过本地 native host 进行，并且扩展不会存储明文凭据。 ## 目录 - [安装 RVault](#install-rvault) - [在本地安装 Helium 扩展](#install-the-helium-extension-locally) - [快速开始](#quick-start) - [备份和还原](#backup-and-restore) - [加密导出和导入](#encrypted-export-and-import) - [TUI 快捷键](#tui-keybindings) - [RVault 的工作原理](#how-rvault-works) - [从源码构建和测试](#build-and-test-from-source) - [发布检查清单](#release-checklist) - [当前限制](#current-boundaries) - [许可证](#license) ## 安装 RVault ### 从 GitHub Releases 获取 在 `v1.2.0` 版本发布后，从发布资产中安装 CLI： ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ata-sesli/rvault/releases/download/v1.2.0/rvault-cli-installer.sh | sh ``` 在 Windows PowerShell 中： ``` powershell -ExecutionPolicy Bypass -c "irm https://github.com/ata-sesli/rvault/releases/download/v1.2.0/rvault-cli-installer.ps1 | iex" ``` 确认安装： ``` rvault --version ``` 预期版本： ``` rvault-cli 1.2.0 ``` ### 从源码构建 要求： - Rust 工具链及 Cargo - Bun，仅用于构建浏览器扩展 - macOS 上的 Helium，仅用于浏览器集成 从此仓库安装 CLI： ``` git clone https://github.com/ata-sesli/rvault.git cd rvault cargo install --path crates/rvault-cli --force rvault --version ``` 运行终端 UI： ``` rvault ``` ## 在本地安装 Helium 扩展 RVault 扩展在 `1.2.0` 版本中尚未发布到 Chrome Web Store。请在 Helium 中在本地安装它。 这个 v1 路径专门针对 **macOS 上的 Helium**。`rvault browser enable` 会将 Helium 的 native messaging manifest 写入此处： ``` ~/Library/Application Support/net.imput.helium/NativeMessagingHosts/io.github.ata_sesli.rvault.json ``` ### 选项 A：从发布 ZIP 包安装 1. 首先安装 `rvault` CLI。 2. 从 `v1.2.0` 的 GitHub Release 中下载 `rvault-extension-1.2.0.zip`。 3. 将其解压到一个稳定的位置，例如： ``` mkdir -p ~/Applications/rvault-extension unzip rvault-extension-1.2.0.zip -d ~/Applications/rvault-extension ``` 4. 打开 Helium 并进入： ``` chrome://extensions ``` 5. 启用 **开发者模式**。 6. 点击 **加载已解压的扩展程序**。 7. 选择： ``` ~/Applications/rvault-extension ``` 8. 将 RVault 注册为 Helium 的 native messaging host： ``` rvault browser enable ``` 9. 点击 Helium 中的 RVault 工具栏图标。 如果你移动或重新安装了 `rvault` 二进制文件，请再次运行此命令： ``` rvault browser enable ``` 要移除 native messaging 注册： ``` rvault browser disable ``` ### 选项 B：在本地构建扩展 从仓库根目录执行： ``` cd extension bun install bun run build ``` 然后在 Helium 中加载此文件夹： ``` extension/build/chrome-mv3-prod ``` 加载扩展后，注册 native host： ``` rvault browser enable ``` 不要加载顶层的 `extension/` 文件夹。Helium 必须加载构建好的 `chrome-mv3-prod` 文件夹。 ### 浏览器集成故障排除 如果扩展提示 native host 不可用： ``` rvault browser disable rvault browser enable ``` 然后在 `chrome://extensions` 中重新加载扩展。 扩展 ID 由 manifest key 固定。预期的 Helium 扩展 ID 为： ``` gnfmkmiklgghclejbbdmjgcldajahfhh ``` ## 快速开始 初始化设置 RVault： ``` rvault setup ``` 解锁密码库： ``` rvault unlock ``` 添加凭据： ``` rvault add github alice:correct-horse-battery-staple ``` 将凭据密码复制到剪贴板： ``` rvault get github alice ``` 生成密码并将其复制到剪贴板： ``` rvault generate --length 20 --special-characters ``` 启动终端 UI： ``` rvault ``` 锁定密码库： ``` rvault lock ``` ## 备份和还原 备份是完整的加密二进制恢复包。备份是供密码库所有者使用的，而不是用于共享选定的条目。 创建备份： ``` rvault backup create --out rvault.rvault-backup ``` 还原备份： ``` rvault backup restore rvault.rvault-backup ``` 跳过交互式还原确认： ``` rvault backup restore rvault.rvault-backup --yes ``` 还原会在确认后替换本地的 RVault 数据。请将备份文件保存在你可控的安全位置。 ## 加密导出和导入 导出文件是加密的二进制 `.rvault-export` 文件，用于与另一个 RVault 用户共享选定条目。 接收方获取其公共的 RVault 身份码： ``` rvault unlock rvault identity ``` 发送方为该接收方导出一个条目： ``` rvault export --to rvault1-recipient-code --entry github alice --out github.rvault-export ``` 发送方可以导出多个选定的条目： ``` rvault export --to rvault1-recipient-code \ --selected github:alice \ --selected email:alice@example.com \ --out shared.rvault-export ``` 接收方导入该文件： ``` rvault unlock rvault import shared.rvault-export ``` 冲突快捷方式： ``` rvault import shared.rvault-export --overwrite-all rvault import shared.rvault-export --skip-all ``` 只有接收方身份才能解密导出文件。 ## TUI 快捷键 ### 主界面表格 | 按键 | 操作 | | --- | --- | | `Up` / `Down` | 在条目间移动 | | `Enter` | 将所选密码复制到剪贴板 | | `a` | 添加新条目 | | `e` | 编辑所选条目 | | `d` | 删除所选条目 | | `p` | 固定或取消固定所选条目 | | `i` | 复制本设备的公共身份码 | | `b` | 创建备份 | | `r` | 还原备份 | | `x` | 导出所选条目 | | `m` | 导入加密的导出文件 | | `S` | 打开排序选择 | | `t` | 打开主题选择 | | `Tab` | 切换到密码生成器 | | `q` / `Esc` | 退出 | | `Shift+Q` | 锁定并退出 | ### 生成器视图 | 按键 | 操作 | | --- | --- | | `Left` / `Right` | 减少或增加密码长度 | | `s` | 切换特殊字符 | | `Enter` | 生成密码并将其复制 | | `Tab` | 返回主表格 | | `q` / `Esc` | 退出 | ### 选择对话框 | 按键 | 操作 | | --- | --- | | `Up` / `Down` | 在选项间移动 | | `j` / `k` | 在排序和主题选择中移动选项 | | `Enter` | 确认 | | `q` / `Esc` | 关闭对话框 | ## RVault 的工作原理 RVault 分为三个 Rust crate 和一个浏览器扩展： - `rvault-core` 负责处理配置、keystore 管理、加密、会话、二进制封装、备份、身份验证、导出/导入、存储以及剪贴板集成。 - `rvault-cli` 构建 `rvault` 二进制文件、CLI 命令以及 native messaging host。 - `rvault-tui` 提供终端 UI。 - `extension` 包含用于 Helium 的 Plasmo MV3 扩展。 在设置时，RVault 会将主密码的哈希值存储在配置目录中，并使用从主密码派生的密钥创建一个加密的本地 keystore 文件。 当密码库解锁后，受保护的操作将使用活动会话密钥，而无需在每个命令执行时都要求输入主密码。 浏览器集成使用 Chrome 风格的 native messaging。当扩展发送 native message 时，Helium 会直接启动 `rvault`。`rvault browser enable` 仅注册 native messaging manifest，它不会启动后台守护进程。 ## 从源码构建和测试 构建 Rust crate： ``` cargo build ``` 运行 Rust 测试： ``` cargo test -p rvault-core cargo test -p rvault-cli cargo test -p rvault-tui cargo check ``` 构建并测试扩展： ``` cd extension bun install bun test bun run build ``` 创建本地扩展 ZIP 包： ``` cd extension/build/chrome-mv3-prod zip -r ../../../rvault-extension-1.2.0.zip . ``` 该 ZIP 包必须将 `manifest.json` 包含在 ZIP 根目录下。 ## 发布检查清单 针对 `1.2.0` 版本： 1. 确认 `Cargo.toml`、`Cargo.lock` 和 `extension/package.json` 中的版本号为 `1.2.0`。 2. 运行 Rust 检查： ``` cargo test -p rvault-core cargo test -p rvault-cli cargo test -p rvault-tui cargo check ``` 3. 运行扩展检查： ``` cd extension bun test bun run build ``` 4. 打标签并推送发布： ``` ./release-rvault 1.2.0 ``` cargo-dist 发布工作流会构建 CLI 安装程序。一个独立的扩展发布工作流会在 GitHub Release 创建后，构建并上传 `rvault-extension-1.2.0.zip`，以便在 Helium 中进行本地安装。 ## 当前限制 - 浏览器扩展在 `1.2.0` 版本中仅支持本地分发；尚未在 Chrome Web Store 上发布。 - 浏览器 native host 注册专门针对 macOS 上的 Helium。 - 此版本不包含对 Firefox 的支持。 - RVault 不提供云端托管的同步服务。 - 导出/导入是加密的接收方共享，而不是明文导出。 - 备份是完整的恢复文件，并在还原时会替换本地的 RVault 数据。 ## 许可证 采用 `MIT` 或 `Apache-2.0` 双重许可。

标签：Rust, SQLite, 可视化界面, 密码管理器, 数据加密, 浏览器扩展, 终端UI, 网络流量审计, 通知系统