Saas CLI Auth Flow

SaaS CLI Authentication Flow

The One Rule: A CLI user must authenticate against a web service without ever exposing credentials in transit, in logs, or at rest — and it must work whether the user has a local browser, is SSH'd into a remote server, or is running in CI.

The Three-Tier Auth Architecture

Every SaaS CLI needs three authentication paths. Users don't choose — the CLI auto-detects the environment and picks the best available tier.

Tier 1: Browser PKCE        Tier 2: Manual PKCE         Tier 3: Device Code (RFC 8628)
(local machine + browser)   (SSH/headless + copy-paste)  (fully headless, no loopback)
┌──────────────┐            ┌──────────────┐             ┌──────────────┐
│ CLI binds    │            │ CLI prints   │             │ CLI requests │
│ localhost    │            │ auth URL     │             │ device code  │
│ :random_port │            │ to stderr    │             │ from server  │
└──────┬───────┘            └──────┬───────┘             └──────┬───────┘
       │ opens browser             │ user opens                 │ displays
       ▼                           │ URL manually               ▼ ABCD-1234
┌──────────────┐            ┌──────┴───────┐             ┌──────────────┐
│ Web login    │            │ Web login    │             │ User visits  │
│ (Google, etc)│            │ + callback   │             │ /verify page │
└──────┬───────┘            │ page shows   │             │ enters code  │
       │ redirect to        │ copy button  │             └──────┬───────┘
       │ localhost:port     └──────┬───────┘                    │ server marks
       ▼                           │ user pastes                │ code verified
┌──────────────┐            ┌──────┴───────┐             ┌──────────────┐
│ CLI receives │            │ CLI parses   │             │ CLI polls    │
│ code+state   │            │ pasted URL   │             │ until verified│
│ on callback  │            │ from stdin   │             │ then exchanges│
└──────┬───────┘            └──────┬───────┘             └──────┬───────┘
       │                           │                            │
       ▼                           ▼                            ▼
       ──── All three converge on token minting (same output) ────
              Tier 1+2: POST /api/v1/auth/token
              Tier 3:   POST /api/v1/auth/device-token
              → { access_token, refresh_token }

Environment Detection Logic

is_interactive()?
├── NO → Error: "Cannot authenticate in non-interactive mode. Use API key."
└── YES
    ├── --remote flag? → Tier 3 (device code)
    ├── --manual flag? → Tier 2 (manual PKCE)
    └── auto-detect:
        ├── SSH_CLIENT or SSH_TTY set? → Tier 3
        ├── Linux: DISPLAY or WAYLAND_DISPLAY set? → Tier 1
        ├── macOS: always has GUI → Tier 1
        ├── Windows: always has GUI → Tier 1
        └── fallback → Tier 2

The Implementation Loop

1. Design protocol doc first (endpoints, error codes, security reqs)
2. Implement Tier 1 (browser PKCE) — the happy path
3. Add Tier 2 (manual paste) — minimal delta from Tier 1
4. Add Tier 3 (device code) — independent flow, new endpoints
5. Harden: timing-safe comparisons, replay prevention, race conditions
6. Add token refresh + revocation
7. Add secure credential storage (keyring → encrypted file fallback)
8. Iterate: abuse tracking, SSO enforcement, suspension checks

Security Invariants (Non-Negotiable)

Token Format Convention

<prefix>_<random_hex>

Access:  <prefix>_<64 hex chars>          (32 random bytes)
Refresh: <prefix>_refresh_<64 hex chars>  (distinct prefix prevents misuse)
API Key: <prefix>_<64 hex chars>          (same format as access token;
                                           distinguished by issuance context,
                                           not prefix — both use server-side lookup)

Validation regex: /^jsm_[a-f0-9]{64}$/ (access), /^jsm_refresh_[a-f0-9]{64}$/ (refresh)

Quick Reference: Endpoints

Anti-Patterns (Never Do)

Credential Storage Hierarchy

1. OS Keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager)
   ↓ (fails silently if unavailable)
2. Encrypted file: ~/.config/<cli>/credentials.json
   • AES-256-GCM with PBKDF2 key derivation
   • Base64url-encoded {salt, nonce, ciphertext}
   ↓ (last resort)
3. Error: inform user, suggest API key as alternative

Checklist: Before You Ship

• PKCE challenge/verifier generated per-session (never cached)
• Auth codes expire in <=60 seconds
• Device codes expire in <=15 minutes
• All token comparisons are timing-safe
• Tokens hashed before database storage
• Concurrent token exchange serialized (advisory locks)
• Suspended/banned users checked at every exchange point
• Callback page works when CLI is on a different machine (copy button)
• User-Agent: <cli>/<version> (<platform>/<arch>) on every request
• Rate limiting on all auth endpoints
• Token refresh doesn't invalidate concurrent requests (lock + atomic swap)
• Logout revokes server-side before clearing local credentials
• Legacy token formats auto-migrated on first use

References