# 可选的系统身份验证与 Vault 锁定

请先使用主密码创建或解锁 Vault。打开 **Settings → Security**（设置 → 安全），检查提供程序的状态，然后启用生物识别解锁。注册时会要求重新进行系统身份验证。之后，登录界面除主密码表单外，还会提供 Touch ID、Windows Hello 或指纹解锁。**Disable and remove enrollment**（停用并移除注册）只会移除本应用缓存的密钥，绝不会删除操作系统中已登记的指纹。

请务必保留主密码：取消、超时、硬件/密钥环不可用以及注册失效时，都需要回退到密码。生物识别注册仅限于当前用户、设备和 Vault。它既不是恢复机制，也不是备份。只有在完成现有的 `SMAZAT` 确认之后，重置 Vault 才会撤销注册，并删除现有的加密配置文件和主机指纹。

| 平台 | 身份验证与存储 | 要求与限制 |
| --- | --- | --- |
| macOS Apple Silicon | 原生 LocalAuthentication / Touch ID；带有 `biometryCurrentSet` 和 `WhenUnlockedThisDeviceOnly` 的 Security.framework 钥匙串 (Keychain) 项目 | 需要已注册的 Touch ID、可用的传感器和可用的登录钥匙串。指纹变更会使该项目失效。生产更新请使用稳定的 Developer ID 签名；临时 (ad hoc) 的 Alpha 签名可能会破坏钥匙串信任和本地网络权限的跟踪。 |
| Windows x64 | 附加到主 HWND 的原生 WinRT Windows Hello 桌面互操作；在 Windows 凭据管理器中使用当前用户 DPAPI 加密的密钥 | 需要已配置的 Hello 指纹、面部识别**或 PIN**。这是一种便捷解锁：Hello 批准由应用强制执行，而 DPAPI 本身并不受生物识别保护。以同一用户身份运行的其他代码可能会解密该凭据。 |
| Ubuntu x64 | 通过 fprintd D-Bus 使用当前用户已注册的指纹；显式的 libsecret / Secret Service 凭据存储 | 需要受支持的读取器、已注册的指纹、正在运行的桌面 Secret Service 和默认密钥环。这是便捷解锁：密钥环中的凭据在密码学上并未与指纹验证绑定。没有 `basic_text` 或明文文件回退。 |

在 Ubuntu 上，可选的运行时软件包为 `python3-gi`、`gir1.2-secret-1`、`gnome-keyring`（或其他兼容的 Secret Service）以及 `fprintd`。请使用操作系统的常规软件包管理器安装缺失的软件包，然后在系统设置中注册指纹。身份验证使用当前用户，不需要 root 权限，也不会更改 PAM。没有桌面密钥环的无头 SSH 会话会报告不可用；它不会悄悄地把密钥存储到其他地方。

## 锁定规则

对于现有安装，自动锁定默认关闭。启用后默认选择 **15 分钟**；支持的值为 Never、1、5、10、15、30 和 60 分钟。应用窗口中的键盘和鼠标输入会被视为活动；收到的 SSH 输出则不算。可选的失焦锁定会把应用的插件窗口视为应用的一部分，并允许正在进行的系统身份验证提示完成。更改这些规则需要主密码。

**每次 Vault 锁定（包括闲置锁定和失焦锁定）都会断开活动的 SSH 会话、关闭插件并停止诊断**。锁定前请保存远程编辑内容。这沿用了现有手动锁定的行为；锁定后，后台插件将无法再使用任何 SSH 凭据。

可选的敏感操作策略会在删除配置文件、安装/移除插件、启动安装程序以及重置已解锁的 Vault 时，要求重新进行系统身份验证。远程终端命令和插件的文件编辑不在此策略范围内。该策略不能替代 SSH 服务器的授权。如果提供程序停止工作，请使用主密码解锁，并凭该密码更改策略。在锁定状态的恢复界面中，经过破坏性操作确认后，仍然可以执行重置。

## Vault 与 IPC 设计

现有的 v1 Vault 仍然使用 AES-256-GCM 和 scrypt；注册不会重写其文件，也不会更改其结构。只有其**派生的 32 字节密钥**的副本会进入操作系统的凭据存储。明文主密码永远不会被存储。本地注册元数据包含随机凭据 ID、提供程序，以及与 Vault 不可变元数据绑定的 SHA-256。恢复出的密钥必须先通过经认证的解密，才能打开会话。主进程缓冲区在使用后会被清除；原生协议字符串只是短暂存在于进程内存中，并不意味着在托管运行时中能够完全擦除内存。

辅助程序通过受限的私有 stdin/stdout 管道通信，不接受 shell 命令，设有身份验证超时，并返回经过清理的错误代码。辅助程序打包在 ASAR 之外的 `resources/biometrics` 中；它们是独立的原生可执行文件，因此不需要 Electron ABI 原生模块。Linux 辅助程序使用系统 Python 和 GI。原生对象和派生密钥永远不会跨越渲染器/插件桥。生物识别 IPC 会验证当前的主窗口及其主框架；插件无法调用它。显式锁定会取消待处理的生物识别和密码解锁操作，因此迟到的批准无法重新打开 Vault。即使操作系统的存储处于离线状态，移除注册也会撤销其本地绑定；无法访问的存储中可能会残留一个无法使用的孤立凭据。

## 构建与验证

`npm run biometrics:build` 会为当前主机平台准备辅助程序；开发启动和发布准备会自动调用它。macOS 需要带有 Security 和 LocalAuthentication 的 Swift/Apple SDK；Windows 需要 Visual Studio C++ Build Tools、Windows SDK 和 C++/WinRT；Linux 会复制 Python 辅助程序。不会添加新的 npm 依赖项。请在每个目标操作系统上原生构建。macOS 辅助程序包含在递归的应用包签名中；由于此桌面应用不在沙盒中运行，它不需要 App Sandbox 权限。生产环境的 macOS 分发仍然需要 Developer ID 签名和公证，这与 OpenPGP 版本签名无关。

请运行 `npm test`、`npm run test:biometrics:ui` 和 `npm run test:diagnostics:ui`。生物识别 Node 测试和隔离的 UI 冒烟测试使用**模拟操作系统适配器**，覆盖成功、拒绝/取消、错误密钥、缺少硬件/注册、重置、超时和迟到结果、Linux 密钥环不可用、操作系统凭据失败、Windows 经 PIN 批准的响应、macOS 注册变更、与现有 Vault 的兼容性、IPC 隔离以及 SSH 清理。这并不能证明硬件身份验证能够成功。

已在 macOS arm64 和 Windows x64 上验证原生编译。macOS 报告 Touch ID 可用；Windows 虚拟机报告 Hello 不可用。指纹/面部/PIN 注册、实际读取受保护的密钥、取消操作系统对话框以及注册变更导致的失效，仍需在每个受支持的系统上进行交互式硬件测试。Linux 辅助程序还必须在配备受支持 fprintd 读取器的桌面上进行测试；无头虚拟机无法完成该验证。

平台参考资料：[Apple 生物识别访问控制](https://developer.apple.com/documentation/security/secaccesscontrolcreateflags/biometrycurrentset)、[Windows 桌面 Hello 互操作](https://learn.microsoft.com/en-us/windows/win32/api/userconsentverifierinterop/nf-userconsentverifierinterop-iuserconsentverifierinterop-requestverificationforwindowasync)、[fprintd 设备生命周期](https://fprint.freedesktop.org/fprintd-dev/Device.html)、[Secret Service 规范](https://specifications.freedesktop.org/secret-service/latest/)。

## macOS 上 SSH 的本地网络访问

如果所有本地 SSH 配置文件都因 `connect EHOSTUNREACH` 而失败，但同一连接在“终端”中可以正常使用，请检查 **System Settings → Privacy & Security → Local Network → CH-J Server Manager**（系统设置 → 隐私与安全性 → 本地网络 → CH-J Server Manager），允许访问，然后完全退出应用并重新打开。如果已经启用，请切换一次该权限并重启。还请检查路由、Wi-Fi/以太网和 VPN：仅凭该错误并不能证明是隐私权限被拒绝。请勿因为这个错误而重置 Vault 或丢弃受信任的 SSH 指纹。

应用声明了 `NSLocalNetworkUsageDescription`，并为 macOS 网络权限/路由错误提供本地化指导。它无法自行授予权限。Apple 建议使用由 Apple 签发的签名身份，以便 macOS 能够在不同构建版本之间可靠地跟踪网络隐私权限；当前的临时 (ad hoc) Alpha 构建版本仍存在这一限制。请参阅 [Apple 关于本地网络隐私的指南](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy)。

## Ubuntu 应用图标

Debian 软件包会以标准 hicolor 尺寸（16–512 px）安装现有的 CH-J 图标，并提供相匹配的桌面条目和 Electron 窗口类。主窗口在重新创建时也会获得该图标。更新已固定在任务栏上的旧启动器后，请先取消固定，再固定新安装的应用；注销后重新登录桌面可以刷新过时的 GNOME 启动器缓存。