cli-authv0.1.0-beta
面向生產的 CLI OAuth 認證
包含所有功能、完全可插拔的認證庫。四種流程。令牌儲存、自動刷新、跨進程鎖、整合系統金鑰管理。每個環節都幫你處理好，也都可以自由替換。
$
npm install cli-auth~/projects/your-cli — zsh
四種流程，一個庫搞掂。
選擇適合你的策略，底層邏輯都幫你整好。
裝置代碼RFC 8628
非常適合伺服器、Docker shell 或任何不能開瀏覽器的機器。
- 輪詢循環自動幫你處理 slow_down 回退和過期時間
- 用 onAuthorization 回調返回使用者碼，自定展示方式
- 當 access token 即將過期時自動刷新
適合以下情況 → 無界面、SSH 或遠端環境。適用於你的 CLI 運行在無法開瀏覽器的地方。使用者可以用自己 laptop 登錄，CLI 背景自動輪詢。
device-code.ts
1import { createCliAuth, keyringStorage } from 'cli-auth';2import { Entry } from '@napi-rs/keyring';3 4const auth = createCliAuth({5 strategy: 'device-code',6 provider: {7 metadata: {8 deviceAuthorizationEndpoint: 'https://your-tenant.logto.app/oidc/device/auth',9 tokenEndpoint: 'https://your-tenant.logto.app/oidc/token',10 },11 },12 clientId: 'your-cli-client',13 storage: keyringStorage({ entry: new Entry('your-cli', 'tokens') }),14 scope: 'openid offline_access',15});16 17await auth.login({18 onAuthorization: ({ userCode, verificationUri }) => {19 console.log(`Visit ${verificationUri} and enter ${userCode}`);20 },21});22 23const accessToken = await auth.getToken();那些 CLI 認證其實需要但沒人跟你講的細節。
下面每一條都是我們實際處理過的 bug、競態或協議規範細節。
slow_down
back-off
PKCE verifier
+ challenge
loopback on
127.0.0.1
O_CREAT | O_EXCL
atomic write
+ rename
cross-process
lock
recheck
after lock
0600
permissions
macOS
Keychain
Windows
Credential Store
Linux
Secret Service
refresh token
single-use
expiry
threshold
per-resource
token cache
proxy / OTel
fetch hook
branded
callback page
custom
parameters
TypeScript
discriminated unions
…and tests.
任何部分都可替換。沒有黑盒子。
保存、鎖定、fetch、回調頁都設有 hooks，絕不硬編碼。點選 slot 就能看到配置自動改寫。
替換
儲存macOS 金鑰鏈、Windows 資格存儲或 Linux Secret Service，取決於操作系統。通過 @napi-rs/keyring 實現。
cli-auth.config.ts
1import { createCliAuth } from 'cli-auth';2 3const auth = createCliAuth({4 strategy: 'authorization-code',5 provider: { /* ... */ },6 clientId: 'your-cli-client',7 storage: keyringStorage({ entry: new Entry('your-cli', 'tokens') }),8});自由選擇身份服務商
只要你的伺服器支援 OAuth 2.0 / OIDC 就可以。告訴庫你的 endpoint 就能跑。我們做這套不是只給 Logto 用。
Logto
Auth0
Okta
Keycloak
Microsoft Entra
Google
Authelia
Any OIDC 2.0 server
Logto
Auth0
Okta
Keycloak
Microsoft Entra
Google
Authelia
Any OIDC 2.0 server