fastpermit 0.1.0__py3-none-any.whl

fastpermit/__init__.py

@@ -0,0 +1,37 @@
+from fastpermit.backends import InMemoryBackend, PermissionBackend
+from fastpermit.core import (
+    BasePermission,
+    PermissionContext,
+    PermissionEvaluator,
+    all_of,
+    any_of,
+)
+from fastpermit.integrations import FastPermit
+from fastpermit.permissions import (
+    AllowAny,
+    DenyAll,
+    HasPermission,
+    HasRole,
+    IsAuthenticated,
+)
+from fastpermit.principal import BasicPrincipal, Principal
+
+__all__ = [
+    "AllowAny",
+    "BasePermission",
+    "BasicPrincipal",
+    "DenyAll",
+    "FastPermit",
+    "HasPermission",
+    "HasRole",
+    "InMemoryBackend",
+    "IsAuthenticated",
+    "PermissionBackend",
+    "PermissionContext",
+    "PermissionEvaluator",
+    "Principal",
+    "all_of",
+    "any_of",
+]
+
+__version__ = "0.1.0"

fastpermit/backends/__init__.py

@@ -0,0 +1,4 @@
+from fastpermit.backends.base import PermissionBackend
+from fastpermit.backends.memory import InMemoryBackend
+
+__all__ = ["InMemoryBackend", "PermissionBackend"]

fastpermit/backends/base.py

@@ -0,0 +1,17 @@
+from collections.abc import Mapping
+from typing import AbstractSet, Any, Protocol
+
+from fastpermit.principal import Principal
+
+
+class PermissionBackend(Protocol):
+    """Storage adapter used to resolve effective permission codes for a principal."""
+
+    async def get_permissions(
+        self,
+        principal: Principal,
+        *,
+        scope: Mapping[str, Any],
+    ) -> AbstractSet[str]:
+        """Return effective permission codes for the principal within the supplied scope."""
+        ...

fastpermit/backends/memory.py

@@ -0,0 +1,42 @@
+from collections.abc import Iterable, Mapping
+from typing import AbstractSet, Any, Hashable
+
+from fastpermit.principal import Principal
+
+
+class InMemoryBackend:
+    """Mutable in-memory permission backend intended for tests and prototypes."""
+
+    def __init__(
+        self,
+        permissions: Mapping[Hashable, Iterable[str]] | None = None,
+    ) -> None:
+        self._permissions: dict[Hashable, set[str]] = {
+            principal_id: set(codes)
+            for principal_id, codes in (permissions or {}).items()
+        }
+
+    async def get_permissions(
+        self,
+        principal: Principal,
+        *,
+        scope: Mapping[str, Any],
+    ) -> AbstractSet[str]:
+        del scope
+        return frozenset(self._permissions.get(principal.id, set()))
+
+    def set_permissions(
+        self,
+        principal_id: Hashable,
+        permissions: Iterable[str],
+    ) -> None:
+        self._permissions[principal_id] = set(permissions)
+
+    def grant(self, principal_id: Hashable, *permissions: str) -> None:
+        self._permissions.setdefault(principal_id, set()).update(permissions)
+
+    def revoke(self, principal_id: Hashable, *permissions: str) -> None:
+        current = self._permissions.get(principal_id)
+        if current is None:
+            return
+        current.difference_update(permissions)

fastpermit/core/__init__.py

@@ -0,0 +1,12 @@
+from fastpermit.core.context import PermissionContext
+from fastpermit.core.evaluator import PermissionEvaluator
+from fastpermit.core.helpers import all_of, any_of
+from fastpermit.core.permission import BasePermission
+
+__all__ = [
+    "BasePermission",
+    "PermissionContext",
+    "PermissionEvaluator",
+    "all_of",
+    "any_of",
+]

fastpermit/core/context.py

@@ -0,0 +1,35 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Hashable
+
+from fastpermit.backends.base import PermissionBackend
+from fastpermit.principal import Principal
+
+
+@dataclass(slots=True)
+class PermissionContext:
+    """Evaluation context shared by every rule in one authorization decision."""
+
+    backend: PermissionBackend
+    scope: Mapping[str, Any] = field(default_factory=dict)
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+    _permissions_cache: dict[Hashable, frozenset[str]] = field(
+        default_factory=dict,
+        init=False,
+        repr=False,
+    )
+
+    async def get_permissions(self, principal: Principal) -> frozenset[str]:
+        """Resolve effective permissions once per principal and evaluation context."""
+        cached = self._permissions_cache.get(principal.id)
+        if cached is not None:
+            return cached
+
+        resolved = frozenset(
+            await self.backend.get_permissions(
+                principal,
+                scope=self.scope,
+            )
+        )
+        self._permissions_cache[principal.id] = resolved
+        return resolved

fastpermit/core/evaluator.py

@@ -0,0 +1,84 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from fastpermit.backends.base import PermissionBackend
+from fastpermit.core.context import PermissionContext
+from fastpermit.core.permission import BasePermission, Decision
+from fastpermit.principal import Principal
+
+
+@dataclass(slots=True)
+class PermissionEvaluator:
+    """Evaluate permission expressions independently from any web framework."""
+
+    backend: PermissionBackend
+
+    async def decision(
+        self,
+        permission: BasePermission,
+        principal: Principal | None,
+        *,
+        scope: Mapping[str, Any] | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> Decision:
+        context = self._context(scope=scope, attributes=attributes)
+        return await permission.evaluate(principal, context)
+
+    async def check(
+        self,
+        permission: BasePermission,
+        principal: Principal | None,
+        *,
+        scope: Mapping[str, Any] | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> bool:
+        decision = await self.decision(
+            permission,
+            principal,
+            scope=scope,
+            attributes=attributes,
+        )
+        return decision is not False
+
+    async def object_decision(
+        self,
+        permission: BasePermission,
+        principal: Principal | None,
+        obj: Any,
+        *,
+        scope: Mapping[str, Any] | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> Decision:
+        context = self._context(scope=scope, attributes=attributes)
+        return await permission.evaluate(principal, context, obj=obj)
+
+    async def check_object(
+        self,
+        permission: BasePermission,
+        principal: Principal | None,
+        obj: Any,
+        *,
+        scope: Mapping[str, Any] | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> bool:
+        decision = await self.object_decision(
+            permission,
+            principal,
+            obj,
+            scope=scope,
+            attributes=attributes,
+        )
+        return decision is not False
+
+    def _context(
+        self,
+        *,
+        scope: Mapping[str, Any] | None,
+        attributes: Mapping[str, Any] | None,
+    ) -> PermissionContext:
+        return PermissionContext(
+            backend=self.backend,
+            scope=scope or {},
+            attributes=attributes or {},
+        )

fastpermit/core/helpers.py

@@ -0,0 +1,24 @@
+from fastpermit.core.permission import BasePermission
+from fastpermit.permissions import AllowAny, DenyAll
+
+
+def all_of(*permissions: BasePermission) -> BasePermission:
+    """Combine rules with logical AND; an empty set allows access."""
+    if not permissions:
+        return AllowAny()
+
+    result = permissions[0]
+    for permission in permissions[1:]:
+        result = result & permission
+    return result
+
+
+def any_of(*permissions: BasePermission) -> BasePermission:
+    """Combine rules with logical OR; an empty set denies access."""
+    if not permissions:
+        return DenyAll()
+
+    result = permissions[0]
+    for permission in permissions[1:]:
+        result = result | permission
+    return result

fastpermit/core/permission.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import Any, Final, TypeAlias
+
+from fastpermit.core.context import PermissionContext
+from fastpermit.principal import Principal
+
+Decision: TypeAlias = bool | None
+_OBJECT_MISSING: Final = object()
+
+
+def _and_decisions(left: Decision, right: Decision) -> Decision:
+    if left is False or right is False:
+        return False
+    if left is True and right is True:
+        return True
+    return None
+
+
+def _or_decisions(left: Decision, right: Decision) -> Decision:
+    if left is True or right is True:
+        return True
+    if left is False and right is False:
+        return False
+    return None
+
+
+def _not_decision(value: Decision) -> Decision:
+    if value is None:
+        return None
+    return not value
+
+
+def _combine_phases(request: Decision, object_: Decision) -> Decision:
+    if request is False or object_ is False:
+        return False
+    if request is None and object_ is None:
+        return None
+    return True
+
+
+class BasePermission:
+    """Base class for request-level, object-level, and composite permission rules.
+
+    Returning ``None`` means the rule is neutral for that evaluation phase. This allows
+    request-only and object-only rules to compose correctly with AND, OR, and NOT.
+    """
+
+    message = "Permission denied."
+
+    async def has_permission(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+    ) -> Decision:
+        """Evaluate a request-level rule or return None when the rule is object-only."""
+        del principal, context
+        return None
+
+    async def has_object_permission(
+        self,
+        principal: Principal | None,
+        obj: Any,
+        context: PermissionContext,
+    ) -> Decision:
+        """Evaluate an object-level rule or return None when the rule is request-only."""
+        del principal, obj, context
+        return None
+
+    async def evaluate(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+        *,
+        obj: Any = _OBJECT_MISSING,
+    ) -> Decision:
+        """Evaluate this rule for the current request and optional resource object."""
+        request_decision = await self.has_permission(principal, context)
+        if obj is _OBJECT_MISSING:
+            return request_decision
+
+        object_decision = await self.has_object_permission(principal, obj, context)
+        return _combine_phases(request_decision, object_decision)
+
+    def __and__(self, other: BasePermission) -> BasePermission:
+        if not isinstance(other, BasePermission):
+            raise TypeError("AND operand must be a BasePermission instance.")
+        return _AndPermission(self, other)
+
+    def __or__(self, other: BasePermission) -> BasePermission:
+        if not isinstance(other, BasePermission):
+            raise TypeError("OR operand must be a BasePermission instance.")
+        return _OrPermission(self, other)
+
+    def __invert__(self) -> BasePermission:
+        return _NotPermission(self)
+
+    def __repr__(self) -> str:
+        return self.__class__.__name__
+
+
+class _BinaryPermission(BasePermission):
+    operator = "?"
+
+    def __init__(self, left: BasePermission, right: BasePermission) -> None:
+        self.left = left
+        self.right = right
+
+    def __repr__(self) -> str:
+        return f"({self.left!r} {self.operator} {self.right!r})"
+
+
+class _AndPermission(_BinaryPermission):
+    operator = "&"
+
+    async def evaluate(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+        *,
+        obj: Any = _OBJECT_MISSING,
+    ) -> Decision:
+        left = await self.left.evaluate(principal, context, obj=obj)
+        if left is False:
+            return False
+
+        right = await self.right.evaluate(principal, context, obj=obj)
+        return _and_decisions(left, right)
+
+
+class _OrPermission(_BinaryPermission):
+    operator = "|"
+
+    async def evaluate(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+        *,
+        obj: Any = _OBJECT_MISSING,
+    ) -> Decision:
+        left = await self.left.evaluate(principal, context, obj=obj)
+        if left is True:
+            return True
+
+        right = await self.right.evaluate(principal, context, obj=obj)
+        return _or_decisions(left, right)
+
+
+class _NotPermission(BasePermission):
+    def __init__(self, permission: BasePermission) -> None:
+        self.permission = permission
+
+    async def evaluate(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+        *,
+        obj: Any = _OBJECT_MISSING,
+    ) -> Decision:
+        decision = await self.permission.evaluate(principal, context, obj=obj)
+        return _not_decision(decision)
+
+    def __repr__(self) -> str:
+        return f"~{self.permission!r}"

fastpermit/integrations/__init__.py

@@ -0,0 +1,141 @@
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, TypeAlias, cast
+
+from fastapi import Depends, HTTPException, Request, status
+
+from fastpermit.backends.base import PermissionBackend
+from fastpermit.core.context import PermissionContext
+from fastpermit.core.evaluator import PermissionEvaluator
+from fastpermit.core.permission import BasePermission
+from fastpermit.permissions import HasPermission
+from fastpermit.principal import Principal
+
+PermissionSpec: TypeAlias = BasePermission | str
+PrincipalLoader: TypeAlias = Callable[..., Any]
+ObjectLoader: TypeAlias = Callable[..., Any]
+
+
+@dataclass(slots=True)
+class _AuthorizationState:
+    principal: Principal | None
+    context: PermissionContext
+
+
+class FastPermit:
+    """Framework integration for FastPermit permission expressions."""
+
+    def __init__(
+        self,
+        *,
+        backend: PermissionBackend,
+        principal_loader: PrincipalLoader,
+    ) -> None:
+        self.backend = backend
+        self.principal_loader = principal_loader
+        self.evaluator = PermissionEvaluator(backend)
+
+    def require(
+        self,
+        permission: PermissionSpec,
+        *,
+        scope: Mapping[str, Any] | None = None,
+    ) -> Callable[..., Any]:
+        """Create a dependency that returns the authorized principal."""
+        compiled = self._compile(permission)
+        principal_loader = self.principal_loader
+
+        async def dependency(
+            request: Request,
+            principal: Any = Depends(principal_loader),
+        ) -> Any:
+            typed_principal = cast(Principal | None, principal)
+            allowed = await self.evaluator.check(
+                compiled,
+                typed_principal,
+                scope=scope,
+                attributes={"request": request},
+            )
+            if not allowed:
+                self._raise_access_error(typed_principal, compiled)
+            return principal
+
+        return dependency
+
+    def require_object(
+        self,
+        permission: PermissionSpec,
+        *,
+        loader: ObjectLoader,
+        scope: Mapping[str, Any] | None = None,
+    ) -> Callable[..., Any]:
+        """Pre-check access, load an object, and authorize it."""
+        compiled = self._compile(permission)
+        principal_loader = self.principal_loader
+
+        async def precheck(
+            request: Request,
+            principal: Any = Depends(principal_loader),
+        ) -> _AuthorizationState:
+            typed_principal = cast(Principal | None, principal)
+            context = PermissionContext(
+                backend=self.backend,
+                scope=scope or {},
+                attributes={"request": request},
+            )
+            decision = await compiled.evaluate(typed_principal, context)
+            if decision is False:
+                self._raise_access_error(typed_principal, compiled)
+            return _AuthorizationState(
+                principal=typed_principal,
+                context=context,
+            )
+
+        async def guarded_loader(
+            state: _AuthorizationState = Depends(precheck),
+            obj: Any = Depends(loader),
+        ) -> Any:
+            del state
+            return obj
+
+        async def dependency(
+            state: _AuthorizationState = Depends(precheck),
+            obj: Any = Depends(guarded_loader),
+        ) -> Any:
+            decision = await compiled.evaluate(
+                state.principal,
+                state.context,
+                obj=obj,
+            )
+            if decision is False:
+                self._raise_access_error(state.principal, compiled)
+            return obj
+
+        return dependency
+
+    @staticmethod
+    def _compile(permission: PermissionSpec) -> BasePermission:
+        if isinstance(permission, str):
+            return HasPermission(permission)
+        if isinstance(permission, BasePermission):
+            return permission
+        raise TypeError("permission must be a permission code or BasePermission instance.")
+
+    @staticmethod
+    def _raise_access_error(
+        principal: Principal | None,
+        permission: BasePermission,
+    ) -> None:
+        if principal is None or not principal.is_authenticated:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication required.",
+            )
+
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=permission.message,
+        )
+
+
+__all__ = ["FastPermit"]

fastpermit/permissions.py

@@ -0,0 +1,108 @@
+from collections.abc import Iterable
+from typing import Literal, cast
+
+from fastpermit.core.context import PermissionContext
+from fastpermit.core.permission import BasePermission, Decision
+from fastpermit.principal import Principal
+
+Mode = Literal["all", "any"]
+
+
+def _validate_mode(mode: str) -> Mode:
+    if mode not in ("all", "any"):
+        raise ValueError("mode must be 'all' or 'any'.")
+    return cast(Mode, mode)
+
+
+class AllowAny(BasePermission):
+    """Always allow the current request."""
+
+    async def has_permission(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+    ) -> bool:
+        del principal, context
+        return True
+
+
+class DenyAll(BasePermission):
+    """Always deny the current request."""
+
+    async def has_permission(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+    ) -> bool:
+        del principal, context
+        return False
+
+
+class IsAuthenticated(BasePermission):
+    """Allow only authenticated principals."""
+
+    message = "Authentication required."
+
+    async def has_permission(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+    ) -> bool:
+        del context
+        return principal is not None and principal.is_authenticated
+
+
+class HasRole(BasePermission):
+    """Require one or more roles already attached to the principal."""
+
+    def __init__(self, *roles: str, mode: str = "any") -> None:
+        if not roles:
+            raise ValueError("HasRole requires at least one role.")
+
+        self.roles = frozenset(roles)
+        self.mode = _validate_mode(mode)
+
+    async def has_permission(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+    ) -> bool:
+        del context
+        if principal is None:
+            return False
+
+        if self.mode == "all":
+            return self.roles.issubset(principal.roles)
+        return bool(self.roles.intersection(principal.roles))
+
+    def __repr__(self) -> str:
+        roles = ", ".join(sorted(self.roles))
+        return f"HasRole({roles}; mode={self.mode})"
+
+
+class HasPermission(BasePermission):
+    """Require effective capability codes resolved by the configured backend."""
+
+    def __init__(self, *permissions: str, mode: str = "all") -> None:
+        if not permissions:
+            raise ValueError("HasPermission requires at least one permission code.")
+
+        self.permissions = frozenset(permissions)
+        self.mode = _validate_mode(mode)
+
+    async def has_permission(
+        self,
+        principal: Principal | None,
+        context: PermissionContext,
+    ) -> Decision:
+        if principal is None:
+            return False
+
+        effective = await context.get_permissions(principal)
+        if self.mode == "all":
+            return self.permissions.issubset(effective)
+        return bool(self.permissions.intersection(effective))
+
+    def __repr__(self) -> str:
+        permissions = ", ".join(sorted(self.permissions))
+        return f"HasPermission({permissions}; mode={self.mode})"

fastpermit/principal.py

@@ -0,0 +1,38 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import AbstractSet, Any, Hashable, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Principal(Protocol):
+    """Minimal read-only identity contract consumed by FastPermit."""
+
+    @property
+    def id(self) -> Hashable:
+        """Stable identifier used by permission backends."""
+        ...
+
+    @property
+    def roles(self) -> AbstractSet[str]:
+        """Roles already attached to the principal by the application."""
+        ...
+
+    @property
+    def attributes(self) -> Mapping[str, Any]:
+        """Application-defined identity attributes available to custom rules."""
+        ...
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Whether the application considers this principal authenticated."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class BasicPrincipal:
+    """Small concrete principal implementation for common applications and tests."""
+
+    id: Hashable
+    roles: frozenset[str] = field(default_factory=frozenset)
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+    is_authenticated: bool = True

fastpermit-0.1.0.dist-info/METADATA

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: fastpermit
+Version: 0.1.0
+Summary: Composable, backend-agnostic authorization for FastAPI.
+Author: Vitalii Semotiuk
+Maintainer: Vitalii Semotiuk
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Vir2S/fastpermit
+Project-URL: Repository, https://github.com/Vir2S/fastpermit
+Project-URL: Issues, https://github.com/Vir2S/fastpermit/issues
+Project-URL: Changelog, https://github.com/Vir2S/fastpermit/blob/master/CHANGELOG.md
+Keywords: fastapi,authorization,permissions,rbac,abac,access-control
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: httpx>=0.28; extra == "dev"
+Requires-Dist: mypy>=1.15; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# FastPermit
+
+[![CI](https://github.com/Vir2S/fastpermit/actions/workflows/ci.yml/badge.svg)](https://github.com/Vir2S/fastpermit/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Composable, backend-agnostic authorization for FastAPI.**
+
+FastPermit keeps authentication and authorization separate. Your application authenticates a
+principal with JWT, OAuth2, Auth0, Keycloak, FastAPI Users, or a custom mechanism. FastPermit then
+decides whether that principal may perform an action.
+
+The core is deliberately small:
+
+- composable permissions with `&`, `|`, and `~`;
+- request-level and object-level authorization;
+- role-based access control (RBAC) primitives;
+- pluggable permission backends;
+- async-first execution;
+- FastAPI dependency integration;
+- no ORM or cache dependency in the core.
+
+> Status: `0.1.0` — first public release.
+
+## Project status
+
+FastPermit is in active early development. The `0.1.x` line focuses on a small, typed,
+backend-agnostic core before adding optional persistence and caching adapters.
+
+Planned next steps:
+
+- SQLAlchemy 2 / PostgreSQL adapter;
+- Redis permission cache and invalidation hooks;
+- tenant and resource scopes;
+- audit and observability hooks.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install fastpermit
+```
+
+For development:
+
+```bash
+git clone https://github.com/Vir2S/fastpermit.git
+cd fastpermit
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+make check
+```
+
+## Quick start
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+
+from fastpermit import BasicPrincipal, FastPermit, HasPermission, InMemoryBackend
+
+app = FastAPI()
+
+backend = InMemoryBackend(
+    {
+        "user-1": {"project:read", "project:update"},
+    }
+)
+
+
+async def get_current_principal() -> BasicPrincipal:
+    # Replace this with JWT, OAuth2, Auth0, Keycloak, or your own authentication.
+    return BasicPrincipal(id="user-1", roles=frozenset({"developer"}))
+
+
+permit = FastPermit(
+    backend=backend,
+    principal_loader=get_current_principal,
+)
+
+
+@app.get("/projects")
+async def list_projects(
+    principal: Annotated[
+        BasicPrincipal,
+        Depends(permit.require("project:read")),
+    ],
+) -> dict[str, str]:
+    return {"principal_id": str(principal.id)}
+```
+
+A string passed to `require()` is shorthand for `HasPermission(...)`:
+
+```python
+Depends(permit.require("project:read"))
+```
+
+is equivalent to:
+
+```python
+Depends(permit.require(HasPermission("project:read")))
+```
+
+## Permission algebra
+
+Permissions can be combined without putting authorization branches in route handlers:
+
+```python
+from fastpermit import HasPermission, HasRole, IsAuthenticated
+
+permission = (
+    IsAuthenticated()
+    & HasPermission("project:update")
+    & (
+        HasRole("admin")
+        | HasPermission("project:update:any")
+    )
+)
+```
+
+Supported operators:
+
+```python
+A() & B()   # AND
+A() | B()   # OR
+~A()        # NOT
+```
+
+The helpers `all_of()` and `any_of()` are available for larger expressions:
+
+```python
+from fastpermit import all_of, any_of
+
+permission = all_of(
+    IsAuthenticated(),
+    HasPermission("project:update"),
+    any_of(
+        HasRole("admin"),
+        HasRole("manager"),
+    ),
+)
+```
+
+## Object-level permissions
+
+Object rules are intentionally separate from loading the object. A custom rule only needs to
+implement `has_object_permission()`:
+
+```python
+from typing import Any
+
+from fastpermit import BasePermission, PermissionContext, Principal
+
+
+class IsOwner(BasePermission):
+    async def has_object_permission(
+        self,
+        principal: Principal | None,
+        obj: Any,
+        context: PermissionContext,
+    ) -> bool:
+        return principal is not None and obj.owner_id == principal.id
+```
+
+Then combine it with ordinary permissions:
+
+```python
+edit_project = (
+    HasPermission("project:update:any")
+    | (
+        HasPermission("project:update")
+        & IsOwner()
+    )
+)
+```
+
+Use it with a FastAPI loader dependency:
+
+```python
+@app.patch("/projects/{project_id}")
+async def update_project(
+    project=Depends(
+        permit.require_object(
+            edit_project,
+            loader=get_project,
+        )
+    ),
+):
+    return project
+```
+
+FastPermit evaluates both request-level and object-level branches as a single expression. Rules
+that do not apply during a phase are neutral rather than implicitly allowing or denying it. This
+keeps expressions such as `HasRole("admin") | IsOwner()` and `~IsOwner()` logically correct.
+
+## Principals
+
+FastPermit uses a small `Principal` protocol rather than a concrete user model. The included
+`BasicPrincipal` is convenient for most applications:
+
+```python
+from fastpermit import BasicPrincipal
+
+principal = BasicPrincipal(
+    id="user-42",
+    roles=frozenset({"manager", "reviewer"}),
+    attributes={"organization_id": "org-1"},
+)
+```
+
+You may return your own object from the authentication dependency as long as it exposes:
+
+```text
+id
+roles
+attributes
+is_authenticated
+```
+
+## Backends
+
+A backend answers one question: which permission codes are effective for this principal in this
+scope?
+
+```python
+from collections.abc import Mapping
+from typing import AbstractSet, Any
+
+from fastpermit import PermissionBackend, Principal
+
+
+class MyBackend(PermissionBackend):
+    async def get_permissions(
+        self,
+        principal: Principal,
+        *,
+        scope: Mapping[str, Any],
+    ) -> AbstractSet[str]:
+        ...
+```
+
+`InMemoryBackend` is included for tests, prototypes, and examples. SQLAlchemy/PostgreSQL and Redis
+adapters are intentionally planned as optional integrations instead of core requirements.
+
+## Request context and scopes
+
+A permission receives `PermissionContext`, which contains:
+
+- the configured backend;
+- a scope mapping;
+- integration-specific attributes;
+- a per-evaluation permission cache.
+
+FastAPI integration exposes the current `Request` as `context.attributes["request"]` without
+making the authorization core depend on FastAPI.
+
+Static scope can be attached to a dependency:
+
+```python
+Depends(
+    permit.require(
+        "billing:read",
+        scope={"tenant": "global"},
+    )
+)
+```
+
+Dynamic tenant scopes are planned for the next integration iteration.
+
+## HTTP semantics
+
+FastPermit does not authenticate requests. Authentication remains the responsibility of your
+principal loader.
+
+When a FastPermit rule denies access:
+
+- an absent or unauthenticated principal produces `401 Unauthorized`;
+- an authenticated principal without sufficient authorization produces `403 Forbidden`.
+
+## Design principles
+
+1. Authentication and authorization are separate concerns.
+2. Routes should describe required access, not implement role branches.
+3. Permission codes are stable capabilities such as `project:update`.
+4. Roles aggregate capabilities; application code should not be coupled to role names where a
+   capability is the real requirement.
+5. Object-level rules belong in permissions, not route handlers.
+6. Storage and caching are adapters, not core concerns.
+7. Authorization expressions must preserve correct semantics across request and object phases.
+
+## Roadmap
+
+### 0.1
+
+- [x] permission core;
+- [x] `AND`, `OR`, `NOT` composition;
+- [x] `all_of()` / `any_of()`;
+- [x] `IsAuthenticated`;
+- [x] `HasRole`;
+- [x] `HasPermission`;
+- [x] object-level permissions;
+- [x] backend protocol;
+- [x] in-memory backend;
+- [x] FastAPI integration;
+- [x] typed package;
+- [x] tests and CI.
+
+### 0.2
+
+- [ ] SQLAlchemy 2.x adapter;
+- [ ] PostgreSQL RBAC reference models;
+- [ ] Alembic examples;
+- [ ] user-role and role-permission repositories.
+
+### 0.3
+
+- [ ] Redis cache adapter;
+- [ ] cache invalidation primitives;
+- [ ] cache versioning;
+- [ ] configurable TTL policies.
+
+### 0.4
+
+- [ ] dynamic tenant scopes;
+- [ ] attribute-based access control helpers;
+- [ ] resource scopes;
+- [ ] policy metadata.
+
+### 0.5
+
+- [ ] authorization audit events;
+- [ ] observability hooks;
+- [ ] OpenTelemetry integration.
+
+## License
+
+MIT
+
+## Maintainer
+
+Created and maintained by [Vitaly Sem](https://github.com/Vir2S).
+
+FastPermit is an independent open-source project developed with support from Born2CodeLab.

fastpermit-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fastpermit/__init__.py,sha256=ITC6V8tcDc0akgujfgcqfklQTFcmXRwlLwuDH-ngFrw,751
+fastpermit/permissions.py,sha256=pAxPAw2zqxOcD8vnhxzEYw3KTropa-XB46TbK3Q2bpc,3079
+fastpermit/principal.py,sha256=qD96eEPARLRaONhlpdzUAY7O2wvnu5PuCNrNPa-Mzjo,1152
+fastpermit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastpermit/backends/__init__.py,sha256=6DzNSiWm-5WVrqVHKpKvMgcYG4CEbUKZIhngzsFthAQ,162
+fastpermit/backends/base.py,sha256=DyASNE25oy-p_VqNXF4ouekzB0O727Yd46t8M4d5AB8,502
+fastpermit/backends/memory.py,sha256=KEXuYieO38aSbzukNQTBkYv2tMvsxSzyNUMp5C3LAqU,1320
+fastpermit/core/__init__.py,sha256=Jn4e076nQS5i5MCKtzbOQg0p01XP8zFyHda1WMgcEn4,334
+fastpermit/core/context.py,sha256=VJLfeSbCDemC_b45fP5YZgwZgvm2P6-hDsn6_HZ7apU,1161
+fastpermit/core/evaluator.py,sha256=97R5IqriyqfwzfdKRQbgaxCjP9S1mzygUsapDZ8fhdw,2470
+fastpermit/core/helpers.py,sha256=y5N625glHRgdMFKbb6FXowKP2GYRWQtgjpzvLKthzYY,715
+fastpermit/core/permission.py,sha256=cXeJH6rCjGP-WIKfD0NWhxG2dSeTn-H7ng20x65RR-w,4809
+fastpermit/integrations/__init__.py,sha256=KQQbeqNk5tJKars7NNYh6OdPYy2oxzJ-g5_9eQXVTGw,4551
+fastpermit-0.1.0.dist-info/licenses/LICENSE,sha256=hMcq3Ijq5-76qGi09IR2l5VfLIBGG8j6qrPEarwowQc,1067
+fastpermit-0.1.0.dist-info/METADATA,sha256=k8-u9iuMC9rcaQuJayLdWXv7m4ORAtIFC9wN6GREK5U,9816
+fastpermit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fastpermit-0.1.0.dist-info/top_level.txt,sha256=nMh8TqMFPremb5Q-AVhz1R2OvUKMaOJtUQfza7aUrPU,11
+fastpermit-0.1.0.dist-info/RECORD,,

fastpermit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastpermit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitaly Sem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastpermit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastpermit