实战：桌面原生登录

一句话：这篇教你理解并搞定 Hermes 桌面端的“原生登录”——一种更安全、更省心的登录方式，全程不需要在 App 里输入密码。

你有没有遇到过这种情况：在某个 App 里点“登录”，结果弹出一个内置小浏览器，页面长得跟外面浏览器不一样，密码管理器失灵，还要重新验证一遍身份？这就是“嵌入式登录”的痛点。

Hermes 桌面端默认采用一种更聪明的方案——原生登录（RFC 8252）。它不搞内置浏览器，而是直接调用你电脑上日常使用的浏览器（Chrome、Safari 等）完成登录。你只需要在熟悉的浏览器里点一下“允许”，App 就自动拿到登录凭证，全程无感。

下面我们分步拆解，看看它到底怎么工作，以及万一出问题怎么办。

第 1 步：App 启动，先“探路”

当你打开 Hermes 桌面端并连接到一个需要登录的网关（Gateway）时，App 不会立刻弹登录框，而是先悄悄访问网关的公开接口 /api/status，看看对方支持哪种登录方式。

GET /api/status

网关会返回一个 auth_flows 字段，相当于一张“能力清单”：

• ["cookie", "native_pkce"] → 支持原生登录，优先使用
• ["cookie"] → 只支持旧版嵌入式登录，App 自动切换
• 字段不存在 → 网关太老，只能用嵌入式登录

你不需要做任何选择，App 会自动判断并选最优方案。

第 2 步：打开系统浏览器，完成授权

如果网关支持原生登录，App 会在本地开一个临时端口（比如 127.0.0.1:随机端口），然后拉起你的系统浏览器，跳转到网关的授权页面。

系统浏览器 → 网关 /auth/native/authorize → 上游身份提供商（如 Nous Portal）

这一步背后有个叫 PKCE 的安全机制（你可以理解为一把“一次性钥匙”），确保登录过程中传输的代码即使被截获也无法被他人使用。你只需要在浏览器里正常登录、点“允许授权”即可。

第 3 步：App 拿回凭证，安全存储

浏览器授权完成后，网关会给你一个一次性代码，并重定向回 App 的本地地址。App 拿到这个代码后，再向网关换取正式的“令牌”（Token）：

POST /auth/native/token
# 携带 code + PKCE verifier

网关返回两个关键东西：

• 访问令牌（短效，几分钟）——每次请求 API 时带上，相当于“临时通行证”
• 刷新令牌（长效，会轮换）——访问令牌过期后，用它换新的

App 会把这些令牌加密存储在你的系统钥匙串（Keychain / 凭据管理器）里，而不是明文保存。

第 4 步：日常使用与自动续期

登录成功后，App 的每次请求都会带上 Authorization: Bearer <访问令牌> 头，而不是用 Cookie。当访问令牌快过期时，App 会自动调用刷新接口：

POST /auth/native/refresh

换一组新令牌，全程无感。如果刷新令牌也失效了（比如被撤销或过期），App 会清空本地令牌，提示你重新登录。

第 5 步：万一失败？自动降级

如果原生登录过程中出了岔子——比如安全软件拦截了本地端口，或者你手滑关掉了浏览器标签页——App 不会卡死，而是自动回退到嵌入式登录，保证你仍然能登录成功。

小总结

原生登录的本质就是：把登录这件事交给专业的浏览器去做，App 只负责安全地保管令牌。它避免了重复输入密码、MFA 验证的麻烦，也杜绝了内置浏览器带来的安全隐患。对普通用户来说，体验就是“点一下浏览器里的按钮，完事”。

下篇预告

登录搞定了，接下来我们聊聊怎么在远程服务器上安全地使用 OAuth 登录——毕竟不是每次都在自己电脑前。下一篇：《实战：OAuth over SSH —— 远程也能安全登录》，敬请期待。