cli-authv0.1.0-beta
你的 CLI 的生产级 OAuth 解决方案
功能齐全、可完全插拔的认证库。支持四种流程。包括令牌存储、自动刷新、跨进程锁定、密钥链集成。每个环节都已处理，每个环节都可替换。
$
npm install cli-auth~/projects/your-cli — zsh
四种授权流程。一套库搞定。
选择一套方案。底层全部帮你搞定。
设备码RFC 8628
适合服务器、Docker Shell，或没法直接打开浏览器的环境。
- 轮询循环自动为你处理 slow_down 退避和过期截止时间
- 通过 onAuthorization 回调显示用户码，展示方式由你决定
- 在访问令牌接近到期时自动刷新
適用場景 → 无头、SSH 或远程环境。只要你的 CLI 运行的地方无法直接打开浏览器即可。用户在本地笔电登入，你的 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、回调页面都可自定义。无硬编码。点选任一插槽即可实时预览配置。
替换
存储方案自动检测并使用 macOS Keychain、Windows Credential Store 或 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