Syk/refactor auth checker functions

[itsoyou]

SYN-116

---

Note

Medium Risk
Touches all password-auth token login paths (JWT/OIDC/OAuth/EPA); changes are structural but errors in claim reconciliation or JWT verification could block or mis-associate logins.

Overview
Refactors the Synapse token authenticator so JWT, OIDC, OAuth, and EPA login paths share the same building blocks instead of duplicating login-type checks, token extraction, and JWT parsing.

Shared helpers in TokenAuthenticator include _acquire_token_data, _veryfiy_jwt (centralized ValueError / JWException / TypeError handling), and _localpart_from_username / _fq_uid_from_username for OAuth username reconciliation.

Claim handling moves into utils: get_claim_from_validation, get_reconciled_claim, and get_reconcile_claim_paths replace inline if_not_none / get_path_in_dict loops in OAuth (and EPA for localpart/displayname). Docstrings are added for several existing utils.

Tests add broad coverage for the new reconciliation helpers in test_sta_utils.py. OIDC drops a redundant user_id_str reassignment before success return; behavior should match the earlier flow where user_id_str was already derived from username.

^{Reviewed by Cursor Bugbot for commit a7e9a4c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 84.00000% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.13%. Comparing base (47a36a5) to head (a7e9a4c).

Files with missing lines	Patch %	Lines
synapse_token_authenticator/token_authenticator.py	81.25%	7 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #97      +/-   ##
==========================================
- Coverage   76.35%   76.13%   -0.23%     
==========================================
  Files           9        9              
  Lines         791      796       +5     
  Branches      146      156      +10     
==========================================
+ Hits          604      606       +2     
+ Misses        131      130       -1     
- Partials       56       60       +4     

Files with missing lines	Coverage Δ
synapse_token_authenticator/utils.py	100.00% <100.00%> (ø)
synapse_token_authenticator/token_authenticator.py	70.57% <81.25%> (-1.28%)	⬇️

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 47a36a5...a7e9a4c. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.