ff-ltitoolkit 0.1.0__py3-none-any.whl

ltitoolkit/core/tool_config/dict.py

@@ -0,0 +1,253 @@
+import typing as t
+import typing_extensions as te
+from ..deployment import Deployment
+from ..registration import Registration, TKeySet
+from ..request import Request
+from .abstract import ToolConfAbstract
+
+TIssConf = te.TypedDict(
+    "TIssConf",
+    {
+        "default": bool,
+        "client_id": str,
+        "auth_login_url": str,
+        "auth_token_url": str,
+        "auth_audience": t.Optional[str],
+        "key_set_url": t.Optional[str],
+        "key_set": t.Optional[TKeySet],
+        "deployment_ids": t.List[str],
+        "private_key_file": t.Optional[str],
+        "public_key_file": t.Optional[str],
+    },
+    total=False,
+)
+
+TJsonData = t.Dict[str, t.Union[t.List[TIssConf], TIssConf]]
+
+
+class ToolConfDict(ToolConfAbstract[Request]):
+    _config = None
+    _private_key_one_client: t.Dict[str, str]
+    _public_key_one_client: t.Dict[str, str]
+    _private_key_many_clients: t.Dict[str, t.Dict[str, str]]
+    _public_key_many_clients: t.Dict[str, t.Dict[str, str]]
+
+    def __init__(self, json_data: TJsonData):
+        """
+        json_data is a dict where each key is issuer and value is issuer's configuration.
+        Configuration could be set in two formats:
+
+        1. { ... "iss": { ... "client_id: "client" ... }, ... }
+        In this case the library will work in the concept: one issuer ~ one client-id
+
+        2. { ... "iss": [ { ... "client_id: "client1" ... }, { ... "client_id: "client2" ... } ], ... }
+        In this case the library will work in concept: one issuer ~ many client-ids
+
+        Example:
+            {
+                "iss1": [{
+                        "default": True,
+                        "client_id": "client_id1",
+                        "auth_login_url": "auth_login_url1",
+                        "auth_token_url": "auth_token_url1",
+                        "auth_audience": None,
+                        "key_set_url": "key_set_url1",
+                        "key_set": None,
+                        "deployment_ids": ["deployment_id1", "deployment_id2"]
+                    }, {
+                        "default": False,
+                        "client_id": "client_id2",
+                        "auth_login_url": "auth_login_url2",
+                        "auth_token_url": "auth_token_url2",
+                        "auth_audience": None,
+                        "key_set_url": "key_set_url2",
+                        "key_set": None,
+                        "deployment_ids": ["deployment_id3", "deployment_id4"]
+                    }],
+                "iss2": [ .... ]
+            }
+
+        default (bool) - this iss config will be used in case if client-id was not passed on the login step
+        client_id - this is the id received in the 'aud' during a launch
+        auth_login_url - the platform's OIDC login endpoint
+        auth_token_url - the platform's service authorization endpoint
+        auth_audience - the platform's OAuth2 Audience (aud). Is used to get platform's access token,
+                        Usually the same as "auth_token_url" but in the common case could be a different url
+        key_set_url - the platform's JWKS endpoint
+        key_set - in case if platform's JWKS endpoint somehow unavailable you may paste JWKS here
+        deployment_ids (list) - The deployment_id passed by the platform during launch
+        """
+        super().__init__()
+        if not isinstance(json_data, dict):
+            raise Exception("Invalid tool conf format. Must be dict")
+
+        for iss, iss_conf in json_data.items():
+            if isinstance(iss_conf, dict):
+                self.set_iss_has_one_client(iss)
+                self._validate_iss_config_item(iss, iss_conf)
+            elif isinstance(iss_conf, list):
+                self.set_iss_has_many_clients(iss)
+                for v in iss_conf:
+                    self._validate_iss_config_item(iss, v)
+            else:
+                raise Exception(
+                    "Invalid tool conf format. Allowed types of elements: list or dict"
+                )
+
+        self._config = json_data
+        self._private_key_one_client = {}
+        self._private_key_many_clients = {}
+        self._public_key_one_client = {}
+        self._public_key_many_clients = {}
+
+    def _validate_iss_config_item(self, iss: str, iss_conf: TIssConf):
+        if not isinstance(iss_conf, dict):
+            raise Exception(
+                f"Invalid configuration {iss} for the {str(iss_conf)} issuer. Must be dict"
+            )
+        required_keys = [
+            "auth_login_url",
+            "auth_token_url",
+            "client_id",
+            "deployment_ids",
+        ]
+        for key in required_keys:
+            if key not in iss_conf:
+                raise Exception(
+                    f"Key '{key}' is missing in the {str(iss_conf)} config for the {iss} issuer"
+                )
+        if not isinstance(iss_conf["deployment_ids"], list):
+            raise Exception(
+                f"Invalid deployment_ids value in the {str(iss_conf)} config for the {iss} issuer. "
+                f"Must be a list"
+            )
+
+    def _get_registration(self, iss: str, iss_conf: TIssConf) -> Registration:
+        reg = Registration()
+        reg.set_auth_login_url(iss_conf["auth_login_url"]).set_auth_token_url(
+            iss_conf["auth_token_url"]
+        ).set_client_id(iss_conf["client_id"]).set_key_set(
+            iss_conf.get("key_set")
+        ).set_key_set_url(
+            iss_conf.get("key_set_url")
+        ).set_issuer(
+            iss
+        ).set_tool_private_key(
+            self.get_private_key(iss, iss_conf["client_id"])
+        )
+        auth_audience = iss_conf.get("auth_audience")
+        if auth_audience:
+            reg.set_auth_audience(auth_audience)
+        public_key = self.get_public_key(iss, iss_conf["client_id"])
+        if public_key:
+            reg.set_tool_public_key(public_key)
+        return reg
+
+    def _get_deployment(self, iss_conf: TIssConf, deployment_id: str):
+        if deployment_id not in iss_conf["deployment_ids"]:
+            return None
+        d = Deployment()
+        return d.set_deployment_id(deployment_id)
+
+    def find_registration_by_issuer(self, iss: str, *args, **kwargs):
+        # pylint: disable=unused-argument
+        iss_conf = self.get_iss_config(iss)
+        return self._get_registration(iss, iss_conf)
+
+    def find_registration_by_params(self, iss: str, client_id: str, *args, **kwargs):
+        # pylint: disable=unused-argument
+        iss_conf = self.get_iss_config(iss, client_id)
+        return self._get_registration(iss, iss_conf)
+
+    def find_deployment(self, iss: str, deployment_id: str):
+        iss_conf = self.get_iss_config(iss)
+        return self._get_deployment(iss_conf, deployment_id)
+
+    def find_deployment_by_params(
+        self, iss: str, deployment_id: str, client_id: str, *args, **kwargs
+    ):
+        # pylint: disable=unused-argument
+        iss_conf = self.get_iss_config(iss, client_id)
+        return self._get_deployment(iss_conf, deployment_id)
+
+    def set_public_key(
+        self, iss: str, key_content: str, client_id: t.Optional[str] = None
+    ):
+        if self.check_iss_has_many_clients(iss):
+            if not client_id:
+                raise Exception("Can't set public key: missing client_id")
+            if iss not in self._public_key_many_clients:
+                self._public_key_many_clients[iss] = {}
+            self._public_key_many_clients[iss][client_id] = key_content
+        else:
+            self._public_key_one_client[iss] = key_content
+
+    def get_public_key(self, iss: str, client_id: t.Optional[str] = None):
+        if self.check_iss_has_many_clients(iss):
+            if not client_id:
+                raise Exception("Can't get public key: missing client_id")
+            clients_dict = self._public_key_many_clients.get(iss, {})
+            if not isinstance(clients_dict, dict):
+                raise Exception("Invalid clients data")
+            return clients_dict.get(client_id)
+        return self._public_key_one_client.get(iss)
+
+    def set_private_key(
+        self, iss: str, key_content: str, client_id: t.Optional[str] = None
+    ):
+        if self.check_iss_has_many_clients(iss):
+            if not client_id:
+                raise Exception("Can't set private key: missing client_id")
+            if iss not in self._private_key_many_clients:
+                self._private_key_many_clients[iss] = {}
+            self._private_key_many_clients[iss][client_id] = key_content  # type: ignore
+        else:
+            self._private_key_one_client[iss] = key_content
+
+    def get_private_key(self, iss: str, client_id: t.Optional[str] = None):
+        if self.check_iss_has_many_clients(iss):
+            if not client_id:
+                raise Exception("Can't get private key: missing client_id")
+            clients_dict = self._private_key_many_clients.get(iss, {})
+            if not isinstance(clients_dict, dict):
+                raise Exception("Invalid clients data")
+            return clients_dict.get(client_id)
+        return self._private_key_one_client.get(iss)
+
+    def get_iss_config(self, iss: str, client_id: t.Optional[str] = None):
+        if not self._config:
+            raise Exception("Config is not set")
+        if iss not in self._config:
+            raise Exception(f"iss {iss} not found in settings")
+        config_iss = self._config[iss]
+
+        if isinstance(config_iss, list):
+            items_len = len(config_iss)
+            for subitem in config_iss:
+                # pylint: disable=too-many-boolean-expressions
+                if (
+                    (client_id and subitem["client_id"] == client_id)
+                    or (not client_id and subitem.get("default", False))
+                    or (not client_id and items_len == 1)
+                ):
+                    return subitem
+            raise Exception(f"iss {iss} [client_id={client_id}] not found in settings")
+        return config_iss
+
+    def get_jwks(
+        self, iss: t.Optional[str] = None, client_id: t.Optional[str] = None, **kwargs
+    ):
+        # pylint: disable=unused-argument
+        if iss or client_id:
+            return super().get_jwks(iss, client_id)
+
+        public_keys = []
+        for iss_item1 in self._public_key_one_client.values():
+            if iss_item1 not in public_keys:
+                public_keys.append(iss_item1)
+        for iss_item2 in self._public_key_many_clients.values():
+            for pub_key in iss_item2.values():
+                if pub_key not in public_keys:
+                    public_keys.append(pub_key)
+
+        return {"keys": [Registration.get_jwk(k) for k in public_keys]}

ltitoolkit/core/tool_config/json_file.py

@@ -0,0 +1,100 @@
+import typing as t
+import json
+import os
+
+from .dict import ToolConfDict, TIssConf, TJsonData
+
+
+class ToolConfJsonFile(ToolConfDict):
+    _configs_dir: str
+
+    def __init__(self, config_file: str):
+        """
+        config_file contains JSON with issuers settings.
+        Each key is issuer and value is issuer's configuration.
+        Configuration could be set in two formats:
+
+        1. { ... "iss": { ... "client_id: "client" ... }, ... }
+        In this case the library will work in the concept: one issuer ~ one client-id
+
+        2. { ... "iss": [ { ... "client_id: "client1" ... }, { ... "client_id: "client2" ... } ], ... }
+        In this case the library will work in concept: one issuer ~ many client-ids
+
+        Example:
+            {
+                "iss1": [{
+                        "default": true,
+                        "client_id": "client_id1",
+                        "auth_login_url": "auth_login_url1",
+                        "auth_token_url": "auth_token_url1",
+                        "auth_audience": null,
+                        "key_set_url": "key_set_url1",
+                        "key_set": null,
+                        "private_key_file": "private.key",
+                        "public_key_file": "public.key",
+                        "deployment_ids": ["deployment_id1", "deployment_id2"]
+                    }, {
+                        "default": false,
+                        "client_id": "client_id2",
+                        "auth_login_url": "auth_login_url2",
+                        "auth_token_url": "auth_token_url2",
+                        "auth_audience": null,
+                        "key_set_url": "key_set_url2",
+                        "key_set": null,
+                        "private_key_file": "private.key",
+                        "public_key_file": "public.key",
+                        "deployment_ids": ["deployment_id3", "deployment_id4"]
+                    }],
+                "iss2": [ .... ]
+            }
+
+        default (bool) - this iss config will be used in case if client-id was not passed on the login step
+        client_id - this is the id received in the 'aud' during a launch
+        auth_login_url - the platform's OIDC login endpoint
+        auth_token_url - the platform's service authorization endpoint
+        auth_audience - the platform's OAuth2 Audience (aud). Is used to get platform's access token,
+                        Usually the same as "auth_token_url" but in the common case could be a different url
+        key_set_url - the platform's JWKS endpoint
+        key_set - in case if platform's JWKS endpoint somehow unavailable you may paste JWKS here
+        private_key_file - relative path to the tool's private key
+        public_key_file - relative path to the tool's public key
+        deployment_ids (list) - The deployment_id passed by the platform during launch
+        """
+        if not os.path.isfile(config_file):
+            raise Exception("LTI tool config file not found: " + config_file)
+        self._configs_dir = os.path.dirname(config_file)
+
+        with open(config_file, encoding="utf-8") as cfg:
+            iss_conf_dict: TJsonData = json.loads(cfg.read())
+            super().__init__(iss_conf_dict)
+
+        for iss in iss_conf_dict:
+            if isinstance(iss_conf_dict[iss], list):
+                for iss_conf in iss_conf_dict[iss]:
+                    client_id = t.cast(TIssConf, iss_conf).get("client_id")
+                    self._process_iss_conf_item(
+                        t.cast(TIssConf, iss_conf), iss, client_id
+                    )
+            else:
+                self._process_iss_conf_item(t.cast(TIssConf, iss_conf_dict[iss]), iss)
+
+    def _process_iss_conf_item(
+        self, iss_conf: TIssConf, iss: str, client_id: t.Optional[str] = None
+    ):
+        private_key_file = iss_conf.get("private_key_file")
+        if not private_key_file:
+            raise Exception("iss config error: private_key_file not found")
+
+        if not private_key_file.startswith("/"):
+            private_key_file = self._configs_dir + "/" + private_key_file
+
+        with open(private_key_file, encoding="utf-8") as prf:
+            self.set_private_key(iss, prf.read(), client_id=client_id)
+
+        public_key_file = iss_conf.get("public_key_file", None)
+        if public_key_file:
+            if not public_key_file.startswith("/"):
+                public_key_file = self._configs_dir + "/" + public_key_file
+
+            with open(public_key_file, encoding="utf-8") as pubf:
+                self.set_public_key(iss, pubf.read(), client_id=client_id)

ltitoolkit/core/utils.py

@@ -0,0 +1,10 @@
+import urllib.parse as urlparse  # type: ignore
+from urllib.parse import urlencode  # type: ignore
+
+
+def add_param_to_url(url: str, param_name: str, param_value: object) -> str:
+    url_parts = list(urlparse.urlparse(url))
+    query = dict(urlparse.parse_qsl(url_parts[4]))
+    query[str(param_name)] = str(param_value)
+    url_parts[4] = urlencode(query)
+    return urlparse.urlunparse(url_parts)

ltitoolkit/dynamic_registration/__init__.py

@@ -0,0 +1,39 @@
+"""LTI 1.3 Dynamic Registration (1EdTech spec).
+
+Lets an LMS admin install the tool by pasting a single URL and clicking submit:
+the tool fetches the LMS's ``openid-configuration``, learns its endpoints
+automatically, registers itself, and stores the returned ``client_id`` — no
+manual copying of credentials. This is what makes "works with any LMS without
+re-reading the docs" real.
+
+Spec: https://www.imsglobal.org/spec/lti-dr/v1p0
+"""
+
+from .models import (
+    DEFAULT_CLAIMS,
+    DEFAULT_SCOPES,
+    MESSAGE_DEEP_LINKING,
+    MESSAGE_RESOURCE_LINK,
+    PlatformConfiguration,
+    ToolMessage,
+    ToolRegistration,
+    ToolRegistrationConfig,
+)
+from .service import DynamicRegistrationService
+from .store import InMemoryRegistrationStore, RegistrationStore
+from .tool_conf import StoredToolConf
+
+__all__ = [
+    "DynamicRegistrationService",
+    "ToolRegistrationConfig",
+    "ToolMessage",
+    "ToolRegistration",
+    "PlatformConfiguration",
+    "RegistrationStore",
+    "InMemoryRegistrationStore",
+    "StoredToolConf",
+    "DEFAULT_SCOPES",
+    "DEFAULT_CLAIMS",
+    "MESSAGE_RESOURCE_LINK",
+    "MESSAGE_DEEP_LINKING",
+]

ltitoolkit/dynamic_registration/models.py

@@ -0,0 +1,192 @@
+"""Data models and constants for LTI 1.3 Dynamic Registration.
+
+Spec: https://www.imsglobal.org/spec/lti-dr/v1p0
+
+The flow exchanges two JSON documents:
+- the platform's *OpenID configuration* (:class:`PlatformConfiguration`), and
+- the tool's *registration request* (built by :class:`ToolRegistrationConfig`).
+
+The platform replies with a ``client_id`` (and possibly a ``deployment_id``),
+captured as a :class:`ToolRegistration`.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+from urllib.parse import urlparse
+
+# -- Spec claim URIs / constants -------------------------------------------
+
+LTI_TOOL_CONFIGURATION = "https://purl.imsglobal.org/spec/lti-tool-configuration"
+LTI_PLATFORM_CONFIGURATION = "https://purl.imsglobal.org/spec/lti-platform-configuration"
+
+MESSAGE_RESOURCE_LINK = "LtiResourceLinkRequest"
+MESSAGE_DEEP_LINKING = "LtiDeepLinkingRequest"
+
+# Sent to the platform's HTML5 Web Message channel to end registration.
+CLOSE_SUBJECT = "org.imsglobal.lti.close"
+
+# LTI Advantage service scopes we request by default.
+SCOPE_AGS_LINEITEM = "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem"
+SCOPE_AGS_RESULT = "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly"
+SCOPE_AGS_SCORE = "https://purl.imsglobal.org/spec/lti-ags/scope/score"
+SCOPE_NRPS = "https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly"
+
+DEFAULT_SCOPES: tuple[str, ...] = (
+    SCOPE_AGS_LINEITEM,
+    SCOPE_AGS_RESULT,
+    SCOPE_AGS_SCORE,
+    SCOPE_NRPS,
+)
+
+DEFAULT_CLAIMS: tuple[str, ...] = ("iss", "sub", "name", "given_name", "family_name", "email")
+
+
+@dataclass
+class ToolMessage:
+    """A message type the tool supports (resource link launch / deep linking)."""
+
+    type: str
+    target_link_uri: str | None = None
+    label: str | None = None
+    icon_uri: str | None = None
+    placements: tuple[str, ...] | None = None
+    custom_parameters: dict[str, str] | None = None
+
+    def to_dict(self) -> dict[str, t.Any]:
+        data: dict[str, t.Any] = {"type": self.type}
+        if self.target_link_uri:
+            data["target_link_uri"] = self.target_link_uri
+        if self.label:
+            data["label"] = self.label
+        if self.icon_uri:
+            data["icon_uri"] = self.icon_uri
+        if self.placements:
+            data["placements"] = list(self.placements)
+        if self.custom_parameters:
+            data["custom_parameters"] = dict(self.custom_parameters)
+        return data
+
+
+@dataclass
+class PlatformConfiguration:
+    """The platform's OpenID configuration document (only fields we need)."""
+
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    jwks_uri: str
+    registration_endpoint: str
+    authorization_server: str | None = None
+    scopes_supported: tuple[str, ...] = ()
+    product_family_code: str | None = None
+    raw: dict[str, t.Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: t.Mapping[str, t.Any]) -> PlatformConfiguration:
+        lti = data.get(LTI_PLATFORM_CONFIGURATION, {}) or {}
+        required = (
+            "issuer",
+            "authorization_endpoint",
+            "token_endpoint",
+            "jwks_uri",
+            "registration_endpoint",
+        )
+        missing = [k for k in required if not data.get(k)]
+        if missing:
+            raise ValueError(
+                f"Platform OpenID configuration is missing fields: {', '.join(missing)}"
+            )
+        return cls(
+            issuer=data["issuer"],
+            authorization_endpoint=data["authorization_endpoint"],
+            token_endpoint=data["token_endpoint"],
+            jwks_uri=data["jwks_uri"],
+            registration_endpoint=data["registration_endpoint"],
+            authorization_server=data.get("authorization_server"),
+            scopes_supported=tuple(data.get("scopes_supported", []) or []),
+            product_family_code=lti.get("product_family_code"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class ToolRegistration:
+    """The persisted result of a successful registration."""
+
+    issuer: str
+    client_id: str
+    auth_login_url: str
+    auth_token_url: str
+    key_set_url: str
+    auth_audience: str | None = None
+    deployment_ids: tuple[str, ...] = ()
+
+
+@dataclass
+class ToolRegistrationConfig:
+    """Static description of this tool, used to build the registration request."""
+
+    client_name: str
+    initiate_login_uri: str
+    redirect_uris: tuple[str, ...]
+    jwks_uri: str
+    target_link_uri: str
+    scopes: tuple[str, ...] = DEFAULT_SCOPES
+    claims: tuple[str, ...] = DEFAULT_CLAIMS
+    domain: str | None = None
+    logo_uri: str | None = None
+    description: str | None = None
+    custom_parameters: dict[str, str] | None = None
+    contacts: tuple[str, ...] | None = None
+    messages: tuple[ToolMessage, ...] = ()
+
+    def _domain(self) -> str:
+        return self.domain or urlparse(self.target_link_uri).netloc
+
+    def _messages(self) -> list[ToolMessage]:
+        if self.messages:
+            return list(self.messages)
+        # Sensible default: support a basic resource-link launch.
+        return [ToolMessage(type=MESSAGE_RESOURCE_LINK)]
+
+    def build_request(self, platform: PlatformConfiguration) -> dict[str, t.Any]:
+        """Build the OpenID client registration body to POST to the platform.
+
+        Requested scopes are intersected with the platform's
+        ``scopes_supported`` when the platform advertises them.
+        """
+        if platform.scopes_supported:
+            scopes = [s for s in self.scopes if s in platform.scopes_supported]
+        else:
+            scopes = list(self.scopes)
+
+        lti_config: dict[str, t.Any] = {
+            "domain": self._domain(),
+            "target_link_uri": self.target_link_uri,
+            "claims": list(self.claims),
+            "messages": [m.to_dict() for m in self._messages()],
+        }
+        if self.description:
+            lti_config["description"] = self.description
+        if self.custom_parameters:
+            lti_config["custom_parameters"] = dict(self.custom_parameters)
+
+        body: dict[str, t.Any] = {
+            "application_type": "web",
+            "response_types": ["id_token"],
+            "grant_types": ["client_credentials", "implicit"],
+            "initiate_login_uri": self.initiate_login_uri,
+            "redirect_uris": list(self.redirect_uris),
+            "client_name": self.client_name,
+            "jwks_uri": self.jwks_uri,
+            "token_endpoint_auth_method": "private_key_jwt",
+            "scope": " ".join(scopes),
+            LTI_TOOL_CONFIGURATION: lti_config,
+        }
+        if self.logo_uri:
+            body["logo_uri"] = self.logo_uri
+        if self.contacts:
+            body["contacts"] = list(self.contacts)
+        return body