background
cli-authv0.1.0-beta

OAuth di livello production per la tua CLI

Una libreria di autenticazione completa e completamente personalizzabile. Quattro flussi. Archiviazione dei token, refresh, lock tra processi, integrazione con keychain. Tutto gestito, tutto sostituibile.

$npm install cli-auth
Vedi su GitHub
Licenza MITNode.js 22+Bun 1.1+Solo ESMTypeScript
~/projects/your-cli — zsh

Quattro flussi. Una sola libreria.

Scegli una strategia. L'infrastruttura è già inclusa.

Device codeRFC 8628

La scelta ideale per server, shell Docker e qualsiasi macchina dove non puoi aprire un browser.

  • Il ciclo di polling gestisce per te il back-off slow_down e la scadenza
  • Il codice utente viene fornito tramite una callback onAuthorization, così decidi tu come mostrarlo
  • Aggiornamento automatico quando l'access token sta per scadere
Quando utilizzare questo → Senza interfaccia grafica, SSH o accesso remoto. Ovunque la tua CLI si trovi in un contesto dove il browser non può arrivare. L'utente accede dal suo portatile mentre la tua CLI esegue il polling in background.
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();

Le cose che nessuno ti dice che servono per l'auth in CLI.

Ogni nota sotto è un vero bug, race condition o punto della specifica che abbiamo già gestito.

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

Sostituisci qualsiasi componente. Niente è una scatola nera.

Storage, lock, fetch e la pagina di callback sono tutti hook. Niente hardcoded. Clicca uno slot e guarda la configurazione riscriversi da sé.

Sostituisci archiviazione
Keychain macOS, Windows Credential Store o Linux Secret Service, secondo cosa offre il sistema. Tramite @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});

Porta il tuo provider di identità

Qualsiasi server OAuth 2.0 / OIDC-compliant va bene. Punta la libreria ai tuoi endpoint e funziona. Non l'abbiamo costruita solo per 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

Domande frequenti

In cosa differisce rispetto a openid-client?

Funziona con Auth0, Okta o il mio provider?

Come funziona davvero il lock tra processi?

E se il keyring di sistema non è disponibile?

Quali runtime sono supportati?

Posso personalizzare la pagina di callback post-login?

Sblocca di più con Logto Cloud

Autenticazione CLI senza dovertela scrivere tu.

Inizia gratuitamente
Contattaci