feat(cli): make OIDC the default auth for HTTPS endpoints, add --edge-auth for Cloudflare

[akram]

Problem Statement

When registering a gateway with openshell gateway add https://<endpoint>, the CLI defaults to the Cloudflare Access edge-auth flow. This flow only works when Cloudflare Access is deployed in front of the gateway — on any other Kubernetes deployment (OpenShift, GKE, EKS, k3d), it hangs for 120 seconds and times out with no guidance.

OIDC is the recommended auth path for production Kubernetes deployments, but users must already know about the --oidc-issuer flag to use it. The current default penalizes the majority of users (direct K8s deployments) in favor of the minority (Cloudflare Access deployments).

This was discussed in the #openshell Slack thread with @taylor Mutch, who noted: "I would honestly be okay with defaulting to the OIDC path as the default."

Proposed Design

Invert the default auth behavior for gateway add with HTTPS endpoints:

Current behavior:

• gateway add https://... → Cloudflare edge-auth (browser opens /auth/connect, waits for CF_Authorization cookie)
• gateway add https://... --oidc-issuer <url> → OIDC browser flow

Proposed behavior:

• gateway add https://... → prompt the user to provide --oidc-issuer or --edge-auth or --local
• gateway add https://... --oidc-issuer <url> → OIDC browser flow (unchanged)
• gateway add https://... --edge-auth → Cloudflare edge-auth flow (opt-in)
• gateway add https://... --local → skip auth entirely (unchanged)

When neither --oidc-issuer nor --edge-auth nor --local is provided, the CLI should display a clear message:

Gateway registered. Choose an authentication method:

  OIDC (recommended for Kubernetes deployments):
    openshell gateway login --oidc-issuer <issuer-url>

  Cloudflare Access (edge-authenticated deployments):
    openshell gateway login --edge-auth

  No authentication (local development only):
    openshell gateway add <endpoint> --local

Changes required

• crates/openshell-cli/src/main.rs — add --edge-auth flag to gateway add and gateway login
• crates/openshell-cli/src/run.rs:940-960 — change the default for HTTPS from edge-auth to prompting
• crates/openshell-cli/src/auth.rs — gate browser_auth_flow() behind the --edge-auth flag

Alternatives Considered

1. Auto-detect from gateway metadata (feat(cli): auto-detect OIDC configuration during gateway add #2098): Query the gateway's Health endpoint to detect OIDC configuration. More seamless but adds complexity and a new API contract. Can be done as a follow-up.

2. Keep CF as default, improve error message (fix(cli): improve error message when edge-auth flow times out on non-Cloudflare deployments #2099): Less disruptive but doesn't solve the UX problem — users still hit a 120-second hang before seeing guidance.

3. Default to OIDC with auto-discovery: Assume OIDC and try to discover the issuer from /.well-known/openid-configuration. Too fragile — the gateway doesn't expose OIDC config on an HTTP endpoint.

Agent Investigation

• Explored crates/openshell-cli/src/run.rs:940-960 — confirmed gateway_add() enters the edge-auth path for any https:// endpoint without --oidc-issuer or --local.
• Explored crates/openshell-cli/src/main.rs:1060-1080 — the GatewayAdd and GatewayLogin command structs. Adding --edge-auth is straightforward alongside existing --oidc-issuer and --local flags.
• Verified on ROSA HCP 4.21: the OIDC flow via --oidc-issuer works correctly. The issue is purely the default behavior.

---

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request