cli-authv0.1.0-beta
あなたの CLI 向けの本格 OAuth
バッテリー同梱＆完全プラガブルな認証ライブラリ。4 つのフロー、トークン保存、リフレッシュ、プロセス間ロック、キーチェーン連携。全てのパーツをハンドリングし、全てのパーツを差し替え可能です。
$
npm install cli-auth~/projects/your-cli — zsh
4 つのフロー、1 つのライブラリ
好みの認証戦略を選ぶだけ。面倒な部分もセットで対応。
デバイスコードRFC 8628
サーバーや Docker シェルなど、ブラウザが開けない環境に最適な方式。
- ポーリングループが 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 認証で誰も教えてくれない落とし穴
ここに挙げた全ての注意点は、実際に発生したバグ・レースコンディション・仕様ハマりの実例です。すでに対応済み。
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 キーチェーン・ Windows Credential Store ・ Linux Secret Service のうち OS が提供するものを利用。@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});任意の ID プロバイダーに対応
OAuth 2.0/OIDC 準拠であればどのサーバーでも OK。エ ンドポイントを指定するだけで動きます。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