background
cli-authv0.1.0-beta

OAuth de nível de produção para sua CLI

Uma biblioteca de autenticação completa e totalmente plugável. Quatro fluxos. Armazenamento de tokens, refresh, bloqueio entre processos, integração com keychain. Cada parte resolvida, cada parte substituível.

$npm install cli-auth
Ver no GitHub
Licença MITNode.js 22+Bun 1.1+Apenas ESMTypeScript
~/projects/your-cli — zsh

Quatro fluxos. Uma biblioteca.

Escolha uma estratégia. A canalização vem junto.

Device codeRFC 8628

O fluxo que você quer em servidores, shells Docker e qualquer máquina onde abrir um navegador não é opção.

  • O loop de polling cuida do back-off slow_down e do deadline de expiração
  • User code exposto por um callback onAuthorization, para você decidir como mostrar
  • Refresh automático quando o access token se aproxima do vencimento
Quando usar este → Headless, SSH ou remoto. Qualquer lugar onde sua CLI vive em algum lugar que o navegador não alcança. O usuário entra pelo laptop enquanto sua CLI fica fazendo polling em segundo plano.
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();

As coisas que ninguém avisa que uma auth de CLI precisa.

Cada nota abaixo é um bug real, uma race condition ou uma cláusula de spec que já cuidamos.

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.
background

Troque qualquer peça. Nada é caixa-preta.

Storage, lock, fetch e página de callback são todos hooks. Nada cravado. Clique num slot e veja a configuração se reescrever.

Trocar o storage
macOS Keychain, Windows Credential Store ou Linux Secret Service, o que o SO oferecer. Via @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});

Use o provedor de identidade que você já tem

Qualquer servidor OAuth 2.0 / OIDC-compliant funciona. Aponte a biblioteca pros seus endpoints e ela roda. Isso não foi feito só pro 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

Perguntas que as pessoas fazem

Qual a diferença em relação ao openid-client?

Funciona com Auth0, Okta ou meu próprio provedor?

Como o lock entre processos funciona de verdade?

E se o keyring do sistema não estiver disponível?

Quais runtimes são suportados?

Posso customizar a página de callback após o login?

Desbloqueie mais com o Logto Cloud

Autenticação de CLI sem precisar escrever você mesmo.

Comece grátis
Fale conosco