scim2-server 0.6.0__tar.gz → 0.6.2__tar.gz

{scim2_server-0.6.0 → scim2_server-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: scim2-server
-Version: 0.6.0
+Version: 0.6.2
 Summary: SCIM server core for any storage and web framework
 Keywords: scim,scim2,provisioning,rfc7643,rfc7644
 Author: Yaal Coop, Christian Friedrich Coors
@@ -217,7 +217,7 @@ 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.10.3
+Requires-Dist: scim2-models>=0.10.6
 Requires-Dist: pytest>=9.1.1 ; extra == 'testing'
 Requires-Python: >=3.11
 Project-URL: repository, https://github.com/python-scim/scim2-server

{scim2_server-0.6.0 → scim2_server-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.6.0"
+version = "0.6.2"
 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.10.3"]
+dependencies = ["scim2-models>=0.10.6"]
 
 [[project.authors]]
 name = "Yaal Coop"

{scim2_server-0.6.0 → scim2_server-0.6.2}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.6.0"
+version = "0.6.2"
 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.10.3",
+    "scim2-models>=0.10.6",
 ]
 
 [project.optional-dependencies]

{scim2_server-0.6.0 → scim2_server-0.6.2}/scim2_server/applications/asgi.py

@@ -6,7 +6,6 @@ from collections.abc import Callable
 from typing import Any
 from urllib.parse import parse_qsl
 
-from scim2_models import SCIMException
 from scim2_models import ScimProvider
 
 from scim2_server.applications.base import VERSION_PREFIX
@@ -79,10 +78,7 @@ class ASGIApplication(BaseApplication):
                 (name.decode(), value.decode()) for name, value in scope["headers"]
             ],
         )
-        try:
-            limit = self.service.max_body_size(request)
-        except SCIMException:
-            limit = None
+        limit = self.service.max_body_size(request)
         body = b""
         more_body = True
         while more_body:

{scim2_server-0.6.0 → scim2_server-0.6.2}/scim2_server/applications/wsgi.py

@@ -10,7 +10,6 @@ from urllib.parse import parse_qsl
 from wsgiref.util import application_uri
 
 from scim2_models import NotFoundException
-from scim2_models import SCIMException
 from scim2_models import ScimProvider
 
 from scim2_server.applications.base import VERSION_PREFIX
@@ -94,10 +93,7 @@ class WSGIApplication(BaseApplication):
         A body without :mdn:`Content-Length` is read up to its end, when the
         server marks its input as terminated.
         """
-        try:
-            limit = self.service.max_body_size(request)
-        except SCIMException:
-            limit = None
+        limit = self.service.max_body_size(request)
         if environ.get("CONTENT_LENGTH"):
             size = int(environ["CONTENT_LENGTH"])
         elif environ.get("wsgi.input_terminated"):

{scim2_server-0.6.0 → scim2_server-0.6.2}/scim2_server/conditions.py

@@ -50,8 +50,11 @@ class EntityTags:
     def matches(self, version: str | None) -> bool:
         """Tell whether a resource version matches the header, with the weak comparison.
 
-        Both :mdn:`If-Match` and :mdn:`If-None-Match` use the weak comparison
-        (:rfc:`RFC 9110 §8.8.3.2 <9110#section-8.8.3.2>`).
+        Both :mdn:`If-Match` and :mdn:`If-None-Match` use the weak comparison.
+        Per :rfc:`RFC 9110 §13.1.1 <9110#section-13.1.1>`, ``If-Match`` uses the
+        strong comparison. But SCIM prefers weak ETags
+        (:rfc:`RFC 7644 §3.14 <7644#section-3.14>`), and the strong comparison
+        never matches them.
 
         :param version: The version of the resource, or :data:`None` when the
             service does not version its resources.

{scim2_server-0.6.0 → scim2_server-0.6.2}/scim2_server/handler.py

@@ -245,18 +245,19 @@ class ScimHandler:
     ) -> tuple[dict[str, Any], Resource[Any] | None]:
         """Apply one step of a bulk request.
 
-        The step resolves the references of the operation, locates it and
-        authorizes it. An operation that failed its validation then keeps its
-        error.
+        The step routes the path of the operation, resolves its references,
+        locates it and authorizes it, so that it fails as a single request
+        would. An operation that failed its validation then keeps its error.
 
         :return: The outcome of the step, and the resource it created or updated.
         """
         operation = plan.operation(step)
-        outcome = self.service.bulk_outcome(operation)
+        outcome = self.service.bulk_outcome(request.base_url, operation)
         try:
+            resource_type = self.service.route_bulk_operation(operation)
             operation = plan.resolve(step)
-            resource_type = self.service.locate_bulk_operation(
-                request.base_url, operation, outcome
+            self.service.locate_bulk_operation(
+                request.base_url, resource_type, operation, outcome
             )
             self.service.authorize_bulk_operation(request, operation, resource_type)
             failure = self.service.bulk_validation_failure(operation, outcome)
@@ -280,12 +281,12 @@ class ScimHandler:
         The data of the operation is already validated, in the context of the
         request the operation stands for.
         """
-        resource_id = self.service.check_bulk_target(operation)
-        if resource_id is None:
+        if operation.method == BulkOperation.Method.post:
             return self.storage.create(
                 resource_type, cast(Resource[Any], operation.data)
             )
 
+        resource_id = cast(str, operation.resource_id)
         conditions = Conditions(if_match=operation.version)
         match operation.method:
             case BulkOperation.Method.put:
@@ -577,18 +578,19 @@ class AsyncScimHandler:
     ) -> tuple[dict[str, Any], Resource[Any] | None]:
         """Apply one step of a bulk request.
 
-        The step resolves the references of the operation, locates it and
-        authorizes it. An operation that failed its validation then keeps its
-        error.
+        The step routes the path of the operation, resolves its references,
+        locates it and authorizes it, so that it fails as a single request
+        would. An operation that failed its validation then keeps its error.
 
         :return: The outcome of the step, and the resource it created or updated.
         """
         operation = plan.operation(step)
-        outcome = self.service.bulk_outcome(operation)
+        outcome = self.service.bulk_outcome(request.base_url, operation)
         try:
+            resource_type = self.service.route_bulk_operation(operation)
             operation = plan.resolve(step)
-            resource_type = self.service.locate_bulk_operation(
-                request.base_url, operation, outcome
+            self.service.locate_bulk_operation(
+                request.base_url, resource_type, operation, outcome
             )
             self.service.authorize_bulk_operation(request, operation, resource_type)
             failure = self.service.bulk_validation_failure(operation, outcome)
@@ -612,12 +614,12 @@ class AsyncScimHandler:
         The data of the operation is already validated, in the context of the
         request the operation stands for.
         """
-        resource_id = self.service.check_bulk_target(operation)
-        if resource_id is None:
+        if operation.method == BulkOperation.Method.post:
             return await self.storage.create(
                 resource_type, cast(Resource[Any], operation.data)
             )
 
+        resource_id = cast(str, operation.resource_id)
         conditions = Conditions(if_match=operation.version)
         match operation.method:
             case BulkOperation.Method.put:

{scim2_server-0.6.0 → scim2_server-0.6.2}/scim2_server/service.py

@@ -5,6 +5,7 @@ from typing import Any
 from typing import TypeVar
 from typing import Union
 from typing import cast
+from urllib.parse import urlsplit
 
 from pydantic import ValidationError
 from pydantic_core import from_json
@@ -14,8 +15,10 @@ from scim2_models import Bulk
 from scim2_models import BulkOperation
 from scim2_models import BulkRequest
 from scim2_models import BulkResponse
+from scim2_models import ChangePassword
 from scim2_models import Context
 from scim2_models import Error
+from scim2_models import ETag
 from scim2_models import Filter
 from scim2_models import ForbiddenException
 from scim2_models import InvalidSyntaxException
@@ -26,7 +29,9 @@ from scim2_models import NotFoundException
 from scim2_models import NotImplementedException
 from scim2_models import Patch
 from scim2_models import PatchOp
+from scim2_models import Path
 from scim2_models import PayloadTooLargeException
+from scim2_models import Reference
 from scim2_models import Resource
 from scim2_models import ResourceType
 from scim2_models import ResponseParameters
@@ -46,7 +51,6 @@ from scim2_server.responses import ScimResponse
 from scim2_server.routing import Operation
 from scim2_server.routing import Target
 from scim2_server.routing import match
-from scim2_server.utils import load_default_service_provider_config
 from scim2_server.utils import parametrize
 
 
@@ -105,6 +109,23 @@ def is_json_media_type(content_type: str | None) -> bool:
     )
 
 
+def patch_only_config() -> ServiceProviderConfig:
+    """Return the configuration of a service that only supports PATCH.
+
+    PATCH only needs the storage to update a resource, so every storage
+    supports it. The other capabilities need a storage that implements them.
+    """
+    return ServiceProviderConfig(
+        patch=Patch(supported=True),
+        bulk=Bulk(supported=False, max_operations=0, max_payload_size=0),
+        filter=Filter(supported=False),
+        change_password=ChangePassword(supported=False),
+        sort=Sort(supported=False),
+        etag=ETag(supported=False),
+        authentication_schemes=[],
+    )
+
+
 class ScimService:
     """The SCIM protocol, without input or output.
 
@@ -116,6 +137,9 @@ class ScimService:
     reads the request, and turns the :class:`~scim2_server.responses.ScimResponse`
     into a response of the framework.
 
+    A provider without ``config`` announces PATCH, and no other capability.
+    The storage must implement each capability the configuration announces.
+
     Every public method can be overridden. ``base_url`` is the root URL of the
     SCIM endpoints, as the client sees it, such as
     ``https://example.com/scim/v2``.
@@ -123,7 +147,7 @@ class ScimService:
 
     def __init__(self, provider: ScimProvider):
         self.provider = provider
-        self.config = provider.config or load_default_service_provider_config()
+        self.config = provider.config or patch_only_config()
 
     # -- Resource types and models --------------------------------------
 
@@ -294,13 +318,13 @@ class ScimService:
     ) -> None:
         """Authorize a resolved bulk operation with :meth:`authorize`.
 
-        An operation without a known resource type or a valid method keeps its
-        validation error, without authorization.
+        An operation without a valid method or path keeps its validation
+        error, without authorization.
         """
-        if resource_type is None or operation.method is None:
+        if resource_type is None:
             return
         target = Target(
-            BULK_OPERATIONS[operation.method],
+            BULK_OPERATIONS[cast(BulkOperation.Method, operation.method)],
             endpoint=self.endpoint_of(resource_type),
             resource_id=operation.resource_id,
         )
@@ -344,13 +368,25 @@ class ScimService:
     def max_body_size(self, request: ScimRequest) -> int | None:
         """Return the largest body the service accepts for a request, in bytes.
 
-        An integration reads at most one byte more, and leaves the 413 answer to
-        the service. A bulk request is limited by maxPayloadSize
-        (:rfc:`RFC 7644 §3.7.4 <7644#section-3.7.4>`). Other requests have no limit.
+        An integration reads at most one byte more, and passes the body to the
+        handler. It must not refuse a larger body itself: the service answers,
+        with a 413 or with an error that comes first, such as a 501 when bulk
+        is not supported.
+
+        A bulk request is limited by maxPayloadSize
+        (:rfc:`RFC 7644 §3.7.4 <7644#section-3.7.4>`). A request that fails
+        whatever its body, such as a request on an unknown path, gets 0.
+        Other requests have no limit.
         """
-        if self.match(request).operation is Operation.bulk:
-            return self.bulk_max_payload_size()
-        return None
+        try:
+            operation = self.match(request).operation
+        except SCIMException:
+            return 0
+        if operation is not Operation.bulk:
+            return None
+        if self.config.bulk is None or not self.config.bulk.supported:
+            return 0
+        return self.bulk_max_payload_size()
 
     def resource_type_at(self, endpoint: str) -> ResourceType:
         """Return the resource type an endpoint serves.
@@ -434,8 +470,13 @@ class ScimService:
 
     @staticmethod
     def ensure_json(content_type: str | None) -> None:
-        """Refuse with a 415 a request body that is not JSON."""
-        if not is_json_media_type(content_type):
+        """Refuse with a 415 a request body that is not JSON.
+
+        Per :rfc:`RFC 7644 §3.8 <7644#section-3.8>`, JSON is the default
+        format: a body without a :mdn:`Content-Type`, or with an empty one,
+        is read as JSON.
+        """
+        if content_type and not is_json_media_type(content_type):
             raise UnsupportedMediaTypeException
 
     def read_body(
@@ -474,11 +515,28 @@ class ScimService:
             f"{base_url.rstrip('/')}/{resource_type.endpoint.strip('/')}/{resource_id}"
         )
 
+    def reference_location(self, base_url: str, reference: str) -> str:
+        """Return the URL of a reference to a resource.
+
+        A reference relative to the SCIM root, such as ``Users/2819c223``,
+        becomes the location of the resource
+        (:rfc:`RFC 7643 §2.3.7 <7643#section-2.3.7>`). Absolute references
+        are kept.
+        """
+        if urlsplit(reference).scheme or reference.startswith("/"):
+            return reference
+        endpoint, _, resource_id = reference.rpartition("/")
+        resource_type = self.get_resource_type_by_endpoint(endpoint)
+        if resource_type is None or not resource_id:
+            return f"{base_url.rstrip('/')}/{reference}"
+        return self.resource_location(base_url, resource_type, resource_id)
+
     def publish(self, base_url: str, resource: Resource[Any]) -> Resource[Any]:
         """Return a copy of a stored resource in the form sent to the client.
 
-        Its location is set, and its version is left out when the service does
-        not support ETags.
+        Its location is set, its references to other resources become URLs
+        with :meth:`reference_location`, and its version is left out when the
+        service does not support ETags.
         """
         assert resource.meta is not None
         assert resource.id is not None
@@ -489,9 +547,41 @@ class ScimService:
         }
         if not self.etag_supported:
             update["version"] = None
-        return resource.model_copy(
-            update={"meta": resource.meta.model_copy(update=update)}
-        )
+        published = resource.model_copy(deep=True)
+        published.meta = resource.meta.model_copy(update=update)
+        self._publish_references(base_url, published)
+        return published
+
+    def _publish_references(self, base_url: str, resource: Resource[Any]) -> None:
+        """Replace in place the references of a resource to other resources by their URLs."""
+
+        def locate(reference: Any) -> Any:
+            if isinstance(reference, list):
+                return [locate(item) for item in reference]
+            if reference is None:
+                return None
+            return self.reference_location(base_url, reference)
+
+        for path in parametrize(Path, type(resource)).iter_paths(
+            target_type=[Reference]
+        ):
+            binding = path.resolve()
+            assert binding is not None
+            target_type = cast(type[Reference[Any]], binding.target_type)
+            reference_types = set(target_type.__reference_types__)
+            if not reference_types or reference_types & {"external", "uri"}:
+                continue
+
+            if binding.sub_field_name is None:
+                path.set(resource, locate(path.get(resource)), strict=False)
+                continue
+
+            head = f"{path.schema}:{path.parts[0]}" if path.schema else path.parts[0]
+            entries = Path(head).get(resource)
+            for entry in entries if isinstance(entries, list) else [entries]:
+                if entry is not None:
+                    reference = getattr(entry, binding.sub_field_name)
+                    setattr(entry, binding.sub_field_name, locate(reference))
 
     @staticmethod
     def resource_response(
@@ -500,9 +590,15 @@ class ScimService:
         response_parameters: ResponseParameters[Any] | None = None,
         status: HTTPStatus = HTTPStatus.OK,
     ) -> ScimResponse:
-        """Return the response carrying a published resource, with its ETag."""
-        assert resource.meta is not None
-        headers = {"ETag": resource.meta.version} if resource.meta.version else {}
+        """Return the response carrying a published resource, with its ETag.
+
+        Per :rfc:`RFC 7643 §3.1 <7643#section-3.1>`, the
+        :mdn:`Content-Location` header holds ``meta.location``.
+        """
+        assert resource.meta is not None and resource.meta.location is not None
+        headers = {"Content-Location": resource.meta.location}
+        if resource.meta.version:
+            headers["ETag"] = resource.meta.version
         body = resource.model_dump(
             scim_ctx=scim_ctx, response_parameters=response_parameters
         )
@@ -798,28 +894,73 @@ class ScimService:
         )
 
     @staticmethod
-    def bulk_outcome(operation: BulkOperation[Resource[Any]]) -> dict[str, Any]:
-        """Start the outcome of a bulk operation, before it runs."""
-        return {"method": operation.method, "bulk_id": operation.bulk_id}
+    def bulk_outcome(
+        base_url: str, operation: BulkOperation[Resource[Any]]
+    ) -> dict[str, Any]:
+        """Start the outcome of a bulk operation, before it runs.
+
+        :rfc:`RFC 7644 §3.7.3 <7644#section-3.7.3>` requires a location for
+        every operation but a failed POST. Until the operation is located, its
+        location is the URL of its path, so that an operation with an unknown
+        endpoint or an unresolved reference still has one.
+        """
+        outcome: dict[str, Any] = {
+            "method": operation.method,
+            "bulk_id": operation.bulk_id,
+        }
+        if operation.method != BulkOperation.Method.post:
+            path = (operation.path or "").lstrip("/")
+            outcome["location"] = f"{base_url.rstrip('/')}/{path}"
+        return outcome
+
+    def route_bulk_operation(
+        self, operation: BulkOperation[Resource[Any]]
+    ) -> ResourceType | None:
+        """Return the resource type a bulk operation acts on.
+
+        The path of the operation is routed as the path of a single request,
+        so that the operation fails with the same status
+        (:rfc:`RFC 7644 §3.7.3 <7644#section-3.7.3>`). An operation without a
+        valid method or path keeps its validation error, and has no resource
+        type.
+
+        :raises ~scim2_models.NotFoundException: When no endpoint has the path
+            of the operation, or no resource type is served at it.
+        :raises ~scim2_server.errors.MethodNotAllowedException: When the
+            endpoint does not support the method of the operation.
+        :raises ~scim2_models.InvalidValueException: When the path is not a
+            resource type endpoint or a resource, such as ``/Me`` or a search
+            (:rfc:`RFC 7644 §3.7 <7644#section-3.7>`).
+        """
+        if operation.method is None or operation.path is None:
+            return None
+        target = match(operation.method, operation.path)
+        if target.me or target.operation not in BULK_OPERATIONS.values():
+            raise InvalidValueException(
+                detail="A bulk operation must target a resource type endpoint or a resource"
+            )
+        return self.resource_type_at(cast(str, target.endpoint))
 
     def locate_bulk_operation(
         self,
         base_url: str,
+        resource_type: ResourceType | None,
         operation: BulkOperation[Resource[Any]],
         outcome: dict[str, Any],
-    ) -> ResourceType | None:
-        """Return the resource type a resolved bulk operation targets, and locate its resource.
+    ) -> None:
+        """Locate the resource of a resolved bulk operation.
 
         The location is set before the operation runs, so a failure still
-        knows it. :rfc:`RFC 7644 §3.7.3 <7644#section-3.7.3>` requires it for
-        every operation but a failed POST.
+        knows it. A POST only gets a location when it succeeds.
         """
-        resource_type = self.get_resource_type_by_endpoint(operation.endpoint or "")
-        if resource_type is not None and operation.resource_id:
+        if (
+            resource_type is not None
+            and operation.resource_id
+            and operation.method != BulkOperation.Method.post
+        ):
             outcome["location"] = self.resource_location(
                 base_url, resource_type, operation.resource_id
             )
-        return resource_type
 
     @staticmethod
     def bulk_validation_failure(
@@ -830,21 +971,6 @@ class ScimService:
             return None
         return {**outcome, "status": operation.status, "response": operation.response}
 
-    @staticmethod
-    def check_bulk_target(operation: BulkOperation[Resource[Any]]) -> str | None:
-        """Check that the path of a bulk operation fits its method.
-
-        :return: The identifier of the targeted resource, or :data:`None` for a POST.
-        :raises ~scim2_models.InvalidValueException: When a POST targets a
-            resource, or another method a resource type endpoint.
-        """
-        resource_id = operation.resource_id
-        if (operation.method == BulkOperation.Method.post) == bool(resource_id):
-            raise InvalidValueException(
-                detail="A POST path must target a resource type endpoint, other methods a resource"
-            )
-        return resource_id
-
     def bulk_failure(
         self, outcome: dict[str, Any], exception: Exception
     ) -> dict[str, Any]:
@@ -900,6 +1026,16 @@ class ScimService:
         meta = Meta(resource_type=type(resource).__name__, location=location)
         return resource.model_copy(update={"meta": meta})
 
+    @staticmethod
+    def discovery_response(resource: DiscoveryResourceT) -> ScimResponse:
+        """Return the response carrying a discovery resource, with its :mdn:`Content-Location`."""
+        assert resource.meta is not None and resource.meta.location is not None
+        return ScimResponse(
+            HTTPStatus.OK,
+            resource.model_dump(),
+            {"Content-Location": resource.meta.location},
+        )
+
     def service_provider_config(
         self, location: str, query: Mapping[str, str]
     ) -> ScimResponse:
@@ -908,9 +1044,7 @@ class ScimService:
         :param location: The URL of the endpoint.
         """
         self.forbid_filter(query)
-        return ScimResponse(
-            HTTPStatus.OK, self.locate(self.config, location).model_dump()
-        )
+        return self.discovery_response(self.locate(self.config, location))
 
     def resource_types(self, location: str, query: Mapping[str, str]) -> ScimResponse:
         """Return the list of the resource types."""
@@ -931,9 +1065,7 @@ class ScimService:
         self.forbid_filter(query)
         for resource_type in self.provider.resource_types:
             if resource_type.id == resource_type_id:
-                return ScimResponse(
-                    HTTPStatus.OK, self.locate(resource_type, location).model_dump()
-                )
+                return self.discovery_response(self.locate(resource_type, location))
         raise NotFoundException(detail=f"Resource type {resource_type_id!r} not found")
 
     def schemas(self, location: str, query: Mapping[str, str]) -> ScimResponse:
@@ -955,9 +1087,7 @@ class ScimService:
         self.forbid_filter(query)
         for schema in self.provider.schemas:
             if schema.id == schema_id:
-                return ScimResponse(
-                    HTTPStatus.OK, self.locate(schema, location).model_dump()
-                )
+                return self.discovery_response(self.locate(schema, location))
         raise NotFoundException(detail=f"Schema {schema_id!r} not found")
 
     # -- Errors ---------------------------------------------------------

{scim2_server-0.6.0 → scim2_server-0.6.2}/scim2_server/storage.py

@@ -26,7 +26,9 @@ class ScimStorage(ABC):
       stored resource, and the resources it receives are not changed either.
     - It fills ``id``, ``meta.resourceType``, ``meta.created``,
       ``meta.lastModified`` and ``meta.version``. It leaves ``meta.location``
-      to the server, which knows the URLs.
+      to the server, which knows the URLs. For the same reason, a reference
+      to another resource, such as ``members.$ref``, can be relative to the
+      SCIM root, such as ``Users/2819c223``. The server returns its URL.
     - The version changes whenever the resource changes. An update that
       changes nothing may keep it.
     - A resource that does not exist raises