fix(cli): improve error message when edge-auth flow times out on non-Cloudflare deployments

[akram]

Agent Diagnostic

• Explored crates/openshell-cli/src/auth.rs:158-168 — the timeout handler returns a generic message: "authentication timed out after 120 seconds. Try again with: openshell gateway login".
• Explored crates/openshell-cli/src/run.rs:1162-1195 — browser_auth_flow() is called for any HTTPS gateway without --oidc-issuer or --local. There is no detection of whether the flow failed because Cloudflare is missing vs. a transient error.
• Verified by deploying on OpenShift without Cloudflare: the timeout message gives no indication that OIDC or --local would work. Re-running gateway login produces the same timeout.

Description

When the Cloudflare Access edge-auth flow times out (no CF_Authorization cookie arrives after 120 seconds), the CLI displays:

⚠ Authentication skipped: authentication timed out after 120 seconds.
Try again with: openshell gateway login

This message is unhelpful because re-running gateway login produces the same result. The user has no indication that the flow requires Cloudflare Access, or that --oidc-issuer is the correct alternative for non-Cloudflare deployments.

Reproduction Steps

1. Deploy the gateway on any Kubernetes cluster without Cloudflare Access
2. Run openshell gateway add https://<endpoint> --gateway-insecure
3. Press Enter to open the browser
4. Wait 120 seconds

Expected: The timeout message suggests alternatives (OIDC, --local).

Actual:

⚠ Authentication skipped: authentication timed out after 120 seconds.
Try again with: openshell gateway login

Environment

• OS: macOS 15.x (Apple Silicon)
• OpenShift: ROSA HCP 4.21 (Kubernetes 1.34.2)
• OpenShell: CLI v0.0.45

Proposed Fix

Replace the timeout message at crates/openshell-cli/src/auth.rs:163-166 with actionable guidance:

⚠ Authentication timed out. The browser-based login requires a Cloudflare Access
  proxy in front of the gateway.

  If your gateway uses OIDC authentication, re-register with:
    openshell gateway add <endpoint> --oidc-issuer <issuer-url>

  If your gateway allows unauthenticated access, re-register with:
    openshell gateway add <endpoint> --local

Related

• bug: gateway add defaults to Cloudflare edge-auth for HTTPS endpoints — no fallback or guidance for non-CF deployments #2057 — root issue documenting the Cloudflare edge-auth default behavior
• feat(cli): auto-detect OIDC configuration during gateway add #2098 — auto-detect OIDC from gateway metadata (longer-term fix)

---

• I pointed my agent at the repo and had it investigate this issue
• I loaded relevant skills (e.g., debug-openshell-cluster, debug-inference, openshell-cli)
• My agent could not resolve this — the diagnostic above explains why

[TaylorMutch]

📋 triage-agent

Triage Assessment

Classification: bug-confirmed

Summary

Current main confirms the timeout guidance is ineffective. The Cloudflare callback flow waits 120 seconds and then recommends openshell gateway login, which dispatches to the same flow and can produce the same timeout. This is additive to #2057 rather than a duplicate: #2057 covers auth-mode selection and discovery, while this issue covers the bounded failure-path guidance that remains relevant when a genuine Cloudflare login times out.

Investigation

• crates/openshell-cli/src/auth.rs defines the 120-second callback timeout and returns only the retry guidance.
• crates/openshell-cli/src/run.rs stores cloudflare_jwt for an unqualified HTTPS gateway and later dispatches gateway login back to browser_auth_flow, confirming the ineffective retry loop.
• The report includes a substantive diagnostic and sufficient reproduction details. No deeper architectural investigation is required to make the error actionable.
• One proposed detail should be corrected during implementation: --local does not mean unauthenticated HTTPS. It selects local mTLS and requires provisioned certificates. The message also should not claim that every timeout proves Cloudflare Access is absent, because a configured Cloudflare callback can fail or time out too.

Recommendation

Keep this issue open as the CLI timeout/error-path bug. Provide condition-aware guidance that identifies the attempted Cloudflare flow, points OIDC users toward the appropriate registration path, mentions --local only for provisioned local mTLS gateways, and preserves a useful retry path for genuine transient Cloudflare failures. Add focused tests around the formatted timeout guidance. This issue is triaged but is not being marked state:agent-ready; that remains a human decision.