feat(auth): implement Device Code login flow and token refresh

[emsearcy]

Summary

Implements lfx auth login, lfx auth token, lfx auth status, and lfx auth logout on top of golang.org/x/oauth2's device authorization grant support (Config.DeviceAuth/DeviceAccessToken) and refresh-token TokenSource, targeting the static per-environment Auth0 client IDs provisioned in LFXV2-2513.

• internal/auth0 (new package): resolves --env to its IdP domain and compiled-in client ID, and drives the device code request, poll, and refresh-token exchange via golang.org/x/oauth2.
• internal/commands/auth.go: real login (interactive device code flow, or --with-token for headless/CI use), token (cached-token fast path, refresh-and-recache on expiry, clear error message on invalid/expired refresh token), status, and logout implementations.
• internal/credstore: extends DeviceState with environment/audience (needed to rebuild the same IdP client on refresh), insecure (guards against mixing state between the keychain and --insecure-storage backends), and adds DeleteDeviceState for logout.
• Includes outstanding .cspell.json wordlist additions/fixes (nolint, containedctx, rundll, plus suppressing spellcheck on the opaque Auth0 client ID literals).

Notably NOT implemented: persistent "device ID"

The epic's background/design notes called for a "Device ID persistence in ~/.local/state/lfx-cli/," modeled on an assumed gh CLI precedent. I checked gh's actual behavior directly: ~/.local/state/gh/device-id exists, but it's generated by internal/telemetry.getOrCreateDeviceID in github.com/cli/cli — an anonymous telemetry identifier, not something used in gh's own OAuth device flow or credential storage. Auth0's device authorization grant has no concept of a device ID either. Since the LFX CLI has no telemetry pipeline in scope here, there's nothing for one to do; left out of credstore.DeviceState with a comment explaining the rationale. See ticket comments on LFXV2-2515/LFXV2-2516 for the full writeup.

Related tickets

• LFXV2-2515 — Implement Device Code login flow (lfx auth login)
• LFXV2-2516 — Implement lfx auth token command

Testing

• go build ./..., go vet ./..., golangci-lint run, revive ./... all pass clean
• Manually smoke-tested the full login/status/token/logout cycle end-to-end against the dev and prod Auth0 tenants (--env development/--env prod), including the interactive device code flow, cached-token fast path, and refresh-token exchange
• Found and fixed a real bug during that prod testing: prod's IdP domain must be its custom domain sso.linuxfoundation.org, not linuxfoundation.auth0.com (see auth0-terraform's own auth0_domain variable) — using the wrong domain surfaced as an Auth0 invalid_request: Missing required parameter: response_type error and a login that never completed

🤖 Generated with GitHub Copilot (via OpenCode)

[Copilot]

Pull request overview

Implements Auth0 device-code authentication and token refresh for the LFX CLI.

Changes:

• Adds environment-aware Auth0 device authorization and refresh support.
• Implements login, token, status, logout, and credential-state cleanup.
• Adds OAuth dependency and spellcheck terms.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
internal/auth0/device.go	Adds Auth0 device and refresh flows.
internal/commands/auth.go	Implements authentication commands.
internal/credstore/credstore.go	Extends and deletes persisted device state.
go.mod	Adds OAuth2 dependency.
go.sum	Records OAuth2 checksums.
.cspell.json	Adds required technical terms.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

internal/auth0/device.go:184

• The caller can pass a context with its own deadline to RequestDeviceCode; DeviceAccessToken derives its polling context from that parent, so DeadlineExceeded is not necessarily caused by the device-code expiry. This branch misreports an earlier caller timeout as an expired device code. Check dc.ctx.Err() (or otherwise distinguish the parent deadline) before mapping the error to ErrExpiredToken.

	// passes in (see RequestDeviceCode), any DeadlineExceeded seen here
	// can only come from that internal one, so it's safe to always treat
	// it as ErrExpiredToken.
	if errors.Is(err, context.DeadlineExceeded) {
		return nil, ErrExpiredToken

internal/commands/auth.go:186

• verification_uri_complete is optional, but both the browser and manual paths use it unconditionally. A valid device response that only supplies verification_uri therefore opens/prints an empty URL and leaves the user unable to complete login. Fall back to dc.VerificationURI when the complete URI is empty.

		fmt.Printf("Opening %s in your browser...\n", dc.VerificationURIComplete)
		if err := openBrowser(dc.VerificationURIComplete); err != nil {

[emsearcy]

AI-assisted: Fixed in d94eda8 — addressed the 2 suppressed Copilot comments from the follow-up review:

• Poll() now checks dc.ctx.Err() before mapping context.DeadlineExceeded to ErrExpiredToken, so a caller-supplied context deadline (distinct from DeviceAccessToken's own internally-derived one) is no longer misreported as an expired device code.
• loginWithDeviceCode now falls back to VerificationURI when VerificationURIComplete is empty (it's optional per RFC 8628 §3.2).

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (5)

internal/commands/auth.go:216

• As in the supplied-token path, credentials are saved before the required device state. A state-file write failure therefore reports login failure while leaving newly issued credentials paired with missing or previous environment metadata. Make the two persistence updates atomic from the caller’s perspective or restore/remove the credential update on failure.

	if err := store.SaveCredentials(credstore.Credentials{
		RefreshToken:      token.RefreshToken,
		AccessToken:       token.AccessToken,
		AccessTokenExpiry: token.Expiry,
	}); err != nil {
		return fmt.Errorf("save credentials: %w", err)
	}

internal/commands/auth.go:209

• A successful Auth0 device exchange can omit refresh_token when the selected custom API does not allow offline access, even though offline_access was requested. This currently persists an empty refresh token and reports “Login successful,” so the session becomes unusable as soon as the cached access token expires. Reject the login with a clear configuration error when token.RefreshToken is empty before saving credentials.

		return errors.New("login was denied")
	case errors.Is(err, auth0.ErrExpiredToken):
		return errors.New("device code expired before login completed")
	default:
		return err

internal/commands/auth.go:152

• Credentials have already been overwritten when SaveDeviceState runs. If writing state.json fails, the command returns an error but leaves the new refresh token paired with missing or stale environment metadata, so a later refresh cannot safely reconstruct its Auth0 client. Persist these as one consistent operation or roll back the credential update when state persistence fails.

This issue also appears on line 210 of the same file.

	if err := store.SaveDeviceState(credstore.DeviceState{
		IDPDomain:   domain,
		Environment: string(env),
		Audience:    audience,
		Insecure:    insecure,
	}); err != nil {
		return fmt.Errorf("save device state: %w", err)

AGENTS.md:50

• This implementation now uses compiled-in static client IDs, but AGENTS.md:177-180 still says the gh-pages CIMD URL is the Device Code client ID. That guidance directly contradicts internal/auth0/device.go:22-26 and can send future maintainers to update an unused client definition. Update the gh-pages section to explain that the CIMD asset is no longer used by this flow.

`lfx auth login` / `status` / `token` / `logout` are fully implemented,
including the Auth0 Device Code flow, refresh-token exchange, and

internal/auth0/device.go:91

• All production callers leave HTTPClient nil, and main supplies context.Background(), so device-code and refresh requests use http.DefaultClient without an overall response timeout. An Auth0 endpoint that accepts a connection but stalls can therefore hang lfx auth login or lfx auth token indefinitely. Provide a bounded default client or add per-request deadlines while retaining the device-flow polling deadline.

	// HTTPClient is used for all requests. Defaults to
	// http.DefaultClient if nil.
	HTTPClient *http.Client

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

internal/commands/auth.go:223

• This has the same partial-login failure mode as --with-token: credentials are replaced before device state is saved. If the state write fails, an older same-backend state remains usable and can direct this new refresh token to the previous environment's token endpoint. Roll back/delete the new credentials on failure, or make persistence of credentials and their routing metadata atomic.

	if err := store.SaveDeviceState(credstore.DeviceState{
		IDPDomain:   domain,
		Environment: string(env),
		Audience:    audience,
		Insecure:    insecure,
	}); err != nil {
		return fmt.Errorf("save device state: %w", err)

[emsearcy]

AI-assisted: Fixed in 98b10cc. persistLogin now calls store.DeleteCredentials() to roll back the just-saved credentials if SaveDeviceState fails, instead of leaving a mismatched credentials/metadata pair.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (5)

internal/commands/auth.go:146

• SaveCredentials has already replaced the selected backend's credentials when SaveDeviceState fails. The command then reports a failed login while leaving the new refresh token paired with stale or missing environment metadata, so a later refresh can target the wrong configured tenant and fail. Persist the credential/state pair transactionally, or restore/delete the newly written credentials when saving the state fails.

	if err := store.SaveCredentials(credstore.Credentials{RefreshToken: refreshToken}); err != nil {
		return fmt.Errorf("save credentials: %w", err)
	}
	if err := store.SaveDeviceState(credstore.DeviceState{

internal/commands/auth.go:217

• This second write can fail after the newly issued credentials have already been saved, leaving credentials and device metadata from different login attempts. A later refresh then uses stale metadata with the new refresh token. Make these writes transactional or roll back the credential write when saving state fails.

	if err := store.SaveDeviceState(credstore.DeviceState{

internal/commands/auth.go:388

• The presence of a credential record does not establish that the user is logged in: --with-token accepts any non-empty string without validation, and stored refresh tokens can later be revoked. In both cases this command prints “Logged in.” even though token acquisition fails. Validate the session (for example by refreshing when no valid access token is cached), or report only that credentials are stored rather than asserting an authenticated status.

			fmt.Println("Logged in.")

internal/commands/auth.go:214

• A successful OAuth token response is not required to include a refresh token. Saving such a response and printing “Login successful” creates a session that necessarily stops working when the access token expires. Check token.RefreshToken before persisting and return an actionable error if Auth0 did not issue one.

	if err := store.SaveCredentials(credstore.Credentials{
		RefreshToken:      token.RefreshToken,
		AccessToken:       token.AccessToken,
		AccessTokenExpiry: token.Expiry,
	}); err != nil {

internal/commands/auth.go:40

• This comment is inaccurate: auth status never reads identity claims; these scopes are used only for the post-login “Logged in as …” message at lines 227-230. Describe that actual use so future scope changes do not rely on a nonexistent status dependency.

// scopes requested during the device code flow. offline_access is required
// to receive a refresh token; the rest identify the user for `auth status`.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

internal/commands/auth.go:299

• If the credential write succeeds but the state write fails (disk full, permissions, or a partial state-file write), the command reports login failure after already replacing the credentials. The new refresh token is then paired with stale environment metadata—or no metadata—so later refreshes fail, and a previously valid login may have been destroyed. Make these writes transactional from the caller’s perspective by restoring/deleting the newly written credentials when state persistence fails (and preserving any prior login as appropriate).

	if err := store.SaveCredentials(creds); err != nil {
		return fmt.Errorf("save credentials: %w", err)
	}
	if err := store.SaveDeviceState(state); err != nil {
		return fmt.Errorf("save device state: %w", err)

internal/commands/auth.go:209

• A successful OAuth token response is not guaranteed to contain a refresh token, even when offline_access is requested (for example, an overridden audience may have offline access disabled). This path still persists the response and prints “Login successful,” so authentication works only until the cached access token expires, after which auth token can never refresh it. Require a non-empty token.RefreshToken before persisting the login and return an actionable configuration/login error otherwise.

			RefreshToken:      token.RefreshToken,

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

internal/commands/auth.go:299

• If the state-file write fails after the keychain/plain-file write succeeds, this failed login has already replaced any working credentials while leaving old or missing environment metadata. The next refresh can therefore target metadata from a different login or become impossible. Persist credentials and their refresh metadata as one atomic unit, or restore the previous credentials/state when the second write fails instead of returning with a split login.

	if err := store.SaveCredentials(creds); err != nil {
		return fmt.Errorf("save credentials: %w", err)
	}
	if err := store.SaveDeviceState(state); err != nil {
		return fmt.Errorf("save device state: %w", err)

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.