认证与 SSH Agent

安全的连接认证是 PhanTerm 的核心。我们采用双轨凭证存储机制和原生 Agent 集成，确保您的敏感凭据始终安全。

凭证的安全存储

无论是主连接密码、跳板机密码，还是 SSH 私钥的保护口令，PhanTerm 都会为您提供严密的本地加密保护。

• Windows 用户：升级到 0.13.0 版本后，PhanTerm 会自动将您的凭据处理并迁移至更高级别的 Windows CNG (Cryptography Next Generation) 加密保护中。该过程完全静默，相比传统的 Windows Credential Manager 提供更强的隔离与安全性。
• macOS / Linux 用户：PhanTerm 会优先将密码保存在您操作系统的系统密钥串 (System Keyring) 中。

您的敏感凭据始终保存在本地 您的密码和凭据绝不会被上传到云端。 当上述系统级密钥管理不可用时（例如某些 headless Linux 服务器），PhanTerm 会安全地回退到使用本地强随机密钥进行 AES-256-GCM 加密存储，密文保存在本地的 connections.yaml 中。

SSH 密钥认证

在创建或编辑连接时，您可以将 Auth Type 设置为 Key，然后选择您的私钥文件路径（例如 ~/.ssh/id_ed25519）。PhanTerm 会安全地读取该密钥用于登录认证，并可自动弹出输入框提示您解密受密码保护的私钥。

SSH Agent 集成

PhanTerm 完美支持 SSH Agent，这意味着您可以避免反复输入私钥密码。

1. 系统 Agent 桥接

如果您已经在操作系统中运行了 SSH Agent：

• Windows: PhanTerm 自动探测并桥接到 OpenSSH Agent (\\.\pipe\openssh-ssh-agent)。
• macOS / Linux: 自动探测并桥接到 SSH_AUTH_SOCK。

2. 内置 Agent 与 Agent 转发

即使您不使用系统级的 Agent，PhanTerm 也在内存中运行着自己的 Agent 服务。 在连接设置中开启 Forward Agent 后，PhanTerm 会通过 RFC 4254 协议安全地将您的凭据授权转发到远程服务器上，使得您能在远程服务器上直接拉取 Git 仓库或跳转到其他机器，而无需将私钥文件复制到远程环境中。

认证优先级顺序： 如果同时启用了多种认证方式，PhanTerm 会按照以下顺序尝试登录：

1. 系统 Agent 提供的密钥
2. PhanTerm 内置 Agent 提供的密钥
3. 指定的私钥文件
4. 用户名与密码

硬件安全密钥与密码学认证

PhanTerm 全面支持基于 FIDO2/U2F 的硬件安全密钥（例如 YubiKey 或 Windows Hello）。这种认证方式将私钥安全地锁定在物理硬件或 TPM 芯片中，不仅提供密码学强度的身份验证，还能从根本上抵御恶意软件通过读取磁盘或内存来窃取凭据的攻击。

物理安全密钥 (YubiKey 等) 桥接指南

如果您使用物理安全密钥，PhanTerm 可以完美地通过系统 SSH Agent 进行桥接（支持 macOS、Linux 和 Windows）：

1. 在终端中运行 ssh-add 将您的安全密钥载入到操作系统的 SSH Agent 中（例如：ssh-add ~/.ssh/id_ed25519_sk）。
2. 在 PhanTerm 的连接表单中，将 Auth Type 设置为 Key。
3. 将 Key Path 指向您安全密钥的公钥文件或私钥占位文件（stub）即可无缝使用。

Windows Hello 原生密钥指南

对于 Windows 用户，PhanTerm 提供了原生的 Windows Hello 硬件密钥集成。这意味着您可以直接在设备的 TPM 芯片中生成不可导出的安全密钥。

安全优势： 私钥生成并永久驻留在 TPM 芯片内部，不可导出。这能有效抵御本地木马或未授权进程静默窃取明文密码或软件私钥的风险。

1. 一键升级路径（极力推荐）

如果您之前使用密码登录服务器，我们极力推荐通过“一键升级”功能将连接提升为硬件保护，流程顺畅安全：

1. 像往常一样使用密码成功连接到服务器。
2. 在连接成功后，界面右下角会弹出“升级为硬件保护”的通知横幅。
3. 同意升级后，系统将进行 Windows Hello 验证（指纹/人脸/PIN），并在本地自动生成绑定硬件的安全密钥。
4. PhanTerm 会自动复用当前活跃会话，将新生成的公钥安全推送到远程服务器的 ~/.ssh/authorized_keys 中。
5. 系统会自动使用新密钥进行一次免密登录验证，一旦验证成功，将自动从本地彻底销毁存储的密码。

2. 新建连接表单路径

在创建新连接时，您也可以在表单中直接选择生成硬件绑定密钥。

已知限制：需要手动配置远程主机

在新建连接表单中生成密钥时，系统仅会在您的本地设备上生成硬件凭证（公钥与私钥 stub）。 由于此时尚未建立任何远程 SSH 会话，系统无法自动推送公钥。您必须手动将生成的 <keyPath>.pub 文件内容拷贝并追加到目标服务器的 ~/.ssh/authorized_keys 中，否则该密钥将无法通过服务器的认证。

Windows Hello 安全边界澄清

为了让您充分了解硬件安全密钥的特性，请注意以下预期的安全机制：

• 强制每次验证：由于 TPM 硬件门禁机制和 WebAuthn 规范的严格要求，PhanTerm 不会且无法在内存中缓存验证状态。这意味着在您每次连接、重新连接或触发 handshake 签名时，操作系统必然会弹出指纹/人脸/PIN 验证框。此操作无法免除，属于核心的预期安全设计。
• 内置缓存的性质：您可能会发现 PhanTerm 包含内置 Agent 缓存机制。该缓存仅用于存放 ssh.Signer 运行时对象以减少磁盘 I/O 和密钥匹配时间，而非免除生物特征验证。