cadurso 0.0.1__tar.gz

cadurso-0.0.1/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.1
+Name: cadurso
+Version: 0.0.1
+Summary: Authorization framework for Python-based applications
+License: MIT
+Author: cadu
+Author-email: cadu.coelho@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+# 🐻Cadurso[^1]
+Authorization framework for Python-based applications. Inspired by _[Oso](https://github.com/osohq/oso)_.
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cadurso)](https://pypi.org/project/cadurso/)
+[![PyPI - Version](https://img.shields.io/pypi/v/cadurso)](https://pypi.org/project/cadurso/)
+
+## Overview
+
+Cadurso is a lightweight and extensible authorization framework designed to handle access control scenarios by building and querying rules. It enables developers to define rules for actors performing actions on resources, with support for synchronous and asynchronous workflows. This library is inspired by the principles of the Oso framework, emphasizing flexibility and clarity in managing authorization.
+
+## Features
+
+- **Declarative Rule Definitions**: Define who can do what with ease. Rules are just Python functions[^2].
+- **Support for Sync and Async**: Handle both blocking and non-blocking authorization queries seamlessly. Rules can also be async.
+- **Immutable**: Prevent rule additions at runtime by freezing the authorization framework after defining rules.
+- **Error Handling**: Comprehensive exceptions for incomplete queries, operational issues, and rule definition errors.
+
+## Use Cases
+
+- Multi-tenant applications requiring fine-grained access control.
+- Implementing Role-Based Access Control, Attribute-Based Access Control or anything in between.
+
+## Core Concepts
+
+The core concepts of a Cadurso-powered authorization system are `Actors`, `Actions`, and `Resources`. They are combined into `Rules` which can be added to a `Cadurso` instance, represent capabilities within a system.
+
+After defining rules, the framework can be marked as "frozen" to prevent further modifications, ensuring the integrity of the authorization system.
+
+### Actors
+
+an `Actor` can be any Python instance. e.g `User`, `ServiceAccount`.
+
+### Actions
+
+`Actions` are operations that `Actors` can attempt on `Resources`. They can be any hashable object.
+
+Good candidates for `Actions` are `str`, `Enum`, etc.
+
+_(But any object that implements `__hash__` and `__eq__` can be used)_
+
+### Resources
+
+`Resources` are entities that `Actors` interact with. They can be any object that needs to be protected. e.g `Document`, `Post`.
+
+### Rules
+
+`Rules` are combinations of `Actors`, `Actions`, and `Resources`. They are expressed as Python functions that return a boolean value.
+
+Cadurso uses the type hints of the rule function to determine the types of the `Actor` and `Resource` arguments. The `Action` is passed as a parameter to the decorator that defines the rule.
+
+Rule format:
+```python
+cadurso = Cadurso()
+
+@cadurso.add_rule(<ACTION>)
+def rule_definition(actor: [ACTOR TYPE], resource: [RESOURCE TYPE]) -> bool:
+    # Return True or False based on the rule logic
+    ...
+```
+
+### State Freezing
+
+Once you are finished defining rules, the framework should be "frozen" to prevent further modifications. This ensures the integrity of the authorization system.
+
+```python
+cadurso.freeze()
+```
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install cadurso
+```
+
+### Complete Example
+
+#### Defining Rules
+```python
+# Initialize the authorization framework
+from cadurso import Cadurso
+cadurso = Cadurso()
+
+# Some Actors and Resources type definitions
+class User:
+    ...
+
+class Document:
+    ...
+
+# Some Actions
+class DocumentPermission(Enum):
+    EDIT = auto()
+    """Edit a document."""
+
+    VIEW = auto()
+    """Visualize a document."""
+
+
+# Define your authorization rules
+@cadurso.add_rule(DocumentPermission.EDIT)
+def owner_can_edit_own_document(actor: User, resource: Document) -> bool:
+    return actor == resource.owner
+
+@cadurso.add_rule(DocumentPermission.EDIT)
+def admin_can_edit_any_document(actor: User, _resource: Document) -> bool:
+    return actor.role == Role.ADMIN
+
+@cadurso.add_rule(DocumentPermission.VIEW)
+def owner_can_edit_own_document(actor: User, resource: Document) -> bool:
+    """Any person who can EDIT a document can also, obviously, VIEW it."""
+    # Piggyback on the EDIT permission.
+    # This way we don't need to write VIEW rules for both owners and admins.
+    return cadurso.can(actor).do(DocumentPermission.EDIT).on(resource)
+
+# Async rules are also okay, if you need them
+@cadurso.add_rule(DocumentPermission.VIEW)
+async def async_rule(actor: User, resource: Document) -> bool:
+    return await some_other_async_check(actor, resource)
+
+
+# Freeze the rules to prevent further modifications
+cadurso.freeze()
+
+# (You are ready to query now)
+# Use your `cadurso` instance as a singleton throughout your application
+```
+
+#### Querying
+
+(Instance definitions)
+```python
+# Some Actors
+john = User(name="John", role=Role.USER)
+gunnar = User(name="Gunnar", role=Role.ADMIN)
+
+# Some Resources
+johns_document = Document(owner=john)
+gunnars_document = Document(owner=gunnar)
+```
+
+(Query: Synchronous APIs)
+```python
+# `.is_allowed()` method to query permissions
+cadurso.is_allowed(john, DocumentPermission.EDIT, johns_document)   # Output: True
+cadurso.is_allowed(john, DocumentPermission.EDIT, gunnars_document) # Output: False
+cadurso.is_allowed(gunnar, DocumentPermission.EDIT, johns_document) # Output: True
+
+# Alternate querying syntax with `.can()`.
+# This is just syntactic sugar for the above.
+cadurso.can(john).do(DocumentPermission.EDIT).on(johns_document)    # Output: True
+cadurso.can(john).do(DocumentPermission.EDIT).on(gunnars_document)  # Output: False
+cadurso.can(gunnar).do(DocumentPermission.EDIT).on(johns_document)  # Output: True
+```
+
+(Query: Asynchronous APIs)
+```python
+# `.is_allowed_async()` method to query permissions asynchronously
+await cadurso.is_allowed_async(john, DocumentPermission.EDIT, johns_document)  # Output: True
+
+# Querying permissions with `.can()` asynchronously
+await cadurso.can(john).do(DocumentPermission.EDIT).on_async(johns_document)   # Output: True
+```
+
+#### More examples?
+
+- **ABAC** (Attribute-based Access Control) in Cadurso:
+  - Check [`/tests/akira/`](./tests/akira) for a full ABAC implementation set in the [Akira](https://en.wikipedia.org/wiki/Akira_(1988_film)) universe.
+
+
+- **RBAC** (Role-based Access Control) in Cadurso:
+  - The [`/tests/brazil/`](./tests/brazil) folder shows a full RBAC implementation set in the [Brazil](https://en.wikipedia.org/wiki/Brazil_(1985_film)) universe.
+
+
+## Contributing
+Contributions are welcome! Please ensure tests are included for any new features or bug fixes. Follow the standard pull request guidelines for this repository.
+
+## License
+Cadurso is licensed under the MIT License. See the LICENSE file for details.
+
+[^1]: Oso means "bear" in Spanish. `Cadurso` is a portmanteau of "Cadu" (my nickname) and "Urso" ("bear", in Portuguese) 😉
+
+[^2]: **Important:** Rules should be pure functions, and avoid mutating the actors or resources passed to them.
+      As we cannot enforce this at runtime, it is the responsibility of the developer to ensure this.
+

cadurso-0.0.1/README.md

@@ -0,0 +1,185 @@
+# 🐻Cadurso[^1]
+Authorization framework for Python-based applications. Inspired by _[Oso](https://github.com/osohq/oso)_.
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cadurso)](https://pypi.org/project/cadurso/)
+[![PyPI - Version](https://img.shields.io/pypi/v/cadurso)](https://pypi.org/project/cadurso/)
+
+## Overview
+
+Cadurso is a lightweight and extensible authorization framework designed to handle access control scenarios by building and querying rules. It enables developers to define rules for actors performing actions on resources, with support for synchronous and asynchronous workflows. This library is inspired by the principles of the Oso framework, emphasizing flexibility and clarity in managing authorization.
+
+## Features
+
+- **Declarative Rule Definitions**: Define who can do what with ease. Rules are just Python functions[^2].
+- **Support for Sync and Async**: Handle both blocking and non-blocking authorization queries seamlessly. Rules can also be async.
+- **Immutable**: Prevent rule additions at runtime by freezing the authorization framework after defining rules.
+- **Error Handling**: Comprehensive exceptions for incomplete queries, operational issues, and rule definition errors.
+
+## Use Cases
+
+- Multi-tenant applications requiring fine-grained access control.
+- Implementing Role-Based Access Control, Attribute-Based Access Control or anything in between.
+
+## Core Concepts
+
+The core concepts of a Cadurso-powered authorization system are `Actors`, `Actions`, and `Resources`. They are combined into `Rules` which can be added to a `Cadurso` instance, represent capabilities within a system.
+
+After defining rules, the framework can be marked as "frozen" to prevent further modifications, ensuring the integrity of the authorization system.
+
+### Actors
+
+an `Actor` can be any Python instance. e.g `User`, `ServiceAccount`.
+
+### Actions
+
+`Actions` are operations that `Actors` can attempt on `Resources`. They can be any hashable object.
+
+Good candidates for `Actions` are `str`, `Enum`, etc.
+
+_(But any object that implements `__hash__` and `__eq__` can be used)_
+
+### Resources
+
+`Resources` are entities that `Actors` interact with. They can be any object that needs to be protected. e.g `Document`, `Post`.
+
+### Rules
+
+`Rules` are combinations of `Actors`, `Actions`, and `Resources`. They are expressed as Python functions that return a boolean value.
+
+Cadurso uses the type hints of the rule function to determine the types of the `Actor` and `Resource` arguments. The `Action` is passed as a parameter to the decorator that defines the rule.
+
+Rule format:
+```python
+cadurso = Cadurso()
+
+@cadurso.add_rule(<ACTION>)
+def rule_definition(actor: [ACTOR TYPE], resource: [RESOURCE TYPE]) -> bool:
+    # Return True or False based on the rule logic
+    ...
+```
+
+### State Freezing
+
+Once you are finished defining rules, the framework should be "frozen" to prevent further modifications. This ensures the integrity of the authorization system.
+
+```python
+cadurso.freeze()
+```
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install cadurso
+```
+
+### Complete Example
+
+#### Defining Rules
+```python
+# Initialize the authorization framework
+from cadurso import Cadurso
+cadurso = Cadurso()
+
+# Some Actors and Resources type definitions
+class User:
+    ...
+
+class Document:
+    ...
+
+# Some Actions
+class DocumentPermission(Enum):
+    EDIT = auto()
+    """Edit a document."""
+
+    VIEW = auto()
+    """Visualize a document."""
+
+
+# Define your authorization rules
+@cadurso.add_rule(DocumentPermission.EDIT)
+def owner_can_edit_own_document(actor: User, resource: Document) -> bool:
+    return actor == resource.owner
+
+@cadurso.add_rule(DocumentPermission.EDIT)
+def admin_can_edit_any_document(actor: User, _resource: Document) -> bool:
+    return actor.role == Role.ADMIN
+
+@cadurso.add_rule(DocumentPermission.VIEW)
+def owner_can_edit_own_document(actor: User, resource: Document) -> bool:
+    """Any person who can EDIT a document can also, obviously, VIEW it."""
+    # Piggyback on the EDIT permission.
+    # This way we don't need to write VIEW rules for both owners and admins.
+    return cadurso.can(actor).do(DocumentPermission.EDIT).on(resource)
+
+# Async rules are also okay, if you need them
+@cadurso.add_rule(DocumentPermission.VIEW)
+async def async_rule(actor: User, resource: Document) -> bool:
+    return await some_other_async_check(actor, resource)
+
+
+# Freeze the rules to prevent further modifications
+cadurso.freeze()
+
+# (You are ready to query now)
+# Use your `cadurso` instance as a singleton throughout your application
+```
+
+#### Querying
+
+(Instance definitions)
+```python
+# Some Actors
+john = User(name="John", role=Role.USER)
+gunnar = User(name="Gunnar", role=Role.ADMIN)
+
+# Some Resources
+johns_document = Document(owner=john)
+gunnars_document = Document(owner=gunnar)
+```
+
+(Query: Synchronous APIs)
+```python
+# `.is_allowed()` method to query permissions
+cadurso.is_allowed(john, DocumentPermission.EDIT, johns_document)   # Output: True
+cadurso.is_allowed(john, DocumentPermission.EDIT, gunnars_document) # Output: False
+cadurso.is_allowed(gunnar, DocumentPermission.EDIT, johns_document) # Output: True
+
+# Alternate querying syntax with `.can()`.
+# This is just syntactic sugar for the above.
+cadurso.can(john).do(DocumentPermission.EDIT).on(johns_document)    # Output: True
+cadurso.can(john).do(DocumentPermission.EDIT).on(gunnars_document)  # Output: False
+cadurso.can(gunnar).do(DocumentPermission.EDIT).on(johns_document)  # Output: True
+```
+
+(Query: Asynchronous APIs)
+```python
+# `.is_allowed_async()` method to query permissions asynchronously
+await cadurso.is_allowed_async(john, DocumentPermission.EDIT, johns_document)  # Output: True
+
+# Querying permissions with `.can()` asynchronously
+await cadurso.can(john).do(DocumentPermission.EDIT).on_async(johns_document)   # Output: True
+```
+
+#### More examples?
+
+- **ABAC** (Attribute-based Access Control) in Cadurso:
+  - Check [`/tests/akira/`](./tests/akira) for a full ABAC implementation set in the [Akira](https://en.wikipedia.org/wiki/Akira_(1988_film)) universe.
+
+
+- **RBAC** (Role-based Access Control) in Cadurso:
+  - The [`/tests/brazil/`](./tests/brazil) folder shows a full RBAC implementation set in the [Brazil](https://en.wikipedia.org/wiki/Brazil_(1985_film)) universe.
+
+
+## Contributing
+Contributions are welcome! Please ensure tests are included for any new features or bug fixes. Follow the standard pull request guidelines for this repository.
+
+## License
+Cadurso is licensed under the MIT License. See the LICENSE file for details.
+
+[^1]: Oso means "bear" in Spanish. `Cadurso` is a portmanteau of "Cadu" (my nickname) and "Urso" ("bear", in Portuguese) 😉
+
+[^2]: **Important:** Rules should be pure functions, and avoid mutating the actors or resources passed to them.
+      As we cannot enforce this at runtime, it is the responsibility of the developer to ensure this.

cadurso-0.0.1/cadurso/__init__.py

@@ -0,0 +1,3 @@
+from .system import Cadurso
+
+__all__ = ["Cadurso"]

cadurso-0.0.1/cadurso/errors.py

@@ -0,0 +1,51 @@
+# Error messages
+from typing import Any
+
+ERROR_CANNOT_ADD_RULE_FROZEN = "Cannot add rules to a frozen Cadurso instance"
+
+ERROR_AUTH_FUNC_NOT_CALLABLE = "Authorization function must be a callable object"
+
+ERROR_AUTH_FUNC_WRONG_ARG_COUNT = (
+    "Authorization function must have two positional parameters"
+)
+
+
+def error_auth_func_wrong_number_of_parameters(param_count: int) -> str:
+    return f"{ERROR_AUTH_FUNC_WRONG_ARG_COUNT}, got {param_count}"
+
+
+ERROR_AUTH_FUNC_ACTION_NOT_HASHABLE = (
+    "Authorization function's target action must be hashable"
+)
+
+
+ERROR_AUTH_FUNC_RETURN_NOT_BOOL_OR_BOOL_AWAITABLE = "Authorization function must return a boolean or an awaitable that returns a boolean"
+
+
+def error_auth_func_return_not_bool_or_bool_awaitable(return_type: Any) -> str:
+    return f'{ERROR_AUTH_FUNC_RETURN_NOT_BOOL_OR_BOOL_AWAITABLE}, got "{return_type}"'
+
+
+ERROR_AUTH_FUNC_PARAM_MUST_BE_POSITIONAL = (
+    "Authorization function parameters must be positional"
+)
+
+
+def error_auth_func_param_not_positional(param_kind: Any, param: Any) -> str:
+    return f"{ERROR_AUTH_FUNC_PARAM_MUST_BE_POSITIONAL}, got {param_kind} on {param}"
+
+
+ERROR_AUTH_FUNC_TYPE_HINT_MUST_BE_TYPE = "type hint must be a type"
+
+
+def error_auth_func_type_hint_not_type(identifier: str, hint_value: Any) -> str:
+    return f'{identifier} {ERROR_AUTH_FUNC_TYPE_HINT_MUST_BE_TYPE}, got "{hint_value}"'
+
+
+ERROR_INSTANCE_NOT_FROZEN = (
+    "Cadurso instance must be frozen before querying permissions"
+)
+
+ERROR_CANNOT_FREEZE_ALREADY_FROZEN = "Cadurso instance is already frozen"
+
+ERROR_QUERY_IS_INCOMPLETE = "Query is incomplete"

cadurso-0.0.1/cadurso/exceptions.py

@@ -0,0 +1,26 @@
+class CadursoBaseError(Exception):
+    pass
+
+
+class CadursoRuleDefinitionError(CadursoBaseError):
+    """
+    Exception that gets raised when `Cadurso` is unable to ingest a new rule definition.
+    """
+
+    pass
+
+
+class CadursoOperationalError(CadursoBaseError):
+    """
+    Exception that gets raised when `Cadurso` encounters an operational error.
+    """
+
+    pass
+
+
+class CadursoIncompleteQueryError(CadursoBaseError):
+    """
+    Exception that gets raised when a query is incomplete and cannot be evaluated.
+    """
+
+    pass

cadurso-0.0.1/cadurso/sugar.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Never
+
+from cadurso.errors import ERROR_QUERY_IS_INCOMPLETE
+from cadurso.exceptions import CadursoIncompleteQueryError
+from cadurso.type_aliases import Action, Actor, AuthorizationDecision, Resource
+
+if TYPE_CHECKING:  # pragma: no cover
+    from cadurso import Cadurso
+
+
+@dataclass
+class OnResourceClause:
+    can_query: "CanQueryBuilder"
+    action: Action
+
+    def on(self, resource: Resource) -> AuthorizationDecision:
+        return self.can_query.cadurso.is_allowed(
+            self.can_query.actor, self.action, resource
+        )
+
+    async def on_async(self, resource: Resource) -> AuthorizationDecision:
+        return await self.can_query.cadurso.is_allowed_async(
+            self.can_query.actor, self.action, resource
+        )
+
+    def __bool__(self) -> Never:
+        """Avoid accidentally using the incomplete query as a boolean"""
+        raise CadursoIncompleteQueryError(
+            f"{ERROR_QUERY_IS_INCOMPLETE}: Do .on() or .on_async() to continue building it"
+        )
+
+
+@dataclass
+class CanQueryBuilder:
+    cadurso: "Cadurso"
+    actor: Actor
+
+    def do(self, action: Action) -> OnResourceClause:
+        return OnResourceClause(can_query=self, action=action)
+
+    def __bool__(self) -> Never:
+        """Avoid accidentally using the incomplete query as a boolean"""
+        raise CadursoIncompleteQueryError(
+            f"{ERROR_QUERY_IS_INCOMPLETE}: Do .do() to continue building it"
+        )

cadurso-0.0.1/cadurso/system.py

@@ -0,0 +1,222 @@
+import asyncio
+import inspect
+import logging
+from typing import Callable, Hashable, cast
+
+from cadurso.errors import (
+    ERROR_AUTH_FUNC_ACTION_NOT_HASHABLE,
+    ERROR_AUTH_FUNC_NOT_CALLABLE,
+    ERROR_CANNOT_ADD_RULE_FROZEN,
+    ERROR_CANNOT_FREEZE_ALREADY_FROZEN,
+    ERROR_INSTANCE_NOT_FROZEN,
+    error_auth_func_param_not_positional,
+    error_auth_func_return_not_bool_or_bool_awaitable,
+    error_auth_func_type_hint_not_type,
+    error_auth_func_wrong_number_of_parameters,
+)
+from cadurso.exceptions import (
+    CadursoOperationalError,
+    CadursoRuleDefinitionError,
+)
+from cadurso.sugar import CanQueryBuilder
+from cadurso.type_aliases import (
+    Action,
+    Actor,
+    ActorType,
+    AuthorizationDecision,
+    AuthorizationFunction,
+    Resource,
+    ResourceType,
+    RuleStorage,
+    RuleStorageKey,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Cadurso:
+    def __init__(self) -> None:
+        self.rule_count = 0
+        self.rule_storage: RuleStorage = {}
+
+        self.__frozen = False
+        """
+        A boolean indicating whether the Cadurso instance is frozen.
+
+        Frozen instances:
+        - Cannot have new rules added to them, and
+        - Cannot be unfrozen.
+        """
+
+    def __add(
+        self,
+        actor_type: ActorType,
+        action: Action,
+        resource_type: ResourceType,
+        authorization_function: AuthorizationFunction,
+    ) -> None:
+        storage_key: RuleStorageKey = (actor_type, action, resource_type)
+
+        self.rule_storage.setdefault(storage_key, set()).add(authorization_function)
+        self.rule_count += 1
+
+    def add_rule(
+        self, action: Action
+    ) -> Callable[[AuthorizationFunction], AuthorizationFunction]:
+        if self.__frozen:
+            raise CadursoRuleDefinitionError(ERROR_CANNOT_ADD_RULE_FROZEN)
+
+        def add_rule_inner(
+            authorization_function: AuthorizationFunction,
+        ) -> AuthorizationFunction:
+            # Check if action is hashable
+            if not isinstance(action, Hashable):
+                raise CadursoRuleDefinitionError(ERROR_AUTH_FUNC_ACTION_NOT_HASHABLE)
+
+            # Check if the authorization function is callable
+            if not callable(authorization_function):
+                raise CadursoRuleDefinitionError(ERROR_AUTH_FUNC_NOT_CALLABLE)
+
+            rule_func_signature = inspect.signature(authorization_function)
+
+            # Function should have, exactly, two parameters
+            if len(rule_func_signature.parameters) != 2:
+                raise CadursoRuleDefinitionError(
+                    error_auth_func_wrong_number_of_parameters(
+                        len(rule_func_signature.parameters)
+                    )
+                )
+
+            # Extract actor and resource Parameter objects from the inspected function signature
+            # Actor is the first parameter, resource is the second
+            actor_parameter, resource_parameter = (
+                rule_func_signature.parameters.values()
+            )
+            identified_parameters = (
+                ("Actor", actor_parameter),
+                ("Resource", resource_parameter),
+            )
+
+            # The two inspected function arguments type hints must be:
+            # - Types,
+            # - which generate Hashable instances, and
+            # - presented as positional arguments
+            for identifier, parameter in identified_parameters:
+                if not isinstance(parameter.annotation, type):
+                    raise CadursoRuleDefinitionError(
+                        error_auth_func_type_hint_not_type(
+                            identifier, parameter.annotation
+                        )
+                    )
+
+                if parameter.kind not in (
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.POSITIONAL_ONLY,
+                ):
+                    raise CadursoRuleDefinitionError(
+                        error_auth_func_param_not_positional(parameter.kind, parameter)
+                    )
+
+            # The return type must be boolean or an awaitable that returns a boolean
+            if not (
+                rule_func_signature.return_annotation is bool
+                or issubclass(rule_func_signature.return_annotation, asyncio.Future)
+            ):
+                raise CadursoRuleDefinitionError(
+                    error_auth_func_return_not_bool_or_bool_awaitable(
+                        rule_func_signature.return_annotation
+                    )
+                )
+
+            # Add the rule to the rule storage
+            # Parameter.annotation is the actual content right of the colon in the function signature
+            self.__add(
+                actor_parameter.annotation,
+                action,
+                resource_parameter.annotation,
+                authorization_function,
+            )
+
+            return authorization_function
+
+        return add_rule_inner
+
+    def is_allowed(
+        self, actor: Actor, action: Action, resource: Resource
+    ) -> AuthorizationDecision:
+        """
+        Evaluate a permission query synchronously.
+        If there are async rules, this method use asyncio.run() to evaluate them.
+        If you are already in an async context, use is_allowed_async() instead.
+
+        :param actor: The actor that is trying to perform an action on a resource.
+        :param action:  The action that the actor is trying to perform.
+        :param resource:  The resource that the actor is trying to perform the action on.
+        :return: A boolean indicating whether the actor is allowed to perform the action on the resource.
+        """
+        if not self.__frozen:
+            raise CadursoOperationalError(ERROR_INSTANCE_NOT_FROZEN)
+
+        for rule in self.rule_storage.get((type(actor), action, type(resource)), []):
+            if inspect.iscoroutinefunction(rule):
+                decision = cast(bool, asyncio.run(rule(actor, resource)))
+            else:
+                decision = cast(bool, rule(actor, resource))
+
+            if decision is not True:
+                logger.debug(
+                    f'"{actor}" is not allowed to "{action}" on "{resource}", trying other rules...'
+                )
+                continue
+
+            logger.debug(f'"{actor}" is allowed to "{action}" on "{resource}"')
+            return True
+
+        return False
+
+    async def is_allowed_async(
+        self, actor: Actor, action: Action, resource: Resource
+    ) -> AuthorizationDecision:
+        """
+        Evaluate a permission query asynchronously.
+
+        :param actor: The actor that is trying to perform an action on a resource.
+        :param action:  The action that the actor is trying to perform.
+        :param resource:  The resource that the actor is trying to perform the action on.
+        :return: A boolean indicating whether the actor is allowed to perform the action on the resource.
+        """
+        for rule in self.rule_storage.get((type(actor), action, type(resource)), []):
+            if inspect.iscoroutinefunction(rule):
+                decision = await rule(actor, resource)
+            else:
+                decision = rule(actor, resource)
+
+            if decision is not True:
+                logger.debug(
+                    f'"{actor}" is not allowed to "{action}" on "{resource}", trying other rules...'
+                )
+                continue
+
+            logger.debug(f'"{actor}" is allowed to "{action}" on "{resource}"')
+            return True
+
+        return False
+
+    def can(self, actor: Actor) -> CanQueryBuilder:
+        """
+        Syntax sugar for asking permissions (Query Builder-style).
+        """
+        return CanQueryBuilder(cadurso=self, actor=actor)
+
+    def freeze(self) -> None:
+        """
+        Freeze the Cadurso instance, preventing new rules from being added.
+        """
+
+        if self.__frozen:
+            raise CadursoOperationalError(ERROR_CANNOT_FREEZE_ALREADY_FROZEN)
+
+        self.__frozen = True
+
+        # Log the number of rules added
+        logger.debug(f"Frozen Cadurso instance with {self.rule_count} rules")

cadurso-0.0.1/cadurso/type_aliases.py

@@ -0,0 +1,48 @@
+from typing import Any, Awaitable, Callable, Hashable
+
+Actor = Any
+"""
+An Actor is an entity (instance) that will be granted or denied access to a resource.
+"""
+
+ActorType = type[Actor]
+"""
+An ActorType is a type that represents an Actor.
+"""
+
+Action = Hashable
+"""
+An Action that an Actor can perform on a Resource.
+
+Anything that implements __hash__ can be used as an ActionType.
+"""
+
+Resource = Any
+"""
+A Resource that an Actor can perform an Action on.
+"""
+
+ResourceType = type[Resource]
+"""
+A ResourceType is a type that represents a Resource.
+"""
+
+AuthorizationDecision = bool
+"""
+An AuthorizationDecision is a boolean that indicates whether an Actor is allowed to perform an Action on a Resource.
+"""
+
+AuthorizationFunction = (
+    Callable[[Actor, Resource], AuthorizationDecision]
+    | Callable[[Actor, Resource], Awaitable[AuthorizationDecision]]
+)
+"""
+An AuthorizationFunction is a function that takes an Actor and a Resource and returns (synchronously or asynchronously)
+an AuthorizationDecision, representing the decision to allow or deny the Actor to perform an Action on the Resource.
+"""
+
+RuleStorageKey = tuple[ActorType, Action, ResourceType]
+RuleStorage = dict[RuleStorageKey, set[AuthorizationFunction]]
+"""
+A RuleStorage is a dictionary that maps a tuple of an Actor, an Action, and a Resource to a set of AuthorizationFunctions.
+"""

cadurso-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[tool.poetry]
+name = "cadurso"
+version = "0.0.1"
+description = "Authorization framework for Python-based applications"
+authors = ["cadu <cadu.coelho@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13"
+]
+
+[tool.poetry.dependencies]
+python = ">=3.11"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+pre-commit = "^4.0.1"
+pytest-asyncio = "^0.25.0"
+mypy = "^1.14.0"
+pytest-cov = "^6.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"