fix(auth): allow custom environments via BW_API_URL; harden token parsing

[kshahbw]

Summary

Three related auth-path hardenings, all grounded in the intent of the env-validation work in ddb2632 / 11a4f95 (kill silent fall-through to production, and turn cryptic failures into actionable ones):

1. resolveEnvironment — restore the explicit-route escape hatch. After that change, any environment outside prod/test/uat was rejected outright — including environments intentionally routed through an explicit BW_API_URL override, which regressed that workflow. This permits a non-built-in environment only when BW_API_URL is set. An explicit route is the opposite of a silent fall-through, so the original guarantee holds: an unrecognized value with no override still fails loudly and never silently resolves to prod.

2. oauth.go — legible error for a non-JSON token response. A 2xx whose body isn't a JSON object (an HTML proxy interstitial, or a misrouted host returning XML) previously died with a cryptic invalid character '<' looking for beginning of value parse error. It now returns "token endpoint returned a non-JSON response — you may be behind a proxy or pointed at the wrong host; check your environment and BW_API_URL."

3. ValidateAPIOverride — reject a schemeless BW_API_URL up front. A BW_API_URL missing its scheme (e.g. stage.api.bandwidth.com instead of https://stage.api.bandwidth.com) reached net/http as the opaque unsupported protocol scheme "". It's now caught at both auth entry points (authenticate() and auth login) with a message that names the fix. Unset stays valid.

Also included (flag for review)

messagingProdOnlyWarning now fires for any non-prod environment, not just test/uat. Slightly beyond the fixes above, but it's the minimum needed to keep #1 from regressing a safety property: a custom-routed environment still hits the production-only messaging host, so without this a custom-env user would send real, billable messages with no warning — exactly the hazard the original hardening closed. Happy to drop it if you'd rather handle separately.

Why this came up

Two users hit auth failures that all trace back to the BW_API_URL override path:

• parsing token response: invalid character '<' — an older binary whose authenticate() predates resolveEnvironment silently fell through to the prod identity host and got a non-JSON gateway body (→ Snyk Vulnerability Dashboard #2 makes this legible; the newer validation prevents the silent prod routing).
• unsupported protocol scheme "" — a BW_API_URL set without https:// (→ Fix GoReleaser homebrew publish to use PR flow #3).
• On a current build the escape-hatch regression also meant a legitimately-routed custom environment was rejected (→ Hello, world: initial code drop for the Bandwidth CLI #1).

Testing

• resolveEnvironment: unit tests for fail-loud (no override) and opt-in (with BW_API_URL); verified in a real binary — unknown env fails loudly without an override, routes the token request to the custom host with one.
• ValidateAPIOverride: unit tests for unset/valid/schemeless; verified in a real binary that a schemeless value yields the actionable message and a scheme'd value routes to the host.
• messagingProdOnlyWarning: unit test asserts any non-prod env warns.
• oauth.go: unit test asserts a 2xx HTML body yields the friendly error, not a parse error.
• go build ./..., full go test ./..., gofmt, and go vet all clean.

🤖 Generated with Claude Code

[bwappsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.