fastapi-guardian 0.1.0__py3-none-any.whl

fastapi_guardian/__init__.py

@@ -0,0 +1,19 @@
+from .dto import (
+    AuthContext,
+    AuthPredicate,
+    BasePermissionGrant,
+    PermissionContext,
+    PermissionDefinition,
+    PredicateContext,
+    Principal,
+)
+
+__all__ = [
+    "BasePermissionGrant",
+    "PermissionDefinition",
+    "AuthPredicate",
+    "PredicateContext",
+    "Principal",
+    "PermissionContext",
+    "AuthContext",
+]

fastapi_guardian/dependencies.py

@@ -0,0 +1,63 @@
+import abc
+import typing
+
+from fastapi.exceptions import HTTPException
+
+from fastapi_guardian import exceptions
+from fastapi_guardian.dto import (
+    AuthContext,
+    AuthPredicatePayload,
+    AuthScope,
+    Identifier,
+    PermissionDefinition,
+    Principal,
+)
+from fastapi_guardian.engine import BaseAuthEngine
+from fastapi_guardian.resource import Resource
+
+
+class BasePermission[T: type[Resource], ID: Identifier](abc.ABC):
+    __slots__ = ("permission", "auth_engine")
+
+    auth_engine: BaseAuthEngine
+
+    def __init__(
+        self,
+        resource: T,
+        action: str,
+        scopes: list[AuthScope] | None = None,
+        predicates: list[AuthPredicatePayload[T, ID]] | None = None,
+        auth_engine: BaseAuthEngine | None = None,
+    ) -> None:
+        if auth_engine is not None:
+            self.auth_engine = auth_engine
+
+        if self.auth_engine is None:
+            raise exceptions.ImproperlyConfigured(
+                "auth_engine is required either as argument or as class attribute"
+            )
+
+        self.permission = PermissionDefinition[T, ID](
+            resource=resource,
+            action=action,
+            scopes=scopes or ["global"],
+            predicates=predicates or [],
+        )
+        self.auth_engine.register_permission(permission=self.permission)
+
+    @abc.abstractmethod
+    async def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> AuthContext:
+        pass
+
+    async def authorize(self, principal: Principal[ID] | None = None) -> AuthContext:
+        if principal is None:
+            raise HTTPException(status_code=401, detail="Unauthorized")
+
+        context = AuthContext[T, ID](
+            principal=principal, current_permission=self.permission
+        )
+        access_granted = self.auth_engine.has_permission(context=context)
+        if access_granted:
+            return context
+
+        raise HTTPException(status_code=403, detail="Forbidden")

fastapi_guardian/dto.py

@@ -0,0 +1,115 @@
+import typing
+
+from pydantic import (
+    BaseModel,
+    Field,
+    SerializerFunctionWrapHandler,
+    ValidationError,
+    model_serializer,
+    model_validator,
+)
+
+from fastapi_guardian.resource import Resource
+
+Identifier = str | int
+AuthScope = typing.Literal["global", "conditional", "resource"]
+
+
+class BasePermissionGrant(BaseModel):
+    resource: str
+    action: str
+    scope: AuthScope
+
+    @model_serializer(mode="wrap")
+    def to_json(self, handler: SerializerFunctionWrapHandler) -> dict:
+        serialized = handler(self)
+        resource = serialized.pop("resource")
+        action = serialized.pop("action")
+        scope = serialized.pop("scope")
+        return {
+            "resource": resource,
+            "action": action,
+            "scope": scope,
+            "extra": serialized,
+        }
+
+    @model_validator(mode="before")
+    @classmethod
+    def from_json(cls, data: typing.Any) -> typing.Any:
+        if isinstance(data, dict):
+            extra = data.pop("extra", {})
+            return {**data, **extra}
+        return data
+
+
+class GlobalPermissionGrant(BasePermissionGrant):
+    scope: typing.Literal["global"] = "global"
+
+
+class ConditionalPermissionGrant(BasePermissionGrant):
+    scope: typing.Literal["conditional"] = "conditional"
+    condition: str
+
+
+class ResourcePermissionGrant(BasePermissionGrant):
+    scope: typing.Literal["resource"] = "resource"
+    resource_id: str
+
+
+PermissionGrant = (
+    GlobalPermissionGrant | ConditionalPermissionGrant | ResourcePermissionGrant
+)
+
+
+class PermissionContext(BaseModel):
+    permissions: list[typing.Annotated[PermissionGrant, Field(discriminator="scope")]]
+
+
+class Principal[ID: Identifier](PermissionContext):
+    id: ID
+    email: str
+    username: str
+    roles: list[str] = Field(default_factory=list)
+
+
+class PredicateContext[T: type[Resource], ID: Identifier](BaseModel):
+    principal: Principal[ID]
+    resource: T
+
+
+class AuthPredicate[T: type[Resource], ID: Identifier](BaseModel):
+    fn: typing.Callable[[PredicateContext[T, ID]], typing.Any]
+    name: str
+    description: str = Field(default="", min_length=0)
+
+
+class AuthPredicatePayload[T: type[Resource], ID: Identifier](typing.TypedDict):
+    fn: typing.Callable[[PredicateContext[T, ID]], typing.Any]
+    name: str
+    description: typing.NotRequired[str]
+
+
+class PermissionDefinition[T: type[Resource], ID: Identifier](BaseModel):
+    """Defines permission required for a given API resource along with all auth metadata."""
+
+    resource: T
+    action: str
+    scopes: typing.Annotated[list[AuthScope], Field(default_factory=lambda: ["global"])]
+    predicates: typing.Annotated[
+        list[AuthPredicate[T, ID]], Field(default_factory=list)
+    ]
+
+    @model_validator(mode="after")
+    def validate_predicates(self) -> typing.Any:
+        if "conditional" in self.scopes and not self.predicates:
+            raise ValidationError(
+                "Conditional permissions must have at least one predicate"
+            )
+        return self
+
+
+class AuthContext[T: type[Resource], ID: Identifier](BaseModel):
+    """Defines all related info to make authorization decision."""
+
+    principal: Principal
+    current_permission: PermissionDefinition[T, ID]

fastapi_guardian/engine.py

@@ -0,0 +1,66 @@
+from collections import defaultdict
+
+from fastapi_guardian import exceptions
+from fastapi_guardian.dto import AuthContext, PermissionDefinition, PermissionGrant
+from fastapi_guardian.resource import Resource
+
+
+class BaseAuthEngine:
+    _permissions: list[PermissionDefinition]
+    # resource -> action -> PermissionDefinition
+    _permission_tree: dict[str, dict[str, PermissionDefinition]]
+
+    def __init__(self) -> None:
+        self._permissions = []
+        self._permission_tree = defaultdict(dict)
+
+    def has_permission(self, *, context: AuthContext) -> bool:
+        """Check if the principal has ANY permission for the given resource and action."""
+        decision = bool(self.matching_grants(context=context))
+        self.log_decision(context=context, decision=decision)
+        return decision
+
+    def matching_grants(self, *, context: AuthContext) -> list[PermissionGrant]:
+        """Get all permission grants that match the given principal, resource and action."""
+        return [
+            grant
+            for grant in context.principal.permissions
+            if grant.resource == context.current_permission.resource.__resource_code__
+            and grant.action == context.current_permission.action
+        ]
+
+    def log_decision(self, *, context: AuthContext, decision: bool) -> None:
+        """Implement in subclass to log access decision."""
+        return None
+
+    def register_permission(self, permission: PermissionDefinition) -> None:
+        """
+        Register new permission into catalog of this engine.
+        Can be used later for introspection and administration (e.g., show list of supported permissions in UI, modify OpenAPI schema, etc.)
+        """
+        resource_code = permission.resource.__resource_code__
+        if (
+            self._permission_tree.get(resource_code, {}).get(permission.action)
+            is not None
+        ):
+            raise exceptions.ImproperlyConfigured(
+                f"Permission {permission.action} already registered for resource {resource_code}."
+                "To avoid confusion, it's currently impossible to re-register the same permission."
+            )
+
+        self._permissions.append(permission)
+        self._permission_tree[resource_code][permission.action] = permission
+
+    def permissions_for(self, resource: type[Resource]) -> list[PermissionDefinition]:
+        """Retuns all registered permissions for the given resource."""
+        return list(self._permission_tree[resource.__resource_code__].values())
+
+    @property
+    def permissions_by_resource(self) -> dict[str, list[PermissionDefinition]]:
+        """Returns all registered permissions grouped by resource."""
+        return {k: list(v.values()) for k, v in self._permission_tree.items()}
+
+    @property
+    def permissions(self) -> list[PermissionDefinition]:
+        """Returns all registered permissions."""
+        return self._permissions

fastapi_guardian/exceptions.py

@@ -0,0 +1,6 @@
+class GuardianException(Exception):
+    pass
+
+
+class ImproperlyConfigured(GuardianException):
+    pass

fastapi_guardian/expression.py

@@ -0,0 +1,213 @@
+"""
+Module contains microlanguage definition for permission conditions.
+
+Grammar is sufficient to parse permission conditions like:
+'self or (attachment_cv or attachment_doc and not supervisor)'
+... and convert to SQLAlchemy expression.
+"""
+
+import typing
+
+from lark import Lark, Token, Transformer
+from lark.exceptions import UnexpectedInput, VisitError
+
+from fastapi_guardian.dto import AuthContext, AuthPredicate
+
+
+class ExpressionError(Exception):
+    pass
+
+
+class ExpressionParsingError(ExpressionError):
+    pass
+
+
+class InvalidPredicateError(ExpressionError):
+    pass
+
+
+class ExpressionEvaluationError(ExpressionError):
+    pass
+
+
+expression_grammar = Lark(
+    r"""
+    ?expression: or_expression
+
+    ?or_expression: and_expression (OR and_expression)*
+    ?and_expression: not_expression (AND not_expression)*
+    ?not_expression: NOT not_expression -> not_expression
+        | atom
+
+    ?atom: PREDICATE -> predicate
+        | "(" expression ")"
+
+    OR.2: "or"
+    AND.2: "and"
+    NOT.2: "not"
+    PREDICATE: /[A-Za-z_][A-Za-z0-9_]*/
+
+    %import common.WS
+    %ignore WS
+""",
+    parser="lalr",
+    start="expression",
+)
+
+
+# Operator precedence used to decide whether to wrap a child node in parentheses
+# during string serialization. Higher number = binds tighter.
+_OR_PRECEDENCE = 1
+_AND_PRECEDENCE = 2
+_NOT_PRECEDENCE = 3
+_ATOM_PRECEDENCE = 4
+
+
+class AbstractPredicateNode:
+    precedence: typing.ClassVar[int] = _ATOM_PRECEDENCE
+    predicate: AuthPredicate
+
+    __slots__ = ("predicate",)
+
+    def __init__(self, *, predicate: AuthPredicate) -> None:
+        self.predicate = predicate
+
+    def to_string(self) -> str:
+        return self.predicate.name
+
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        raise NotImplementedError
+
+
+class AbstractNotNode:
+    precedence: typing.ClassVar[int] = _NOT_PRECEDENCE
+    child: AnyAbstractNode
+
+    __slots__ = ("child",)
+
+    def __init__(self, *, child: AnyAbstractNode) -> None:
+        self.child = child
+
+    def to_string(self) -> str:
+        return f"not {_render_child(self.child, self.precedence)}"
+
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        raise NotImplementedError
+
+
+class AbstractAndNode:
+    precedence: typing.ClassVar[int] = _AND_PRECEDENCE
+    children: tuple[AnyAbstractNode, ...]
+
+    __slots__ = ("children",)
+
+    def __init__(self, *, children: tuple[AnyAbstractNode, ...]) -> None:
+        self.children = children
+
+    def to_string(self) -> str:
+        return " and ".join(
+            _render_child(child, self.precedence) for child in self.children
+        )
+
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        raise NotImplementedError
+
+
+class AbstractOrNode:
+    precedence: typing.ClassVar[int] = _OR_PRECEDENCE
+    children: tuple[AnyAbstractNode, ...]
+
+    __slots__ = ("children",)
+
+    def __init__(self, *, children: tuple[AnyAbstractNode, ...]) -> None:
+        self.children = children
+
+    def to_string(self) -> str:
+        return " or ".join(
+            _render_child(child, self.precedence) for child in self.children
+        )
+
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        raise NotImplementedError
+
+
+AnyAbstractNode = (
+    AbstractPredicateNode | AbstractNotNode | AbstractAndNode | AbstractOrNode
+)
+
+
+def _render_child(child: AnyAbstractNode, parent_precedence: int) -> str:
+    rendered = child.to_string()
+    if child.precedence < parent_precedence:
+        return f"({rendered})"
+    return rendered
+
+
+class ExpressionTransformer[NodeT: AnyAbstractNode](Transformer[Token, NodeT]):
+    """Transform Lark parse tree into AST of `Node` instances."""
+
+    or_node: type[AbstractOrNode] = AbstractOrNode
+    and_node: type[AbstractAndNode] = AbstractAndNode
+    not_node: type[AbstractNotNode] = AbstractNotNode
+    predicate_node: type[AbstractPredicateNode] = AbstractPredicateNode
+
+    def __init__(self, *, predicates: list[AuthPredicate]) -> None:
+        super().__init__()
+        self._predicates_by_name = {
+            predicate.name: predicate for predicate in predicates
+        }
+
+    def predicate(self, items: list[Token]) -> AbstractPredicateNode:
+        name = items[0].value
+        predicate = self._predicates_by_name.get(name)
+        if predicate is None:
+            raise InvalidPredicateError(f"Unknown predicate '{name}'")
+        return self.predicate_node(predicate=predicate)
+
+    def not_expression(self, items: list[typing.Any]) -> AbstractNotNode:
+        return self.not_node(child=items[1])
+
+    def and_expression(self, items: list[typing.Any]) -> AbstractAndNode:
+        return self.and_node(
+            children=tuple(item for item in items if not isinstance(item, Token))
+        )
+
+    def or_expression(self, items: list[typing.Any]) -> AbstractOrNode:
+        return self.or_node(
+            children=tuple(item for item in items if not isinstance(item, Token))
+        )
+
+
+class PermissionExpression:
+    def __init__(
+        self,
+        *,
+        expression: str,
+        predicates: list[AuthPredicate],
+        transformer_class: type[ExpressionTransformer],
+    ) -> None:
+        self.expression = expression
+        self.predicates = predicates
+        try:
+            parse_tree = expression_grammar.parse(expression)
+        except UnexpectedInput as exc:
+            raise ExpressionParsingError(str(exc)) from exc
+        try:
+            self._root: AnyAbstractNode = transformer_class(
+                predicates=predicates
+            ).transform(parse_tree)
+        except VisitError as exc:
+            if isinstance(exc.orig_exc, ExpressionError):
+                raise exc.orig_exc from exc
+            raise ExpressionParsingError(str(exc.orig_exc)) from exc
+
+    def __repr__(self) -> str:
+        return self._root.to_string()
+
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        try:
+            return self._root.evaluate(context)
+        except ExpressionError:
+            raise
+        except Exception as exc:
+            raise ExpressionEvaluationError(str(exc)) from exc

fastapi_guardian/ext/sqlalchemy.py

@@ -0,0 +1,147 @@
+import typing
+
+from sqlalchemy import Select, and_, false, not_, or_, true
+from sqlalchemy.orm import InstrumentedAttribute
+from sqlalchemy.sql.elements import ColumnElement
+
+from fastapi_guardian import exceptions
+from fastapi_guardian.dto import AuthContext, AuthPredicate, PredicateContext
+from fastapi_guardian.engine import BaseAuthEngine
+from fastapi_guardian.expression import (
+    AbstractAndNode,
+    AbstractNotNode,
+    AbstractOrNode,
+    AbstractPredicateNode,
+    ExpressionTransformer,
+    PermissionExpression,
+)
+from fastapi_guardian.resource import Resource
+
+
+class SqlAlchemyPredicateNode(AbstractPredicateNode):
+    def evaluate(self, context: AuthContext) -> ColumnElement[bool]:
+        predicate_context = PredicateContext[type[Resource], typing.Any](
+            principal=context.principal, resource=context.current_permission.resource
+        )
+        return typing.cast("ColumnElement[bool]", self.predicate.fn(predicate_context))
+
+
+class SqlAlchemyNotNode(AbstractNotNode):
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        return not_(self.child.evaluate(context))
+
+
+class SqlAlchemyAndNode(AbstractAndNode):
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        return and_(*(child.evaluate(context) for child in self.children))
+
+
+class SqlAlchemyOrNode(AbstractOrNode):
+    def evaluate(self, context: AuthContext) -> typing.Any:
+        return or_(*(child.evaluate(context) for child in self.children))
+
+
+AnySqlAlchemyNode = (
+    SqlAlchemyPredicateNode | SqlAlchemyNotNode | SqlAlchemyAndNode | SqlAlchemyOrNode
+)
+
+
+class SqlAlchemyExpressionTransformer(ExpressionTransformer[AnySqlAlchemyNode]):
+    predicate_node: type[SqlAlchemyPredicateNode] = SqlAlchemyPredicateNode
+    not_node: type[SqlAlchemyNotNode] = SqlAlchemyNotNode
+    and_node: type[SqlAlchemyAndNode] = SqlAlchemyAndNode
+    or_node: type[SqlAlchemyOrNode] = SqlAlchemyOrNode
+
+
+class SqlalchemyPermissionExpression(PermissionExpression):
+    def __init__(self, *, expression: str, predicates: list[AuthPredicate]) -> None:
+        super().__init__(
+            expression=expression,
+            predicates=predicates,
+            transformer_class=SqlAlchemyExpressionTransformer,
+        )
+
+
+class SqlalchemyResource(Resource):
+    __resource_id_column__: str = "id"
+
+    def __init_subclass__(cls, __resource_abstract__: bool = False) -> None:
+        if __resource_abstract__:
+            return
+
+        resource_name = getattr(cls, "__resource_name__", None) or getattr(
+            cls, "__tablename__", None
+        )
+        if resource_name is None:
+            raise exceptions.ImproperlyConfigured(
+                "Either __resource_name__ or __tablename__ must be set"
+            )
+
+        if not isinstance(getattr(cls, "__resource_app_name__", None), str):
+            raise exceptions.ImproperlyConfigured(
+                "__resource_app_name__ string must be set for non-abstract resources"
+            )
+
+        cls.__resource_name__ = resource_name
+        cls.__resource_code__ = (
+            f"{cls.__resource_app_name__}.{cls.__resource_name__}".lower()
+        )
+
+
+class SqlalchemyAuthEngine(BaseAuthEngine):
+    def filter_query[RowT: tuple[typing.Any, ...]](
+        self,
+        context: AuthContext[type[SqlalchemyResource], typing.Any],
+        query: Select[RowT],
+    ) -> Select[RowT]:
+        """
+        Filter the query based on the principal's permissions for the given resource and action.
+
+        New filter applied as a chained filter() call,
+        in current sqlalchemy implementation it's AND'ed with the existing filters,
+        so for chained filter calls it should "Just Work™".
+        """
+        expression = self._build_scoped_filter(context=context)
+        return query.filter(expression)
+
+    def _build_scoped_filter(self, *, context: AuthContext) -> ColumnElement[bool]:
+        grants = self.matching_grants(context=context)
+        if not grants:
+            return false()
+
+        expressions: list[ColumnElement[bool]] = []
+        resource_ids: list[str] = []
+
+        for grant in grants:
+            match grant.scope:
+                case "global":
+                    return true()
+                case "resource":
+                    resource_ids.append(grant.resource_id)
+                case "conditional":
+                    expression = SqlalchemyPermissionExpression(
+                        expression=grant.condition,
+                        predicates=context.current_permission.predicates,
+                    )
+                    if expression is not None:
+                        expressions.append(expression.evaluate(context=context))
+
+        if resource_ids:
+            id_column = getattr(
+                context.current_permission.resource,
+                context.current_permission.resource.__resource_id_column__,
+                None,
+            )
+            if id_column is None:
+                raise exceptions.ImproperlyConfigured(
+                    f"Resource '{context.current_permission.resource.__resource_code__}' "
+                    f"has no id column '{context.current_permission.resource.__resource_id_column__}' but resource scoped permission provided"
+                )
+            else:
+                id_column = typing.cast("InstrumentedAttribute[typing.Any]", id_column)
+                expressions.append(id_column.in_(resource_ids))
+
+        if not expressions:
+            return false()
+
+        return or_(*expressions)

fastapi_guardian/ext/tortoise.py

@@ -0,0 +1,185 @@
+import functools
+import typing
+from collections.abc import Callable
+
+from tortoise.expressions import Q
+from tortoise.models import Model
+from tortoise.queryset import QuerySet
+
+from fastapi_guardian import exceptions
+from fastapi_guardian.dto import AuthContext, AuthPredicate, PredicateContext
+from fastapi_guardian.engine import BaseAuthEngine
+from fastapi_guardian.expression import (
+    AbstractAndNode,
+    AbstractNotNode,
+    AbstractOrNode,
+    AbstractPredicateNode,
+    ExpressionTransformer,
+    PermissionExpression,
+)
+from fastapi_guardian.resource import Resource
+
+
+class TortoisePredicateNode(AbstractPredicateNode):
+    def evaluate(self, context: AuthContext) -> Q:
+        predicate_context = PredicateContext[type[Resource], typing.Any](
+            principal=context.principal, resource=context.current_permission.resource
+        )
+        return typing.cast("Q", self.predicate.fn(predicate_context))
+
+
+class TortoiseNotNode(AbstractNotNode):
+    def evaluate(self, context: AuthContext) -> Q:
+        return ~self.child.evaluate(context)
+
+
+class TortoiseAndNode(AbstractAndNode):
+    def evaluate(self, context: AuthContext) -> Q:
+        return functools.reduce(
+            lambda left, right: left & right,
+            (child.evaluate(context) for child in self.children),
+        )
+
+
+class TortoiseOrNode(AbstractOrNode):
+    def evaluate(self, context: AuthContext) -> Q:
+        return functools.reduce(
+            lambda left, right: left | right,
+            (child.evaluate(context) for child in self.children),
+        )
+
+
+AnyTortoiseNode = (
+    TortoisePredicateNode | TortoiseNotNode | TortoiseAndNode | TortoiseOrNode
+)
+
+
+class TortoiseExpressionTransformer(ExpressionTransformer[AnyTortoiseNode]):
+    predicate_node: type[TortoisePredicateNode] = TortoisePredicateNode
+    not_node: type[TortoiseNotNode] = TortoiseNotNode
+    and_node: type[TortoiseAndNode] = TortoiseAndNode
+    or_node: type[TortoiseOrNode] = TortoiseOrNode
+
+
+class TortoisePermissionExpression(PermissionExpression):
+    def __init__(self, *, expression: str, predicates: list[AuthPredicate]) -> None:
+        super().__init__(
+            expression=expression,
+            predicates=predicates,
+            transformer_class=TortoiseExpressionTransformer,
+        )
+
+
+class LazyAttribute[T]:
+    def __init__(self, *, getter: Callable[[type], T]) -> None:
+        self.getter = getter
+
+    def __get__(self, instance: typing.Any, owner: type[Model]) -> T:
+        return self.getter(owner)
+
+
+def get_resource_name(owner: type[Model]) -> str:
+    resource_name = owner._meta.db_table
+    if resource_name:
+        return resource_name
+
+    raise exceptions.ImproperlyConfigured(
+        "Either __resource_name__ or Tortoise _meta.db_table must be available. Perhaps, you forgot to call Tortoise.init()?"
+    )
+
+
+def get_app_name(cls: type[Model]) -> str:
+    resource_app_name = cls._meta.app
+    if resource_app_name:
+        return resource_app_name
+
+    raise exceptions.ImproperlyConfigured(
+        "Either __resource_app_name__ or Tortoise _meta.app must be available. Perhaps, you forgot to call Tortoise.init()?"
+    )
+
+
+def get_resource_code(owner: type[Resource]) -> str:
+    return f"{owner.__resource_app_name__}.{owner.__resource_name__}".lower()
+
+
+class TortoiseResource(Resource):
+    """
+    Base class for Tortoise-backed resources.
+
+
+    Due to Tortoise paradigm of deferred model configuration, resource name and app name are resolved lazily. If no explicit override is set,
+    they come from ``_meta.db_table`` and ``_meta.app`` and must be accessed only after ``Tortoise.init()`` has been called.
+    """
+
+    __resource_abstract__: typing.ClassVar[bool] = True
+    __resource_name__: typing.ClassVar[str] = typing.cast(
+        "str", LazyAttribute(getter=get_resource_name)
+    )
+    __resource_app_name__: typing.ClassVar[str] = typing.cast(
+        "str", LazyAttribute(getter=get_app_name)
+    )
+    __resource_code__: typing.ClassVar[str] = typing.cast(
+        "str", LazyAttribute(getter=get_resource_code)
+    )
+    __resource_id_column__: typing.ClassVar[str] = "id"
+
+
+class TortoiseAuthEngine(BaseAuthEngine):
+    def filter_query[T: Model](
+        self,
+        context: AuthContext[type[TortoiseResource], typing.Any],
+        query: QuerySet[T],
+    ) -> QuerySet[T]:
+        """
+        Filter the query based on the principal's permissions for the given resource and action.
+
+        New filter is applied as a chained filter() call. Tortoise ANDs chained
+        filters with any user-provided filters already present on the query.
+        """
+        expression = self._build_scoped_filter(context=context)
+        return query.filter(expression)
+
+    def _build_scoped_filter(
+        self,
+        *,
+        context: AuthContext[type[TortoiseResource], typing.Any],
+    ) -> Q:
+        grants = self.matching_grants(context=context)
+        if not grants:
+            return Q(pk__in=[])
+
+        expressions: list[Q] = []
+        resource_ids: list[str] = []
+
+        for grant in grants:
+            match grant.scope:
+                case "global":
+                    return Q()
+                case "resource":
+                    resource_ids.append(grant.resource_id)
+                case "conditional":
+                    expression = TortoisePermissionExpression(
+                        expression=grant.condition,
+                        predicates=context.current_permission.predicates,
+                    )
+                    expressions.append(expression.evaluate(context=context))
+
+        if resource_ids:
+            id_column = context.current_permission.resource.__resource_id_column__
+            if (
+                id_column
+                not in typing.cast(
+                    type[Model], context.current_permission.resource
+                )._meta.fields_map
+            ):
+                raise exceptions.ImproperlyConfigured(
+                    f"Resource '{context.current_permission.resource.__resource_code__}' "
+                    f"has no id column '{id_column}' but resource scoped permission provided"
+                )
+            filter_kwargs: typing.Any = {f"{id_column}__in": resource_ids}
+            expressions.append(Q(**filter_kwargs))
+
+        if not expressions:
+            return Q(pk__in=[])
+
+        return functools.reduce(lambda left, right: left | right, expressions)

fastapi_guardian/resource.py

@@ -0,0 +1,4 @@
+class Resource:
+    __resource_name__: str
+    __resource_app_name__: str
+    __resource_code__: str

fastapi_guardian/tortoise_test.py

@@ -0,0 +1,14 @@
+from tortoise import fields, models
+
+
+class User(models.Model):
+    id = fields.IntField(primary_key=True)
+    name = fields.CharField(max_length=255)
+    email = fields.CharField(max_length=255)
+    password = fields.CharField(max_length=255)
+
+
+class Post(models.Model):
+    id = fields.IntField(primary_key=True)
+    title = fields.CharField(max_length=255)
+    content = fields.TextField()

fastapi_guardian-0.1.0.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: fastapi-guardian
+Version: 0.1.0
+Summary: Flexible permissions for FastAPI
+Keywords: fastapi,authorization,security
+Author: achopik
+Author-email: achopik <artikchopik@gmail.com>
+License-Expression: MIT
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: fastapi>=0.130.0
+Requires-Dist: lark>=1.3.1
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: sqlalchemy>=2.0.10 ; extra == 'sqlalchemy'
+Requires-Dist: tortoise-orm>=1.1.0 ; extra == 'tortoise'
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/achopik/fastapi-guardian
+Provides-Extra: sqlalchemy
+Provides-Extra: tortoise
+Description-Content-Type: text/markdown
+
+# fastapi-guardian
+
+```fastapi-guardian``` is a WIP Python library created for flexible permission management in FastAPI applications. It provides a generic engine and ORM bindings to perform access checks and DB-level filtering operations.
+
+## Features
+
+- Generic engine for permission management
+- SQLAlchemy and Tortoise ORM bindings for access filtering
+- Database-agnostic core decision engine
+- Expression mini-DSL for permission conditions (AND, OR, NOT) with custom dev-defined predicates (e.g, 'self', 'only_drafts')
+- 3 scopes of permissions: global, resource-based (access to specific resource instance denoted by ID) and conditional (access to specific resource instance based on custom conditions defined in application code)
+- FastAPI-native dependency injection via `Permission` dependency.
+- Fully typed library definitions, especially user-facing interfaces.
+- 🚧 Minimal AI involvement and fully covered with tests. 
+
+
+## Supported Python version
+
+Currently, library is designed to work with Python 3.14+
+
+
+## Installation
+
+```bash
+pip install fastapi-guardian
+```
+
+## Quickstart
+
+```py
+import enum
+import typing
+
+import uvicorn
+from fastapi import Depends, FastAPI, HTTPException, Request, status
+from pydantic import BaseModel
+from sqlalchemy.engine import create_engine
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    Mapped,
+    Session,
+    mapped_column,
+    relationship,
+    sessionmaker,
+)
+from sqlalchemy.schema import ForeignKey
+from sqlalchemy.sql import select
+from sqlalchemy.types import JSON, Integer, String
+from starlette.middleware.sessions import SessionMiddleware
+
+from fastapi_guardian.dependencies import BasePermission
+from fastapi_guardian.dto import AuthContext, Principal
+from fastapi_guardian.ext.sqlalchemy import SqlalchemyAuthEngine, SqlalchemyResource
+
+
+
+# 1. Define your sqlalchemy models, inherit SqlalchemyResource
+class Base(DeclarativeBase, SqlalchemyResource, __resource_abstract__=True):
+    __resource_app_name__ = "example"
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+
+
+class Role(Base):
+    __tablename__ = "roles"
+
+    name: Mapped[str] = mapped_column(String(255))
+    permission_grants: Mapped[list["RolePermissionGrant"]] = relationship(
+        "RolePermissionGrant", back_populates="role"
+    )
+    users: Mapped[list["UserRole"]] = relationship("UserRole", back_populates="role")
+
+
+class RolePermissionGrant(Base):
+    __tablename__ = "role_permission_grants"
+
+    role_id: Mapped[int] = mapped_column(Integer, ForeignKey("roles.id"))
+    role: Mapped["Role"] = relationship("Role", back_populates="permission_grants")
+    resource: Mapped[str] = mapped_column(String(255))
+    action: Mapped[str] = mapped_column(String(255))
+    scope: Mapped[str] = mapped_column(String(255))
+    extra: Mapped[dict] = mapped_column(JSON)
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    username: Mapped[str] = mapped_column(String(255))
+    email: Mapped[str] = mapped_column(String(255))
+    password: Mapped[str] = mapped_column(String(255))
+
+    articles: Mapped[list["Article"]] = relationship("Article", back_populates="author")
+    roles: Mapped[list["UserRole"]] = relationship("UserRole", back_populates="user")
+
+
+class Article(Base):
+    __tablename__ = "articles"
+
+    title: Mapped[str] = mapped_column(String(255))
+    content: Mapped[str] = mapped_column(String(255))
+    author_id: Mapped[int] = mapped_column(Integer, ForeignKey("users.id"))
+    author: Mapped["User"] = relationship("User", back_populates="articles")
+    category: Mapped[str] = mapped_column(String(255))
+
+
+
+# 2. Create your auth engine
+auth_engine = SqlalchemyAuthEngine[Base]()
+
+
+# 3. Create your permission dependency class and authentication logic
+def get_authorized_principal(
+    request: Request, db: Session = Depends(get_db)
+) -> Principal[int] | None:
+    user_id = request.session.get("user_id")
+    if user_id is None:
+        return None  # Alternatively, you can raise an HTTPException here, but None is handled by permission itself
+    user = db.query(User).filter(User.id == user_id).first()
+    if user is None:
+        return None
+
+    permissions = (
+        db.query(RolePermissionGrant)
+        .join(Role, Role.id == RolePermissionGrant.role_id)
+        .join(UserRole, UserRole.role_id == Role.id)
+        .filter(UserRole.user_id == user_id)
+        .all()
+    )
+
+    return Principal(
+        id=user.id,
+        email=user.email,
+        username=user.username,
+        permissions=[
+            {
+                "resource": permission.resource,
+                "action": permission.action,
+                "scope": permission.scope,
+                **permission.extra,
+            }
+            for permission in permissions
+        ],
+    )
+
+
+class AppPermission[T: type[Base]](BasePermission[T, int]):
+    auth_engine = auth_engine
+
+    async def __call__(self, principal: typing.Annotated[Principal, Depends(get_authorized_principal)]):
+        return await self.authorize(principal=principal)
+
+
+# Note: You can use any string value as an action, enum prefered here for typed suggestions and consistency across the application.
+class AuthAction(enum.StrEnum):
+    READ = "read"
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+
+
+# 4. Define your API endpoints
+@app.get("/users")
+async def get_users(
+    auth_ctx: AuthContext = Depends(
+        AppPermission(
+            resource=User,
+            action=AuthAction.READ,
+            scopes=["global", "resource", "conditional"],
+            predicates=[
+                {
+                    "name": "self",
+                    "fn": lambda ctx: ctx.resource.id == ctx.principal.id,
+                    "description": "Allow access to own user resource",
+                },
+            ],
+        )
+    ),
+    db: Session = Depends(get_db),
+) -> list[UserDto]:
+    query = select(User)
+    query = auth_engine.filter_query(context=auth_ctx, query=query)
+    users = db.execute(query).scalars().all()
+    return [
+        UserDto(id=user.id, username=user.username, email=user.email) for user in users
+    ]
+
+
+@app.post("/users")
+async def create_user(
+    body: UserCreateDto,
+    # By default, permission assumes only global scope, which is the case for most of CREATE actions
+    _auth: AuthContext = Depends(
+        AppPermission(resource=User, action=AuthAction.CREATE)
+    ),
+    db: Session = Depends(get_db),
+) -> UserDto:
+    user = User(username=body.username, email=body.email, password=body.password)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return UserDto(id=user.id, username=user.username, email=user.email)
+
+
+@app.get("/articles")
+async def get_articles(
+    auth_ctx: AuthContext = Depends(
+        AppPermission(
+            resource=Article,
+            action=AuthAction.READ,
+            scopes=["global", "resource", "conditional"],
+            predicates=[
+                {
+                    "name": "self",
+                    "fn": lambda ctx: ctx.resource.author_id == ctx.principal.id,
+                    "description": "Allow access to own articles",
+                },
+                {
+                    "name": "only_published",
+                    "fn": lambda ctx: ctx.resource.category == "published",
+                    "description": "Allow access to published articles only",
+                },
+            ],
+        )
+    ),
+    db: Session = Depends(get_db),
+) -> list[ArticleDto]:
+    query = select(Article)
+    # Note: Apply filter to query manually here. Expression will be added as AND statement to the existing filters.
+    query = auth_engine.filter_query(context=auth_ctx, query=query)
+    articles = db.execute(query).scalars().all()
+    return [
+        ArticleDto(
+            id=article.id,
+            title=article.title,
+            content=article.content,
+            author_id=article.author_id,
+            category=article.category,
+        )
+        for article in articles
+    ]
+
+# 5. Create and store permission grants somewhere (completely up to you, check examples for to-go model definitions, auth engine only cares about Principal DTO):
+grant = RolePermissionGrant(
+    role_id=author_role.id,
+    resource=Article.__resource_code__,
+    action=AuthAction.READ,
+    scope="conditional",
+    # Notice that we can use expression mini-DSL here to build complex conditions.
+    extra={"condition": "self or only_published"},
+)
+```
+
+For detailed ready-to-run examples, see [examples](examples) directory.

fastapi_guardian-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+fastapi_guardian/__init__.py,sha256=i7DwHhN-J0w61Xz2BlBUwGsxy52JqW25vSZO18UbHBs,344
+fastapi_guardian/dependencies.py,sha256=Hh-V5D_8KJxGe8LblG_2QB26Vi2c4U8RoNLvC3CBJmw,1934
+fastapi_guardian/dto.py,sha256=G6bgJguHKCSKmvwyZuuwexgSUtFNyRiJ3zJ3sWJFgo4,3219
+fastapi_guardian/engine.py,sha256=aLNCVJ8iNsmbW6RoSON9e7_UHImYLd0nHze5tMyddd4,2915
+fastapi_guardian/exceptions.py,sha256=fNXEMl7qV3jVMB4JqGOgylSzTKiPehvOqv-K5TzWAlM,103
+fastapi_guardian/expression.py,sha256=QaUGRnj382M-w7Q8TBJMCbQvlD6DTMIQ0J0_Bq616Zs,6063
+fastapi_guardian/ext/sqlalchemy.py,sha256=IH5QKIuJiOAOrg0gIXy1E8_D0sNIkfD1m5rIgACHfn0,5487
+fastapi_guardian/ext/tortoise.py,sha256=FTzUSE8MyLd1v_3fmAupjMEnuqnGbP1e-wgA9jUNEz4,6391
+fastapi_guardian/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_guardian/resource.py,sha256=457pBTFK6irXqyPpIhDT0ktPFr-HUeEsCBoIl3kLtG4,101
+fastapi_guardian/tortoise_test.py,sha256=CGHsBYHO5exeGSq-SGH7MBC-rNXDhyazU23rJEvxHx4,393
+fastapi_guardian-0.1.0.dist-info/WHEEL,sha256=Qb5DWjqM6GZuPp3VmTlAFSGqNRK8vceyVqRFxrfa8YA,80
+fastapi_guardian-0.1.0.dist-info/METADATA,sha256=tpGX5PVvOuU-s3dGzTRlAkHUh3hPvVSRwXDe69bI1q0,9346
+fastapi_guardian-0.1.0.dist-info/RECORD,,

fastapi_guardian-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.4
+Root-Is-Purelib: true
+Tag: py3-none-any