fix(oauth): handle missing expires_in in OAuth token response (supersedes #3992)

[jonpspri]

🔗 Related Issue

Closes #3989
Supersedes #3992 (couldn't push amendments to the contributor's fork)

---

📝 Summary

Picks up @ecthelion77's original fix in #3992 for the `TypeError` raised when an OAuth provider omits `expires_in` from its token response (RFC 6749 §5.1 marks it RECOMMENDED, not REQUIRED — e.g. GitHub OAuth Apps), then layers in review-driven hardening:

• Original fix (commit 1, by @ecthelion77): when `expires_in` is absent, store `expires_at` as `NULL` instead of crashing.
• Hardening (commit 2):
  • New `parse_expires_in()` validator that rejects negative, malformed, or non-scalar values with a clean `OAuthError` instead of letting `ValueError` bubble.
  • Refresh path uses the same parser, so initial-auth and refresh agree on what "missing `expires_in`" means (was hardcoded to `3600` fallback, creating path-dependent semantics).
  • `cleanup_expired_tokens` now ages out `NULL`-expiry rows so they don't accumulate forever (covers the SQL three-valued logic gotcha — `NULL < cutoff` evaluates to `NULL`).
  • `_is_token_expired` docstring documents the `NULL` contract and cross-references the cleanup policy.
  • Removed now-dead `OAUTH_DEFAULT_TIMEOUT` from `config.py`, `.env.example`, helm chart (`values.yaml`/`values.schema.json`/`README.md`), 4 docs files, and 3 test mocks.
  • Lazy `%`-style logging on new lines; dropped redundant `int()` cast.
• Second-pass review fixes (commit 3):
  • Refresh path now preserves prior TTL (`expires_at - updated_at`) when the refresh response omits `expires_in`, instead of clearing `expires_at` to `NULL` and silently stopping all future proactive refreshes. Falls back to `NULL` only when there was no prior TTL to preserve (genuine no-expiry providers).
  • `cleanup_expired_tokens` ages `NULL`-expiry rows by `updated_at` (advances on re-auth), not `created_at` (which would delete recently re-authorized tokens).
  • `parse_expires_in` rejects non-integer floats per RFC, and sign-checks the original numeric before `int()` truncation (so `-0.5` correctly raises "negative" instead of silently becoming `0`).

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)

---

🧪 Verification

Check	Command	Status
OAuth scope unit tests	`pytest tests/unit/mcpgateway/services/test_token_storage_service.py tests/unit/mcpgateway/services/test_oauth_manager.py tests/unit/mcpgateway/services/test_oauth_manager_pkce.py tests/unit/mcpgateway/test_oauth_manager.py`	✅ 390 passed
Plugin scope unit tests	`pytest tests/integration/test_encoded_exfil.py tests/integration/test_rate_limiter.py tests/unit/mcpgateway/plugins/...`	✅ 292 passed, 63 skipped (integration), 2 xfail
Doctests	`pytest --doctest-modules mcpgateway/services/oauth_manager.py mcpgateway/services/token_storage_service.py`	✅ 12 passed
black / isort	`make black isort`	✅ clean
ruff	`uv tool run ruff check` on touched files	✅ no new findings (4 pre-existing F841 in untouched test code)
bandit	`uv tool run bandit -ll` on touched files	✅ no new findings
pylint	`uv tool run pylint` on touched files	✅ score 7.04 → 9.72

---

✅ Checklist

• Code formatted (`make black isort pre-commit`)
• Tests added/updated for changes (~17 new unit + integration tests, including parametrized edge cases for `parse_expires_in` and the new TTL-preservation refresh path)
• Documentation updated (4 docs files updated to remove dead `OAUTH_DEFAULT_TIMEOUT` references; `_is_token_expired` and `cleanup_expired_tokens` docstrings expanded with the new `NULL`-expiry contract)
• No secrets or credentials committed

---

📓 Notes

Original author credit: The first commit is signed by @ecthelion77 from #3992 — please give them the merge attribution. The branch is rebased onto current `main`; the second and third commits are the review-driven refinements described above.

Why a new PR? PR #3992 came from a fork I lack push access to (`maintainerCanModify` is set on the PR, but cross-repo push requires either SSH collaborator access on the fork or HTTPS-token auth that the upstream maintainer permission alone doesn't grant). Rather than ask @ecthelion77 to apply the changes manually, I'm opening this PR with the rebased + amended history. Once this is reviewed/merged, #3992 should be closed in favor of it.

Behavior changes worth highlighting in the changelog (none are silent breaking changes for callers, but operators should know):

• `OAUTH_DEFAULT_TIMEOUT` config knob removed (was dead after the fix).
• Tokens with no provider-supplied `expires_in` are now stored with `expires_at = NULL` (treated as never-expires locally) and aged out of `oauth_tokens` after `max_age_days` from `updated_at`.
• Refresh responses missing `expires_in` now preserve the prior TTL instead of either crashing (pre-fix) or clearing the expiry to `NULL` (intermediate state never released).