kinto 23.2.1__py3-none-any.whl

kinto/core/listeners/__init__.py

@@ -0,0 +1,9 @@
+class ListenerBase:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __call__(self, event):
+        """
+        :param event: Incoming event
+        """
+        raise NotImplementedError()

kinto/core/metrics.py

@@ -0,0 +1,94 @@
+import types
+
+from zope.interface import Interface, implementer
+
+from kinto.core import utils
+
+
+class IMetricsService(Interface):
+    """
+    An interface that defines the metrics service contract.
+    Any class implementing this must provide all its methods.
+    """
+
+    def timer(key):
+        """
+        Watch execution time in seconds.
+        """
+
+    def observe(self, key, value, labels=[]):
+        """
+        Observe a give `value` for the specified `key`.
+        """
+
+    def count(key, count=1, unique=None):
+        """
+        Count occurrences. If `unique` is set, overwrites the counter value
+        on each call.
+
+        `unique` should be of type ``list[tuple[str,str]]``.
+        """
+
+
+class NoOpTimer:
+    def __call__(self, f):
+        @utils.safe_wraps(f)
+        def _wrapped(*args, **kwargs):
+            return f(*args, **kwargs)
+
+        return _wrapped
+
+    def __enter__(self):
+        pass
+
+    def __exit__(self, *args, **kwargs):
+        pass
+
+
+@implementer(IMetricsService)
+class NoOpMetricsService:
+    def timer(self, key, value=None, labels=[]):
+        return NoOpTimer()
+
+    def observe(self, key, value, labels=[]):
+        pass
+
+    def count(self, key, count=1, unique=None):
+        pass
+
+
+def watch_execution_time(metrics_service, obj, prefix="", classname=None):
+    """
+    Decorate all methods of an object in order to watch their execution time.
+    Metrics will be named `{prefix}.{classname}.{method}`.
+    """
+    classname = classname or utils.classname(obj)
+    members = dir(obj)
+    for name in members:
+        method = getattr(obj, name)
+        is_method = isinstance(method, types.MethodType)
+        if not name.startswith("_") and is_method:
+            metric_name = f"{prefix}.{classname}.seconds"
+            labels = [("method", name)]
+            decorated_method = metrics_service.timer(metric_name, labels=labels)(method)
+            setattr(obj, name, decorated_method)
+
+
+def listener_with_timer(config, key, func):
+    """
+    Add a timer with the specified `key` on the specified `func`.
+    This is used to avoid evaluating `config.registry.metrics` during setup time
+    to avoid having to deal with initialization order and configuration committing.
+    """
+
+    def wrapped(*args, **kwargs):
+        metrics_service = config.registry.metrics
+        if not metrics_service:
+            # This only happens if `kinto.core.initialization.setup_metrics` is
+            # not listed in the `initialization_sequence` setting.
+            return func(*args, **kwargs)
+        # If metrics are enabled, monitor execution time of listeners.
+        with metrics_service.timer(key + ".seconds" if not key.endswith(".seconds") else key):
+            return func(*args, **kwargs)
+
+    return wrapped

kinto/core/openapi.py

@@ -0,0 +1,115 @@
+from kinto.core.cornice_swagger import CorniceSwagger
+from kinto.core.cornice_swagger.converters.schema import TypeConverter
+from kinto.core.schema import Any
+
+
+class AnyTypeConverter(TypeConverter):
+    """Convert type agnostic parameter to swagger."""
+
+    def __call__(self, schema_node):
+        return {}
+
+
+class OpenAPI(CorniceSwagger):
+    """OpenAPI documentation generator."""
+
+    custom_type_converters = {Any: AnyTypeConverter}
+    """Kinto additional type converters."""
+
+    security_definitions = {}
+    """Kinto security definitions. May be used for setting other security methods."""
+
+    security_roles = {}
+    """Kinto resource security roles. May be used for setting OAuth roles by plugins."""
+
+    @classmethod
+    def expose_authentication_method(cls, method_name, definition):
+        """Allow security extensions to expose authentication methods on the
+        OpenAPI documentation. The definition field should correspond to a
+        valid OpenAPI security definition. Refer the OpenAPI 2.0 specification
+        for more information.
+        https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
+
+        Below are some examples for BasicAuth and OAuth2::
+
+            {
+                "type": "basic",
+                "description" "My basicauth method."
+
+            }
+
+            {
+                "type": "oauth2",
+                "authorizationUrl": "https://oauth-stable.dev.lcip.org/v1",
+                "flow": "implicit",
+                "scopes": {"kinto": "Kinto user scope."}
+            }
+
+        """
+        cls.security_definitions[method_name] = definition
+        cls.security_roles[method_name] = definition.get("scopes", {}).keys()
+
+    def __init__(self, services, request):
+        super().__init__(services)
+
+        self.request = request
+        self.settings = request.registry.settings
+
+        self.api_title = self.settings["project_name"]
+        self.api_version = self.settings["http_api_version"]
+        self.ignore_ctypes = ["application/json-patch+json"]
+
+        # Matches the base routing address - See kinto.core.initialization
+        self.base_path = f"/v{self.api_version.split('.')[0]}"
+
+    def generate(self):
+        base_spec = {
+            "host": self.request.host,
+            "schemes": [self.settings.get("http_scheme") or "http"],
+            "securityDefinitions": self.security_definitions,
+        }
+
+        return super(OpenAPI, self).generate(swagger=base_spec)
+
+    def default_tags(self, service, method):
+        """Povides default tags to views."""
+
+        base_tag = service.name.capitalize()
+        base_tag = base_tag.replace("-plural", "s")
+        base_tag = base_tag.replace("-object", "s")
+
+        return [base_tag]
+
+    def default_op_ids(self, service, method):
+        """Povides default operation ids to methods if not defined on view."""
+
+        method = method.lower()
+        method_mapping = {"post": "create", "put": "update"}
+        if method in method_mapping:
+            method = method_mapping[method]
+
+        resource = service.name
+        if method == "create":
+            resource = resource.replace("-plural", "")
+
+        resource = resource.replace("-plural", "s")
+        resource = resource.replace("-object", "")
+        op_id = f"{method}_{resource}"
+
+        return op_id
+
+    def default_security(self, service, method):
+        """Provides OpenAPI security properties based on kinto policies."""
+
+        definitions = service.definitions
+
+        # Get method view arguments
+        for definition in definitions:  # pragma: no branch
+            met, view, args = definition
+            if met == method:
+                break
+
+        if args.get("permission") == "__no_permission_required__":
+            return []
+        else:
+            return [{name: list(roles)} for name, roles in self.security_roles.items()]

kinto/core/permission/__init__.py

@@ -0,0 +1,202 @@
+import logging
+
+from pyramid.settings import asbool
+
+
+logger = logging.getLogger(__name__)
+
+
+__HEARTBEAT_KEY__ = "__heartbeat__"
+
+
+class PermissionBase:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def initialize_schema(self, dry_run=False):
+        """Create every necessary objects (like tables or indices) in the
+        backend.
+
+        This is executed with the ``kinto migrate`` command.
+
+        :param bool dry_run: simulate instead of executing the operations.
+        """
+        raise NotImplementedError
+
+    def flush(self):
+        """Delete all data stored in the permission backend."""
+        raise NotImplementedError
+
+    def add_user_principal(self, user_id, principal):
+        """Add an additional principal to a user.
+
+        :param str user_id: The user_id to add the principal to.
+        :param str principal: The principal to add.
+        """
+        raise NotImplementedError
+
+    def remove_user_principal(self, user_id, principal):
+        """Remove an additional principal from a user.
+
+        :param str user_id: The user_id to remove the principal to.
+        :param str principal: The principal to remove.
+        """
+        raise NotImplementedError
+
+    def remove_principal(self, principal):
+        """Remove a principal from every user.
+
+        :param str principal: The principal to remove.
+        """
+        raise NotImplementedError
+
+    def get_user_principals(self, user_id):
+        """Return the set of additionnal principals given to a user.
+
+        :param str user_id: The user_id to get the list of groups for.
+        :returns: The list of group principals the user is in.
+        :rtype: set
+
+        """
+        raise NotImplementedError
+
+    def add_principal_to_ace(self, object_id, permission, principal):
+        """Add a principal to an Access Control Entry.
+
+        :param str object_id: The object to add the permission principal to.
+        :param str permission: The permission to add the principal to.
+        :param str principal: The principal to add to the ACE.
+        """
+        raise NotImplementedError
+
+    def remove_principal_from_ace(self, object_id, permission, principal):
+        """Remove a principal to an Access Control Entry.
+
+        :param str object_id: The object to remove the permission principal to.
+        :param str permission: The permission that should be removed.
+        :param str principal: The principal to remove to the ACE.
+        """
+        raise NotImplementedError
+
+    def get_object_permission_principals(self, object_id, permission):
+        """Return the set of principals of a bound permission
+        (unbound permission + object id).
+
+        :param str object_id: The object_id the permission is set to.
+        :param str permission: The permission to query.
+        :returns: The list of user principals
+        :rtype: set
+
+        """
+        raise NotImplementedError
+
+    def get_accessible_objects(self, principals, bound_permissions=None, with_children=True):
+        """Return the list of objects where the specified `principals`
+        have some permissions.
+
+        If `bound_permissions` parameter is specified, the list is limited to
+        the specified object or permissions.
+
+        :param list principals: List of user principals
+        :param list bound_permissions: An optional list of tuples
+            (object_id, permission) to limit the results.
+            The object ids can be a pattern, (e.g. ``*``, ``'/my/articles*'``).
+        :param bool with_children: Include the children of object ids or not.
+
+        :returns: A mapping whose keys are the object_ids and the values are
+            the related list of permissions.
+        :rtype: dict
+        """
+        raise NotImplementedError
+
+    def get_authorized_principals(self, bound_permissions):
+        """Return the full set of authorized principals for a list of bound
+        permissions (object + permission).
+
+        :param str object_id: The object_id the permission is set to.
+        :param list bound_permissions: An list of tuples
+            (object_id, permission) to be fetched.
+        :returns: The list of user principals
+        :rtype: set
+
+        """
+        raise NotImplementedError
+
+    def check_permission(self, principals, bound_permissions):
+        """Test if a principal set have got a permission on an object.
+
+        :param set principals:
+            A set of user principals to test the permission against.
+        :param list bound_permissions: An list of tuples
+            (object_id, permission) to be checked.
+        :rtype: bool
+        """
+        principals = set(principals)
+        authorized = self.get_authorized_principals(bound_permissions)
+        return len(authorized & principals) > 0
+
+    def get_object_permissions(self, object_id, permissions=None):
+        return self.get_objects_permissions([object_id], permissions)[0]
+
+    def get_objects_permissions(self, objects_ids, permissions=None):
+        """Return a list of mapping, for each object id specified, with the
+        set of principals for each permission.
+
+        :param list objects_ids: The list of object_ids.
+        :param list permissions: Optional list of permissions to limit the
+            results. If not specified, retrieve all.
+        :returns: A list of dictionnaries with the list of user principals for
+            each object permission.
+        :rtype: list
+        """
+        raise NotImplementedError
+
+    def replace_object_permissions(self, object_id, permissions):
+        """Update the set of principals allowed to perform some actions on an
+        object.
+
+        The only update of permissions allowed by Kinto's API is
+        complete replacement of some permission (e.g. I don't know who
+        was previously allowed to read this object, but now it's Joe,
+        Frank, and Paul). This method implements that, completely
+        replacing the set of principals who are granted the given
+        permissions (while leaving other permissions alone).
+
+        :param str object_id: The object to replace permissions on.
+        :param permissions: A dict of perm -> principals (where
+        principals is an iterable of individuals) to be granted on
+        this object.
+
+        """
+        raise NotImplementedError
+
+    def delete_object_permissions(self, *object_id_list):
+        """Delete all listed object permissions.
+
+        :param str object_id: Remove given objects permissions.
+        """
+        raise NotImplementedError
+
+
+def heartbeat(backend):
+    def ping(request):
+        """Test the permission backend is operational.
+
+        :param request: current request object
+        :type request: :class:`~pyramid:pyramid.request.Request`
+        :returns: ``True`` is everything is ok, ``False`` otherwise.
+        :rtype: bool
+        """
+        try:
+            if asbool(request.registry.settings.get("readonly")):
+                # Do not try to write in readonly mode.
+                backend.get_user_principals(__HEARTBEAT_KEY__)
+            else:
+                backend.add_user_principal(__HEARTBEAT_KEY__, "alive")
+                backend.remove_user_principal(__HEARTBEAT_KEY__, "alive")
+        except Exception:
+            logger.exception("Heartbeat Error")
+            return False
+        return True
+
+    return ping

kinto/core/permission/memory.py

@@ -0,0 +1,167 @@
+import re
+
+from kinto.core.decorators import synchronized
+from kinto.core.permission import PermissionBase
+
+
+class Permission(PermissionBase):
+    """Permission backend implementation in local process memory.
+
+    Enable in configuration::
+
+        kinto.permission_backend = kinto.core.permission.memory
+
+    :noindex:
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.flush()
+
+    def initialize_schema(self, dry_run=False):
+        # Nothing to do.
+        pass
+
+    def flush(self):
+        self._store = {}
+
+    @synchronized
+    def add_user_principal(self, user_id, principal):
+        user_key = f"user:{user_id}"
+        user_principals = self._store.get(user_key, set())
+        user_principals.add(principal)
+        self._store[user_key] = user_principals
+
+    @synchronized
+    def remove_user_principal(self, user_id, principal):
+        user_key = f"user:{user_id}"
+        user_principals = self._store.get(user_key, set())
+        try:
+            user_principals.remove(principal)
+        except KeyError:
+            pass
+        if len(user_principals) == 0:
+            if user_key in self._store:
+                del self._store[user_key]
+        else:
+            self._store[user_key] = user_principals
+
+    @synchronized
+    def remove_principal(self, principal):
+        for key, user_principals in self._store.items():
+            if not key.startswith("user:"):
+                continue
+            try:
+                user_principals.remove(principal)
+            except KeyError:
+                pass
+
+    @synchronized
+    def get_user_principals(self, user_id):
+        # Fetch the groups the user is in.
+        user_key = f"user:{user_id}"
+        members = self._store.get(user_key, set())
+        # Fetch the groups system.Authenticated is in.
+        group_authenticated = self._store.get("user:system.Authenticated", set())
+        return members | group_authenticated
+
+    @synchronized
+    def add_principal_to_ace(self, object_id, permission, principal):
+        permission_key = f"permission:{object_id}:{permission}"
+        object_permission_principals = self._store.get(permission_key, set())
+        object_permission_principals.add(principal)
+        self._store[permission_key] = object_permission_principals
+
+    @synchronized
+    def remove_principal_from_ace(self, object_id, permission, principal):
+        permission_key = f"permission:{object_id}:{permission}"
+        object_permission_principals = self._store.get(permission_key, set())
+        try:
+            object_permission_principals.remove(principal)
+        except KeyError:
+            pass
+        if len(object_permission_principals) == 0:
+            if permission_key in self._store:
+                del self._store[permission_key]
+        else:
+            self._store[permission_key] = object_permission_principals
+
+    @synchronized
+    def get_object_permission_principals(self, object_id, permission):
+        permission_key = f"permission:{object_id}:{permission}"
+        members = self._store.get(permission_key, set())
+        return members
+
+    @synchronized
+    def get_accessible_objects(self, principals, bound_permissions=None, with_children=True):
+        principals = set(principals)
+        candidates = []
+        if bound_permissions is None:
+            for key, value in self._store.items():
+                if key.startswith("permission:"):
+                    _, object_id, permission = key.split(":", 2)
+                    candidates.append((object_id, permission, value))
+        else:
+            for pattern, perm in bound_permissions:
+                id_match = ".*" if with_children else "[^/]+"
+                regexp = re.compile(f"^{pattern.replace('*', id_match)}$")
+                for key, value in self._store.items():
+                    if key.endswith(perm):
+                        object_id = key.split(":")[1]
+                        if regexp.match(object_id):
+                            candidates.append((object_id, perm, value))
+
+        perms_by_object_id = {}
+        for object_id, perm, value in candidates:
+            if len(principals & value) > 0:
+                perms_by_object_id.setdefault(object_id, set()).add(perm)
+        return perms_by_object_id
+
+    @synchronized
+    def get_authorized_principals(self, bound_permissions):
+        principals = set()
+        for obj_id, perm in bound_permissions:
+            principals |= self.get_object_permission_principals(obj_id, perm)
+        return principals
+
+    @synchronized
+    def get_objects_permissions(self, objects_ids, permissions=None):
+        result = []
+        for object_id in objects_ids:
+            if permissions is None:
+                aces = [k for k in self._store.keys() if k.startswith(f"permission:{object_id}:")]
+            else:
+                aces = [f"permission:{object_id}:{permission}" for permission in permissions]
+            perms = {}
+            for ace in aces:
+                # Should work with 'permission:/url/id:object:create'.
+                permission = ace.split(":", 2)[2]
+                perms[permission] = set(self._store[ace])
+            result.append(perms)
+        return result
+
+    @synchronized
+    def replace_object_permissions(self, object_id, permissions):
+        for permission, principals in permissions.items():
+            permission_key = f"permission:{object_id}:{permission}"
+            if permission_key in self._store and len(principals) == 0:
+                del self._store[permission_key]
+            elif principals:
+                self._store[permission_key] = set(principals)
+        return permissions
+
+    @synchronized
+    def delete_object_permissions(self, *object_id_list):
+        to_delete = []
+        for key in self._store.keys():
+            object_id = key.split(":")[1]
+            for pattern in object_id_list:
+                regexp = re.compile(f"^{pattern.replace('*', '.*')}$")
+                if regexp.match(object_id):
+                    to_delete.append(key)
+        for k in to_delete:
+            del self._store[k]
+
+
+def load_from_config(config):
+    return Permission()