ff-ltitoolkit 0.1.0__py3-none-any.whl

ltitoolkit/advantage/service.py

@@ -0,0 +1,96 @@
+"""A clean facade over the LTI Advantage services of a validated launch.
+
+Wraps a validated ``MessageLaunch`` and exposes the two portable, every-LMS
+services with explicit availability guards and a couple of ergonomic helpers:
+
+- **NRPS** — the course roster (paginated transparently by the core).
+- **AGS** — read/write grades for *this tool's* activities.
+
+It does not reimplement the spec logic (that lives in the vendored core); it
+gives applications a small, typed, documented surface so they never import from
+``ltitoolkit.core`` directly.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from datetime import datetime, timezone
+
+from ..core.grade import Grade
+from ..exceptions import LtiToolkitError
+
+if t.TYPE_CHECKING:
+    from ..core.assignments_grades import AssignmentsGradesService
+    from ..core.lineitem import LineItem
+    from ..core.message_launch import MessageLaunch
+    from ..core.names_roles import NamesRolesProvisioningService, TMember
+    from ..core.service_connector import TServiceConnectorResponse
+
+
+class AdvantageServiceUnavailable(LtiToolkitError):
+    """Raised when a launch did not grant the requested Advantage service."""
+
+
+class LaunchAdvantage:
+    """Ergonomic access to AGS/NRPS for a single validated launch."""
+
+    def __init__(self, message_launch: MessageLaunch) -> None:
+        self._launch = message_launch
+
+    # -- Names & Role Provisioning (roster) --------------------------------
+
+    def has_names_and_roles(self) -> bool:
+        return self._launch.has_nrps()
+
+    def names_and_roles(self) -> NamesRolesProvisioningService:
+        if not self.has_names_and_roles():
+            raise AdvantageServiceUnavailable(
+                "This launch does not include the Names and Role Provisioning Service"
+            )
+        return self._launch.get_nrps()
+
+    def get_roster(self, resource_link_id: str | None = None) -> list[TMember]:
+        """Return all course members (every page), optionally filtered by resource link."""
+        return self.names_and_roles().get_members(resource_link_id)
+
+    # -- Assignment & Grade Services (grades) ------------------------------
+
+    def has_grades(self) -> bool:
+        return self._launch.has_ags()
+
+    def grades(self) -> AssignmentsGradesService:
+        if not self.has_grades():
+            raise AdvantageServiceUnavailable(
+                "This launch does not include the Assignment and Grade Services"
+            )
+        return self._launch.get_ags()
+
+    def submit_score(
+        self,
+        *,
+        user_id: str,
+        score_given: float,
+        score_maximum: float,
+        activity_progress: str = "Completed",
+        grading_progress: str = "FullyGraded",
+        comment: str | None = None,
+        timestamp: str | None = None,
+        lineitem: LineItem | None = None,
+    ) -> TServiceConnectorResponse:
+        """Push a score back to the gradebook for ``user_id``.
+
+        Defaults to the line item carried by the launch; pass ``lineitem`` to
+        target a specific one. ``timestamp`` defaults to now (ISO 8601, UTC).
+        """
+        grade = (
+            Grade()
+            .set_user_id(user_id)
+            .set_score_given(score_given)
+            .set_score_maximum(score_maximum)
+            .set_activity_progress(activity_progress)
+            .set_grading_progress(grading_progress)
+            .set_timestamp(timestamp or datetime.now(timezone.utc).isoformat())
+        )
+        if comment is not None:
+            grade.set_comment(comment)
+        return self.grades().put_grade(grade, lineitem)

ltitoolkit/core/__init__.py

@@ -0,0 +1,19 @@
+"""Vendored LTI 1.3 Advantage engine.
+
+This package is a vendored, rebranded copy of PyLTI1p3 (MIT licensed). It
+provides the spec-correct, security-critical LTI 1.3 primitives: OIDC login,
+JWT/JWKS validation, message launches, and the LTI Advantage services
+(Assignment & Grade Services, Names & Role Provisioning, Deep Linking).
+
+We vendor rather than depend on it so we own the code and can patch it; upstream
+is unmaintained (last release 2022) but implements a frozen specification. See
+``LICENSE`` at the repository root for the original MIT terms.
+
+Do not import from here directly in application code — use the public
+``ltitoolkit`` API and framework adapters instead. This subpackage is internal.
+"""
+
+# Upstream PyLTI1p3 release this vendored copy is based on.
+VENDORED_FROM = "PyLTI1p3 2.0.0"
+
+__version__ = "2.0.0"

ltitoolkit/core/actions.py

@@ -0,0 +1,6 @@
+import typing_extensions as te
+
+
+class Action:
+    OIDC_LOGIN: te.Final = "oidc_login"
+    MESSAGE_LAUNCH: te.Final = "message_launch"

ltitoolkit/core/assignments_grades.py

@@ -0,0 +1,300 @@
+import typing as t
+import typing_extensions as te
+from .exception import LtiException
+from .lineitem import LineItem
+from .grade import Grade
+from .lineitem import TLineItem
+from .service_connector import ServiceConnector, TServiceConnectorResponse
+
+
+TAssignmentsGradersData = te.TypedDict(
+    "TAssignmentsGradersData",
+    {
+        "scope": t.List[
+            te.Literal[
+                "https://purl.imsglobal.org/spec/lti-ags/scope/score",
+                "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
+                "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
+                "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly",
+            ]
+        ],
+        "lineitems": str,
+        "lineitem": str,
+    },
+    total=False,
+)
+
+
+class AssignmentsGradesService:
+    _service_connector: ServiceConnector
+    _service_data: TAssignmentsGradersData
+
+    def __init__(
+        self, service_connector: ServiceConnector, service_data: TAssignmentsGradersData
+    ):
+        self._service_connector = service_connector
+        self._service_data = service_data
+
+    def can_read_lineitem(self) -> bool:
+        return (
+            "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly"
+            in self._service_data["scope"]
+            or "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem"
+            in self._service_data["scope"]
+        )
+
+    def can_create_lineitem(self) -> bool:
+        return (
+            "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem"
+            in self._service_data["scope"]
+        )
+
+    def can_read_grades(self) -> bool:
+        return (
+            "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly"
+            in self._service_data["scope"]
+        )
+
+    def can_put_grade(self) -> bool:
+        return (
+            "https://purl.imsglobal.org/spec/lti-ags/scope/score"
+            in self._service_data["scope"]
+        )
+
+    def put_grade(
+        self, grade: Grade, lineitem: t.Optional[LineItem] = None
+    ) -> TServiceConnectorResponse:
+        """
+        Send grade to the LTI platform.
+
+        :param grade: Grade instance
+        :param lineitem: LineItem instance
+        :return: dict with HTTP response body and headers
+        """
+
+        if not self.can_put_grade():
+            raise LtiException("Can't put grade: Missing required scope")
+
+        if lineitem:
+            if not lineitem.get_id():
+                lineitem = self.find_or_create_lineitem(lineitem)
+            score_url = lineitem.get_id()
+        elif not lineitem and self._service_data.get("lineitem"):
+            score_url = self._service_data.get("lineitem")
+        else:
+            raise LtiException("Can't find lineitem to put grade")
+
+        assert score_url is not None
+        score_url = self._add_url_path_ending(score_url, "scores")
+        return self._service_connector.make_service_request(
+            self._service_data["scope"],
+            score_url,
+            is_post=True,
+            data=grade.get_value(),
+            content_type="application/vnd.ims.lis.v1.score+json",
+        )
+
+    def get_lineitem(self, lineitem_url: t.Optional[str] = None):
+        """
+        Retrieves an individual lineitem. By default retrieves the lineitem
+        associated with the LTI message.
+
+        :param lineitem_url: endpoint for LTI line item (optional)
+        :return: LineItem instance
+        """
+        if not self.can_read_lineitem():
+            raise LtiException("Can't read lineitem: Missing required scope")
+
+        if lineitem_url is None:
+            lineitem_url = self._service_data["lineitem"]
+
+        lineitem_response = self._service_connector.make_service_request(
+            self._service_data["scope"],
+            lineitem_url,
+            accept="application/vnd.ims.lis.v2.lineitem+json",
+        )
+        return LineItem(t.cast(TLineItem, lineitem_response["body"]))
+
+    def get_lineitems_page(
+        self, lineitems_url: t.Optional[str] = None
+    ) -> t.Tuple[list, t.Optional[str]]:
+        """
+        Get one page with line items.
+
+        :param lineitems_url: LTI platform's URL (optional)
+        :return: tuple in format: (list with line items, next page url)
+        """
+        if not self.can_read_lineitem():
+            raise LtiException("Can't read lineitem: Missing required scope")
+
+        if not lineitems_url:
+            lineitems_url = self._service_data["lineitems"]
+
+        lineitems = self._service_connector.make_service_request(
+            self._service_data["scope"],
+            lineitems_url,
+            accept="application/vnd.ims.lis.v2.lineitemcontainer+json",
+        )
+        if not isinstance(lineitems["body"], list):
+            raise LtiException("Unknown response type received for line items")
+        return lineitems["body"], lineitems["next_page_url"]
+
+    def get_lineitems(self) -> list:
+        """
+        Get list of all available line items.
+
+        :return: list
+        """
+        lineitems_res_lst = []
+        lineitems_url: t.Optional[str] = self._service_data["lineitems"]
+
+        while lineitems_url:
+            lineitems, lineitems_url = self.get_lineitems_page(lineitems_url)
+            lineitems_res_lst.extend(lineitems)
+
+        return lineitems_res_lst
+
+    def find_lineitem(self, prop_name: str, prop_value: t.Any) -> t.Optional[LineItem]:
+        """
+        Find line item by some property (ID/Tag).
+
+        :param prop_name: property name
+        :param prop_value: property value
+        :return: LineItem instance or None
+        """
+        lineitems_url: t.Optional[str] = self._service_data["lineitems"]
+
+        while lineitems_url:
+            lineitems, lineitems_url = self.get_lineitems_page(lineitems_url)
+            for lineitem in lineitems:
+                lineitem_prop_value = lineitem.get(prop_name)
+                if lineitem_prop_value == prop_value:
+                    return LineItem(lineitem)
+        return None
+
+    def find_lineitem_by_id(self, ln_id: str) -> t.Optional[LineItem]:
+        """
+        Find line item by ID.
+
+        :param ln_id: str
+        :return: LineItem instance or None
+        """
+        return self.find_lineitem("id", ln_id)
+
+    def find_lineitem_by_tag(self, tag: str) -> t.Optional[LineItem]:
+        """
+        Find line item by Tag.
+
+        :param tag: str
+        :return: LineItem instance or None
+        """
+        return self.find_lineitem("tag", tag)
+
+    def find_lineitem_by_resource_link_id(
+        self, resource_link_id: str
+    ) -> t.Optional[LineItem]:
+        """
+        Find line item by Resource LinkID.
+
+        :param resource_link_id: str
+        :return: LineItem instance or None
+        """
+        return self.find_lineitem("resourceLinkId", resource_link_id)
+
+    def find_lineitem_by_resource_id(self, resource_id: str) -> t.Optional[LineItem]:
+        """
+        Find line item by Resource ID.
+
+        :param resource_id: str
+        :return: LineItem instance or None
+        """
+        return self.find_lineitem("resourceId", resource_id)
+
+    def find_or_create_lineitem(
+        self, new_lineitem: LineItem, find_by: str = "tag"
+    ) -> LineItem:
+        """
+        Try to find line item using ID or Tag. New lime item will be created if nothing is found.
+
+        :param new_lineitem: LineItem instance
+        :param find_by: str ("tag"/"id")
+        :return: LineItem instance (based on response from the LTI platform)
+        """
+        if find_by == "tag":
+            tag = new_lineitem.get_tag()
+            if not tag:
+                raise LtiException("Tag value is not specified")
+            lineitem = self.find_lineitem_by_tag(tag)
+        elif find_by == "id":
+            line_id = new_lineitem.get_id()
+            if not line_id:
+                raise LtiException("ID value is not specified")
+            lineitem = self.find_lineitem_by_id(line_id)
+        elif find_by == "resource_link_id":
+            resource_link_id = new_lineitem.get_resource_link_id()
+            if not resource_link_id:
+                raise LtiException("Resource Link ID value is not specified")
+            lineitem = self.find_lineitem_by_resource_link_id(resource_link_id)
+        elif find_by == "resource_id":
+            resource_id = new_lineitem.get_resource_id()
+            if not resource_id:
+                raise LtiException("Resource ID value is not specified")
+            lineitem = self.find_lineitem_by_resource_id(resource_id)
+        else:
+            raise LtiException('Invalid "find_by" value: ' + str(find_by))
+
+        if lineitem:
+            return lineitem
+
+        if not self.can_create_lineitem():
+            raise LtiException("Can't create lineitem: Missing required scope")
+
+        created_lineitem = self._service_connector.make_service_request(
+            self._service_data["scope"],
+            self._service_data["lineitems"],
+            is_post=True,
+            data=new_lineitem.get_value(),
+            content_type="application/vnd.ims.lis.v2.lineitem+json",
+            accept="application/vnd.ims.lis.v2.lineitem+json",
+        )
+        if not isinstance(created_lineitem["body"], dict):
+            raise LtiException("Unknown response type received for create line item")
+        return LineItem(t.cast(TLineItem, created_lineitem["body"]))
+
+    def get_grades(self, lineitem: t.Optional[LineItem] = None) -> list:
+        """
+        Return all grades for the passed line item (across all users enrolled in the line item's context).
+
+        :param lineitem: LineItem instance
+        :return: list of grades
+        """
+        if not self.can_read_grades():
+            raise LtiException("Can't read grades: Missing required scope")
+
+        if lineitem:
+            lineitem_id = lineitem.get_id()
+        else:
+            lineitem_id = self._service_data.get("lineitem")
+
+        if not lineitem_id:
+            return []
+
+        results_url = self._add_url_path_ending(lineitem_id, "results")
+        scores = self._service_connector.make_service_request(
+            self._service_data["scope"],
+            results_url,
+            accept="application/vnd.ims.lis.v2.resultcontainer+json",
+        )
+        if not isinstance(scores["body"], list):
+            raise LtiException("Unknown response type received for results")
+        return scores["body"]
+
+    @staticmethod
+    def _add_url_path_ending(url: str, url_path_ending: str) -> str:
+        if "?" in url:
+            url_parts = url.split("?")
+            new_url = url_parts[0]
+            new_url += "" if new_url.endswith("/") else "/"
+            return new_url + url_path_ending + "?" + url_parts[1]
+        url += "" if url.endswith("/") else "/"
+        return url + url_path_ending

ltitoolkit/core/contrib/django/__init__.py

@@ -0,0 +1,5 @@
+# flake8: noqa
+from .message_launch import DjangoMessageLaunch
+from .oidc_login import DjangoOIDCLogin
+from .launch_data_storage.cache import DjangoCacheDataStorage
+from .lti1p3_tool_config import DjangoDbToolConf

ltitoolkit/core/contrib/django/cookie.py

@@ -0,0 +1,56 @@
+import http.cookies as Cookie  # type: ignore
+import django  # type: ignore
+from ltitoolkit.core.cookie import CookieService
+
+# Add support for the SameSite attribute (obsolete when PY37 is unsupported).
+# pylint: disable=protected-access
+if "samesite" not in Cookie.Morsel._reserved:  # type: ignore
+    Cookie.Morsel._reserved.setdefault("samesite", "SameSite")  # type: ignore
+
+
+class DjangoCookieService(CookieService):
+    _request = None
+    _cookie_data_to_set = None
+
+    def __init__(self, request):
+        self._request = request
+        self._cookie_data_to_set = {}
+
+    def _get_key(self, key):
+        return self._cookie_prefix + "-" + key
+
+    def get_cookie(self, name):
+        return self._request.get_cookie(self._get_key(name))
+
+    def set_cookie(self, name, value, exp=3600):
+        self._cookie_data_to_set[self._get_key(name)] = {
+            "value": value,
+            "exp": exp,
+        }
+
+    def update_response(self, response):
+        for key, cookie_data in self._cookie_data_to_set.items():
+            kwargs = {
+                "value": cookie_data["value"],
+                "max_age": cookie_data["exp"],
+                "secure": self._request.is_secure(),
+                "httponly": True,
+                "path": "/",
+            }
+
+            if self._request.is_secure():
+                # samesite argument was added in Django 2.1, but samesite could be set as None only from Django 3.1
+                # https://github.com/django/django/pull/11894
+                django_support_samesite_none = django.VERSION[0] > 3 or (
+                    django.VERSION[0] == 3 and django.VERSION[1] >= 1
+                )
+
+                # SameSite=None and Secure=True are required to work inside iframes
+                if django_support_samesite_none:
+                    kwargs["samesite"] = "None"
+                    response.set_cookie(key, **kwargs)
+                else:
+                    response.set_cookie(key, **kwargs)
+                    response.cookies[key]["samesite"] = "None"
+            else:
+                response.set_cookie(key, **kwargs)

ltitoolkit/core/contrib/django/launch_data_storage/cache.py

@@ -0,0 +1,10 @@
+from django.core.cache import caches  # type: ignore
+from ltitoolkit.core.launch_data_storage.cache import CacheDataStorage
+
+
+class DjangoCacheDataStorage(CacheDataStorage):
+    _cache = None
+
+    def __init__(self, cache_name="default", **kwargs):
+        self._cache = caches[cache_name]
+        super().__init__(cache_name, **kwargs)

ltitoolkit/core/contrib/django/lti1p3_tool_config/__init__.py

@@ -0,0 +1,139 @@
+import json
+
+from ltitoolkit.core.deployment import Deployment
+from ltitoolkit.core.exception import LtiException
+from ltitoolkit.core.registration import Registration
+from ltitoolkit.core.tool_config.abstract import ToolConfAbstract
+
+
+default_app_config = (
+    "ltitoolkit.core.contrib.django.lti1p3_tool_config.apps.PyLTI1p3ToolConfig"
+)
+
+
+class DjangoDbToolConf(ToolConfAbstract):
+    _lti_tools = None
+    _tools_cls = None
+    _keys_cls = None
+
+    def __init__(self):
+        # pylint: disable=import-outside-toplevel
+        from .models import LtiTool, LtiToolKey
+
+        super().__init__()
+        self._lti_tools = {}
+        self._tools_cls = LtiTool
+        self._keys_cls = LtiToolKey
+
+    def get_lti_tool(self, iss, client_id):
+        # pylint: disable=no-member
+        lti_tool = (
+            self._lti_tools.get(iss)
+            if client_id is None
+            else self._lti_tools.get(iss, {}).get(client_id)
+        )
+        if lti_tool:
+            return lti_tool
+
+        if client_id is None:
+            lti_tool = (
+                self._tools_cls.objects.filter(issuer=iss, is_active=True)
+                .order_by("use_by_default")
+                .first()
+            )
+        else:
+            try:
+                lti_tool = self._tools_cls.objects.get(
+                    issuer=iss, client_id=client_id, is_active=True
+                )
+            except self._tools_cls.DoesNotExist:
+                pass
+
+        if lti_tool is None:
+            raise LtiException(
+                f"iss {iss} [client_id={client_id}] not found in settings"
+            )
+
+        if client_id is None:
+            self._lti_tools[iss] = lti_tool
+        else:
+            if iss not in self._lti_tools:
+                self._lti_tools[iss] = {}
+            self._lti_tools[iss][client_id] = lti_tool
+
+        return lti_tool
+
+    def check_iss_has_one_client(self, iss):
+        return False
+
+    def check_iss_has_many_clients(self, iss):
+        return True
+
+    def find_registration_by_issuer(self, iss, *args, **kwargs):
+        pass
+
+    def find_registration_by_params(self, iss, client_id, *args, **kwargs):
+        lti_tool = self.get_lti_tool(iss, client_id)
+        auth_audience = lti_tool.auth_audience if lti_tool.auth_audience else None
+        key_set = json.loads(lti_tool.key_set) if lti_tool.key_set else None
+        key_set_url = lti_tool.key_set_url if lti_tool.key_set_url else None
+        tool_public_key = (
+            lti_tool.tool_key.public_key if lti_tool.tool_key.public_key else None
+        )
+
+        reg = Registration()
+        reg.set_auth_login_url(lti_tool.auth_login_url).set_auth_token_url(
+            lti_tool.auth_token_url
+        ).set_auth_audience(auth_audience).set_client_id(
+            lti_tool.client_id
+        ).set_key_set(
+            key_set
+        ).set_key_set_url(
+            key_set_url
+        ).set_issuer(
+            lti_tool.issuer
+        ).set_tool_private_key(
+            lti_tool.tool_key.private_key
+        ).set_tool_public_key(
+            tool_public_key
+        )
+        return reg
+
+    def find_deployment(self, iss, deployment_id):
+        pass
+
+    def find_deployment_by_params(self, iss, deployment_id, client_id, *args, **kwargs):
+        lti_tool = self.get_lti_tool(iss, client_id)
+        deployment_ids = (
+            json.loads(lti_tool.deployment_ids) if lti_tool.deployment_ids else []
+        )
+        if deployment_id not in deployment_ids:
+            return None
+        d = Deployment()
+        return d.set_deployment_id(deployment_id)
+
+    def get_jwks(self, iss=None, client_id=None, **kwargs):
+        # pylint: disable=no-member
+        search_kwargs = {}
+        if iss:
+            search_kwargs["lti_tools__issuer"] = iss
+        if client_id:
+            search_kwargs["lti_tools__client_id"] = client_id
+
+        if search_kwargs:
+            search_kwargs["lti_tools__is_active"] = True
+            qs = self._keys_cls.objects.filter(**search_kwargs)
+        else:
+            qs = self._keys_cls.objects.all()
+
+        jwks = []
+        public_key_lst = []
+
+        for key in qs:
+            if key.public_key and key.public_key not in public_key_lst:
+                if key.public_jwk:
+                    jwks.append(json.loads(key.public_jwk))
+                else:
+                    jwks.append(Registration.get_jwk(key.public_key))
+                public_key_lst.append(key.public_key)
+        return {"keys": jwks}

ltitoolkit/core/contrib/django/lti1p3_tool_config/admin.py

@@ -0,0 +1,48 @@
+# mypy: ignore-errors
+from django.contrib import admin
+
+from .models import LtiTool, LtiToolKey
+
+
+class LtiToolKeyAdmin(admin.ModelAdmin):
+    """Admin for LTI Tool Key"""
+
+    list_display = ("id", "name")
+
+    add_fieldsets = ((None, {"fields": ("name", "private_key", "public_key")}),)
+
+    change_fieldsets = (
+        (None, {"fields": ("name", "private_key", "public_key", "public_jwk")}),
+    )
+
+    readonly_fields = ("public_jwk",)
+
+    def get_form(self, request, obj=None, **kwargs):  # pylint: disable=arguments-differ
+        help_texts = {
+            "public_key_jwk_json": "Tool's generated Public key presented as JWK."
+        }
+        kwargs.update({"help_texts": help_texts})
+        return super().get_form(request, obj, **kwargs)
+
+    def get_fieldsets(self, request, obj=None):  # pylint: disable=unused-argument
+        if not obj:
+            return self.add_fieldsets
+        return self.change_fieldsets
+
+
+class LtiToolAdmin(admin.ModelAdmin):
+    """Admin for LTI Tool"""
+
+    search_fields = (
+        "title",
+        "issuer",
+        "client_id",
+        "auth_login_url",
+        "auth_token_url",
+        "key_set_url",
+    )
+    list_display = ("id", "title", "is_active", "issuer", "client_id", "deployment_ids")
+
+
+admin.site.register(LtiToolKey, LtiToolKeyAdmin)
+admin.site.register(LtiTool, LtiToolAdmin)