scim2-server 0.7.0__tar.gz → 0.8.0__tar.gz

{scim2_server-0.7.0 → scim2_server-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: scim2-server
-Version: 0.7.0
+Version: 0.8.0
 Summary: SCIM server core for any storage and web framework
 Keywords: scim,scim2,provisioning,rfc7643,rfc7644
 Author: Yaal Coop, Christian Friedrich Coors
@@ -217,12 +217,14 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Environment :: Web Environment
 Classifier: Programming Language :: Python
 Classifier: Operating System :: OS Independent
-Requires-Dist: scim2-models>=0.12.0
+Requires-Dist: scim2-models>=0.12.2
+Requires-Dist: cryptography>=50.0.1 ; extra == 'cursor'
 Requires-Dist: precis-i18n>=1.1.2 ; extra == 'precis'
 Requires-Dist: pytest>=9.1.1 ; extra == 'testing'
 Requires-Python: >=3.11
 Project-URL: repository, https://github.com/python-scim/scim2-server
 Project-URL: funding, https://github.com/sponsors/python-scim
+Provides-Extra: cursor
 Provides-Extra: precis
 Provides-Extra: testing
 Description-Content-Type: text/markdown

{scim2_server-0.7.0 → scim2_server-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.7.0"
+version = "0.8.0"
 description = "SCIM server core for any storage and web framework"
 readme = "README.md"
 keywords = [
@@ -28,7 +28,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 requires-python = ">= 3.11"
-dependencies = ["scim2-models>=0.12.0"]
+dependencies = ["scim2-models>=0.12.2"]
 
 [[project.authors]]
 name = "Yaal Coop"
@@ -44,6 +44,7 @@ file = "LICENSE"
 [project.optional-dependencies]
 testing = ["pytest>=9.1.1"]
 precis = ["precis-i18n>=1.1.2"]
+cursor = ["cryptography>=50.0.1"]
 
 [project.urls]
 repository = "https://github.com/python-scim/scim2-server"
@@ -63,9 +64,10 @@ dev = [
     "aiosqlite>=0.22.1",
     "precis-i18n>=1.1.2",
     "mypy>=2.3.1",
-    "scim2-client[werkzeug]>=0.11.2",
+    "scim2-client>=0.12.0",
     "scim2-tester>=0.5.1",
     "werkzeug>=3.0.3",
+    "cryptography>=50.0.1",
 ]
 doc = [
     "shibuya>=2024.5.15",
@@ -73,6 +75,7 @@ doc = [
     "sphinx-argparse>=0.6.1",
     "sphinx-design>=0.6.1",
     "sphinx-issues>=5.0.0",
+    "sphinxcontrib-mermaid>=2.1.1",
 ]
 
 [tool.uv]

{scim2_server-0.7.0 → scim2_server-0.8.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.7.0"
+version = "0.8.0"
 description = "SCIM server core for any storage and web framework"
 authors = [
     {name="Yaal Coop", email="contact@yaal.coop"},
@@ -29,7 +29,7 @@ classifiers = [
 
 requires-python = ">= 3.11"
 dependencies = [
-    "scim2-models>=0.12.0",
+    "scim2-models>=0.12.2",
 ]
 
 [project.optional-dependencies]
@@ -39,6 +39,9 @@ testing = [
 precis = [
     "precis-i18n>=1.1.2",
 ]
+cursor = [
+    "cryptography>=50.0.1",
+]
 
 [project.urls]
 repository = "https://github.com/python-scim/scim2-server"
@@ -58,9 +61,10 @@ dev = [
     "aiosqlite>=0.22.1",
     "precis-i18n>=1.1.2",
     "mypy>=2.3.1",
-    "scim2-client[werkzeug]>=0.11.2",
+    "scim2-client>=0.12.0",
     "scim2-tester>=0.5.1",
     "werkzeug>=3.0.3",
+    "cryptography>=50.0.1",
 ]
 doc = [
     "shibuya>=2024.5.15",
@@ -68,6 +72,7 @@ doc = [
     "sphinx-argparse>=0.6.1",
     "sphinx-design>=0.6.1",
     "sphinx-issues>=5.0.0",
+    "sphinxcontrib-mermaid>=2.1.1",
 ]
 
 [tool.uv]

{scim2_server-0.7.0 → scim2_server-0.8.0}/scim2_server/applications/asgi.py

@@ -73,7 +73,9 @@ class ASGIApplication(BaseApplication):
             method=scope["method"],
             base_url=self.get_base_url(scope),
             path=self.split_path(self.get_path(scope)),
-            query=dict(parse_qsl(scope["query_string"].decode())),
+            query=dict(
+                parse_qsl(scope["query_string"].decode(), keep_blank_values=True)
+            ),
             headers=[
                 (name.decode(), value.decode()) for name, value in scope["headers"]
             ],

{scim2_server-0.7.0 → scim2_server-0.8.0}/scim2_server/applications/base.py

@@ -1,4 +1,5 @@
 import logging
+import os
 from typing import Any
 
 from scim2_models import SCIMException
@@ -19,12 +20,18 @@ class BaseApplication:
     :param service: The service serving the requests, built upon ``provider``.
         Pass a subclass of :class:`~scim2_server.service.ScimService` to change
         one of its steps, such as the URL of the resources. A
-        :class:`~scim2_server.service.ScimService` of ``provider`` by default.
+        :class:`~scim2_server.service.ScimService` of ``provider`` by default,
+        whose secret comes from the ``SCIM2_SERVER_SECRET`` environment
+        variable.
     """
 
     def __init__(self, provider: ScimProvider, service: ScimService | None = None):
         self.provider = provider
-        self.service = service if service is not None else ScimService(provider)
+        self.service = (
+            service
+            if service is not None
+            else ScimService(provider, secret=os.environ.get("SCIM2_SERVER_SECRET"))
+        )
         self.log = logging.getLogger("scim2_server")
 
     @staticmethod

{scim2_server-0.7.0 → scim2_server-0.8.0}/scim2_server/applications/wsgi.py

@@ -81,7 +81,9 @@ class WSGIApplication(BaseApplication):
             method=environ["REQUEST_METHOD"],
             base_url=self.get_base_url(environ),
             path=self.split_path(environ.get("PATH_INFO", "")),
-            query=dict(parse_qsl(environ.get("QUERY_STRING", ""))),
+            query=dict(
+                parse_qsl(environ.get("QUERY_STRING", ""), keep_blank_values=True)
+            ),
             headers=headers,
         )
         request.body = self.read_body(environ, request)

scim2_server-0.8.0/scim2_server/cursor.py

@@ -0,0 +1,107 @@
+"""The cursors of :rfc:`RFC 9865 <9865>`, which hide the position of a page from the client.
+
+This module needs the ``cursor`` extra, which installs ``cryptography``.
+"""
+
+import base64
+import json
+import os
+import time
+from typing import Any
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from scim2_models import ExpiredCursorException
+from scim2_models import InvalidCountException
+from scim2_models import InvalidCursorException
+
+VERSION = b"\x01"
+SALT_SIZE = 16
+NONCE_SIZE = 12
+TAG_SIZE = 16
+HEADER_SIZE = len(VERSION) + SALT_SIZE + NONCE_SIZE
+
+
+class Cursors:
+    """Seal the position of a page into a cursor, and open the cursor back.
+
+    A cursor is encrypted and authenticated with AES-GCM, so the client can
+    neither read nor forge it (:rfc:`RFC 9865 §5.2 <9865#section-5.2>`). It
+    holds the query it belongs to, the ``count`` of the query, and the time it
+    was issued.
+
+    Each cursor has its own key, derived from the secret and a random salt.
+    The number of cursors a secret seals is then not bounded by the number of
+    messages AES-GCM allows for a single key.
+
+    :param secret: The secret the keys of the cursors derive from. Every
+        process of the server needs the same secret.
+    """
+
+    def __init__(self, secret: str | bytes):
+        self.secret = secret.encode() if isinstance(secret, str) else secret
+
+    def _aead(self, salt: bytes) -> AESGCM:
+        """Return the cipher of the cursors sealed with a salt."""
+        key = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt,
+            info=b"scim2-server cursor",
+        ).derive(self.secret)
+        return AESGCM(key)
+
+    def seal(self, query: str, count: int | None, position: Any) -> str:
+        """Return the cursor of a position, for the query and the count it belongs to."""
+        content = json.dumps(
+            {"q": query, "n": count, "t": int(time.time()), "p": position},
+            separators=(",", ":"),
+        ).encode()
+        salt = os.urandom(SALT_SIZE)
+        nonce = os.urandom(NONCE_SIZE)
+        sealed = self._aead(salt).encrypt(nonce, content, VERSION)
+        token = VERSION + salt + nonce + sealed
+        return base64.urlsafe_b64encode(token).rstrip(b"=").decode()
+
+    def open(
+        self, cursor: str, query: str, count: int | None, timeout: int | None
+    ) -> Any:
+        """Return the position a cursor holds.
+
+        :param timeout: The number of seconds a cursor stays valid, if any.
+        :raises ~scim2_models.InvalidCursorException: When the cursor was not
+            issued by this server, or for another query.
+        :raises ~scim2_models.InvalidCountException: When the cursor was
+            issued for another ``count``.
+        :raises ~scim2_models.ExpiredCursorException: When the cursor is
+            older than ``timeout``.
+        """
+        try:
+            token = base64.urlsafe_b64decode(cursor + "=" * (-len(cursor) % 4))
+        except ValueError:
+            raise InvalidCursorException from None
+
+        if token[:1] != VERSION or len(token) < HEADER_SIZE + TAG_SIZE:
+            raise InvalidCursorException
+
+        salt = token[len(VERSION) : len(VERSION) + SALT_SIZE]
+        nonce = token[len(VERSION) + SALT_SIZE : HEADER_SIZE]
+        try:
+            content = json.loads(
+                self._aead(salt).decrypt(nonce, token[HEADER_SIZE:], VERSION)
+            )
+        except InvalidTag:
+            raise InvalidCursorException from None
+
+        if content["q"] != query:
+            raise InvalidCursorException
+
+        if content["n"] != count:
+            raise InvalidCountException
+
+        if timeout is not None and time.time() - content["t"] > timeout:
+            raise ExpiredCursorException
+
+        return content["p"]

{scim2_server-0.7.0 → scim2_server-0.8.0}/scim2_server/handler.py

@@ -2,6 +2,7 @@ from typing import Any
 from typing import cast
 
 from scim2_models import BulkOperation
+from scim2_models import Pagination
 from scim2_models import PatchOp
 from scim2_models import Resource
 from scim2_models import ResourceType
@@ -15,6 +16,21 @@ from scim2_server.routing import Operation
 from scim2_server.service import ScimService
 from scim2_server.storage import AsyncScimStorage
 from scim2_server.storage import ScimStorage
+from scim2_server.storage import async_search_page
+from scim2_server.storage import projection
+from scim2_server.storage import search_page
+
+
+def _check_cursors(
+    service: ScimService, storage: ScimStorage | AsyncScimStorage
+) -> None:
+    """Refuse a storage without cursors, when the configuration of the service announces them."""
+    supported = storage.supports_cursors and storage._search_takes_position
+    if service._pages_by(Pagination.DefaultPaginationMethod.cursor) and not supported:
+        raise TypeError(
+            f"The configuration announces cursor pagination, which "
+            f"{type(storage).__qualname__} does not support."
+        )
 
 
 class ScimHandler:
@@ -27,9 +43,14 @@ class ScimHandler:
     :class:`~scim2_models.SCIMException`, that :meth:`ScimService.error_response
     <scim2_server.service.ScimService.error_response>` turns into a response.
     Any other exception is a bug.
+
+    :raises TypeError: When the configuration of the service announces
+        cursor pagination, and the storage does not
+        :attr:`~scim2_server.storage.ScimStorage.supports_cursors`.
     """
 
     def __init__(self, service: ScimService, storage: ScimStorage):
+        _check_cursors(service, storage)
         self.service = service
         self.storage = storage
 
@@ -75,7 +96,9 @@ class ScimHandler:
             )
             with self.storage.operation():
                 resource = self.storage.get(
-                    resource_type, cast(str, target.resource_id)
+                    resource_type,
+                    cast(str, target.resource_id),
+                    **projection(self.storage, response_parameters),
                 )
             response = self.service.query_response(
                 request.base_url,
@@ -202,13 +225,15 @@ class ScimHandler:
             authorized_types = self.service.authorized_types(
                 request, target, resource_types
             )
-            search_request = self.service.read_search_query(
+            search_request, position = self.service.read_search_query(
                 resource_types, request.query
             )
             with self.storage.operation():
-                total, resources = self.storage.search(authorized_types, search_request)
+                page = search_page(
+                    self.storage, authorized_types, search_request, position=position
+                )
             return self.service.search_response(
-                request.base_url, total, resources, search_request
+                request.base_url, resource_types, page, search_request
             )
 
     def search_with_body(self, request: ScimRequest) -> ScimResponse:
@@ -219,13 +244,15 @@ class ScimHandler:
             authorized_types = self.service.authorized_types(
                 request, target, resource_types
             )
-            search_request = self.service.read_search_body(
+            search_request, position = self.service.read_search_body(
                 resource_types, request.body, request.header("Content-Type")
             )
             with self.storage.operation():
-                total, resources = self.storage.search(authorized_types, search_request)
+                page = search_page(
+                    self.storage, authorized_types, search_request, position=position
+                )
             return self.service.search_response(
-                request.base_url, total, resources, search_request
+                request.base_url, resource_types, page, search_request
             )
 
     # -- Bulk -----------------------------------------------------------
@@ -350,9 +377,14 @@ class AsyncScimHandler:
 
     It calls the same steps of the same service, and awaits the storage
     between them.
+
+    :raises TypeError: When the configuration of the service announces
+        cursor pagination, and the storage does not
+        :attr:`~scim2_server.storage.AsyncScimStorage.supports_cursors`.
     """
 
     def __init__(self, service: ScimService, storage: AsyncScimStorage):
+        _check_cursors(service, storage)
         self.service = service
         self.storage = storage
 
@@ -398,7 +430,9 @@ class AsyncScimHandler:
             )
             async with self.storage.operation():
                 resource = await self.storage.get(
-                    resource_type, cast(str, target.resource_id)
+                    resource_type,
+                    cast(str, target.resource_id),
+                    **projection(self.storage, response_parameters),
                 )
             response = self.service.query_response(
                 request.base_url,
@@ -531,15 +565,15 @@ class AsyncScimHandler:
             authorized_types = self.service.authorized_types(
                 request, target, resource_types
             )
-            search_request = self.service.read_search_query(
+            search_request, position = self.service.read_search_query(
                 resource_types, request.query
             )
             async with self.storage.operation():
-                total, resources = await self.storage.search(
-                    authorized_types, search_request
+                page = await async_search_page(
+                    self.storage, authorized_types, search_request, position=position
                 )
             return self.service.search_response(
-                request.base_url, total, resources, search_request
+                request.base_url, resource_types, page, search_request
             )
 
     async def search_with_body(self, request: ScimRequest) -> ScimResponse:
@@ -550,15 +584,15 @@ class AsyncScimHandler:
             authorized_types = self.service.authorized_types(
                 request, target, resource_types
             )
-            search_request = self.service.read_search_body(
+            search_request, position = self.service.read_search_body(
                 resource_types, request.body, request.header("Content-Type")
             )
             async with self.storage.operation():
-                total, resources = await self.storage.search(
-                    authorized_types, search_request
+                page = await async_search_page(
+                    self.storage, authorized_types, search_request, position=position
                 )
             return self.service.search_response(
-                request.base_url, total, resources, search_request
+                request.base_url, resource_types, page, search_request
             )
 
     # -- Bulk -----------------------------------------------------------

{scim2_server-0.7.0 → scim2_server-0.8.0}/scim2_server/memory.py

@@ -10,12 +10,14 @@ from typing import Union
 from typing import cast
 
 from scim2_models import AttributeBinding
+from scim2_models import InvalidCursorException
 from scim2_models import Meta
 from scim2_models import NotFoundException
 from scim2_models import Path
 from scim2_models import PreconditionFailedException
 from scim2_models import Resource
 from scim2_models import ResourceType
+from scim2_models import ResponseParameters
 from scim2_models import ScimFilter
 from scim2_models import SearchRequest
 from scim2_models import Uniqueness
@@ -23,6 +25,9 @@ from scim2_models import UniquenessException
 
 from scim2_server.storage import AsyncScimStorage
 from scim2_server.storage import ScimStorage
+from scim2_server.storage import SearchPage
+from scim2_server.storage import projection
+from scim2_server.storage import search_page
 from scim2_server.utils import parametrize
 
 
@@ -31,6 +36,112 @@ def utcnow() -> datetime.datetime:
     return datetime.datetime.now(datetime.UTC)
 
 
+def _page(
+    search_request: SearchRequest[Any], position: Any, resources: list[Resource[Any]]
+) -> SearchPage:
+    """Sort every matching resource by its sort value then its identifier, and return the page a search asks for.
+
+    A cursor position holds the sort value and the identifier of the resource
+    the page starts after, or ends before, so the pages stay stable.
+    """
+    descending = (
+        search_request.sort_by is not None
+        and search_request.sort_order == SearchRequest.SortOrder.descending
+    )
+    pairs = sorted(
+        ((_sort_key(search_request, resource), resource) for resource in resources),
+        key=lambda pair: pair[0],
+        reverse=descending,
+    )
+    found = [resource for _, resource in pairs]
+    if search_request.cursor is None:
+        start = search_request.start_index_0 or 0
+        stop = None if search_request.count is None else start + search_request.count
+        return SearchPage(len(found), found[start:stop])
+
+    if search_request.count == 0:
+        return SearchPage(len(found), [])
+
+    start, stop = _bounds(
+        [key for key, _ in pairs], position, search_request.count, descending
+    )
+    page = SearchPage(len(found), found[start:stop])
+    if page.resources and stop < len(found):
+        page.next = _position("next", pairs[stop - 1][0])
+    if page.resources and start > 0:
+        page.previous = _position("previous", pairs[start][0])
+    return page
+
+
+SortKey = tuple[bool, Any, str]
+
+
+def _sort_key(search_request: SearchRequest[Any], resource: Resource[Any]) -> SortKey:
+    """Return the key that orders a resource: its sort value, missing values last, then its identifier."""
+    value = search_request.sort_value(resource)
+    return value is None, value if value is not None else "", cast(str, resource.id)
+
+
+def _bounds(
+    keys: list[SortKey], position: Any, count: int | None, descending: bool
+) -> tuple[int, int]:
+    """Return the slice of the sorted keys that a cursor page covers."""
+    if position is None:
+        return 0, len(keys) if count is None else min(count, len(keys))
+
+    direction, anchor = _read_position(position)
+
+    def before(key: SortKey) -> bool:
+        return key > anchor if descending else key < anchor
+
+    if direction == "next":
+        start = sum(1 for key in keys if before(key) or key == anchor)
+        stop = len(keys) if count is None else min(start + count, len(keys))
+        return start, stop
+
+    stop = sum(1 for key in keys if before(key))
+    start = 0 if count is None else max(stop - count, 0)
+    return start, stop
+
+
+def _position(direction: str, key: SortKey) -> dict[str, Any]:
+    """Return the position of the page that starts after, or ends before, a sort key."""
+    missing, value, identifier = key
+    return {"d": direction, "k": None if missing else _encode(value), "i": identifier}
+
+
+def _read_position(position: Any) -> tuple[str, SortKey]:
+    """Return the direction and the sort key of a position that _page gave."""
+    try:
+        direction, value, identifier = position["d"], position["k"], position["i"]
+    except (TypeError, KeyError):
+        raise InvalidCursorException from None
+    if direction not in ("next", "previous") or not isinstance(identifier, str):
+        raise InvalidCursorException
+    if value is None:
+        return direction, (True, "", identifier)
+    return direction, (False, _decode(value), identifier)
+
+
+def _encode(value: Any) -> Any:
+    """Return a sort value in a form JSON can hold."""
+    if isinstance(value, datetime.datetime):
+        return {"datetime": value.isoformat()}
+    if isinstance(value, str | bool | int | float):
+        return value
+    raise TypeError(f"A cursor cannot hold a sort value of type {type(value).__name__}")
+
+
+def _decode(value: Any) -> Any:
+    """Return the sort value that _encode gave."""
+    if not isinstance(value, dict):
+        return value
+    try:
+        return datetime.datetime.fromisoformat(value["datetime"])
+    except (KeyError, TypeError, ValueError):
+        raise InvalidCursorException from None
+
+
 class InMemoryStorage(ScimStorage):
     """A storage keeping the resources in memory, for tests, debugging and demos.
 
@@ -41,6 +152,8 @@ class InMemoryStorage(ScimStorage):
         ``meta.lastModified``. Pass a fixed clock to get predictable dates.
     """
 
+    supports_cursors = True
+
     def __init__(self, clock: Callable[[], datetime.datetime] = utcnow) -> None:
         self.resources: list[Resource[Any]] = []
         self.clock = clock
@@ -68,15 +181,25 @@ class InMemoryStorage(ScimStorage):
         with self.lock:
             yield
 
-    def get(self, resource_type: ResourceType, resource_id: str) -> Resource[Any]:
+    def get(
+        self,
+        resource_type: ResourceType,
+        resource_id: str,
+        *,
+        response_parameters: ResponseParameters[Any] | None = None,
+    ) -> Resource[Any]:
         with self.lock:
             return self.resources[self._index(resource_type, resource_id)].model_copy(
                 deep=True
             )
 
     def search(
-        self, resource_types: list[ResourceType], search_request: SearchRequest[Any]
-    ) -> tuple[int, list[Resource[Any]]]:
+        self,
+        resource_types: list[ResourceType],
+        search_request: SearchRequest[Any],
+        *,
+        position: Any = None,
+    ) -> SearchPage:
         with self.lock:
             candidates = [
                 resource.model_copy(deep=True)
@@ -90,13 +213,7 @@ class InMemoryStorage(ScimStorage):
             scim_filter = parametrize(ScimFilter, Union[models])(str(scim_filter))  # noqa: UP007
 
         found = [r for r in candidates if scim_filter is None or scim_filter.match(r)]
-        found = search_request.sort(found)
-
-        start_index = (search_request.start_index or 1) - 1
-        page = found[start_index:]
-        if search_request.count is not None:
-            page = page[: search_request.count]
-        return len(found), page
+        return _page(search_request, position, found)
 
     def create(
         self, resource_type: ResourceType, resource: Resource[Any]
@@ -228,6 +345,8 @@ class AsyncInMemoryStorage(AsyncScimStorage):
         :class:`InMemoryStorage` to change how identifiers are generated.
     """
 
+    supports_cursors = True
+
     def __init__(self, storage: InMemoryStorage | None = None) -> None:
         self.storage = storage if storage is not None else InMemoryStorage()
 
@@ -236,13 +355,27 @@ class AsyncInMemoryStorage(AsyncScimStorage):
         """The stored resources."""
         return self.storage.resources
 
-    async def get(self, resource_type: ResourceType, resource_id: str) -> Resource[Any]:
-        return self.storage.get(resource_type, resource_id)
+    async def get(
+        self,
+        resource_type: ResourceType,
+        resource_id: str,
+        *,
+        response_parameters: ResponseParameters[Any] | None = None,
+    ) -> Resource[Any]:
+        return self.storage.get(
+            resource_type,
+            resource_id,
+            **projection(self.storage, response_parameters),
+        )
 
     async def search(
-        self, resource_types: list[ResourceType], search_request: SearchRequest[Any]
-    ) -> tuple[int, list[Resource[Any]]]:
-        return self.storage.search(resource_types, search_request)
+        self,
+        resource_types: list[ResourceType],
+        search_request: SearchRequest[Any],
+        *,
+        position: Any = None,
+    ) -> SearchPage:
+        return search_page(self.storage, resource_types, search_request, position)
 
     async def create(
         self, resource_type: ResourceType, resource: Resource[Any]