ff-ltitoolkit 0.1.0__py3-none-any.whl

ltitoolkit/core/registration.py

@@ -0,0 +1,119 @@
+import json
+import typing as t
+import typing_extensions as te
+from jwcrypto.jwk import JWK  # type: ignore
+
+
+TKey = te.TypedDict("TKey", {"kid": str, "alg": str}, total=True)
+TKeySet = te.TypedDict("TKeySet", {"keys": t.List[TKey]}, total=True)
+
+
+class Registration:
+    _issuer: t.Optional[str] = None
+    _client_id: t.Optional[str] = None
+    _key_set_url: t.Optional[str] = None
+    _key_set: t.Optional[TKeySet] = None
+    _auth_token_url: t.Optional[str] = None
+    _auth_login_url: t.Optional[str] = None
+    _tool_private_key: t.Optional[str] = None
+    _auth_audience: t.Optional[str] = None
+    _tool_public_key = None
+    _kid: t.Optional[str] = None
+
+    def get_issuer(self) -> t.Optional[str]:
+        return self._issuer
+
+    def set_issuer(self, issuer: str) -> "Registration":
+        self._issuer = issuer
+        return self
+
+    def get_client_id(self) -> t.Optional[str]:
+        return self._client_id
+
+    def set_client_id(self, client_id: str) -> "Registration":
+        self._client_id = client_id
+        return self
+
+    def get_key_set(self) -> t.Optional[TKeySet]:
+        return self._key_set
+
+    def set_key_set(self, key_set: t.Optional[TKeySet]) -> "Registration":
+        self._key_set = key_set
+        return self
+
+    def get_key_set_url(self) -> t.Optional[str]:
+        return self._key_set_url
+
+    def set_key_set_url(self, key_set_url: t.Optional[str]) -> "Registration":
+        self._key_set_url = key_set_url
+        return self
+
+    def get_auth_token_url(self) -> t.Optional[str]:
+        return self._auth_token_url
+
+    def set_auth_token_url(self, auth_token_url: str) -> "Registration":
+        self._auth_token_url = auth_token_url
+        return self
+
+    def get_auth_login_url(self) -> t.Optional[str]:
+        return self._auth_login_url
+
+    def set_auth_login_url(self, auth_login_url: str) -> "Registration":
+        self._auth_login_url = auth_login_url
+        return self
+
+    def get_auth_audience(self) -> t.Optional[str]:
+        return self._auth_audience
+
+    def set_auth_audience(self, auth_audience: str) -> "Registration":
+        self._auth_audience = auth_audience
+        return self
+
+    def get_tool_private_key(self) -> t.Optional[str]:
+        return self._tool_private_key
+
+    def set_tool_private_key(self, tool_private_key: str) -> "Registration":
+        self._tool_private_key = tool_private_key
+        return self
+
+    def get_tool_public_key(self):
+        return self._tool_public_key
+
+    def set_tool_public_key(self, tool_public_key) -> "Registration":
+        self._tool_public_key = tool_public_key
+        return self
+
+    @classmethod
+    def get_jwk(cls, public_key: str) -> t.Mapping[str, t.Any]:
+        jwk_obj = JWK.from_pem(public_key.encode("utf-8"))
+        public_jwk = json.loads(jwk_obj.export_public())
+        public_jwk["alg"] = "RS256"
+        public_jwk["use"] = "sig"
+        return public_jwk
+
+    def get_jwks(self) -> t.List[t.Mapping[str, t.Any]]:
+        keys = []
+        public_key = self.get_tool_public_key()
+        if public_key:
+            keys.append(Registration.get_jwk(public_key))
+        return keys
+
+    def set_kid(self, kid: str) -> "Registration":
+        """Pin the ``kid`` used in signed client assertions.
+
+        Set this when the tool publishes its JWKS with an explicit key id (e.g.
+        a named ``kid`` rather than a PEM-derived thumbprint), so the assertion
+        header ``kid`` matches a key the platform can resolve in the JWKS. When
+        unset, ``get_kid`` falls back to the public key's own ``kid`` (if any).
+        """
+        self._kid = kid
+        return self
+
+    def get_kid(self) -> t.Optional[str]:
+        if self._kid:
+            return self._kid
+        key = self.get_tool_public_key()
+        if key:
+            jwk = Registration.get_jwk(key)
+            return jwk.get("kid") if jwk else None
+        return None

ltitoolkit/core/request.py

@@ -0,0 +1,17 @@
+from abc import ABCMeta, abstractmethod
+
+
+class Request:
+    __metaclass__ = ABCMeta
+
+    @property
+    def session(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def is_secure(self) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_param(self, key: str) -> str:
+        raise NotImplementedError

ltitoolkit/core/roles.py

@@ -0,0 +1,109 @@
+from abc import ABCMeta
+import typing as t
+import typing_extensions as te
+
+
+class RoleType:
+    SYSTEM: te.Final = "system"
+    INSTITUTION: te.Final = "institution"
+    CONTEXT: te.Final = "membership"
+
+
+class AbstractRole:
+    __metaclass__ = ABCMeta
+    _base_prefix: str = "http://purl.imsglobal.org/vocab/lis/v2"
+    _role_types = [RoleType.SYSTEM, RoleType.INSTITUTION, RoleType.CONTEXT]
+    _jwt_roles: t.List[str] = []
+    _common_roles: t.Optional[t.Tuple] = None
+    _system_roles: t.Optional[t.Tuple] = None
+    _institution_roles: t.Optional[t.Tuple] = None
+    _context_roles: t.Optional[t.Tuple] = None
+
+    def __init__(self, jwt_body):
+        self._jwt_roles = jwt_body.get(
+            "https://purl.imsglobal.org/spec/lti/claim/roles", []
+        )
+
+    def check(self) -> bool:
+        for role_str in self._jwt_roles:
+            role_name, role_type = self.parse_role_str(role_str)
+            res = self._check_access(role_name, role_type)
+            if res:
+                return True
+        return False
+
+    def _check_access(self, role_name: str, role_type: t.Optional[str] = None):
+        return bool(
+            (
+                self._system_roles
+                and role_type == RoleType.SYSTEM
+                and role_name in self._system_roles
+            )
+            or (
+                self._institution_roles
+                and role_type == RoleType.INSTITUTION
+                and role_name in self._institution_roles
+            )
+            or (
+                self._context_roles
+                and role_type == RoleType.CONTEXT
+                and role_name in self._context_roles
+            )
+            or (
+                self._common_roles
+                and role_type is None
+                and role_name in self._common_roles
+            )
+        )
+
+    def parse_role_str(self, role_str: str) -> t.Tuple[str, t.Optional[str]]:
+        if role_str.startswith(self._base_prefix):
+            role = role_str[len(self._base_prefix) :]
+            role_parts = role.split("/")
+            role_name_parts = role.split("#")
+
+            if len(role_parts) > 1 and len(role_name_parts) > 1:
+                role_type = role_parts[1]
+                role_name = role_name_parts[1]
+                if role_type in self._role_types:
+                    return role_name, role_type
+                return role_name, None
+        return role_str, None
+
+
+class StaffRole(AbstractRole):
+    _system_roles = ("Administrator", "SysAdmin")
+    _institution_roles = ("Faculty", "SysAdmin", "Staff", "Instructor")
+
+
+class StudentRole(AbstractRole):
+    _common_roles = ("Learner", "Member", "User")
+    _system_roles = ("User",)
+    _institution_roles = ("Student", "Learner", "Member", "ProspectiveStudent", "User")
+    _context_roles = ("Learner", "Member")
+
+
+class TeacherRole(AbstractRole):
+    _common_roles = ("Instructor", "Administrator")
+    _context_roles = ("Instructor", "Administrator")
+
+
+class TeachingAssistantRole(AbstractRole):
+    _context_roles = ("TeachingAssistant",)
+
+
+class DesignerRole(AbstractRole):
+    _common_roles = ("ContentDeveloper",)
+    _context_roles = ("ContentDeveloper",)
+
+
+class ObserverRole(AbstractRole):
+    _common_roles = ("Mentor",)
+    _context_roles = ("Mentor",)
+
+
+class TransientRole(AbstractRole):
+    _common_roles = ("Transient",)
+    _system_roles = ("Transient",)
+    _institution_roles = ("Transient",)
+    _context_roles = ("Transient",)

ltitoolkit/core/service_connector.py

@@ -0,0 +1,144 @@
+import hashlib
+import re
+import time
+import typing as t
+import uuid
+
+import jwt  # type: ignore
+import requests
+import typing_extensions as te
+from .exception import LtiServiceException
+from .registration import Registration
+
+TServiceConnectorResponse = te.TypedDict(
+    "TServiceConnectorResponse",
+    {
+        "headers": t.Union[t.Dict[str, str], t.MutableMapping[str, str]],
+        "body": t.Union[None, int, float, t.List[object], t.Dict[str, object], str],
+        "next_page_url": t.Optional[str],
+    },
+)
+
+
+REQUESTS_USER_AGENT = "PyLTI1p3-client"
+
+
+class ServiceConnector:
+    _registration: Registration
+    _access_tokens: t.Dict[str, str]
+
+    def __init__(
+        self,
+        registration: Registration,
+        requests_session: t.Optional[requests.Session] = None,
+    ):
+        self._registration = registration
+        self._access_tokens = {}
+        if requests_session:
+            self._requests_session = requests_session
+        else:
+            self._requests_session = requests.Session()
+            self._requests_session.headers["User-Agent"] = REQUESTS_USER_AGENT
+
+    def get_access_token(self, scopes: t.Sequence[str]) -> str:
+        # Don't fetch the same key more than once
+        scopes = sorted(scopes)
+        scopes_str: str = "|".join(scopes)
+        scopes_bytes = scopes_str.encode("utf-8")
+
+        scope_key = hashlib.md5(scopes_bytes).hexdigest()
+
+        if scope_key in self._access_tokens:
+            return self._access_tokens[scope_key]
+
+        # Build up JWT to exchange for an auth token
+        client_id = self._registration.get_client_id()
+        assert client_id is not None, "client_id should be set at this point"
+        auth_url = self._registration.get_auth_token_url()
+        assert auth_url is not None, "auth_url should be set at this point"
+        auth_audience = self._registration.get_auth_audience()
+        aud = auth_audience if auth_audience else auth_url
+
+        jwt_claim: t.Dict[str, t.Union[str, int]] = {
+            "iss": str(client_id),
+            "sub": str(client_id),
+            "aud": str(aud),
+            "iat": int(time.time()) - 5,
+            "exp": int(time.time()) + 60,
+            "jti": "lti-service-token-" + str(uuid.uuid4()),
+        }
+        headers = {}
+        kid = self._registration.get_kid()
+        if kid:
+            headers = {"kid": kid}
+
+        # Sign the JWT with our private key (given by the platform on registration)
+        private_key = self._registration.get_tool_private_key()
+        assert private_key is not None, "Private key should be set at this point"
+        jwt_val = self.encode_jwt(jwt_claim, private_key, headers)
+
+        auth_request = {
+            "grant_type": "client_credentials",
+            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+            "client_assertion": jwt_val,
+            "scope": " ".join(scopes),
+        }
+
+        # Make request to get auth token
+        r = self._requests_session.post(auth_url, data=auth_request)
+        if not r.ok:
+            raise LtiServiceException(r)
+        response = r.json()
+
+        self._access_tokens[scope_key] = response["access_token"]
+        return self._access_tokens[scope_key]
+
+    def encode_jwt(
+        self,
+        message: t.Dict[str, t.Union[str, int]],
+        private_key: str,
+        headers: t.Dict[str, str],
+    ) -> str:
+        jwt_val = jwt.encode(message, private_key, algorithm="RS256", headers=headers)
+        if isinstance(jwt_val, bytes):
+            return jwt_val.decode("utf-8")
+        return jwt_val
+
+    def make_service_request(
+        self,
+        scopes: t.Sequence[str],
+        url: str,
+        is_post: bool = False,
+        data: t.Optional[str] = None,
+        content_type: str = "application/json",
+        accept: str = "application/json",
+        case_insensitive_headers: bool = False,
+    ) -> TServiceConnectorResponse:
+        access_token = self.get_access_token(scopes)
+        headers = {"Authorization": "Bearer " + access_token, "Accept": accept}
+
+        if is_post:
+            headers["Content-Type"] = content_type
+            post_data = data or None
+            r = self._requests_session.post(url, data=post_data, headers=headers)
+        else:
+            r = self._requests_session.get(url, headers=headers)
+
+        if not r.ok:
+            raise LtiServiceException(r)
+
+        next_page_url = None
+        link_header = r.headers.get("link", "")
+        if link_header:
+            match = re.search(
+                r'<([^>]*)>;\s*rel="next"',
+                link_header.replace("\n", " ").lower().strip(),
+            )
+            if match:
+                next_page_url = match.group(1)
+
+        return {
+            "headers": r.headers if case_insensitive_headers else dict(r.headers),
+            "body": r.json() if r.content else None,
+            "next_page_url": next_page_url if next_page_url else None,
+        }

ltitoolkit/core/session.py

@@ -0,0 +1,70 @@
+import typing as t
+from .launch_data_storage.session import SessionDataStorage
+from .request import Request
+from .launch_data_storage.base import LaunchDataStorage
+
+
+TStateParams = t.Dict[str, object]
+TJwtBody = t.Mapping[str, t.Any]
+
+
+class SessionService:
+    data_storage: LaunchDataStorage[t.Any]
+    _launch_data_lifetime = 86400
+    _session_prefix = "lti1p3"
+
+    def __init__(self, request: Request):
+        self.data_storage = SessionDataStorage()
+        self.data_storage.set_request(request)
+
+    def _get_key(
+        self, key: str, nonce: t.Optional[str] = None, add_prefix: bool = True
+    ):
+        return (
+            ((self._session_prefix + "-") if add_prefix else "")
+            + key
+            + (("-" + nonce) if nonce else "")
+        )
+
+    def _set_value(self, key: str, value: object):
+        self.data_storage.set_value(key, value, exp=self._launch_data_lifetime)
+
+    def _get_value(self, key: str) -> t.Any:
+        return self.data_storage.get_value(key)
+
+    def get_launch_data(self, key: str) -> TJwtBody:
+        return self._get_value(self._get_key(key, add_prefix=False))
+
+    def save_launch_data(self, key: str, jwt_body: TJwtBody):
+        self._set_value(self._get_key(key, add_prefix=False), jwt_body)
+
+    def save_nonce(self, nonce: str):
+        self._set_value(self._get_key("nonce", nonce), True)
+
+    def check_nonce(self, nonce: str) -> bool:
+        nonce_key = self._get_key("nonce", nonce)
+        return self.data_storage.check_value(nonce_key)
+
+    def save_state_params(self, state: str, params: TStateParams):
+        self._set_value(self._get_key(state), params)
+
+    def get_state_params(self, state: str) -> TStateParams:
+        return self._get_value(self._get_key(state))
+
+    def set_state_valid(self, state: str, id_token_hash: str):
+        return self._set_value(self._get_key(state + "-id-token-hash"), id_token_hash)
+
+    def check_state_is_valid(self, state: str, id_token_hash: str) -> bool:
+        return self._get_value(self._get_key(state + "-id-token-hash")) == id_token_hash
+
+    def set_data_storage(self, data_storage: LaunchDataStorage[t.Any]):
+        self.data_storage = data_storage
+
+    def set_launch_data_lifetime(self, time_sec: int):
+        if self.data_storage.can_set_keys_expiration():
+            self._launch_data_lifetime = time_sec
+        else:
+            raise Exception(
+                f"{self.data_storage.__class__.__name__} launch storage doesn't support "
+                f"manual change expiration of the keys"
+            )

ltitoolkit/core/tool_config/__init__.py

@@ -0,0 +1,4 @@
+# flake8: noqa
+from .abstract import ToolConfAbstract
+from .dict import ToolConfDict
+from .json_file import ToolConfJsonFile

ltitoolkit/core/tool_config/abstract.py

@@ -0,0 +1,117 @@
+import typing as t
+from abc import ABCMeta, abstractmethod
+import typing_extensions as te
+from ..deployment import Deployment
+from ..registration import Registration
+from ..request import Request
+
+
+REQ = t.TypeVar("REQ", bound=Request)
+
+
+class IssuerToClientRelation:
+    ONE_CLIENT_ID_PER_ISSUER: te.Final = "one-issuer-one-client-id"
+    MANY_CLIENTS_IDS_PER_ISSUER: te.Final = "one-issuer-many-client-ids"
+
+
+class ToolConfAbstract(t.Generic[REQ]):
+    __metaclass__ = ABCMeta
+    issuers_relation_types: t.MutableMapping[str, str] = {}
+
+    def check_iss_has_one_client(self, iss: str) -> bool:
+        """
+        Two methods check_iss_has_one_client / check_iss_has_many_clients are needed for the the backward compatibility
+        with the previous versions of the library (1.4.0 and early) where ToolConfDict supported only client_id per iss.
+        Should return False for all new ToolConf-s
+        """
+        iss_type = self.issuers_relation_types.get(
+            iss, IssuerToClientRelation.ONE_CLIENT_ID_PER_ISSUER
+        )
+        return iss_type == IssuerToClientRelation.ONE_CLIENT_ID_PER_ISSUER
+
+    def check_iss_has_many_clients(self, iss: str) -> bool:
+        """
+        Should return True for all new ToolConf-s
+        """
+        iss_type = self.issuers_relation_types.get(
+            iss, IssuerToClientRelation.ONE_CLIENT_ID_PER_ISSUER
+        )
+        return iss_type == IssuerToClientRelation.MANY_CLIENTS_IDS_PER_ISSUER
+
+    def set_iss_has_one_client(self, iss: str):
+        self.issuers_relation_types[
+            iss
+        ] = IssuerToClientRelation.ONE_CLIENT_ID_PER_ISSUER
+
+    def set_iss_has_many_clients(self, iss: str):
+        self.issuers_relation_types[
+            iss
+        ] = IssuerToClientRelation.MANY_CLIENTS_IDS_PER_ISSUER
+
+    def find_registration(self, iss: str, *args, **kwargs) -> Registration:
+        """
+        Backward compatibility method
+        """
+        return self.find_registration_by_issuer(iss, *args, **kwargs)
+
+    @abstractmethod
+    def find_registration_by_issuer(self, iss: str, *args, **kwargs) -> Registration:
+        """
+        Find registration in case if iss has only one client id, i.e
+        in case of { ... "iss": { ... "client_id: "client" ... }, ... } config.
+
+        You may skip implementation of this method in case if all iss in your config could have more than one client id.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def find_registration_by_params(
+        self, iss: str, client_id: str, *args, **kwargs
+    ) -> Registration:
+        """
+        Find registration in case if iss has many client ids, i.e
+        in case of { ... "iss": [ { ... "client_id: "client1" ... }, { ... "client_id: "client2" ... } ], ... } config.
+
+        You may skip implementation of this method in case if all iss in your config couldn't have more than one
+        client id, but it is outdated and not recommended way of storing configuration.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def find_deployment(self, iss: str, deployment_id: str) -> t.Optional[Deployment]:
+        """
+        Find deployment in case if iss has only one client id, i.e
+        in case of { ... "iss": { ... "client_id: "client" ... }, ... } config.
+
+        You may skip implementation of this method in case if all iss in your config could have more than one client id.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def find_deployment_by_params(
+        self, iss: str, deployment_id: str, client_id: str, *args, **kwargs
+    ) -> t.Optional[Deployment]:
+        """
+        Find deployment in case if iss has many client ids, i.e
+        in case of { ... "iss": [ { ... "client_id: "client1" ... }, { ... "client_id: "client2" ... } ], ... } config.
+
+        You may skip implementation of this method in case if all iss in your config couldn't have more than one
+        client id, but it is outdated and not recommended way of storing configuration.
+        """
+        raise NotImplementedError
+
+    def get_jwks(
+        self, iss: t.Optional[str] = None, client_id: t.Optional[str] = None, **kwargs
+    ):
+        keys: t.List[t.Mapping[str, t.Any]] = []
+        if iss:
+            if self.check_iss_has_one_client(iss):
+                reg = self.find_registration(iss)
+            elif self.check_iss_has_many_clients(iss):
+                if not client_id:
+                    raise Exception("client_id is not specified")
+                reg = self.find_registration_by_params(iss, client_id, **kwargs)
+            else:
+                raise Exception("Invalid issuer relation type")
+            keys = reg.get_jwks()
+        return {"keys": keys}