eager-auth 2.2.0__tar.gz → 2.2.2__tar.gz

{eager_auth-2.2.0 → eager_auth-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: eager-auth
-Version: 2.2.0
+Version: 2.2.2
 Summary: Standard OIDC relying party for Eager FastAPI services — verification core
 Project-URL: Homepage, https://github.com/Whats-Next-CC/eager-auth
 Project-URL: Source, https://github.com/Whats-Next-CC/eager-auth
@@ -20,7 +20,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27
 Requires-Dist: joserfc>=1.0
-Requires-Dist: pyjwt[crypto]>=2.9
+Requires-Dist: pyjwt[crypto]>=2.15.0
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == 'dev'
 Requires-Dist: fastapi>=0.110; extra == 'dev'

{eager_auth-2.2.0 → eager_auth-2.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eager-auth"
-version = "2.2.0"
+version = "2.2.2"
 description = "Standard OIDC relying party for Eager FastAPI services — verification core"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,7 +20,9 @@ classifiers = [
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 dependencies = [
-    "pyjwt[crypto]>=2.9",
+    # 2.15.0 is the first release with no open advisory: of the thirteen published on
+    # 2026-09-29/30, 2.14.0 fixed twelve and GHSA-42vr-xj54-vc7v still affects 2.14.0.
+    "pyjwt[crypto]>=2.15.0",
     "httpx>=0.27",
     "joserfc>=1.0",
 ]

{eager_auth-2.2.0 → eager_auth-2.2.2}/src/eager_auth/fastapi.py

@@ -19,11 +19,13 @@ pulling a web framework in.
 from __future__ import annotations
 
 from collections.abc import Callable
+from html import escape
 from urllib.parse import quote, urlsplit
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
-from fastapi.responses import JSONResponse, RedirectResponse
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse
 
+from eager_auth.config import AuthConfig
 from eager_auth.context import AuthContext
 from eager_auth.errors import AuthError, DiscoveryError
 from eager_auth.flow import complete_login, logout_url, start_login
@@ -58,6 +60,67 @@ def _clear(response: Response, attrs: CookieAttributes) -> None:
     response.delete_cookie(attrs.name, path=attrs.path)
 
 
+#: What a GET on the logout route answers: one form posting back, and no script, so nothing on
+#: the page can submit it for the person. CONTRACT.md section 10.
+_LOGOUT_PAGE = (
+    '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+    '<meta name="viewport" content="width=device-width, initial-scale=1">'
+    "<title>Sign out</title></head><body>"
+    '<form method="post" action="{action}"><p>Sign out?</p>'
+    '<button type="submit">Sign out</button></form></body></html>'
+)
+
+#: Not cached, and never framed: a framing site could otherwise place the button under a click.
+_LOGOUT_PAGE_HEADERS = {
+    "Cache-Control": "no-store",
+    "X-Frame-Options": "DENY",
+    # No form-action: Chromium applies it to the redirect after the POST, which would block the
+    # hand-off to the broker.
+    "Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'",
+}
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+# What a path may carry unencoded (RFC 3986 pchar minus "%"); everything else is re-encoded.
+_PATH_SAFE = "/:@!$&'()*+,;=-._~"
+
+
+def _origin_of(url: str) -> str | None:
+    """`scheme://host[:port]`, lower-cased with the default port dropped, or None."""
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError:
+        return None
+    if parts.scheme not in _DEFAULT_PORTS or not parts.hostname:
+        return None
+    try:
+        # Browsers serialise an internationalised host as punycode in Origin.
+        host = parts.hostname.encode("idna").decode("ascii")
+    except UnicodeError:
+        return None
+    if port is None or port == _DEFAULT_PORTS[parts.scheme]:
+        return f"{parts.scheme}://{host}"
+    return f"{parts.scheme}://{host}:{port}"
+
+
+def came_from_this_site(request: Request, config: AuthConfig) -> bool:
+    """Whether the browser says this request was made by a page of this service.
+
+    The site is the origin of `redirect_uri`, never the request host, which behind a load
+    balancer is the internal one. `Origin` decides when it is a real origin; when it is absent
+    or opaque (`null`) only `Sec-Fetch-Site: same-origin` will do. A request carrying neither
+    is refused, since every current browser sends one of them on a form POST.
+    """
+    origin = request.headers.get("origin")
+    # "null" is sent on every POST from a page with Referrer-Policy: no-referrer, same-origin
+    # included, so an opaque Origin says nothing and fetch metadata decides instead.
+    if origin is not None and origin != "null":
+        site = _origin_of(config.redirect_uri) if config.redirect_uri else None
+        return site is not None and _origin_of(origin) == site
+    return request.headers.get("sec-fetch-site") == "same-origin"
+
+
 def _read_principal(request: Request, ctx: AuthContext) -> Principal | None:
     """Return the principal this request carries, or None.
 
@@ -155,8 +218,13 @@ def _destination(request: Request) -> str | None:
         query = f"?{parts.query}" if parts.query else ""
         return safe_next(f"{parts.path}{query}")
 
+    # `request.url.path` is decoded, so "/a%20b" would reach safe_next as "/a b" and be dropped,
+    # while the TypeScript gate sees the encoded path and keeps it: the same person would land
+    # on different pages. Encoding it again gives safe_next what the browser sent, the way the
+    # WHATWG URL in the TypeScript gate does. A "%" is re-encoded too, so nothing decodes twice.
+    path = quote(request.url.path, safe=_PATH_SAFE)
     query = f"?{request.url.query}" if request.url.query else ""
-    return safe_next(f"{request.url.path}{query}")
+    return safe_next(f"{path}{query}")
 
 
 def _login_path(request: Request, ctx: AuthContext) -> str:
@@ -200,10 +268,12 @@ def create_auth_router(ctx: AuthContext) -> APIRouter:
 
     @router.get("/callback")
     def callback(request: Request, code: str | None = None, state: str | None = None) -> Response:
-        """Finish a login. Any failure clears both cookies and starts over."""
+        """Finish a login. Any failure clears the pending cookie and starts over."""
         failure = RedirectResponse(f"{ctx.config.route_prefix}/login", status_code=307)
+        # Only the pending cookie is cleared. A failed callback is reachable by any top-level
+        # link, so clearing the session here would let any site sign anybody out (CONTRACT.md
+        # section 10).
         _clear(failure, pending_cookie(ctx.config))
-        _clear(failure, session_cookie(ctx.config))
 
         if not code or not state:
             return failure
@@ -250,9 +320,23 @@ def create_auth_router(ctx: AuthContext) -> APIRouter:
         _clear(response, pending_cookie(ctx.config))
         return response
 
-    @router.api_route("/logout", methods=["GET", "POST"])
+    @router.api_route("/logout", methods=["GET", "HEAD"])
+    def confirm_logout(request: Request) -> Response:
+        """Answer a page with one button, so a link works and a cross-site GET changes nothing."""
+        local = safe_next(request.query_params.get("next"))
+        action = f"{ctx.config.route_prefix}/logout"
+        if local:
+            action += f"?next={quote(local, safe='')}"
+        return HTMLResponse(
+            _LOGOUT_PAGE.format(action=escape(action, quote=True)),
+            headers=_LOGOUT_PAGE_HEADERS,
+        )
+
+    @router.post("/logout")
     def logout(request: Request) -> Response:
         """Clear our session, then hand off to the broker when it offers a logout."""
+        if not came_from_this_site(request, ctx.config):
+            return JSONResponse({"detail": "logout must come from this site"}, status_code=403)
         # `next` is honoured for a local logout. With a broker the landing page is whatever
         # post_logout_redirect_uri the broker has registered — it cannot be a relative path,
         # and it must not come from the request host (behind a load balancer that is internal).
@@ -264,7 +348,8 @@ def create_auth_router(ctx: AuthContext) -> APIRouter:
             request.cookies.get(ctx.config.logout_cookie_name), config=ctx.config
         )
         broker = logout_url(ctx.config, ctx.discovery, id_token_hint=hint)
-        response = RedirectResponse(broker or local, status_code=307)
+        # 303: the browser follows with GET, so the broker receives its query parameters.
+        response = RedirectResponse(broker or local, status_code=303)
         _clear(response, session_cookie(ctx.config))
         _clear(response, pending_cookie(ctx.config))
         _clear(response, logout_cookie(ctx.config))

{eager_auth-2.2.0 → eager_auth-2.2.2}/src/eager_auth/pending.py

@@ -14,7 +14,9 @@ from __future__ import annotations
 
 import datetime as dt
 import json
+import re
 from dataclasses import dataclass
+from urllib.parse import urljoin, urlsplit
 
 from joserfc import jwe
 from joserfc.errors import JoseError
@@ -28,16 +30,32 @@ from eager_auth.session import session_key
 _HEADER = {"alg": "dir", "enc": "A256GCM"}
 
 
+# "/" and then printable ASCII only (0x21-0x7E), never "//" and never a backslash anywhere.
+_PLAIN_PATH = re.compile(r"/(?![/\\])[\x21-\x7e]*")
+
+# Any origin will do for the second check: a value resolves to its base's origin against every
+# base, or against none. The configured one is not needed, so neither is a config parameter.
+_PROBE_ORIGIN = "https://origin.invalid"
+
+
 def safe_next(candidate: str | None) -> str | None:
-    """Accept only a same-site relative path.
+    """Accept only a path of this site.
 
     Anything absolute, scheme-relative or backslash-escaped is dropped rather than corrected.
-    Silently sending a freshly authenticated user to an attacker's host is the exact shape of
-    a post-login open redirect.
+    So is anything outside printable ASCII: a browser removes tabs and line breaks while it
+    parses a Location, so "/<TAB>/evil.example" would arrive as "//evil.example" and leave the
+    site. Percent-encoded bytes stay encoded in a Location and are kept. Silently sending a
+    freshly authenticated user to an attacker's host is the exact shape of a post-login open
+    redirect.
     """
-    if not candidate or not candidate.startswith("/"):
+    if not candidate or "\\" in candidate:
+        return None
+    if not _PLAIN_PATH.fullmatch(candidate):
         return None
-    if candidate.startswith("//") or candidate.startswith("/\\"):
+    # Belt and braces: the pattern above already rules out every way of leaving the origin
+    # known today. Resolving it the way a browser would catches the one not known yet.
+    resolved = urlsplit(urljoin(_PROBE_ORIGIN + "/", candidate))
+    if f"{resolved.scheme}://{resolved.netloc}" != _PROBE_ORIGIN:
         return None
     return candidate
 

{eager_auth-2.2.0 → eager_auth-2.2.2}/src/eager_auth/tokens.py

@@ -74,7 +74,9 @@ def _header_algorithm(token: str, config: AuthConfig) -> str:
     """Read `alg` from the header and refuse anything symmetric, before touching keys."""
     try:
         header = jwt.get_unverified_header(token)
-    except jwt.InvalidTokenError as exc:
+    # RecursionError: a deeply nested header is attacker input read before any signature
+    # check, and PyJWT has let json.loads raise it unwrapped (GHSA-8wjv-2p76-3863).
+    except (jwt.InvalidTokenError, RecursionError) as exc:
         raise MalformedTokenError(f"cannot read token header: {exc}") from exc
 
     algorithm = header.get("alg")

{eager_auth-2.2.0 → eager_auth-2.2.2}/tests/test_fastapi.py

@@ -28,11 +28,14 @@ from eager_auth import (
 )
 from eager_auth.fastapi import create_auth_router, current_principal, require_role
 from eager_auth.flow import PendingLogin
+from eager_auth.pending import unseal_pending
 
 VECTORS = json.loads(
     (Path(__file__).resolve().parents[3] / "conformance" / "flow-vectors.json").read_text()
 )
 KEY = VECTORS["session_interop"]["key_b64url"]
+#: What a browser sends on a form POST from a page of this service.
+SAME_ORIGIN = {"origin": VECTORS["logout_request"]["site"]}
 
 
 @pytest.fixture
@@ -103,6 +106,10 @@ def client(ctx) -> TestClient:
     def private(user: Principal = Depends(current_principal(ctx))):  # noqa: B008
         return {"sub": user.sub, "roles": list(user.roles)}
 
+    @app.get("/docs/{name}")
+    def doc(name: str, user: Principal = Depends(current_principal(ctx))):  # noqa: B008
+        return {"name": name}
+
     @app.get("/admin")
     def admin(user: Principal = Depends(require_role(ctx, "admin"))):  # noqa: B008
         return {"ok": True}
@@ -187,6 +194,16 @@ def test_a_broken_callback_starts_over_and_leaves_no_session(client, config, que
     assert not response.cookies.get(config.cookie_name), reason
 
 
+def test_a_failed_callback_does_not_end_an_existing_session(client, config):
+    """A top-level link to the callback is a cross-site GET; it must not sign anybody out."""
+    client.cookies.set(config.cookie_name, session_cookie_value(config))
+
+    response = client.get(f"{config.route_prefix}/callback?code=abc&state=forged")
+
+    assert response.headers["location"].endswith("/login")
+    assert not _clears_session(response, config)
+
+
 def test_a_callback_without_the_pending_cookie_is_refused(client, config):
     """Someone replaying a callback URL has no sealed state and cannot be trusted."""
     response = client.get(f"{config.route_prefix}/callback?code=abc&state=the-state")
@@ -216,6 +233,15 @@ def test_next_accepts_relative_paths(candidate):
     assert safe_next(candidate) == candidate
 
 
+NEXT_CASES = VECTORS["next_path"]["cases"]
+
+
+@pytest.mark.parametrize("case", NEXT_CASES, ids=[c["name"] for c in NEXT_CASES])
+def test_next_matches_the_shared_matrix(case):
+    """The TypeScript adapter runs the same cases; the two must not disagree on a path."""
+    assert safe_next(case["candidate"]) == case["expect"]
+
+
 def test_a_hostile_next_does_not_survive_the_round_trip(client, config):
     pending = PendingLogin(
         authorization_url="", state="the-state", nonce="the-nonce", code_verifier="v" * 43
@@ -229,6 +255,41 @@ def test_a_hostile_next_does_not_survive_the_round_trip(client, config):
     assert response.headers["location"] == "/", "hostile next dropped, not followed"
 
 
+HOSTILE_LOGIN_NEXT = [
+    "%2F%2Fevil.test",
+    "/%09/evil.test",
+    "/%0A/evil.test",
+    "/%5Cevil.test",
+    "https%3A%2F%2Fevil.test%2F",
+]
+
+
+@pytest.mark.parametrize("encoded", HOSTILE_LOGIN_NEXT)
+def test_login_decodes_next_before_it_judges_it(client, config, encoded):
+    """The query is decoded first, so an encoded tab or "//" is judged as what it becomes."""
+    response = client.get(f"{config.route_prefix}/login?next={encoded}")
+
+    pending = unseal_pending(response.cookies[config.pending_cookie_name], config=config)
+    assert pending.next_path is None
+
+
+def test_login_keeps_a_plain_next_with_its_query(client, config):
+    response = client.get(f"{config.route_prefix}/login?next=%2Freports%3Fpage%3D2")
+
+    pending = unseal_pending(response.cookies[config.pending_cookie_name], config=config)
+    assert pending.next_path == "/reports?page=2"
+
+
+@pytest.mark.parametrize(
+    ("path", "expected"),
+    [("/docs/a%20b", "/docs/a%20b"), ("/docs/caf%C3%A9", "/docs/caf%C3%A9")],
+)
+def test_the_gate_keeps_an_encoded_path_encoded(client, path, expected):
+    """Judged as the browser sent it, as the TypeScript gate does, not decoded and dropped."""
+    target = urlparse(client.get(path).headers["location"])
+    assert parse_qs(target.query)["next"] == [expected]
+
+
 # --- guarding routes ----------------------------------------------------------------------
 
 
@@ -365,11 +426,80 @@ def test_me_without_a_session_is_a_401_a_frontend_can_branch_on(client, config):
     assert response.json() == {"authenticated": False}
 
 
+LOGOUT_CASES = VECTORS["logout_request"]["cases"]
+
+
+def _clears_session(response, config) -> bool:
+    return any(
+        header.startswith(f"{config.cookie_name}=") and "max-age=0" in header.lower()
+        for header in response.headers.get_list("set-cookie")
+    )
+
+
+@pytest.mark.parametrize("case", LOGOUT_CASES, ids=[c["name"] for c in LOGOUT_CASES])
+def test_logout_matches_the_shared_matrix(case, client, config):
+    """Who may sign a person out. The TypeScript adapter runs the same cases."""
+    client.cookies.set(config.cookie_name, session_cookie_value(config))
+    response = client.request(
+        case["method"], f"{config.route_prefix}/logout", headers=case["headers"]
+    )
+    expected = case["expect"]
+
+    assert response.status_code == expected["status"]
+    assert _clears_session(response, config) is expected["signed_out"]
+    if expected["signed_out"]:
+        assert response.headers["location"].startswith(VECTORS["discovery"]["end_session_endpoint"])
+    if "content_type" in expected:
+        assert response.headers["content-type"].startswith(expected["content_type"])
+        assert "no-store" in response.headers["cache-control"]
+        assert f'action="{expected["form_action"]}"' in response.text
+        assert 'method="post"' in response.text
+        assert "<script" not in response.text.lower()
+        if expected.get("no_framing"):
+            assert response.headers["x-frame-options"] == "DENY"
+            assert "frame-ancestors 'none'" in response.headers["content-security-policy"]
+        for directive in expected.get("csp_omits", []):
+            assert directive not in response.headers["content-security-policy"]
+
+
+def test_a_service_without_a_redirect_uri_trusts_only_fetch_metadata(
+    ctx, config, discovery_for_ctx
+):
+    """No configured site means no Origin can match it; same-origin fetch metadata still can."""
+    worker = AuthContext(
+        replace(config, redirect_uri=None), keys=ctx.keys, discovery=discovery_for_ctx
+    )
+    app = FastAPI()
+    app.include_router(create_auth_router(worker))
+    client = TestClient(app, follow_redirects=False)
+    path = f"{config.route_prefix}/logout"
+
+    assert client.post(path, headers={"origin": "https://svc.example.test"}).status_code == 403
+    assert client.post(path, headers={"sec-fetch-site": "same-origin"}).status_code == 303
+
+
+def test_a_unicode_site_matches_the_punycode_origin_browsers_send(ctx, config, discovery_for_ctx):
+    """Browsers serialise an IDN host as punycode in Origin; the configured site must match it."""
+    site = AuthContext(
+        replace(config, redirect_uri="https://b\u00fccher.example/api/auth/callback"),
+        keys=ctx.keys,
+        discovery=discovery_for_ctx,
+    )
+    app = FastAPI()
+    app.include_router(create_auth_router(site))
+    client = TestClient(app, follow_redirects=False)
+
+    response = client.post(
+        f"{config.route_prefix}/logout", headers={"origin": "https://xn--bcher-kva.example"}
+    )
+    assert response.status_code == 303
+
+
 def test_logout_clears_the_cookie_and_hands_off_to_the_broker(client, config):
     client.cookies.set(config.cookie_name, session_cookie_value(config))
-    response = client.get(f"{config.route_prefix}/logout")
+    response = client.post(f"{config.route_prefix}/logout", headers=SAME_ORIGIN)
 
-    assert response.status_code == 307
+    assert response.status_code == 303
     assert response.headers["location"].startswith(VECTORS["discovery"]["end_session_endpoint"])
     cleared = response.headers.get("set-cookie", "")
     assert config.cookie_name in cleared
@@ -393,7 +523,7 @@ def test_logout_without_a_broker_endpoint_stays_local(config, signer, token_hand
     app.include_router(create_auth_router(ctx))
     client = TestClient(app, follow_redirects=False)
 
-    response = client.get(f"{config.route_prefix}/logout")
+    response = client.post(f"{config.route_prefix}/logout", headers=SAME_ORIGIN)
     assert response.headers["location"] == "/"
 
 
@@ -468,9 +598,16 @@ def test_logout_next_is_honoured_when_there_is_no_broker_endpoint(config, signer
     app.include_router(create_auth_router(ctx))
     client = TestClient(app, follow_redirects=False)
 
-    assert client.get(f"{config.route_prefix}/logout?next=/bye").headers["location"] == "/bye"
+    assert (
+        client.post(f"{config.route_prefix}/logout?next=/bye", headers=SAME_ORIGIN).headers[
+            "location"
+        ]
+        == "/bye"
+    )
     # A hostile next is still dropped.
-    hostile = client.get(f"{config.route_prefix}/logout?next=https://evil.test/")
+    hostile = client.post(
+        f"{config.route_prefix}/logout?next=https://evil.test/", headers=SAME_ORIGIN
+    )
     assert hostile.headers["location"] == "/"
 
 
@@ -599,7 +736,7 @@ def test_logout_names_the_session_so_the_broker_does_not_have_to_ask(ctx, config
 
     _establish_session(client, config)
 
-    response = client.get(f"{config.route_prefix}/logout")
+    response = client.post(f"{config.route_prefix}/logout", headers=SAME_ORIGIN)
 
     params = parse_qs(urlparse(response.headers["location"]).query)
     assert "id_token_hint" in params, "the broker was told whose session to end"
@@ -610,7 +747,7 @@ def test_logout_discards_the_hint_it_just_spent(client, config):
     """One shot. A hint left behind would name a session that no longer exists."""
     _establish_session(client, config)
 
-    response = client.get(f"{config.route_prefix}/logout")
+    response = client.post(f"{config.route_prefix}/logout", headers=SAME_ORIGIN)
 
     cleared = [
         header
@@ -627,8 +764,8 @@ def test_logout_without_a_stored_hint_still_reaches_the_broker(client, config):
     """
     client.cookies.set(config.cookie_name, session_cookie_value(config))
 
-    response = client.get(f"{config.route_prefix}/logout")
+    response = client.post(f"{config.route_prefix}/logout", headers=SAME_ORIGIN)
 
-    assert response.status_code == 307
+    assert response.status_code == 303
     assert response.headers["location"].startswith(VECTORS["discovery"]["end_session_endpoint"])
     assert "id_token_hint" not in parse_qs(urlparse(response.headers["location"]).query)

eager_auth-2.2.2/tests/test_hostile_tokens.py

@@ -0,0 +1,32 @@
+"""Tokens built to crash the parser rather than to forge a principal.
+
+The header is read before any signature check, so whatever it contains comes from an
+unauthenticated caller. Every such token must end as a typed InvalidTokenError (a 401),
+never as an exception the framework turns into a 500.
+"""
+
+import base64
+
+import pytest
+
+from eager_auth import InvalidTokenError, verify_id_token
+
+
+def _b64(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def _token_with_header(header: bytes) -> str:
+    return f"{_b64(header)}.{_b64(b'{}')}.{_b64(b'signature')}"
+
+
+@pytest.mark.parametrize("depth", [10_000, 100_000])
+def test_deeply_nested_header_is_malformed_not_a_crash(depth, config, resolver):
+    # GHSA-8wjv-2p76-3863: PyJWT 2.13.0 lets json.loads raise RecursionError here, which
+    # is a RuntimeError, not an InvalidTokenError. Which typed error it becomes depends on the
+    # interpreter: up to 3.13 json.loads recurses and the header is malformed; 3.14 parses it
+    # iteratively and the token fails at the signature instead. Either is a 401, never a 500.
+    header = b'{"alg":"RS256","x":' + b"[" * depth + b"]" * depth + b"}"
+
+    with pytest.raises(InvalidTokenError):
+        verify_id_token(_token_with_header(header), config=config, keys=resolver)