ff-ltitoolkit 0.1.0__py3-none-any.whl

ltitoolkit/fastapi/request.py

@@ -0,0 +1,77 @@
+"""Starlette/FastAPI request adapter for the vendored LTI core.
+
+The core's :class:`ltitoolkit.core.request.Request` exposes a *synchronous*
+``get_param()``. Starlette, however, reads the form body asynchronously
+(``await request.form()``). We bridge this by extracting all request data
+*eagerly* in :meth:`FastApiRequest.from_request` (inside the async route) and
+then serving it synchronously from an in-memory mapping — so the core never has
+to ``await`` anything.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from starlette.requests import Request as StarletteRequest
+
+from ltitoolkit.core.request import Request
+
+
+class FastApiRequest(Request):
+    """A core ``Request`` backed by data pulled from a Starlette request.
+
+    Construct it with :meth:`from_request` from inside an async handler; that is
+    the only place the (async) form body can be read.
+    """
+
+    def __init__(
+        self,
+        *,
+        cookies: t.Mapping[str, str],
+        session: t.MutableMapping[str, t.Any],
+        request_data: t.Mapping[str, t.Any],
+        request_is_secure: bool,
+    ) -> None:
+        super().__init__()
+        self._cookies = cookies
+        self._session = session
+        self._request_data = request_data
+        self._request_is_secure = request_is_secure
+
+    @classmethod
+    async def from_request(cls, request: StarletteRequest) -> FastApiRequest:
+        """Eagerly read query/form params, cookies and session from Starlette.
+
+        The default launch-data storage writes to ``request.session``, which
+        requires Starlette's ``SessionMiddleware`` to be installed. If it is not,
+        a throwaway dict is used (fine for cache-backed storage, but session
+        storage will not persist across requests).
+        """
+        request_data: dict[str, t.Any] = dict(request.query_params)
+        if request.method != "GET":
+            form = await request.form()
+            request_data.update({key: form[key] for key in form})
+
+        # request.session only exists when SessionMiddleware is active.
+        session: t.MutableMapping[str, t.Any]
+        session = request.session if "session" in request.scope else {}
+
+        return cls(
+            cookies=dict(request.cookies),
+            session=session,
+            request_data=request_data,
+            request_is_secure=request.url.scheme == "https",
+        )
+
+    @property
+    def session(self) -> t.MutableMapping[str, t.Any]:
+        return self._session
+
+    def get_param(self, key: str) -> t.Any:
+        return self._request_data.get(key)
+
+    def get_cookie(self, key: str) -> str | None:
+        return self._cookies.get(key)
+
+    def is_secure(self) -> bool:
+        return self._request_is_secure

ltitoolkit/fastapi/session.py

@@ -0,0 +1,13 @@
+"""Session service adapter.
+
+The core's :class:`ltitoolkit.core.session.SessionService` is framework-neutral:
+its default backend (``SessionDataStorage``) simply reads and writes
+``request.session``. For FastAPI that is the dict provided by Starlette's
+``SessionMiddleware``, so no behaviour needs to change here.
+"""
+
+from ltitoolkit.core.session import SessionService
+
+
+class FastApiSessionService(SessionService):
+    pass

ltitoolkit/http.py

@@ -0,0 +1,80 @@
+"""HTTP session construction with sane, safe defaults.
+
+The vendored core issues requests with **no timeout**, which can hang a worker
+indefinitely if the LMS stalls. Rather than patch the vendored code, we provide
+a session whose adapter injects a default timeout on every request, and we pass
+that session into the core services and our own token service.
+
+Retries are **disabled by default** and, when enabled, are restricted to
+idempotent methods (GET/HEAD/OPTIONS). LTI score submission and token requests
+are POSTs and must never be retried blindly (risk of duplicate side effects).
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+import requests
+from requests.adapters import HTTPAdapter
+from requests.models import PreparedRequest
+from urllib3.util.retry import Retry
+
+# (connect timeout, read timeout) in seconds.
+DEFAULT_TIMEOUT: tuple[float, float] = (10.0, 30.0)
+
+_IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+class TimeoutHTTPAdapter(HTTPAdapter):
+    """An adapter that applies a default timeout when a call omits one."""
+
+    def __init__(
+        self, *args: t.Any, timeout: float | tuple[float, float] = DEFAULT_TIMEOUT, **kwargs: t.Any
+    ) -> None:
+        self._timeout = timeout
+        super().__init__(*args, **kwargs)
+
+    def send(  # noqa: PLR0913 - signature mirrors requests' HTTPAdapter.send
+        self,
+        request: PreparedRequest,
+        stream: bool = False,
+        timeout: t.Any = None,
+        verify: t.Any = True,
+        cert: t.Any = None,
+        proxies: t.Any = None,
+    ) -> t.Any:
+        if timeout is None:
+            timeout = self._timeout
+        return super().send(
+            request, stream=stream, timeout=timeout, verify=verify, cert=cert, proxies=proxies
+        )
+
+
+def build_session(
+    *,
+    timeout: float | tuple[float, float] = DEFAULT_TIMEOUT,
+    retries: int = 0,
+    backoff_factor: float = 0.3,
+    user_agent: str = "ltitoolkit",
+) -> requests.Session:
+    """Create a ``requests.Session`` with a default timeout and optional retries.
+
+    :param timeout: default ``(connect, read)`` timeout for every request.
+    :param retries: max retries for *idempotent* methods only (0 disables them).
+    :param backoff_factor: exponential backoff between retries.
+    :param user_agent: ``User-Agent`` header sent with every request.
+    """
+    session = requests.Session()
+    session.headers["User-Agent"] = user_agent
+
+    retry = Retry(
+        total=retries,
+        backoff_factor=backoff_factor,
+        status_forcelist=(429, 500, 502, 503, 504),
+        allowed_methods=_IDEMPOTENT_METHODS,
+        raise_on_status=False,
+    )
+    adapter = TimeoutHTTPAdapter(timeout=timeout, max_retries=retry)
+    session.mount("https://", adapter)
+    session.mount("http://", adapter)
+    return session

ltitoolkit/token/__init__.py

@@ -0,0 +1,20 @@
+"""Generic OAuth2 client-credentials token minting.
+
+The tool authenticates to an LMS by signing a JWT with its *own* private key
+(the key behind its JWKS) and exchanging it for an access token via the
+client-credentials grant — no user login, no copied credentials.
+
+This is reused for both LTI Advantage service calls (AGS/NRPS — portable) and
+LMS-proprietary API calls (Canvas etc. — used by per-LMS adapters). Only the
+*scopes* and *endpoints* differ per LMS; the auth mechanism here is shared.
+"""
+
+from .cache import AccessToken, InMemoryTokenCache, TokenCache
+from .service import AccessTokenService
+
+__all__ = [
+    "AccessToken",
+    "TokenCache",
+    "InMemoryTokenCache",
+    "AccessTokenService",
+]

ltitoolkit/token/cache.py

@@ -0,0 +1,47 @@
+"""Access-token value object and pluggable cache.
+
+Tokens are cached per scope-set and reused until they are near expiry. The cache
+is an interface (:class:`TokenCache`) so applications can swap the default
+in-process dict for Redis, a database, etc. — important when running multiple
+workers that should share tokens (the default cache is per-process only).
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AccessToken:
+    """An OAuth2 access token with the scopes it was issued for and its expiry."""
+
+    value: str
+    scopes: tuple[str, ...]
+    expires_at: float  # epoch seconds
+
+    def is_expired(self, *, leeway: float = 60.0, now: float) -> bool:
+        """True if the token is at/after its expiry (minus a safety ``leeway``)."""
+        return now >= (self.expires_at - leeway)
+
+
+@t.runtime_checkable
+class TokenCache(t.Protocol):
+    """Minimal cache interface for storing access tokens by key."""
+
+    def get(self, key: str) -> AccessToken | None: ...
+
+    def set(self, key: str, token: AccessToken) -> None: ...
+
+
+class InMemoryTokenCache:
+    """Default per-process cache. Not shared across workers/processes."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, AccessToken] = {}
+
+    def get(self, key: str) -> AccessToken | None:
+        return self._store.get(key)
+
+    def set(self, key: str, token: AccessToken) -> None:
+        self._store[key] = token

ltitoolkit/token/service.py

@@ -0,0 +1,165 @@
+"""Client-credentials access-token service.
+
+The tool authenticates to an LMS by signing a short-lived *client assertion* JWT
+with its own private key and exchanging it (``grant_type=client_credentials``)
+for an access token — no user login, no copied secrets. This is the auth half of
+both LTI Advantage service calls and LMS-proprietary API calls (e.g. listing
+Canvas files); only the requested *scopes* differ.
+
+This service adds, on top of the vendored core's signing:
+
+- **expiry-aware caching** (reuse a token until it nears expiry), and
+- **explicit timeouts** and **typed errors**
+
+which the core's in-memory token cache lacks. The security-critical RSA signing
+is delegated to PyJWT exactly as the core does it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+import typing as t
+import uuid
+
+import jwt
+import requests
+
+from ..exceptions import AccessTokenError
+from ..http import build_session
+from .cache import AccessToken, InMemoryTokenCache, TokenCache
+
+if t.TYPE_CHECKING:
+    from ..core.registration import Registration
+
+_JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+# Client-assertion lifetime. Kept short per the LTI security spec.
+_ASSERTION_LIFETIME = 60
+# Fallback token lifetime if the platform omits ``expires_in``.
+_DEFAULT_TOKEN_LIFETIME = 3600
+
+
+class AccessTokenService:
+    """Mint and cache client-credentials access tokens for a registration."""
+
+    def __init__(
+        self,
+        registration: Registration,
+        *,
+        session: requests.Session | None = None,
+        cache: TokenCache | None = None,
+        timeout: float | tuple[float, float] = (10.0, 30.0),
+        expiry_leeway: float = 60.0,
+        clock: t.Callable[[], float] = time.time,
+    ) -> None:
+        self._registration = registration
+        self._session = session if session is not None else build_session(timeout=timeout)
+        self._cache: TokenCache = cache if cache is not None else InMemoryTokenCache()
+        self._timeout = timeout
+        self._leeway = expiry_leeway
+        self._clock = clock
+
+    def get_token(self, scopes: t.Sequence[str]) -> str:
+        """Return a valid access token for ``scopes``, minting one if needed."""
+        if not scopes:
+            raise ValueError("At least one scope is required")
+
+        key = self._cache_key(scopes)
+        cached = self._cache.get(key)
+        if cached is not None and not cached.is_expired(
+            leeway=self._leeway, now=self._clock()
+        ):
+            return cached.value
+
+        token = self._request_token(scopes)
+        self._cache.set(key, token)
+        return token.value
+
+    # -- internals ---------------------------------------------------------
+
+    @staticmethod
+    def _cache_key(scopes: t.Sequence[str]) -> str:
+        canonical = "|".join(sorted(scopes)).encode("utf-8")
+        return hashlib.sha256(canonical).hexdigest()
+
+    def _build_client_assertion(self) -> str:
+        client_id = self._registration.get_client_id()
+        token_url = self._registration.get_auth_token_url()
+        assert client_id is not None, "Registration is missing client_id"
+        assert token_url is not None, "Registration is missing auth_token_url"
+        audience = self._registration.get_auth_audience() or token_url
+        private_key = self._registration.get_tool_private_key()
+        assert private_key is not None, "Registration is missing the tool private key"
+
+        now = int(self._clock())
+        claims: dict[str, t.Any] = {
+            "iss": str(client_id),
+            "sub": str(client_id),
+            "aud": str(audience),
+            "iat": now - 5,
+            "exp": now + _ASSERTION_LIFETIME,
+            "jti": "ltitoolkit-" + uuid.uuid4().hex,
+        }
+        headers: dict[str, str] = {}
+        kid = self._registration.get_kid()
+        if kid:
+            headers["kid"] = kid
+
+        encoded = jwt.encode(claims, private_key, algorithm="RS256", headers=headers)
+        # PyJWT < 2 returned bytes; normalise to str.
+        return encoded.decode("utf-8") if isinstance(encoded, bytes) else encoded
+
+    def _request_token(self, scopes: t.Sequence[str]) -> AccessToken:
+        token_url = self._registration.get_auth_token_url()
+        assert token_url is not None, "Registration is missing auth_token_url"
+
+        payload = {
+            "grant_type": "client_credentials",
+            "client_assertion_type": _JWT_BEARER,
+            "client_assertion": self._build_client_assertion(),
+            "scope": " ".join(scopes),
+        }
+
+        try:
+            response = self._session.post(token_url, data=payload, timeout=self._timeout)
+        except requests.Timeout as exc:
+            raise AccessTokenError(
+                f"Timed out requesting access token: {exc}",
+                url=token_url,
+                is_timeout=True,
+            ) from exc
+        except requests.RequestException as exc:
+            raise AccessTokenError(
+                f"Error requesting access token: {exc}", url=token_url
+            ) from exc
+
+        if not response.ok:
+            raise AccessTokenError(
+                "Access token request rejected by the platform",
+                status_code=response.status_code,
+                url=token_url,
+                response_text=response.text,
+            )
+
+        try:
+            body = response.json()
+            access_token = body["access_token"]
+        except (ValueError, KeyError, TypeError) as exc:
+            raise AccessTokenError(
+                "Malformed access token response from the platform",
+                status_code=response.status_code,
+                url=token_url,
+                response_text=response.text,
+            ) from exc
+
+        expires_in = body.get("expires_in", _DEFAULT_TOKEN_LIFETIME)
+        try:
+            expires_at = self._clock() + float(expires_in)
+        except (TypeError, ValueError):
+            expires_at = self._clock() + _DEFAULT_TOKEN_LIFETIME
+
+        return AccessToken(
+            value=access_token,
+            scopes=tuple(sorted(scopes)),
+            expires_at=expires_at,
+        )