實戰：桌面原生登入

一句話：這篇教你理解並搞定 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 —— 遠端也能安全登入》，敬請期待。