Files

T

alex 3f5965bf36 docs: CLI 設計加入個人存取權杖（PAT）登入（issue #1）

- bear login 新增 --token <PAT>：以個人存取權杖免瀏覽器登入
- 同步更新 whoami/token/logout/status 於 PAT 模式下的行為
- 憑證檔規格區分 Device Flow 與 PAT、退出碼、指令↔端點對應
- 新增 BEAR_TOKEN 環境變數（一次性／CI 用）與開放問題

2026-08-30 13:41:20 +08:00

4.2 KiB

Raw Blame History

🐻 Bear CLI

Bear CLI 是澳特科技（Alter Technology）單點登入系統 Bear 的終端機（CLI）客戶端：讓使用者在 Linux 終端機以 Bear 帳號登入（Device Flow 或個人存取權杖）、查詢身分、取得 Token，作為 SSO 的終端入口。

狀態：規劃階段。本倉庫目前只規劃指令介面（command spec），尚未實作任何程式碼。伺服器端採用的 OIDC Device Authorization Grant（RFC 8628） 方向，詳見 bear 倉庫的設計文件 docs/cli-feature-plan.md（issue #17）。 Bear 已支援個人存取權杖（Personal Access Token，PAT）；CLI 規劃以其作為完全免瀏覽器的替代登入方式（見下文）。

為什麼需要 CLI

Bear 目前所有流程都依賴「瀏覽器」：登入 /login、儀表板 Launch、Relying Party 走 Authorization Code Flow + PKCE。但終端機沒有瀏覽器可互動，無法完成 redirect_uri 回跳，因此需要一個為「無瀏覽器／輸入受限裝置」設計的登入流程，讓 bear 指令也能以 OIDC 身分登入並取用 Token。此外，Bear 現已支援個人存取權杖（PAT），CLI 亦可直接以 PAT 登入，完全免瀏覽器，適合 CI／腳本／一次性使用。

指令總覽

指令	說明	階段
`bear login`	啟動 Device Flow 登入；或 `--token <PAT>` 以個人存取權杖登入	P2
`bear whoami`	顯示目前登入身分（`GET /userinfo`）	P2
`bear token [--refresh]`	印出 access token（過期自動 refresh），供 pipe 給其他工具	P2
`bear logout`	撤銷 refresh token（`POST /revoke`）	P2
`bear status`	顯示登入狀態與 token 剩餘效期	P2
`bear apps`	列出公開應用（需新增公開應用清單 API）	P3

完整指令規格（選項、行為、輸出、退出碼）見 docs/commands.md。

全域選項

選項	說明	預設
`--issuer URL`	Bear（OIDC Provider）位址	`https://alterminal.com`
`--config PATH`	設定檔路徑	`~/.config/bear/config.json`
`--json`	機器可讀輸出（JSON）	—
`-v, --verbose`	顯示詳細日誌	—
`-h, --help`	顯示說明	—
`--version`	顯示版本	—

登入流程（`bear login`，示意）

Device Flow（預設）

$ bear login
正在向 https://alterminal.com 註冊裝置...
請在瀏覽器開啟：https://alterminal.com/device
輸入代碼：ABCD-EFGH

（等待授權中...）
已登入：alice@example.com

登入後，CLI 將 refresh token 寫入本機憑證檔（0600），access token 僅做短命快取。

個人存取權杖（PAT，免瀏覽器）

$ bear login --token <PAT>
已登入：alice@example.com

以 PAT 登入不產生 refresh token；CLI 直接將該 PAT 寫入憑證檔（0600）作為憑證，適合 CI／腳本等無瀏覽器情境。

憑證與設定檔

檔	路徑	內容	權限
設定	`~/.config/bear/config.json`	`issuer`、`client_id`、`scope`	0644
憑證	`~/.local/state/bear/credentials.json`	Device Flow：`refresh_token`＋快取 `access_token`/`expires_at`；PAT：直接存 `access_token`（無 refresh）	0600

里程碑

階段	內容
P1 伺服器：Device Flow	`device_codes` 資料表、`POST /device_authorization`、`GET/POST /device` 授權頁、token 端點 `device_code` grant、Discovery 更新（於 bear 倉庫）
P2 CLI 登入	本倉庫實作 `login`（Device Flow 或 `--token <PAT>`）／`whoami`／`token`／`logout`／`status`、憑證儲存 0600
P3 進階	`bear apps`（公開應用清單 API）、QR 顯示、系統 keyring、發行二進位

技術方向（規劃）

語言：Elixir（與 Bear 主專案一致），HTTP 一律使用 Req。
發行：mix escript（單檔可執行）或 mix release 自包含二進位（待定）。
安全：device_code 只存 SHA-256 雜湊、user_code 限流、憑證檔 0600、token 與 PAT 一律不入 log／commit（PAT 僅在建立當下顯示一次，CLI 只「使用」不「管理」）。

4.2 KiB Raw Blame History Unescape Escape