fix(config): keep reading the 2.x token, allowed-hosts and proxy names in 3.1 (FX-35)

[tunjayoff]

FX-35, release-blocking for 3.1.0. Owner decision of 2026-10-09: the 2.x names that 3.0.0 documented for protecting the server are still read in 3.1, with a deprecation warning, and removed in 3.2. The orchestrator added the proxy names under the same rule because they are a privacy matter.

Problem

P30 (#186) stopped reading every 2.x environment name, and a name that is still set only produces a legacy_name warning. But 3.0.0's README and docs/deploy told users to protect the server with SOFASCORE_API_TOKEN and SOFASCORE_ALLOWED_HOSTS. Upgrading to 3.1 without renaming them would have:

• dropped the access token without saying so: the API answers without a token, which is dangerous behind a reverse proxy;
• dropped the host allow-list;
• for USE_PROXY / PROXY_URL, sent SofaScore requests from the user's real address instead of the configured proxy.

The Docker entry point made the allow-list case worse. It no longer counted SOFASCORE_ALLOWED_HOSTS as "given", so it exported SOFASCORE_SERVER__ALLOWED_HOSTS=localhost,…, which would have overridden the old list even after the loader read it again.

Change

Loader (sofascore_scraper/config/loader.py): a small explicit table DEPRECATED_NAMES with four names that are deprecated but still read:

old name	setting	new name
SOFASCORE_API_TOKEN	server.token	SOFASCORE_SERVER__TOKEN (env only)
SOFASCORE_ALLOWED_HOSTS	server.allowed_hosts	SOFASCORE_SERVER__ALLOWED_HOSTS / server.allowed_hosts
USE_PROXY	client.use_proxy	SOFASCORE_CLIENT__USE_PROXY / client.use_proxy
PROXY_URL	client.proxy	SOFASCORE_CLIENT__PROXY / client.proxy

Rules:

• An old name is parsed exactly like its new environment variable: the same coerce, and a secret is stripped. It sits in the environment layer, so it wins over sofascore.toml and overrides.json, as the legacy environment layer did in 3.0. One difference from 3.0: there an old name that came only from .env ranked below the file. 3.1 loads .env into the environment, so the old name now ranks like any .env line, the same as the new names. Its Source carries deprecated=True, and its layer is env, so the Settings page row is locked.
• The new name wins when both are set, and the old one is reported as ignored. "Set" here means the new environment variable or a flag. For the token and the proxy URL it also means a token_env / proxy_env that names a variable. When token_env / proxy_env names the old variable itself (what ssc config init --from-legacy writes), the variable is read through that setting and gives no warning, as before.
• PROXY_URL on its own does not turn the proxy on, as in 3.0 and 2.x: it needs USE_PROXY=true (decision D19's auto-enable applies to new names only).
• An invalid old value is a ConfigError that names the old variable, for example USE_PROXY: expected true or false…. This differs from 3.0, where USE_PROXY=maybe silently meant false; values like 1/yes now mean true, as for the new name.
• USE_PROXY and PROXY_URL are added to the watched environment names, so a change is seen without a reload. The two SOFASCORE_* names were already covered by the prefix.
• All other 2.x names are still not read. The P30 tests that assert this are kept; the only cases that changed are the ones about these four names.

Warning text (code legacy_name, the same in the log, config show / config validate warnings and diagnostics):

• read: SOFASCORE_API_TOKEN (set in the environment) is deprecated; still read in 3.1, removed in 3.2; use SOFASCORE_SERVER__TOKEN.
• both set: SOFASCORE_API_TOKEN (set in .env) is ignored because SOFASCORE_SERVER__TOKEN is also set; SOFASCORE_API_TOKEN is deprecated and removed in 3.2: remove it.
• The other names keep … is no longer read since 3.1; use ….

Where the old name shows up:

• ssc doctor: new strings doctor_env_deprecated_name and doctor_env_deprecated_ignored (en and tr). They show where the name is set (.env or the environment) using the FX-33 origin rule, and the fix line works as before.
• ssc config show: each row has a new replaced_by field (null unless the value came from a deprecated name). The text output reads server.token = "***" [env: SOFASCORE_API_TOKEN, deprecated, use SOFASCORE_SERVER__TOKEN].
• Diagnostics: the same source text, plus a new settings.warnings list holding the loader's warnings, which contain names only.
• API / Settings page: Setting gains an optional replaced_by. This is an additive API change: docs/api/openapi-v1.json and frontend/src/api/v1/schema.ts were regenerated. The locked row says "Set by the old environment variable SOFASCORE_API_TOKEN. It is deprecated: still read in 3.1, removed in 3.2. Rename it to SOFASCORE_SERVER__TOKEN." (en and tr).
• security.token_variable(): names SOFASCORE_API_TOKEN when the token came from it, so the short-token start-up warning names the right variable.

Secret handling. A token from the old name gets the same treatment as one from SOFASCORE_SERVER__TOKEN:

• It is env-only and locked: PATCH refuses server.token, and writing another key does not carry the token into overrides.json.
• It is masked in config show, the Settings API, diagnostics and logs. redact already knew both old names.
• PROXY_URL shows only the masked user info, and its row is locked.
• The OpenAPI generator also drops SOFASCORE_API_TOKEN from its isolated environment.

serve --host 0.0.0.0 starts with the old allow-list name, as in 3.0. The list comes from the settings, allowed_hosts_from = "settings", and nothing is written to the environment.

Docker entry point: counts SOFASCORE_ALLOWED_HOSTS again, from the environment or from .env, as 3.0 did. A test case covers each source.

Docs: docs/deploy/README.md (access token and host allow-list sections), .env.example, the docker-compose.yml comment, and the entry point and module docstrings now say the four names still work in 3.1 with a warning and are removed in 3.2. README.md / README.tr.md on main have no "Upgrading from 3.0" section (it comes with #195), so suggested wording is below. Not touched: CHANGELOG.md, research/**, docs/design/**.

Tests

tests/test_fx35_deprecated_names.py, for each of the four names:

• old name only: the value is used, the source is env, deprecated and locked, and the warning names where it is set (environment or .env);
• new name only: no warning;
• both: the new name wins and the old one is reported as ignored.

Plus:

• Precedence: above the file and below a flag; token_env / proxy_env win; the variable named by --from-legacy is silent.
• Proxy: PROXY_URL alone does not turn the proxy on; USE_PROXY=false turns off a new-name proxy.
• Parsing: an invalid old value is an error, and a blank one is silent.
• Other 2.x names are still not read.
• Token: a token from the old name enforces auth on /api/v1, with and without a root path (/sofa); the new name wins when both are set.
• Secrets: the token is masked, locked and never written to overrides.json; the proxy password is masked and its row locked.
• serve: --host 0.0.0.0 starts with SOFASCORE_ALLOWED_HOSTS, and exposed_without_token goes away with SOFASCORE_API_TOKEN.
• CLI output: config show / config validate give the JSON and text described above.
• doctor: each name in .env and in the environment, the both-set case, and Turkish.
• Diagnostics: values masked, source text, warnings.

Adjusted existing tests:

• the P30 cases that used SOFASCORE_API_TOKEN / PROXY_URL as "not read" now use SOFA_CAPTCHA_TOKEN, which is still not read;
• the ConfigManager getter test expects USE_PROXY / PROXY_URL to be read and the new name to win;
• the row shapes gain replaced_by;
• two entry-point cases were added;
• one frontend test covers the deprecated lock text.

Local runs:

• full suite with STORE_SHADOW_CHECK=1: 9779 passed, 39 skipped, 22 deselected
• ruff check .: clean
• frontend: npm ci, npm run build, npm run lint and npm test (368 passed)

Changelog entry

For the release PR #195. Add under a new ### Deprecated heading in ## [3.1.0]:

### Deprecated

- **`SOFASCORE_API_TOKEN`, `SOFASCORE_ALLOWED_HOSTS`, `USE_PROXY` and `PROXY_URL` are still read
  in 3.1 and removed in 3.2.** 3.0.0 documented the first two for protecting the server, and
  dropping them would leave it without its access token or host allow-list, or send SofaScore
  requests from your own address instead of the proxy. Each one still set is read as its new name
  and logged, with `ssc config show` and `ssc doctor`, as deprecated: rename it to
  `SOFASCORE_SERVER__TOKEN`, `SOFASCORE_SERVER__ALLOWED_HOSTS`, `SOFASCORE_CLIENT__USE_PROXY` or
  `SOFASCORE_CLIENT__PROXY`. When both names are set the new one wins and the old one is reported
  as ignored. `PROXY_URL` alone still does not switch the proxy on (it needs `USE_PROXY=true`, as
  before), and the Settings page shows such a value as locked by the old name (FX-35).

and replace the first bullet of "Upgrading from 3.0" in the same section with:

- **The 2.x environment names are no longer read**, except four deprecated ones (see Deprecated).
  A value set as `DATA_DIR`, `REQUEST_RATE_LIMIT`, `APP_LANGUAGE`, `LOG_LEVEL`, … (in `.env`, the
  shell, a service file or the container settings) is ignored, and the default applies: an old
  `DATA_DIR` leaves the app on the default data folder. `SOFASCORE_API_TOKEN`,
  `SOFASCORE_ALLOWED_HOSTS`, `USE_PROXY` and `PROXY_URL` still work in 3.1 with a warning and are
  removed in 3.2. Rename each to `SOFASCORE_<SECTION>__<KEY>` (`SOFASCORE_STORAGE__DATA_DIR`,
  `SOFASCORE_CLIENT__RATE`, `SOFASCORE_SERVER__TOKEN`, …). `ssc doctor` and `ssc config show` list
  every old name still set, with its new name and where it is set; `ssc config init --from-legacy >
  sofascore.toml` writes the old `.env` and `config/leagues.txt` as a config file.

If the "Removed" section lists "the 2.x environment names", make it "the 2.x environment names (except the four under Deprecated)".

README wording (for #195, "Upgrading from 3.0")

README.md, replacing the bullet "Rename the 2.x environment names.":

- **Rename the 2.x environment names.** 3.1.0 no longer reads `DATA_DIR`, `REQUEST_RATE_LIMIT`, `APP_LANGUAGE`, `LOG_LEVEL` and the other 2.x names, wherever they are set (`.env`, the shell, a service file, the container settings): the default applies instead, so an old `DATA_DIR` leaves the app on the default data folder. Four of them are deprecated instead: `SOFASCORE_API_TOKEN`, `SOFASCORE_ALLOWED_HOSTS`, `USE_PROXY` and `PROXY_URL` still work in 3.1, with a warning, and are removed in 3.2; when the new name is set too, the new one wins. Use `SOFASCORE_<SECTION>__<KEY>` (`SOFASCORE_STORAGE__DATA_DIR`, `SOFASCORE_SERVER__TOKEN`, `SOFASCORE_SERVER__ALLOWED_HOSTS`, `SOFASCORE_CLIENT__PROXY`, …). `ssc doctor` and `ssc config show` list each old name still set with its new name and where it is set; `ssc config init --from-legacy > sofascore.toml` writes the old settings as a config file.

README.tr.md, replacing "2.x ortam adlarını yeniden adlandırın.":

- **2.x ortam adlarını yeniden adlandırın.** 3.1.0 `DATA_DIR`, `REQUEST_RATE_LIMIT`, `APP_LANGUAGE`, `LOG_LEVEL` ve öteki 2.x adlarını, nerede verilmiş olurlarsa olsunlar (`.env`, kabuk, bir servis dosyası, konteyner ayarları), artık okumaz; yerlerine varsayılan geçerlidir: eski bir `DATA_DIR` uygulamayı varsayılan veri klasöründe bırakır. Dördü ise kullanımdan kalktı: `SOFASCORE_API_TOKEN`, `SOFASCORE_ALLOWED_HOSTS`, `USE_PROXY` ve `PROXY_URL` 3.1'de bir uyarıyla hâlâ çalışır, 3.2'de kaldırılır; yeni adı da verilmişse yenisi geçerlidir. `SOFASCORE_<BÖLÜM>__<ANAHTAR>` adlarını kullanın (`SOFASCORE_STORAGE__DATA_DIR`, `SOFASCORE_SERVER__TOKEN`, `SOFASCORE_SERVER__ALLOWED_HOSTS`, `SOFASCORE_CLIENT__PROXY`, …). `ssc doctor` ve `ssc config show` hâlâ verilmiş her eski adı yeni adıyla ve nerede verildiğiyle listeler; `ssc config init --from-legacy > sofascore.toml` eski ayarları bir yapılandırma dosyası olarak yazar.

The "Configuration" bullet ("The variable names of 2.x … are not read since 3.1.0") could add: "; four of them (SOFASCORE_API_TOKEN, SOFASCORE_ALLOWED_HOSTS, USE_PROXY, PROXY_URL) are deprecated and still read until 3.2". In Turkish: "; dördü (SOFASCORE_API_TOKEN, SOFASCORE_ALLOWED_HOSTS, USE_PROXY, PROXY_URL) kullanımdan kalktı ve 3.2'ye kadar okunur".

Other 2.x names: reported, not changed

• API_BASE_URL (client.base_url): this is the only other one whose loss touches privacy. A 2.x/3.0 user who pointed it at their own relay or mirror would, after 3.1, send requests straight to www.sofascore.com from their own address. 3.0's docs did not present it as a protection, and doctor flags a non-SofaScore base URL anyway.
• SOFASCORE_THROTTLE_DIR, REQUEST_RATE_LIMIT, MAX_CONCURRENT: losing them can raise the request rate (several processes no longer share one budget, or the default rate applies). That is a block risk, not a security or privacy one.
• None of the rest switches on protection, masking or a proxy: IGNORE_RATE_LIMIT going away is safer, and LOG_DIR, SOFASCORE_BROWSER_PROFILE and DATA_DIR change locations only.