Lattice CLI auth: adopt credential storage patterns from GWS CLI analysis

[gmoon]

Summary

Based on analysis of Google Workspace CLI auth architecture, here are recommended patterns for the Lattice CLI auth integration. These complement the existing auth infrastructure (device flow endpoints, API key scopes, token introspection) in forkzero/auth.

Recommended auth commands

lattice auth login          # Device flow → stores refresh token (encrypted)
lattice auth login --org    # Switch active org context
lattice auth status         # Show method, org, scopes, token validity
lattice auth export         # Masked credentials for debugging
lattice auth export --unmasked  # For CI credential transfer
lattice auth logout         # Clear stored credentials
lattice auth api-keys       # Manage API keys (create, list, revoke)

Credential fallback chain

Check in order, fail hard on explicit config, fall through silently on ambient:

1. FORKZERO_TOKEN env var — direct access token injection (CI/pipelines)
2. FORKZERO_CREDENTIALS_FILE env var — path to credential JSON
3. Encrypted keyring store — OS keychain via keyring crate (from lattice auth login)
4. Encrypted file fallback — ~/.forkzero/credentials.enc when keyring unavailable (headless Linux)
5. Interactive device flow — prompt user to authenticate via browser

Credential storage patterns

• Keyring with file fallback: Use keyring crate for OS keychain, fall back to ~/.forkzero/encryption_key for headless environments. Auto-migrate from file to keyring when available.
• AES-256-GCM encryption at rest: Never store plaintext credentials by default
• Atomic file writes: Write to temp file + rename to prevent corruption on crash
• Unix permissions: Directories 0o700, credential files 0o600
• Scope normalization: Sort + deduplicate scopes for consistent token cache keys

Multi-org profile support

API keys are scoped to user + organization. The CLI needs:

• Active org context stored in config
• --org flag to override per-command
• lattice auth login --org to switch context
• lattice auth status shows current org

API key scopes

The auth API now validates scopes using service:action convention (forkzero/auth#11, PR #12):

Scope	Description
lattice:read	Read lattice data (requirements, theses, sources)
lattice:push	Push lattice updates (create/update/resolve nodes)

See the integration guide for creating and introspecting scoped keys.

Dependencies

• forkzero/auth#10 — Add device_code grant type to lattice-app Hydra client
• forkzero/lattice#5 — Lattice CLI auth login command
• forkzero-auth Rust SDK: REQ-RSSDK-002 (device flow + credential storage), REQ-RSSDK-008 (OIDC discovery)

Anti-patterns to avoid (from GWS CLI)

• No device flow — GWS uses browser redirect only, breaks in SSH/containers. We have device flow via Hydra.
• No multi-account — GWS stores single credential set. We need multi-org from the start.
• No 401 retry with refresh — GWS only retries on 429. We should attempt token refresh on 401 before failing.
• Hardcoded OAuth endpoints — GWS has Google URLs as constants. Use OIDC discovery (/.well-known/openid-configuration).

Reference

Source analysis: SRC-GWS in forkzero/auth lattice

[gmoon]

Tracking

This issue has been decomposed into lattice requirements and implementation issues:

Requirement	Issue	Priority	Description
REQ-CLI-023	#10	P1	Auth login with device flow + encrypted credential storage
REQ-CLI-024	#11	P1	Credential fallback chain
REQ-CLI-025	#12	P1	Multi-org profile support
REQ-CLI-026	#13	P2	Auth status, export, logout, API key management

Lattice source: SRC-AUTH-PATTERNS — references this issue and the GWS CLI analysis.

This issue remains open as the tracking parent. Close when all child issues are resolved.