python-authz 0.5.0__tar.gz → 0.6.0__tar.gz

{python_authz-0.5.0 → python_authz-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-authz
-Version: 0.5.0
+Version: 0.6.0
 Summary: A framework-agnostic ReBAC/RBAC/ABAC authorization engine built on one Zanzibar-style relationship graph
 Author: Anupam Gupta
 Author-email: Anupam Gupta <anupam@trois.in>
@@ -53,13 +53,15 @@ kept in agreement with each other.
 
 ## Status
 
-Early release, version 0.5:
+Release, version 0.6.0:
 
-- the core engine, async SQLite and PostgreSQL storage backends, and the
-  optional FastAPI `Depends()` integration (`authz.integrations.fastapi`,
-  installed via `python-authz[fastapi]`)
-- a reference sample app (`examples/sample_app/`) and OAuth2/JWT auth
-  integration recipes (`examples/auth_integrations/`)
+- **Unified ReBAC + RBAC + ABAC**: Zanzibar-style relationship graphs with dynamic runtime ABAC context.
+- **Audit Trail & Policy Explanation**: `Client.explain()` returning `EvaluationDecision` with traversed paths, matched tuples, condition evaluations, and human-readable reasons.
+- **Batch Evaluation & Caching**: `Client.check_batch()` evaluating sequences of `CheckItem`s with per-batch ephemeral read caching.
+- **Introspection**: `Client.list_permissions()` and `Client.list_objects()` for resource and subject discovery.
+- **Declarative Built-in ABAC Predicates**: `builtin_conditions()` and `PythonCallableEvaluator.with_builtins()` (`max_amount`, `min_amount`, `equals_attr`, `in_set`, `jurisdiction_match`, `not_same_subject`).
+- **Enhanced FastAPI Integration**: `requires()` with `get_context`, path/query/header resource parameter resolution, and `explain_access()` storing decisions on `request.state.authz_decision`.
+- Async SQLite and PostgreSQL storage backends.
 
 ## Roadmap
 

{python_authz-0.5.0 → python_authz-0.6.0}/README.md

@@ -26,13 +26,15 @@ kept in agreement with each other.
 
 ## Status
 
-Early release, version 0.5:
-
-- the core engine, async SQLite and PostgreSQL storage backends, and the
-  optional FastAPI `Depends()` integration (`authz.integrations.fastapi`,
-  installed via `python-authz[fastapi]`)
-- a reference sample app (`examples/sample_app/`) and OAuth2/JWT auth
-  integration recipes (`examples/auth_integrations/`)
+Release, version 0.6.0:
+
+- **Unified ReBAC + RBAC + ABAC**: Zanzibar-style relationship graphs with dynamic runtime ABAC context.
+- **Audit Trail & Policy Explanation**: `Client.explain()` returning `EvaluationDecision` with traversed paths, matched tuples, condition evaluations, and human-readable reasons.
+- **Batch Evaluation & Caching**: `Client.check_batch()` evaluating sequences of `CheckItem`s with per-batch ephemeral read caching.
+- **Introspection**: `Client.list_permissions()` and `Client.list_objects()` for resource and subject discovery.
+- **Declarative Built-in ABAC Predicates**: `builtin_conditions()` and `PythonCallableEvaluator.with_builtins()` (`max_amount`, `min_amount`, `equals_attr`, `in_set`, `jurisdiction_match`, `not_same_subject`).
+- **Enhanced FastAPI Integration**: `requires()` with `get_context`, path/query/header resource parameter resolution, and `explain_access()` storing decisions on `request.state.authz_decision`.
+- Async SQLite and PostgreSQL storage backends.
 
 ## Roadmap
 

{python_authz-0.5.0 → python_authz-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-authz"
-version = "0.5.0"
+version = "0.6.0"
 description = "A framework-agnostic ReBAC/RBAC/ABAC authorization engine built on one Zanzibar-style relationship graph"
 readme = "README.md"
 license = "MIT"

{python_authz-0.5.0 → python_authz-0.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-authz"
-version = "0.5.0"
+version = "0.6.0"
 description = "A framework-agnostic ReBAC/RBAC/ABAC authorization engine built on one Zanzibar-style relationship graph"
 readme = "README.md"
 license = "MIT"

{python_authz-0.5.0 → python_authz-0.6.0}/src/authz/__init__.py

@@ -1,5 +1,9 @@
-from authz.conditions import ConditionEvaluator, PythonCallableEvaluator
-from authz.engine import Client, UsersetTree
+from authz.conditions import (
+    ConditionEvaluator,
+    PythonCallableEvaluator,
+    builtin_conditions,
+)
+from authz.engine import CheckItem, Client, EvaluationDecision, UsersetTree
 from authz.errors import (
     AuthError,
     ConditionNotFound,
@@ -27,6 +31,7 @@ from authz.tuples import Condition, ObjectRef, RelationTuple, SubjectRef
 
 __all__ = [
     "AuthError",
+    "CheckItem",
     "Client",
     "Condition",
     "ConditionEvaluator",
@@ -34,6 +39,7 @@ __all__ = [
     "CycleDetected",
     "DepthLimitExceeded",
     "Direct",
+    "EvaluationDecision",
     "Exclusion",
     "From",
     "Intersection",
@@ -54,6 +60,7 @@ __all__ = [
     "Union",
     "UsersetTree",
     "WouldCreateCycle",
+    "builtin_conditions",
 ]
 
 

python_authz-0.6.0/src/authz/conditions.py

@@ -0,0 +1,113 @@
+import inspect
+from typing import Any, Awaitable, Callable, Mapping, Protocol, Union
+
+from authz.errors import ConditionNotFound
+
+ConditionFn = Callable[..., Union[bool, Awaitable[bool]]]
+
+
+class ConditionEvaluator(Protocol):
+    def is_registered(self, name: str) -> bool: ...
+
+    async def evaluate(
+        self, name: str, subject: str, resource: str, context: Mapping[str, Any]
+    ) -> bool: ...
+
+
+class PythonCallableEvaluator:
+    def __init__(self) -> None:
+        self._conditions: dict[str, ConditionFn] = {}
+
+    @classmethod
+    def with_builtins(
+        cls, extra: Mapping[str, ConditionFn] | None = None
+    ) -> "PythonCallableEvaluator":
+        evaluator = cls()
+        for name, fn in builtin_conditions().items():
+            evaluator.register(name, fn)
+        if extra:
+            for name, fn in extra.items():
+                evaluator.register(name, fn)
+        return evaluator
+
+    def register(self, name: str, fn: ConditionFn) -> None:
+        self._conditions[name] = fn
+
+    def is_registered(self, name: str) -> bool:
+        return name in self._conditions
+
+    async def evaluate(
+        self, name: str, subject: str, resource: str, context: Mapping[str, Any]
+    ) -> bool:
+        try:
+            fn = self._conditions[name]
+        except KeyError:
+            raise ConditionNotFound(name) from None
+        result = fn(subject=subject, resource=resource, **context)
+        if inspect.isawaitable(result):
+            result = await result
+        return bool(result)
+
+
+def _max_amount(*, subject: str, resource: str, **ctx: Any) -> bool:
+    try:
+        amount = float(ctx.get("amount", 0))
+    except (ValueError, TypeError):
+        amount = 0.0
+    try:
+        max_amount = float(ctx.get("max_amount", float("inf")))
+    except (ValueError, TypeError):
+        max_amount = float("inf")
+    return amount <= max_amount
+
+
+def _min_amount(*, subject: str, resource: str, **ctx: Any) -> bool:
+    try:
+        amount = float(ctx.get("amount", 0))
+    except (ValueError, TypeError):
+        amount = 0.0
+    try:
+        min_amount = float(ctx.get("min_amount", 0))
+    except (ValueError, TypeError):
+        min_amount = 0.0
+    return amount >= min_amount
+
+
+def _equals_attr(*, subject: str, resource: str, **ctx: Any) -> bool:
+    attr_name = str(ctx.get("attribute", ""))
+    return ctx.get(attr_name) == ctx.get("expected")
+
+
+def _in_set(*, subject: str, resource: str, **ctx: Any) -> bool:
+    attr_name = str(ctx.get("attribute", ""))
+    allowed = ctx.get("allowed_values")
+    if allowed is None:
+        allowed = ()
+    return ctx.get(attr_name) in allowed
+
+
+def _jurisdiction_match(*, subject: str, resource: str, **ctx: Any) -> bool:
+    jur = ctx.get("jurisdiction")
+    if "allowed_jurisdictions" in ctx:
+        allowed = ctx.get("allowed_jurisdictions")
+        if allowed is None:
+            allowed = ()
+        return jur in allowed
+    if "required_jurisdiction" in ctx:
+        return jur == ctx.get("required_jurisdiction")
+    return True
+
+
+def _not_same_subject(*, subject: str, resource: str, **ctx: Any) -> bool:
+    return subject != ctx.get("excluded_subject")
+
+
+def builtin_conditions() -> dict[str, ConditionFn]:
+    return {
+        "max_amount": _max_amount,
+        "min_amount": _min_amount,
+        "equals_attr": _equals_attr,
+        "in_set": _in_set,
+        "jurisdiction_match": _jurisdiction_match,
+        "not_same_subject": _not_same_subject,
+    }

python_authz-0.6.0/src/authz/engine.py

@@ -0,0 +1,635 @@
+from collections import deque
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+from authz.conditions import ConditionEvaluator, ConditionFn
+from authz.errors import (
+    ConditionNotFound,
+    CycleDetected,
+    DepthLimitExceeded,
+    NamespaceNotFound,
+    RelationNotFound,
+    WouldCreateCycle,
+)
+from authz.schema import (
+    Direct,
+    Exclusion,
+    From,
+    Intersection,
+    Namespace,
+    RewriteRule,
+    TupleToUserset,
+    Union,
+    check_schema_cycles,
+    tupleset_relations,
+)
+from authz.storage.base import Storage, Token
+from authz.tuples import ObjectRef, RelationTuple, SubjectRef
+
+
+@dataclass(frozen=True)
+class CheckItem:
+    subject: str
+    permission: str
+    resource: str
+    context: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class EvaluationDecision:
+    allowed: bool
+    subject: str
+    permission: str
+    resource: str
+    matched_tuples: tuple[RelationTuple, ...] = ()
+    visited_path: tuple[str, ...] = ()
+    condition_results: tuple[tuple[str, bool], ...] = ()
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class UsersetTree:
+    relation: str
+    object: ObjectRef
+    direct_subjects: tuple[str, ...] = ()
+    children: tuple["UsersetTree", ...] = ()
+
+
+class _TraceCollector:
+    __slots__ = ("visited_path", "matched_tuples", "condition_results")
+
+    def __init__(self) -> None:
+        self.visited_path: list[str] = []
+        self.matched_tuples: list[RelationTuple] = []
+        self.condition_results: list[tuple[str, bool]] = []
+
+
+class Client:
+    def __init__(
+        self,
+        storage: Storage,
+        condition_evaluator: ConditionEvaluator,
+        max_depth: int = 25,
+    ):
+        self._storage = storage
+        self._conditions = condition_evaluator
+        self._max_depth = max_depth
+        self._namespaces: dict[str, Namespace] = {}
+        self._traversal_relations: dict[str, set[str]] = {}
+
+    def register_schema(self, *namespaces: Namespace) -> None:
+        for ns in namespaces:
+            check_schema_cycles(ns)
+            self._namespaces[ns.name] = ns
+            traversal: set[str] = set()
+            for rule in ns.relations.values():
+                traversal |= tupleset_relations(rule)
+            self._traversal_relations[ns.name] = traversal
+
+    def register_condition(self, name: str, fn: ConditionFn) -> None:
+        self._conditions.register(name, fn)
+
+    @property
+    def schema(self) -> dict[str, Namespace]:
+        return self._namespaces
+
+    @property
+    def _schema(self) -> dict[str, Namespace]:
+        return self._namespaces
+
+    def _get_relation(self, namespace: str, relation: str) -> RewriteRule:
+        ns = self._namespaces.get(namespace)
+        if ns is None:
+            raise NamespaceNotFound(namespace)
+        rule = ns.relations.get(relation)
+        if rule is None:
+            raise RelationNotFound(namespace, relation)
+        return rule
+
+    def _validate_tuple(self, t: RelationTuple) -> None:
+        self._get_relation(t.namespace, t.relation)
+        if t.condition is not None and not self._conditions.is_registered(t.condition.name):
+            raise ConditionNotFound(t.condition.name)
+
+    def _is_graph_edge(self, t: RelationTuple) -> bool:
+        if t.relation in self._traversal_relations.get(t.namespace, set()):
+            return True
+        return t.subject_ref.is_userset
+
+    async def _guard_against_cycle(self, t: RelationTuple) -> None:
+        source = (t.namespace, t.object_id)
+        subject_ref = t.subject_ref
+        if subject_ref.is_userset:
+            start = (subject_ref.namespace, subject_ref.object_id, subject_ref.relation)
+        else:
+            start = (subject_ref.namespace, subject_ref.object_id, t.relation)
+
+        visited: set[tuple[str, str]] = set()
+        queue: deque[tuple[str, str, str]] = deque([start])
+        while queue:
+            namespace, object_id, relation = queue.popleft()
+            if (namespace, object_id) == source:
+                raise WouldCreateCycle(t, f"{t.object} -> {namespace}:{object_id}")
+            if (namespace, object_id) in visited:
+                continue
+            visited.add((namespace, object_id))
+            existing = await self._storage.read_tuples(
+                namespace, object_id=object_id, relation=relation
+            )
+            for et in existing:
+                eref = et.subject_ref
+                if eref.is_userset:
+                    queue.append((eref.namespace, eref.object_id, eref.relation))
+                elif relation in self._traversal_relations.get(namespace, set()):
+                    queue.append((eref.namespace, eref.object_id, relation))
+
+    async def write(self, tuples: Sequence[RelationTuple]) -> Token:
+        for t in tuples:
+            self._validate_tuple(t)
+        async with self._storage.transaction():
+            for t in tuples:
+                if self._is_graph_edge(t):
+                    await self._guard_against_cycle(t)
+                await self._storage.write_tuples([t])
+            return await self._storage.current_token()
+
+    async def delete(self, tuples: Sequence[RelationTuple]) -> Token:
+        for t in tuples:
+            self._get_relation(t.namespace, t.relation)
+        return await self._storage.delete_tuples(tuples)
+
+    async def read(
+        self,
+        namespace: str,
+        object_id: str | None = None,
+        relation: str | None = None,
+        subject: str | None = None,
+    ) -> list[RelationTuple]:
+        if namespace not in self._namespaces:
+            raise NamespaceNotFound(namespace)
+        if relation is not None:
+            self._get_relation(namespace, relation)
+        return await self._storage.read_tuples(
+            namespace, object_id=object_id, relation=relation, subject=subject
+        )
+
+    async def _read_tuples(
+        self,
+        namespace: str,
+        object_id: str | None = None,
+        relation: str | None = None,
+        subject: str | None = None,
+        *,
+        read_cache: dict[tuple[str, str | None, str | None, str | None], list[RelationTuple]] | None = None,
+    ) -> list[RelationTuple]:
+        if read_cache is not None:
+            key = (namespace, object_id, relation, subject)
+            if key in read_cache:
+                return read_cache[key]
+            result = await self._storage.read_tuples(
+                namespace, object_id=object_id, relation=relation, subject=subject
+            )
+            read_cache[key] = result
+            return result
+        return await self._storage.read_tuples(
+            namespace, object_id=object_id, relation=relation, subject=subject
+        )
+
+    async def check(
+        self,
+        subject: str,
+        permission: str,
+        resource: str,
+        *,
+        at_least_as_fresh_as: Token | None = None,
+        context: Mapping[str, Any] | None = None,
+        _read_cache: dict[tuple[str, str | None, str | None, str | None], list[RelationTuple]] | None = None,
+    ) -> bool:
+        if at_least_as_fresh_as is not None:
+            await self._storage.wait_for_token(at_least_as_fresh_as)
+        target = ObjectRef.parse(resource)
+        self._get_relation(target.namespace, permission)
+        return await self._check_relation(
+            subject,
+            target.namespace,
+            target.object_id,
+            permission,
+            [],
+            context=context,
+            read_cache=_read_cache,
+        )
+
+    async def explain(
+        self,
+        subject: str,
+        permission: str,
+        resource: str,
+        *,
+        at_least_as_fresh_as: Token | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> EvaluationDecision:
+        if at_least_as_fresh_as is not None:
+            await self._storage.wait_for_token(at_least_as_fresh_as)
+        target = ObjectRef.parse(resource)
+        self._get_relation(target.namespace, permission)
+
+        collector = _TraceCollector()
+        allowed = await self._check_relation(
+            subject,
+            target.namespace,
+            target.object_id,
+            permission,
+            [],
+            context=context,
+            collector=collector,
+        )
+
+        target_node = f"{resource}#{permission}"
+        if allowed:
+            matched = tuple(collector.matched_tuples)
+            chain = [subject]
+            for t in matched:
+                node = f"{t.namespace}:{t.object_id}#{t.relation}"
+                if node not in chain:
+                    chain.append(node)
+            if target_node not in chain:
+                chain.append(target_node)
+            reason = f"Allowed via {' -> '.join(chain)}"
+        else:
+            matched = ()
+            reason = f"Denied: no matching relation or condition failed for {subject} on {target_node}"
+
+        return EvaluationDecision(
+            allowed=allowed,
+            subject=subject,
+            permission=permission,
+            resource=resource,
+            matched_tuples=matched,
+            visited_path=tuple(collector.visited_path),
+            condition_results=tuple(collector.condition_results),
+            reason=reason,
+        )
+
+    async def check_batch(
+        self,
+        checks: Sequence[CheckItem],
+        *,
+        at_least_as_fresh_as: Token | None = None,
+    ) -> list[bool]:
+        if at_least_as_fresh_as is not None:
+            await self._storage.wait_for_token(at_least_as_fresh_as)
+        read_cache: dict[tuple[str, str | None, str | None, str | None], list[RelationTuple]] = {}
+        results: list[bool] = []
+        for item in checks:
+            res = await self.check(
+                item.subject,
+                item.permission,
+                item.resource,
+                context=item.context,
+                _read_cache=read_cache,
+            )
+            results.append(res)
+        return results
+
+    async def list_permissions(
+        self,
+        subject: str,
+        resource: str,
+        permissions: Sequence[str] | None = None,
+        *,
+        at_least_as_fresh_as: Token | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> list[str]:
+        target = ObjectRef.parse(resource)
+        ns = self._namespaces.get(target.namespace)
+        if ns is None:
+            raise NamespaceNotFound(target.namespace)
+        if permissions is None:
+            candidate_perms = list(ns.relations.keys())
+        else:
+            candidate_perms = list(permissions)
+        checks = [
+            CheckItem(
+                subject=subject,
+                permission=perm,
+                resource=resource,
+                context=context,
+            )
+            for perm in candidate_perms
+        ]
+        results = await self.check_batch(checks, at_least_as_fresh_as=at_least_as_fresh_as)
+        return [perm for perm, allowed in zip(candidate_perms, results) if allowed]
+
+    async def list_objects(
+        self,
+        subject: str,
+        permission: str,
+        namespace: str,
+        candidate_ids: Sequence[str] | None = None,
+        *,
+        at_least_as_fresh_as: Token | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> list[str]:
+        self._get_relation(namespace, permission)
+        if candidate_ids is None:
+            if at_least_as_fresh_as is not None:
+                await self._storage.wait_for_token(at_least_as_fresh_as)
+                at_least_as_fresh_as = None
+            tuples = await self._storage.read_tuples(namespace)
+            seen: set[str] = set()
+            discovered: list[str] = []
+            for t in tuples:
+                if t.object_id not in seen:
+                    seen.add(t.object_id)
+                    discovered.append(t.object_id)
+            candidate_ids = discovered
+
+        if not candidate_ids:
+            return []
+
+        checks = [
+            CheckItem(
+                subject=subject,
+                permission=permission,
+                resource=f"{namespace}:{oid}",
+                context=context,
+            )
+            for oid in candidate_ids
+        ]
+        results = await self.check_batch(checks, at_least_as_fresh_as=at_least_as_fresh_as)
+        return [oid for oid, allowed in zip(candidate_ids, results) if allowed]
+
+    async def _check_relation(
+        self,
+        subject: str,
+        namespace: str,
+        object_id: str,
+        relation: str,
+        path: list[tuple[str, str, str]],
+        *,
+        context: Mapping[str, Any] | None = None,
+        collector: _TraceCollector | None = None,
+        read_cache: dict[tuple[str, str | None, str | None, str | None], list[RelationTuple]] | None = None,
+    ) -> bool:
+        node = (namespace, object_id, relation)
+        node_str = f"{namespace}:{object_id}#{relation}"
+        if collector is not None and node_str not in collector.visited_path:
+            collector.visited_path.append(node_str)
+
+        if node in path:
+            trail = [f"{ns}:{oid}#{rel}" for ns, oid, rel in path]
+            trail.append(node_str)
+            raise CycleDetected(trail)
+        if len(path) >= self._max_depth:
+            raise DepthLimitExceeded(self._max_depth)
+        rule = self._get_relation(namespace, relation)
+        return await self._eval_rule(
+            rule,
+            subject,
+            namespace,
+            object_id,
+            relation,
+            path + [node],
+            context=context,
+            collector=collector,
+            read_cache=read_cache,
+        )
+
+    async def _eval_rule(
+        self,
+        rule: RewriteRule,
+        subject: str,
+        namespace: str,
+        object_id: str,
+        relation: str,
+        path: list[tuple[str, str, str]],
+        *,
+        context: Mapping[str, Any] | None = None,
+        collector: _TraceCollector | None = None,
+        read_cache: dict[tuple[str, str | None, str | None, str | None], list[RelationTuple]] | None = None,
+    ) -> bool:
+        if isinstance(rule, Direct):
+            return await self._eval_direct(
+                subject,
+                namespace,
+                object_id,
+                relation,
+                path,
+                context=context,
+                collector=collector,
+                read_cache=read_cache,
+            )
+        if isinstance(rule, Union):
+            for child in rule.children:
+                mark = len(collector.matched_tuples) if collector is not None else 0
+                if await self._eval_rule(
+                    child,
+                    subject,
+                    namespace,
+                    object_id,
+                    relation,
+                    path,
+                    context=context,
+                    collector=collector,
+                    read_cache=read_cache,
+                ):
+                    return True
+                if collector is not None:
+                    del collector.matched_tuples[mark:]
+            return False
+        if isinstance(rule, Intersection):
+            mark = len(collector.matched_tuples) if collector is not None else 0
+            for child in rule.children:
+                if not await self._eval_rule(
+                    child,
+                    subject,
+                    namespace,
+                    object_id,
+                    relation,
+                    path,
+                    context=context,
+                    collector=collector,
+                    read_cache=read_cache,
+                ):
+                    if collector is not None:
+                        del collector.matched_tuples[mark:]
+                    return False
+            return True
+        if isinstance(rule, Exclusion):
+            mark = len(collector.matched_tuples) if collector is not None else 0
+            if not await self._eval_rule(
+                rule.base,
+                subject,
+                namespace,
+                object_id,
+                relation,
+                path,
+                context=context,
+                collector=collector,
+                read_cache=read_cache,
+            ):
+                if collector is not None:
+                    del collector.matched_tuples[mark:]
+                return False
+            sub_mark = len(collector.matched_tuples) if collector is not None else 0
+            sub_result = await self._eval_rule(
+                rule.subtract,
+                subject,
+                namespace,
+                object_id,
+                relation,
+                path,
+                context=context,
+                collector=collector,
+                read_cache=read_cache,
+            )
+            if collector is not None:
+                del collector.matched_tuples[sub_mark:]
+            if sub_result:
+                if collector is not None:
+                    del collector.matched_tuples[mark:]
+                return False
+            return True
+        if isinstance(rule, From):
+            return await self._check_relation(
+                subject,
+                namespace,
+                object_id,
+                rule.relation,
+                path,
+                context=context,
+                collector=collector,
+                read_cache=read_cache,
+            )
+        if isinstance(rule, TupleToUserset):
+            parents = await self._read_tuples(
+                namespace,
+                object_id=object_id,
+                relation=rule.tupleset_relation,
+                read_cache=read_cache,
+            )
+            for pt in parents:
+                pref = pt.subject_ref
+                mark = len(collector.matched_tuples) if collector is not None else 0
+                if await self._check_relation(
+                    subject,
+                    pref.namespace,
+                    pref.object_id,
+                    rule.computed_relation,
+                    path,
+                    context=context,
+                    collector=collector,
+                    read_cache=read_cache,
+                ):
+                    if collector is not None:
+                        collector.matched_tuples.append(pt)
+                    return True
+                if collector is not None:
+                    del collector.matched_tuples[mark:]
+            return False
+        raise TypeError(f"unsupported rewrite rule: {rule!r}")
+
+    async def _eval_direct(
+        self,
+        subject: str,
+        namespace: str,
+        object_id: str,
+        relation: str,
+        path: list[tuple[str, str, str]],
+        *,
+        context: Mapping[str, Any] | None = None,
+        collector: _TraceCollector | None = None,
+        read_cache: dict[tuple[str, str | None, str | None, str | None], list[RelationTuple]] | None = None,
+    ) -> bool:
+        subject_ref = SubjectRef.parse(subject)
+        tuples = await self._read_tuples(
+            namespace, object_id=object_id, relation=relation, read_cache=read_cache
+        )
+        for t in tuples:
+            if t.condition is not None:
+                merged_ctx = {**t.condition.context, **(context or {})}
+                holds = await self._conditions.evaluate(
+                    t.condition.name, subject, f"{namespace}:{object_id}", merged_ctx
+                )
+                if collector is not None:
+                    collector.condition_results.append((t.condition.name, holds))
+                if not holds:
+                    continue
+            tref = t.subject_ref
+            if not tref.is_userset:
+                if tref.namespace == subject_ref.namespace and tref.object_id == subject_ref.object_id:
+                    if collector is not None:
+                        collector.matched_tuples.append(t)
+                    return True
+            else:
+                mark = len(collector.matched_tuples) if collector is not None else 0
+                if await self._check_relation(
+                    subject,
+                    tref.namespace,
+                    tref.object_id,
+                    tref.relation,
+                    path,
+                    context=context,
+                    collector=collector,
+                    read_cache=read_cache,
+                ):
+                    if collector is not None:
+                        collector.matched_tuples.append(t)
+                    return True
+                if collector is not None:
+                    del collector.matched_tuples[mark:]
+        return False
+
+    async def expand(self, permission: str, resource: str) -> "UsersetTree":
+        target = ObjectRef.parse(resource)
+        rule = self._get_relation(target.namespace, permission)
+        return await self._expand_rule(rule, target.namespace, target.object_id, permission)
+
+    async def _expand_rule(
+        self, rule, namespace: str, object_id: str, relation: str
+    ) -> "UsersetTree":
+        direct_subjects: list[str] = []
+        children: list[UsersetTree] = []
+
+        async def walk(r) -> None:
+            if isinstance(r, Direct):
+                tuples = await self._storage.read_tuples(
+                    namespace, object_id=object_id, relation=relation
+                )
+                direct_subjects.extend(t.subject for t in tuples)
+            elif isinstance(r, (Union, Intersection)):
+                for child in r.children:
+                    await walk(child)
+            elif isinstance(r, Exclusion):
+                await walk(r.base)
+            elif isinstance(r, From):
+                children.append(
+                    await self._expand_rule(
+                        self._get_relation(namespace, r.relation),
+                        namespace,
+                        object_id,
+                        r.relation,
+                    )
+                )
+            elif isinstance(r, TupleToUserset):
+                parents = await self._storage.read_tuples(
+                    namespace, object_id=object_id, relation=r.tupleset_relation
+                )
+                for pt in parents:
+                    pref = pt.subject_ref
+                    children.append(
+                        await self._expand_rule(
+                            self._get_relation(pref.namespace, r.computed_relation),
+                            pref.namespace,
+                            pref.object_id,
+                            r.computed_relation,
+                        )
+                    )
+
+        await walk(rule)
+        return UsersetTree(
+            relation=relation,
+            object=ObjectRef(namespace, object_id),
+            direct_subjects=tuple(direct_subjects),
+            children=tuple(children),
+        )

python_authz-0.6.0/src/authz/integrations/fastapi.py

@@ -0,0 +1,86 @@
+import inspect
+from typing import Any, Awaitable, Callable, Mapping
+
+from fastapi import Depends, HTTPException, Request
+
+from authz.engine import Client, EvaluationDecision
+
+ResourceFn = Callable[[Request], str | Awaitable[str]]
+ContextFn = Callable[[Request], Mapping[str, Any] | Awaitable[Mapping[str, Any]]]
+
+__all__ = ["ContextFn", "ResourceFn", "explain_access", "requires"]
+
+
+async def _resolve_resource(resource: str | ResourceFn, request: Request) -> str:
+    if isinstance(resource, str):
+        params = {
+            **dict(request.headers),
+            **dict(request.query_params),
+            **dict(request.path_params),
+        }
+        return resource.format(**params)
+    result = resource(request)
+    if inspect.isawaitable(result):
+        result = await result
+    return result
+
+
+async def _resolve_context(
+    get_context: ContextFn | None, request: Request
+) -> Mapping[str, Any] | None:
+    if get_context is None:
+        return None
+    try:
+        result = get_context(request)
+    except TypeError:
+        result = get_context()  # type: ignore[call-arg]
+    if inspect.isawaitable(result):
+        result = await result
+    return result
+
+
+def requires(
+    permission: str,
+    resource: str | ResourceFn,
+    *,
+    get_client: Callable[..., Client | Awaitable[Client]],
+    get_subject: Callable[..., str | Awaitable[str]],
+    get_context: ContextFn | None = None,
+    detail: str = "Forbidden",
+) -> Callable:
+    async def dependency(
+        request: Request,
+        client: Client = Depends(get_client),
+        subject: str = Depends(get_subject),
+    ) -> None:
+        resolved = await _resolve_resource(resource, request)
+        ctx = await _resolve_context(get_context, request)
+        if not await client.check(subject, permission, resolved, context=ctx):
+            raise HTTPException(status_code=403, detail=detail)
+
+    return dependency
+
+
+def explain_access(
+    permission: str,
+    resource: str | ResourceFn,
+    *,
+    get_client: Callable[..., Client | Awaitable[Client]],
+    get_subject: Callable[..., str | Awaitable[str]],
+    get_context: ContextFn | None = None,
+    detail: str = "Forbidden",
+) -> Callable:
+    async def dependency(
+        request: Request,
+        client: Client = Depends(get_client),
+        subject: str = Depends(get_subject),
+    ) -> EvaluationDecision:
+        resolved = await _resolve_resource(resource, request)
+        ctx = await _resolve_context(get_context, request)
+        decision = await client.explain(subject, permission, resolved, context=ctx)
+        request.state.authz_decision = decision
+        if not decision.allowed:
+            raise HTTPException(status_code=403, detail=detail)
+        return decision
+
+    return dependency

python_authz-0.5.0/src/authz/conditions.py

@@ -1,37 +0,0 @@
-import inspect
-from typing import Any, Awaitable, Callable, Mapping, Protocol, Union
-
-from authz.errors import ConditionNotFound
-
-ConditionFn = Callable[..., Union[bool, Awaitable[bool]]]
-
-
-class ConditionEvaluator(Protocol):
-    def is_registered(self, name: str) -> bool: ...
-
-    async def evaluate(
-        self, name: str, subject: str, resource: str, context: Mapping[str, Any]
-    ) -> bool: ...
-
-
-class PythonCallableEvaluator:
-    def __init__(self) -> None:
-        self._conditions: dict[str, ConditionFn] = {}
-
-    def register(self, name: str, fn: ConditionFn) -> None:
-        self._conditions[name] = fn
-
-    def is_registered(self, name: str) -> bool:
-        return name in self._conditions
-
-    async def evaluate(
-        self, name: str, subject: str, resource: str, context: Mapping[str, Any]
-    ) -> bool:
-        try:
-            fn = self._conditions[name]
-        except KeyError:
-            raise ConditionNotFound(name) from None
-        result = fn(subject=subject, resource=resource, **context)
-        if inspect.isawaitable(result):
-            result = await result
-        return bool(result)

python_authz-0.5.0/src/authz/engine.py

@@ -1,297 +0,0 @@
-from collections import deque
-from dataclasses import dataclass
-from typing import Sequence
-
-from authz.conditions import ConditionEvaluator, ConditionFn
-from authz.errors import (
-    ConditionNotFound,
-    CycleDetected,
-    DepthLimitExceeded,
-    NamespaceNotFound,
-    RelationNotFound,
-    WouldCreateCycle,
-)
-from authz.schema import (
-    Direct,
-    Exclusion,
-    From,
-    Intersection,
-    Namespace,
-    RewriteRule,
-    TupleToUserset,
-    Union,
-    check_schema_cycles,
-    tupleset_relations,
-)
-from authz.storage.base import Storage, Token
-from authz.tuples import ObjectRef, RelationTuple, SubjectRef
-
-
-@dataclass(frozen=True)
-class UsersetTree:
-    relation: str
-    object: ObjectRef
-    direct_subjects: tuple[str, ...] = ()
-    children: tuple["UsersetTree", ...] = ()
-
-
-class Client:
-    def __init__(
-        self,
-        storage: Storage,
-        condition_evaluator: ConditionEvaluator,
-        max_depth: int = 25,
-    ):
-        self._storage = storage
-        self._conditions = condition_evaluator
-        self._max_depth = max_depth
-        self._namespaces: dict[str, Namespace] = {}
-        self._traversal_relations: dict[str, set[str]] = {}
-
-    def register_schema(self, *namespaces: Namespace) -> None:
-        for ns in namespaces:
-            check_schema_cycles(ns)
-            self._namespaces[ns.name] = ns
-            traversal: set[str] = set()
-            for rule in ns.relations.values():
-                traversal |= tupleset_relations(rule)
-            self._traversal_relations[ns.name] = traversal
-
-    def register_condition(self, name: str, fn: ConditionFn) -> None:
-        self._conditions.register(name, fn)
-
-    def _get_relation(self, namespace: str, relation: str) -> RewriteRule:
-        ns = self._namespaces.get(namespace)
-        if ns is None:
-            raise NamespaceNotFound(namespace)
-        rule = ns.relations.get(relation)
-        if rule is None:
-            raise RelationNotFound(namespace, relation)
-        return rule
-
-    def _validate_tuple(self, t: RelationTuple) -> None:
-        self._get_relation(t.namespace, t.relation)
-        if t.condition is not None and not self._conditions.is_registered(t.condition.name):
-            raise ConditionNotFound(t.condition.name)
-
-    def _is_graph_edge(self, t: RelationTuple) -> bool:
-        if t.relation in self._traversal_relations.get(t.namespace, set()):
-            return True
-        return t.subject_ref.is_userset
-
-    async def _guard_against_cycle(self, t: RelationTuple) -> None:
-        source = (t.namespace, t.object_id)
-        subject_ref = t.subject_ref
-        if subject_ref.is_userset:
-            start = (subject_ref.namespace, subject_ref.object_id, subject_ref.relation)
-        else:
-            start = (subject_ref.namespace, subject_ref.object_id, t.relation)
-
-        visited: set[tuple[str, str]] = set()
-        queue: deque[tuple[str, str, str]] = deque([start])
-        while queue:
-            namespace, object_id, relation = queue.popleft()
-            if (namespace, object_id) == source:
-                raise WouldCreateCycle(t, f"{t.object} -> {namespace}:{object_id}")
-            if (namespace, object_id) in visited:
-                continue
-            visited.add((namespace, object_id))
-            existing = await self._storage.read_tuples(
-                namespace, object_id=object_id, relation=relation
-            )
-            for et in existing:
-                eref = et.subject_ref
-                if eref.is_userset:
-                    queue.append((eref.namespace, eref.object_id, eref.relation))
-                elif relation in self._traversal_relations.get(namespace, set()):
-                    queue.append((eref.namespace, eref.object_id, relation))
-
-    async def write(self, tuples: Sequence[RelationTuple]) -> Token:
-        for t in tuples:
-            self._validate_tuple(t)
-        async with self._storage.transaction():
-            for t in tuples:
-                if self._is_graph_edge(t):
-                    await self._guard_against_cycle(t)
-                await self._storage.write_tuples([t])
-            return await self._storage.current_token()
-
-    async def delete(self, tuples: Sequence[RelationTuple]) -> Token:
-        for t in tuples:
-            self._get_relation(t.namespace, t.relation)
-        return await self._storage.delete_tuples(tuples)
-
-    async def read(
-        self,
-        namespace: str,
-        object_id: str | None = None,
-        relation: str | None = None,
-        subject: str | None = None,
-    ) -> list[RelationTuple]:
-        if namespace not in self._namespaces:
-            raise NamespaceNotFound(namespace)
-        if relation is not None:
-            self._get_relation(namespace, relation)
-        return await self._storage.read_tuples(
-            namespace, object_id=object_id, relation=relation, subject=subject
-        )
-
-    async def check(
-        self,
-        subject: str,
-        permission: str,
-        resource: str,
-        *,
-        at_least_as_fresh_as: Token | None = None,
-    ) -> bool:
-        if at_least_as_fresh_as is not None:
-            await self._storage.wait_for_token(at_least_as_fresh_as)
-        target = ObjectRef.parse(resource)
-        self._get_relation(target.namespace, permission)
-        return await self._check_relation(
-            subject, target.namespace, target.object_id, permission, []
-        )
-
-    async def _check_relation(
-        self,
-        subject: str,
-        namespace: str,
-        object_id: str,
-        relation: str,
-        path: list[tuple[str, str, str]],
-    ) -> bool:
-        node = (namespace, object_id, relation)
-        if node in path:
-            trail = [f"{ns}:{oid}#{rel}" for ns, oid, rel in path]
-            trail.append(f"{namespace}:{object_id}#{relation}")
-            raise CycleDetected(trail)
-        if len(path) >= self._max_depth:
-            raise DepthLimitExceeded(self._max_depth)
-        rule = self._get_relation(namespace, relation)
-        return await self._eval_rule(
-            rule, subject, namespace, object_id, relation, path + [node]
-        )
-
-    async def _eval_rule(
-        self,
-        rule,
-        subject: str,
-        namespace: str,
-        object_id: str,
-        relation: str,
-        path: list[tuple[str, str, str]],
-    ) -> bool:
-        if isinstance(rule, Direct):
-            return await self._eval_direct(subject, namespace, object_id, relation, path)
-        if isinstance(rule, Union):
-            for child in rule.children:
-                if await self._eval_rule(child, subject, namespace, object_id, relation, path):
-                    return True
-            return False
-        if isinstance(rule, Intersection):
-            for child in rule.children:
-                if not await self._eval_rule(child, subject, namespace, object_id, relation, path):
-                    return False
-            return True
-        if isinstance(rule, Exclusion):
-            if not await self._eval_rule(rule.base, subject, namespace, object_id, relation, path):
-                return False
-            return not await self._eval_rule(
-                rule.subtract, subject, namespace, object_id, relation, path
-            )
-        if isinstance(rule, From):
-            return await self._check_relation(subject, namespace, object_id, rule.relation, path)
-        if isinstance(rule, TupleToUserset):
-            parents = await self._storage.read_tuples(
-                namespace, object_id=object_id, relation=rule.tupleset_relation
-            )
-            for pt in parents:
-                pref = pt.subject_ref
-                if await self._check_relation(
-                    subject, pref.namespace, pref.object_id, rule.computed_relation, path
-                ):
-                    return True
-            return False
-        raise TypeError(f"unsupported rewrite rule: {rule!r}")
-
-    async def _eval_direct(
-        self,
-        subject: str,
-        namespace: str,
-        object_id: str,
-        relation: str,
-        path: list[tuple[str, str, str]],
-    ) -> bool:
-        subject_ref = SubjectRef.parse(subject)
-        tuples = await self._storage.read_tuples(namespace, object_id=object_id, relation=relation)
-        for t in tuples:
-            if t.condition is not None:
-                holds = await self._conditions.evaluate(
-                    t.condition.name, subject, f"{namespace}:{object_id}", t.condition.context
-                )
-                if not holds:
-                    continue
-            tref = t.subject_ref
-            if not tref.is_userset:
-                if tref.namespace == subject_ref.namespace and tref.object_id == subject_ref.object_id:
-                    return True
-            else:
-                if await self._check_relation(
-                    subject, tref.namespace, tref.object_id, tref.relation, path
-                ):
-                    return True
-        return False
-
-    async def expand(self, permission: str, resource: str) -> "UsersetTree":
-        target = ObjectRef.parse(resource)
-        rule = self._get_relation(target.namespace, permission)
-        return await self._expand_rule(rule, target.namespace, target.object_id, permission)
-
-    async def _expand_rule(
-        self, rule, namespace: str, object_id: str, relation: str
-    ) -> "UsersetTree":
-        direct_subjects: list[str] = []
-        children: list[UsersetTree] = []
-
-        async def walk(r) -> None:
-            if isinstance(r, Direct):
-                tuples = await self._storage.read_tuples(
-                    namespace, object_id=object_id, relation=relation
-                )
-                direct_subjects.extend(t.subject for t in tuples)
-            elif isinstance(r, (Union, Intersection)):
-                for child in r.children:
-                    await walk(child)
-            elif isinstance(r, Exclusion):
-                await walk(r.base)
-            elif isinstance(r, From):
-                children.append(
-                    await self._expand_rule(
-                        self._get_relation(namespace, r.relation),
-                        namespace,
-                        object_id,
-                        r.relation,
-                    )
-                )
-            elif isinstance(r, TupleToUserset):
-                parents = await self._storage.read_tuples(
-                    namespace, object_id=object_id, relation=r.tupleset_relation
-                )
-                for pt in parents:
-                    pref = pt.subject_ref
-                    children.append(
-                        await self._expand_rule(
-                            self._get_relation(pref.namespace, r.computed_relation),
-                            pref.namespace,
-                            pref.object_id,
-                            r.computed_relation,
-                        )
-                    )
-
-        await walk(rule)
-        return UsersetTree(
-            relation=relation,
-            object=ObjectRef(namespace, object_id),
-            direct_subjects=tuple(direct_subjects),
-            children=tuple(children),
-        )

python_authz-0.5.0/src/authz/integrations/fastapi.py

@@ -1,37 +0,0 @@
-import inspect
-from typing import Awaitable, Callable
-
-from fastapi import Depends, HTTPException, Request
-
-from authz.engine import Client
-
-ResourceFn = Callable[[Request], str | Awaitable[str]]
-
-
-async def _resolve_resource(resource: str | ResourceFn, request: Request) -> str:
-    if isinstance(resource, str):
-        return resource.format(**request.path_params)
-    result = resource(request)
-    if inspect.isawaitable(result):
-        result = await result
-    return result
-
-
-def requires(
-    permission: str,
-    resource: str | ResourceFn,
-    *,
-    get_client: Callable[..., Client | Awaitable[Client]],
-    get_subject: Callable[..., str | Awaitable[str]],
-    detail: str = "Forbidden",
-) -> Callable:
-    async def dependency(
-        request: Request,
-        client: Client = Depends(get_client),
-        subject: str = Depends(get_subject),
-    ) -> None:
-        resolved = await _resolve_resource(resource, request)
-        if not await client.check(subject, permission, resolved):
-            raise HTTPException(status_code=403, detail=detail)
-
-    return dependency