fix(opensky): load OAuth credential files and retire Basic auth (#1229)

Read OpenSky OAuth credentials from OPENSKY_CREDENTIALS_FILE and stop sending retired Basic authentication. Update setup diagnostics and guidance.

Keep credential-file warnings free of parser excerpts and filesystem error details, cover both failure paths with a regression test, and use a launcher-compatible absolute path example.

Original contribution by quanticsoul4772, with credential-warning and documentation follow-up by Sameh Khamis.

Co-authored-by: quanticsoul4772 <[email protected]>
Co-authored-by: Sameh Khamis <[email protected]>

docs/opensky-auth.md

@@ -3,10 +3,11 @@
 God's Eye View uses explicit auth modes for `/api/flights`:
 
 - `OPENSKY_AUTH_MODE=oauth` (default, recommended)
-- `OPENSKY_AUTH_MODE=auto` (OAuth first, then Basic fallback)
-- `OPENSKY_AUTH_MODE=basic`
+- `OPENSKY_AUTH_MODE=auto` (OAuth when configured, otherwise anonymous)
 - `OPENSKY_AUTH_MODE=anon`
 
+`OPENSKY_AUTH_MODE=basic` is retired (see below).
+
 Reference: OpenSky REST API docs recommend OAuth2 Client Credentials flow.
 
 ## Quick Start (OAuth Client JSON)
@@ -41,13 +42,18 @@ Launchers resolve OAuth creds in this order:
 2. `OPENSKY_CREDENTIALS_FILE`
 3. Keychain (`opensky-network` / `client_id`, `client_secret`)
 
-## Basic Auth (Legacy)
+The server itself reads 1 and 2, so `npm run dev`, `npm run preview` and
+Pinokio also work with only `OPENSKY_CREDENTIALS_FILE` set in `.env`, on any
+platform. It reads the file on each token refresh.
 
-Basic auth is still supported for now, but OpenSky is moving away from it.
+## Basic Auth (Retired)
 
-```bash
-OPENSKY_AUTH_MODE=basic ./scripts/dev-fresh.sh
-```
+OpenSky stopped accepting username/password (HTTP Basic) sign-in on
+2026-03-18; its API now takes only OAuth2 client credentials. With
+`OPENSKY_AUTH_MODE=basic` the server no longer sends `OPENSKY_USERNAME` /
+`OPENSKY_PASSWORD`: it requests anonymously (reason `basic_retired`) and
+logs once what to set instead. Create an API client on your OpenSky
+account page and use its `credentials.json` as above.
 
 ## Troubleshooting
 
@@ -61,6 +67,6 @@ Useful reasons:
 
 - `oauth_invalid_or_missing`: OAuth client not found/usable
 - `oauth_invalid_credentials`: OAuth client rejected by OpenSky
-- `basic_invalid_credentials`: username/password rejected
-- `missing_basic_creds`: basic mode missing user/pass
+- `missing_oauth_creds`: auto mode found no OAuth client
+- `basic_retired`: basic mode requested; answered anonymously
 - `rate_limited`: OpenSky throttling