feat(auth): add OIDC device authorization flow for CLI authentication

[chadcrum]

Summary

OIDC device authorization for the DCM CLI - dcm login / dcm logout, token storage (keyring with file fallback), authenticated HTTP transport with refresh, and a DCM_TOKEN / --token bypass for CI.

Split into three commits for easier review:

1. feat(auth): core code - auth / commands / config
2. test(auth): all test files
3. chore(auth): go.mod / go.sum + CLAUDE.md / README.md

Related PRs

• Spec: docs(ai): add OIDC auth spec and decisions (FLPATH-4477) #30
• E2E test plan: docs(test-plans): add DCM CLI OIDC auth e2e test plan (FLPATH-4477) utilities#34

Closes https://issues.redhat.com/browse/FLPATH-4477

[gabriel-farache]

Review done with an agent. It supported the other comments and added one

[gabriel-farache]

/agentic_review

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Windows cmd URL injection ✓ Resolved 🐞 Bug ⛨ Security

Description

On Windows, openBrowser executes cmd.exe /c start <url> with a verification URL taken directly
from the OIDC device authorization response, allowing cmd.exe metacharacter parsing and potential
command execution. A malicious/compromised issuer (or tampered issuer response) can trigger code
execution when dcm login opens the browser.

Code

internal/auth/auth.go[R154-157]

+		cmd = exec.Command("open", url)
+	case "windows":
+		cmd = exec.Command("cmd", "/c", "start", url)
+	default:

Evidence

DeviceLogin selects openURL from provider-supplied verification URI fields and calls
openBrowser(openURL). On Windows, openBrowser shells out via cmd.exe /c start, introducing a
shell interpretation boundary for attacker-controlled URL content.

internal/auth/auth.go[49-52]
internal/auth/auth.go[67-68]
internal/auth/auth.go[150-160]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`openBrowser` uses `exec.Command("cmd", "/c", "start", url)` on Windows. Because `cmd.exe` parses metacharacters and `start` is a shell builtin, a crafted URL can be interpreted as additional commands.

## Issue Context
The URL passed to `openBrowser` is derived from `devAuth.VerificationURIComplete` / `devAuth.VerificationURI` returned by the OIDC provider during device authorization.

## Fix Focus Areas
- internal/auth/auth.go[150-160]

## Suggested fix
- Avoid invoking `cmd.exe` entirely on Windows. Prefer a Windows-native URL opener that does not involve shell parsing (e.g., `rundll32 url.dll,FileProtocolHandler <url>`), or use a dedicated library.
- Additionally, parse/validate the URL and only allow expected schemes (typically `http`/`https`) before attempting to open it.
- Add a unit test (Windows build-tagged if needed) ensuring special characters in the URL do not result in extra argv segments/shell interpretation.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Stale token endpoint saved ✓ Resolved 🐞 Bug ☼ Reliability

Description

AuthTransport.refreshToken uses current.TokenEndpoint (which may come from a reloaded TokenData)
for the refresh request, but then persists TokenEndpoint from the pre-lock tokenData argument.
This can overwrite newer stored endpoint metadata and cause later refreshes to target the wrong
token endpoint.

Code

internal/auth/transport.go[R115-118]

+		RefreshToken:  newToken.RefreshToken,
+		IDToken:       idToken,
+		Expiry:        newToken.Expiry,
+		TokenEndpoint: tokenData.TokenEndpoint,

Evidence

The function explicitly switches current to reloaded and uses current.TokenEndpoint for the
refresh request, but constructs the persisted refreshed token with `TokenEndpoint:
tokenData.TokenEndpoint, which can be stale relative to current`.

internal/auth/transport.go[74-86]
internal/auth/transport.go[91-96]
internal/auth/transport.go[112-119]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
During refresh, `refreshToken` may switch to `current = reloaded`, but the persisted refreshed TokenData writes `TokenEndpoint` from the older `tokenData` argument instead of from `current`.

## Issue Context
This code is in a `RoundTripper` and can be hit under concurrent request usage of the same `http.Client`.

## Fix Focus Areas
- internal/auth/transport.go[82-119]

## Suggested fix
- Build the refreshed TokenData using `current` consistently:
 - `TokenEndpoint: current.TokenEndpoint`
- Consider adding a regression test that:
 - Loads an expired token with TokenEndpoint=A
 - Before refresh persists, make the store return a reloaded expired token with TokenEndpoint=B
 - Assert the final stored TokenEndpoint is B (the one actually used to refresh).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. HomeDir error ignored ✓ Resolved 🐞 Bug ⛨ Security

Description

The file token store ignores os.UserHomeDir errors and falls back to using an empty home value,
which results in writing credentials under a relative .dcm/ directory. This can persist tokens in
an unexpected working directory and increase the risk of accidental credential
exposure/misplacement.

Code

internal/auth/token.go[R137-140]

+func newFileStore() *fileStore {
+	home, _ := os.UserHomeDir()
+	return &fileStore{dir: filepath.Join(home, ".dcm")}
+}

Evidence

newFileStore drops the UserHomeDir error and uses the possibly-empty home to construct the token
directory, and writeAll then creates/writes under that directory, making token persistence location
dependent on the current working directory.

internal/auth/token.go[137-140]
internal/auth/token.go[164-177]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`newFileStore()` discards the error from `os.UserHomeDir()`. When it fails, the resulting path becomes relative (e.g., `.dcm/tokens.json`), so credentials may be stored in the process working directory.

## Issue Context
This path is used when keyring access is unavailable and the code falls back to the file-backed store.

## Fix Focus Areas
- internal/auth/token.go[137-140]
- internal/auth/token.go[164-178]

## Suggested fix
- Do not silently fall back to a relative directory.
- Prefer changing store construction to surface an error (e.g., `NewTokenStore() (TokenStore, error)`), and handle it in callers (`login`, `logout`, and `buildHTTPClient`).
- If changing the API is too invasive, at minimum:
 - Detect `UserHomeDir` error and make file-store operations fail fast with a clear error rather than writing to a relative path (e.g., set an invalid dir and return descriptive errors from Save/Load/Delete).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[chadcrum]

Review done with an agent. It supported the other comments and added one

Thanks @gabriel-farache - the TLS refresh one was valid. Fixed in 0152e50 (issuer-derived RefreshTransport).

[gciavarrini]

lgtm

[jordigilh]

Our thread (unused issuerURL + gofumpt in transport_test.go) is fixed. No further concerns.