chore: refactor token authenticator

[itsoyou]

SYN-77
SYN-95

[cursor]

PR Summary

High Risk
Touches authentication config parsing and all JWT/OIDC/OAuth/ePA login paths in a large structural rewrite, so regressions could break logins or reject previously accepted configs.

Overview
Reworks the token authenticator around Pydantic v2 config models and clearer module boundaries, without intending to change login behavior.

Config now uses typed Pydantic models (JWT/OIDC/OAuth/ePA) with validators for secrets, JWKs, algorithms, and auth backends. HTTP auth helpers move into http_auth.py and no longer mutate input when parsing.

TokenAuthenticator is split up: web resources move to dedicated modules, and OAuth login is broken into JWT validation, introspection, and finish-login helpers. OpenID provider metadata parsing also moves onto a Pydantic model.

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

[codecov]

Codecov Report

❌ Patch coverage is 69.35065% with 118 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.90%. Comparing base (749505a) to head (627183c).

Files with missing lines	Patch %	Lines
synapse_token_authenticator/config.py	73.79%	22 Missing and 16 partials ⚠️
synapse_token_authenticator/http_auth.py	35.59%	38 Missing ⚠️
synapse_token_authenticator/token_authenticator.py	76.81%	21 Missing and 11 partials ⚠️
synapse_token_authenticator/metadata.py	55.55%	4 Missing ⚠️
synapse_token_authenticator/login_metadata.py	78.57%	3 Missing ⚠️
synapse_token_authenticator/public_key.py	66.66%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #93      +/-   ##
==========================================
+ Coverage   72.05%   73.90%   +1.85%     
==========================================
  Files           5        9       +4     
  Lines         773      801      +28     
  Branches      144      143       -1     
==========================================
+ Hits          557      592      +35     
+ Misses        157      150       -7     
  Partials       59       59              

Files with missing lines	Coverage Δ
synapse_token_authenticator/__init__.py	100.00% <100.00%> (ø)
synapse_token_authenticator/utils.py	100.00% <100.00%> (+8.92%)	⬆️
synapse_token_authenticator/login_metadata.py	78.57% <78.57%> (ø)
synapse_token_authenticator/public_key.py	66.66% <66.66%> (ø)
synapse_token_authenticator/metadata.py	55.55% <55.55%> (ø)
synapse_token_authenticator/token_authenticator.py	76.47% <76.81%> (+4.93%)	⬆️
synapse_token_authenticator/config.py	74.32% <73.79%> (+9.34%)	⬆️
synapse_token_authenticator/http_auth.py	35.59% <35.59%> (ø)

---

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 749505a...627183c. Read the comment docs.

🚀 New features to boost your workflow:

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

[nico-famedly]

I think the title should really be more specific. The branch name for example has a lot more info already.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Wrong allowed_client_ids type
  • Changed allowed_client_ids from str | None to list[str] | None so documented YAML lists validate and client_id membership checks work.
• ✅ Fixed: ePa path fields too narrow
  • Typed EPaConfig.localpart_path and displayname_path as Path | None so list-form paths validate like OAuth configs.

Or push these changes by commenting:

@cursor push b023de2517

Preview (b023de2517)

diff --git a/synapse_token_authenticator/config.py b/synapse_token_authenticator/config.py
--- a/synapse_token_authenticator/config.py
+++ b/synapse_token_authenticator/config.py
@@ -89,7 +89,7 @@
     client_secret: str
     project_id: str
     organization_id: str
-    allowed_client_ids: str | None = None
+    allowed_client_ids: list[str] | None = None
     allow_registration: bool = False
 
 
@@ -185,8 +185,8 @@
     jwk_set: JwkSetField = None
     jwk_file: str | None = None
     jwks_endpoint: str | None = None
-    localpart_path: str | None = None
-    displayname_path: str | None = None
+    localpart_path: Path | None = None
+    displayname_path: Path | None = None
     lowercase_localpart: bool = False
 
     @model_validator(mode="after")

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 627183c. Configure here.}

[cursor]

Wrong allowed_client_ids type

High Severity

Issue: allowed_client_ids is typed as str | None, so Pydantic rejects the documented list form and breaks OIDC config load. Membership checks and the README both treat it as a client-id list.
Fix: Type it as list[str] | None.

allowed_client_ids: list[str] | None = None

 

^{Reviewed by Cursor Bugbot for commit 627183c. Configure here.}

[cursor]

ePa path fields too narrow

Medium Severity

Issue: EPaConfig.localpart_path and displayname_path are typed as str | None, but docs and get_path_in_dict support Path (str | list[str]). List-form paths that used to load now fail Pydantic validation.
Fix: Use Path | None, same as the OAuth validation configs.

localpart_path: Path | None = None
displayname_path: Path | None = None

 

^{Reviewed by Cursor Bugbot for commit 627183c. Configure here.}