pyedookit 0.3.2__tar.gz → 0.4.0__tar.gz

{pyedookit-0.3.2 → pyedookit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyedookit
-Version: 0.3.2
+Version: 0.4.0
 Summary: Async client for the Edookit parent portal (edookit.net)
 Project-URL: Homepage, https://github.com/TFoxik/pyedookit
 Author: TFoxik
@@ -70,17 +70,22 @@ asyncio.run(main())
 ### Sessions
 
 The password is only used by `login()`. Store `session.to_json()` instead,
-and treat it like a password: it holds the Plus4U cookie, which signs in
-for about 19 days. Load it with `Session.from_json()`.
+and treat it like a password: it holds the Plus4U sign-in, which lasts about
+19 days (`session.plus4u_expires_at` tells you when, or is `None` if that's
+unknown or already past). Load it with
+`Session.from_json()`; sessions stored by 0.3.x still load.
 
-The edookit session itself lasts 30-60 minutes. When it runs out, call
-`refresh(session)` to get a new one from the Plus4U cookie. When `refresh()`
-raises `AuthError`, the Plus4U cookie has expired too and you need `login()`
-again.
+`EdookitClient` renews the short-lived edookit session by itself and
+retries once. Pass `on_session_update` to persist each renewed session:
+
+    client = EdookitClient(session, on_session_update=lambda s: save(s.to_json()))
+
+When the Plus4U sign-in has expired too, calls raise `AuthError` and you
+need `login()` again.
 
 | Exception | Meaning | What to do |
 |---|---|---|
-| `SessionExpired` | the edookit session ran out | `refresh()` and retry |
+| `SessionExpired` | still expired right after a renewal | retry later |
 | `AuthError` | bad credentials, or the Plus4U cookie expired | `login()` |
 | `EdookitConnectionError` | network error or 30 s timeout | retry later |
 | `ParseError` | the portal's markup changed | the parser needs updating |

{pyedookit-0.3.2 → pyedookit-0.4.0}/README.md

@@ -48,17 +48,22 @@ asyncio.run(main())
 ### Sessions
 
 The password is only used by `login()`. Store `session.to_json()` instead,
-and treat it like a password: it holds the Plus4U cookie, which signs in
-for about 19 days. Load it with `Session.from_json()`.
+and treat it like a password: it holds the Plus4U sign-in, which lasts about
+19 days (`session.plus4u_expires_at` tells you when, or is `None` if that's
+unknown or already past). Load it with
+`Session.from_json()`; sessions stored by 0.3.x still load.
 
-The edookit session itself lasts 30-60 minutes. When it runs out, call
-`refresh(session)` to get a new one from the Plus4U cookie. When `refresh()`
-raises `AuthError`, the Plus4U cookie has expired too and you need `login()`
-again.
+`EdookitClient` renews the short-lived edookit session by itself and
+retries once. Pass `on_session_update` to persist each renewed session:
+
+    client = EdookitClient(session, on_session_update=lambda s: save(s.to_json()))
+
+When the Plus4U sign-in has expired too, calls raise `AuthError` and you
+need `login()` again.
 
 | Exception | Meaning | What to do |
 |---|---|---|
-| `SessionExpired` | the edookit session ran out | `refresh()` and retry |
+| `SessionExpired` | still expired right after a renewal | retry later |
 | `AuthError` | bad credentials, or the Plus4U cookie expired | `login()` |
 | `EdookitConnectionError` | network error or 30 s timeout | retry later |
 | `ParseError` | the portal's markup changed | the parser needs updating |

{pyedookit-0.3.2 → pyedookit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyedookit"
-version = "0.3.2"
+version = "0.4.0"
 description = "Async client for the Edookit parent portal (edookit.net)"
 readme = "README.md"
 requires-python = ">=3.12"

{pyedookit-0.3.2 → pyedookit-0.4.0}/src/pyedookit/__init__.py

@@ -10,11 +10,13 @@ from .exceptions import (
 from .models import PORTAL_TZ, Lesson, PaymentRequest, Payments, SchoolEvent, Term
 from .parsers.fingerprint import content_fingerprint
 from .session import Session
+from .transport import CookieStore
 
 __all__ = [
     "CAPTURE_PAGES",
     "PORTAL_TZ",
     "AuthError",
+    "CookieStore",
     "EdookitClient",
     "EdookitConnectionError",
     "EdookitError",

pyedookit-0.4.0/src/pyedookit/auth.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import json as _json
+import re
+import secrets
+
+import aiohttp
+from yarl import URL
+
+from . import transport
+from .exceptions import AuthError
+from .session import PLUS4U_HOST, Session, school_base, school_host, validate_school
+from .transport import CookieStore, Response
+
+_PLUS4U_OIDC_BASE = (
+    "https://uuidentity.plus4u.net/uu-oidc-maing02/bb977a99f4cc4c37a2afce3fd599d0a7"
+)
+_AUTH_URL = f"{_PLUS4U_OIDC_BASE}/oidc/auth"
+_AUTH_PASSWORD_URL = f"{_PLUS4U_OIDC_BASE}/authPassword/authenticate"
+_REALM_CODE = "uuIdentityPasswordAuthNRealm"
+
+# Confirmed against a real portal: the OIDC client_id is per-school, not a
+# single value shared across every Edookit install (third-party docs this
+# was originally inferred from implied otherwise). Each school's /user/login
+# page embeds it in a small inline JS config block, e.g.
+#   uu_app_oidc_providers_oidcg02_client_id: "983960dcb7b84b34b9aecc5194381d56"
+# so it has to be scraped fresh per school rather than hardcoded.
+_CLIENT_ID_RE = re.compile(
+    r"uu_app_oidc_providers_oidcg02_client_id\s*:\s*['\"]([^'\"]+)['\"]"
+)
+
+# Edookit sends the browser back to one of these paths when a session has
+# expired or was never valid; shared with client.py so "did we get logged
+# out" is checked the same way everywhere.
+LOGIN_MARKERS = ("/user/login", "/user/oidc")
+
+
+def is_login_url(url: str) -> bool:
+    return any(marker in url for marker in LOGIN_MARKERS)
+
+
+def _callback_url(school: str) -> str:
+    return f"{school_base(school)}/user/oidc-login-callback"
+
+
+def _auth_params(
+    school: str, client_id: str, state: str, *, prompt_none: bool = False
+) -> dict[str, str]:
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": _callback_url(school),
+        "scope": "openid",
+        "state": state,
+    }
+    if prompt_none:
+        params["prompt"] = "none"
+    return params
+
+
+async def _discover_client_id(
+    http: aiohttp.ClientSession, school: str, cookies: CookieStore
+) -> str:
+    """Scrape the school's own /user/login page for its Plus4U client_id.
+
+    Its Set-Cookie response - PHPSESSID etc. - lands in `cookies` and so
+    joins the rest of the login flow, rather than being discarded.
+    """
+    result = await transport.request(http, "GET", f"{school_base(school)}/user/login", cookies)
+    match = _CLIENT_ID_RE.search(result.text)
+    if not match:
+        raise AuthError(f"could not find a Plus4U client_id on {school}'s login page")
+    return match.group(1)
+
+
+def _session_from_cookies(school: str, cookies: CookieStore) -> Session:
+    if not cookies.get(school_host(school), "PHPSESSID"):
+        raise AuthError("login flow completed but no edookit session cookie was set")
+    return Session(school=school, cookies=cookies)
+
+
+async def _finish_callback(
+    http: aiohttp.ClientSession, callback_url: str, cookies: CookieStore, school: str
+) -> Session:
+    """Follow the final OIDC callback redirect chain and build a Session from it.
+
+    Shared tail of login() and refresh(): both end with "GET the code=
+    callback, make sure we didn't land back on the login page, then read the
+    cookies that piled up along the way."
+
+    Confirmed against a real browser trace (HAR): after the callback GET
+    resolves (still 200 on /oidc/callback), the browser makes one more GET
+    to the portal root, which is what actually settles the session server
+    side - skipping it leaves the account looking like it has almost no
+    modules enabled (only the dashboard and badges), even though login
+    itself succeeded and the session cookies are valid.
+    """
+    result = await transport.request(http, "GET", callback_url, cookies, follow_redirects=True)
+    if is_login_url(result.url):
+        raise AuthError("edookit rejected the Plus4U authorization code")
+    settle = await transport.request(
+        http, "GET", school_base(school), cookies, follow_redirects=True
+    )
+    if is_login_url(settle.url):
+        raise AuthError("session did not settle after the OIDC callback")
+    return _session_from_cookies(school, cookies)
+
+
+async def probe_client_id(school: str) -> str:
+    """Discover a school's Plus4U client_id without logging in.
+
+    Used by scripts/capture_fixtures.py to show what login()/refresh() will
+    use for this school before spending the user's password.
+    """
+    validate_school(school)
+    async with transport.http_session(None) as http:
+        return await _discover_client_id(http, school, CookieStore())
+
+
+async def _authorize(
+    http: aiohttp.ClientSession, school: str, cookies: CookieStore, *, prompt_none: bool = False
+) -> tuple[str, str, Response]:
+    """Start the OIDC authorization: shared opening of login() and refresh()."""
+    client_id = await _discover_client_id(http, school, cookies)
+    state = secrets.token_urlsafe(16)
+    params = _auth_params(school, client_id, state, prompt_none=prompt_none)
+    return client_id, state, await transport.request(
+        http, "GET", _AUTH_URL, cookies, params=params
+    )
+
+
+async def login(
+    school: str,
+    username: str,
+    password: str,
+    *,
+    http: aiohttp.ClientSession | None = None,
+) -> Session:
+    """Run the Plus4U OIDC password login and return a usable Session.
+
+    Raises AuthError if the credentials are rejected or the flow's shape has
+    changed (e.g. Edookit or Plus4U altered a redirect), and
+    EdookitConnectionError if either host can't be reached.
+
+    A passed-in `http` session must not keep its own cookies (use
+    `aiohttp.DummyCookieJar()`): cookies are tracked per host by hand here,
+    and a real jar would also collect and resend them.
+    """
+    validate_school(school)
+    cookies = CookieStore()
+    async with transport.http_session(http) as http:
+        client_id, state, step1 = await _authorize(http, school, cookies)
+        if not step1.is_redirect or not step1.location:
+            raise AuthError(f"expected a redirect from Plus4U auth endpoint, got {step1.status}")
+        login_url = URL(step1.location)
+        server_state = login_url.query.get("state", state)
+        server_client_id = login_url.query.get("clientId", client_id)
+
+        payload = {
+            "clientId": server_client_id,
+            "state": server_state,
+            "rememberMe": True,
+            "realmCode": _REALM_CODE,
+            "username": username,
+            "password": password,
+        }
+        step2 = await transport.request(http, "POST", _AUTH_PASSWORD_URL, cookies, json=payload)
+        if step2.status in (400, 401):
+            raise AuthError("Plus4U rejected the username or password")
+        continue_url = step2.location
+        if not continue_url and step2.text:
+            try:
+                body = _json.loads(step2.text)
+            except ValueError:
+                body = None
+            if isinstance(body, dict):
+                continue_url = body.get("redirectUrl")
+        if not continue_url:
+            raise AuthError("Plus4U password auth did not return a continuation URL")
+
+        step3 = await transport.request(http, "GET", continue_url, cookies)
+        if not step3.location or "code=" not in step3.location:
+            raise AuthError("Plus4U did not return an authorization code")
+
+        return await _finish_callback(http, step3.location, cookies, school)
+
+
+async def refresh(session: Session, *, http: aiohttp.ClientSession | None = None) -> Session:
+    """Obtain a fresh edookit session using the stored Plus4U cookies.
+
+    No password is needed; this is what keeps a long-running Home Assistant
+    integration logged in across the ~30-60 minute edookit session lifetime.
+    Raises AuthError if the Plus4U cookies have themselves expired (roughly
+    every 19 days), which means a full `login()` with the password is needed.
+    `http` has the same cookie-jar requirement as in `login()`.
+    """
+    # Only the Plus4U cookies: the portal answers /user/login with a redirect
+    # to /oidc/logout when it sees the expired edookit session, so the new
+    # edookit session is built from scratch, exactly like in login().
+    cookies = session.cookies.for_host(PLUS4U_HOST)
+    async with transport.http_session(http) as http:
+        _, _, step1 = await _authorize(http, session.school, cookies, prompt_none=True)
+        if not step1.is_redirect or not step1.location or "code=" not in step1.location:
+            raise AuthError("Plus4U session expired; full login required")
+
+        return await _finish_callback(http, step1.location, cookies, session.school)

{pyedookit-0.3.2 → pyedookit-0.4.0}/src/pyedookit/client.py

@@ -2,17 +2,21 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
+from collections.abc import Callable
 
 import aiohttp
 
-from . import auth
-from .exceptions import EdookitConnectionError, SessionExpired
+from . import auth, transport
+from .exceptions import SessionExpired
 from .models import Lesson, Payments, SchoolEvent, Term
 from .parsers.events import parse_events
 from .parsers.payments import parse_payments
 from .parsers.timetable import parse_terms, parse_timetable
 from .session import Session
 
+_LOGGER = logging.getLogger(__name__)
+
 _TIMETABLE_PATH = "/timetable/"
 _EVENTS_PATH = "/timetable/upcoming"
 _PAYMENTS_PATH = "/payments/"
@@ -28,10 +32,10 @@ CAPTURE_PAGES: dict[str, str] = {
 class EdookitClient:
     """Fetches parsed data from one school's Edookit parent portal.
 
-    Holds a `Session` that the caller is responsible for persisting and
-    refreshing (see `pyedookit.auth.refresh`); this class only detects when
-    the current session has gone stale and raises `SessionExpired` so the
-    caller can refresh and retry.
+    Renews an expired edookit session by itself from the Plus4U sign-in and
+    retries once; `on_session_update` receives each renewed `Session` so the
+    caller can persist it. `AuthError` means the Plus4U sign-in expired too
+    and a full `login()` is needed.
 
     Pass `http` to reuse an existing `aiohttp.ClientSession` across requests
     instead of opening a new connection per call; otherwise one is created
@@ -43,9 +47,17 @@ class EdookitClient:
     the caller's event loop.
     """
 
-    def __init__(self, session: Session, http: aiohttp.ClientSession | None = None) -> None:
+    def __init__(
+        self,
+        session: Session,
+        http: aiohttp.ClientSession | None = None,
+        *,
+        on_session_update: Callable[[Session], None] | None = None,
+    ) -> None:
         self._session = session
         self._http = http
+        self._on_session_update = on_session_update
+        self._renew_lock = asyncio.Lock()
 
     @property
     def session(self) -> Session:
@@ -78,39 +90,45 @@ class EdookitClient:
         return await self._get(path)
 
     async def _get(self, path: str, params: dict[str, int] | None = None) -> str:
-        url = f"{self._session.base_url}{path}"
-        # allow_redirects=False: our Cookie/CSRF headers are set manually, and
-        # older aiohttp forwards a manually-set Cookie header to a redirect's
-        # target even when that target is a different host - so an expired
-        # session's redirect to Plus4U must never be followed with them
-        # attached. Any redirect at all means the session isn't good anymore.
+        session = self._session
         try:
-            async with (
-                auth.http_session(self._http) as http,
-                http.get(
-                    url,
-                    params=params,
-                    headers=auth.build_headers(self._session),
-                    allow_redirects=False,
-                    timeout=auth.REQUEST_TIMEOUT,
-                ) as resp,
-            ):
-                if resp.status in auth.REDIRECT_STATUSES:
-                    raise SessionExpired("edookit session has expired")
-                body = await resp.text()
-        except (aiohttp.ClientError, TimeoutError) as err:
-            raise EdookitConnectionError(f"request to {url} failed: {err}") from err
-        if _redirects_to_login(resp.headers.get("Content-Type", ""), body):
+            return await self._fetch(session, path, params)
+        except SessionExpired:
+            _LOGGER.debug("Edookit session expired, renewing it")
+            await self._renew(session)
+        return await self._fetch(self._session, path, params)
+
+    async def _renew(self, stale: Session) -> None:
+        async with self._renew_lock:
+            if self._session is not stale:
+                return
+            self._session = await auth.refresh(stale, http=self._http)
+            if self._on_session_update is not None:
+                self._on_session_update(self._session)
+
+    async def _fetch(self, session: Session, path: str, params: dict[str, int] | None) -> str:
+        async with transport.http_session(self._http) as http:
+            response = await transport.request(
+                http,
+                "GET",
+                f"{session.base_url}{path}",
+                session.cookies,
+                headers={"X-CSRF-Token": session.csrf_token, "X-Requested-With": "XMLHttpRequest"},
+                params=params,
+            )
+        if response.is_redirect or _is_ajax_redirect(response.content_type, response.text):
             raise SessionExpired("edookit session has expired")
-        return body
+        return response.text
 
 
-def _redirects_to_login(content_type: str, body: str) -> bool:
-    """Whether the portal answered with its AJAX-style login redirect.
+def _is_ajax_redirect(content_type: str, body: str) -> bool:
+    """Whether the portal answered with an AJAX-style redirect.
 
-    Requests carry X-Requested-With, so an expired session gets a 200 with
-    {"redirect": "https://<school>.edookit.net/user/login?message=1"} rather
-    than an HTTP redirect (confirmed against a real portal).
+    Requests carry X-Requested-With, so an expired session gets a 200 with a
+    JSON {"redirect": url} rather than an HTTP redirect. Both shapes seen on a
+    real portal are expired sessions: /user/login?message=1 and
+    /oidc/logout?performCallback=.... A redirect answer never carries the
+    page, so the target URL is deliberately not inspected.
     """
     if not content_type.startswith("application/json"):
         return False
@@ -118,5 +136,4 @@ def _redirects_to_login(content_type: str, body: str) -> bool:
         data = json.loads(body)
     except ValueError:
         return False
-    redirect = data.get("redirect") if isinstance(data, dict) else None
-    return isinstance(redirect, str) and auth.is_login_url(redirect)
+    return isinstance(data, dict) and isinstance(data.get("redirect"), str)

pyedookit-0.4.0/src/pyedookit/session.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .exceptions import AuthError
+from .transport import Cookie, CookieStore
+
+PLUS4U_HOST = "uuidentity.plus4u.net"
+
+# A school subdomain becomes part of every portal URL with no other encoding,
+# so reject anything that isn't a bare hostname label - otherwise a value
+# like "evil.com/" or "evil.com#" would send the session's cookies off-portal.
+_SCHOOL_RE = re.compile(r"[a-z0-9][a-z0-9-]{0,62}")
+
+
+def validate_school(school: str) -> None:
+    if not _SCHOOL_RE.fullmatch(school):
+        raise AuthError(f"{school!r} is not a valid Edookit school subdomain")
+
+
+def school_host(school: str) -> str:
+    return f"{school}.edookit.net"
+
+
+def school_base(school: str) -> str:
+    return f"https://{school_host(school)}"
+
+
+@dataclass(slots=True)
+class Session:
+    """Everything needed to talk to a school's portal without the password.
+
+    `cookies` holds the short-lived edookit session (30-60 minutes) and the
+    long-lived Plus4U sign-in that `refresh()` renews it from. Treat the
+    serialised form like a password.
+    """
+
+    school: str
+    cookies: CookieStore = field(repr=False)
+
+    def __post_init__(self) -> None:
+        validate_school(self.school)
+
+    @classmethod
+    def from_cookies(
+        cls, school: str, edookit: Mapping[str, str], plus4u: Mapping[str, str]
+    ) -> Session:
+        return cls(
+            school,
+            CookieStore(
+                {
+                    school_host(school): {n: Cookie(v) for n, v in edookit.items()},
+                    PLUS4U_HOST: {n: Cookie(v) for n, v in plus4u.items()},
+                }
+            ),
+        )
+
+    @property
+    def host(self) -> str:
+        return school_host(self.school)
+
+    @property
+    def base_url(self) -> str:
+        return school_base(self.school)
+
+    @property
+    def csrf_token(self) -> str:
+        return self.cookies.get(self.host, "uu.app.csrf") or ""
+
+    @property
+    def plus4u_expires_at(self) -> datetime | None:
+        return self.cookies.expires(PLUS4U_HOST, "uoid.ps")
+
+    def to_json(self) -> str:
+        return json.dumps({"school": self.school, "cookies": self.cookies.to_dict()})
+
+    @classmethod
+    def from_json(cls, raw: str) -> Session:
+        data = json.loads(raw)
+        if "cookies" in data:
+            return cls(data["school"], CookieStore.from_dict(data["cookies"]))
+        # Written by pyedookit <= 0.3.x: two plain dicts and no cookie expiry.
+        return cls.from_cookies(data["school"], data["edookit_cookies"], data["plus4u_cookies"])