python-authz 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

authz/__init__.py

@@ -1,7 +1,12 @@
-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,
+    CardinalityViolationError,
     ConditionNotFound,
     CycleDetected,
     DepthLimitExceeded,
@@ -19,6 +24,7 @@ from authz.schema import (
     RewriteRule,
     TupleToUserset,
     Union,
+    build_role_hierarchy,
 )
 from authz.storage.base import Storage, Token
 from authz.storage.postgres import PostgresStorage
@@ -27,6 +33,8 @@ from authz.tuples import Condition, ObjectRef, RelationTuple, SubjectRef
 
 __all__ = [
     "AuthError",
+    "CardinalityViolationError",
+    "CheckItem",
     "Client",
     "Condition",
     "ConditionEvaluator",
@@ -34,6 +42,7 @@ __all__ = [
     "CycleDetected",
     "DepthLimitExceeded",
     "Direct",
+    "EvaluationDecision",
     "Exclusion",
     "From",
     "Intersection",
@@ -54,6 +63,8 @@ __all__ = [
     "Union",
     "UsersetTree",
     "WouldCreateCycle",
+    "build_role_hierarchy",
+    "builtin_conditions",
 ]
 
 

authz/conditions.py

@@ -18,6 +18,18 @@ 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
 
@@ -35,3 +47,67 @@ class PythonCallableEvaluator:
         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,
+    }

authz/engine.py

@@ -1,9 +1,10 @@
 from collections import deque
 from dataclasses import dataclass
-from typing import Sequence
+from typing import Any, Mapping, Sequence
 
 from authz.conditions import ConditionEvaluator, ConditionFn
 from authz.errors import (
+    CardinalityViolationError,
     ConditionNotFound,
     CycleDetected,
     DepthLimitExceeded,
@@ -27,6 +28,26 @@ 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
@@ -35,6 +56,15 @@ class UsersetTree:
     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,
@@ -60,6 +90,14 @@ class Client:
     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:
@@ -110,6 +148,32 @@ class Client:
         for t in tuples:
             self._validate_tuple(t)
         async with self._storage.transaction():
+            target_subjects: dict[tuple[str, str, str], list[str]] = {}
+            for t in tuples:
+                ns = self._namespaces[t.namespace]
+                max_limit = ns.max_subjects_for(t.relation)
+                if max_limit is not None:
+                    target_key = (t.namespace, t.object_id, t.relation)
+                    if target_key not in target_subjects:
+                        existing = await self._storage.read_tuples(
+                            t.namespace, object_id=t.object_id, relation=t.relation
+                        )
+                        target_subjects[target_key] = list(
+                            dict.fromkeys(et.subject for et in existing)
+                        )
+                    current = target_subjects[target_key]
+                    if t.subject not in current:
+                        if len(current) >= max_limit:
+                            raise CardinalityViolationError(
+                                namespace=t.namespace,
+                                object_id=t.object_id,
+                                relation=t.relation,
+                                max_subjects=max_limit,
+                                existing_subjects=tuple(current),
+                                attempted_subject=t.subject,
+                            )
+                        current.append(t.subject)
+
             for t in tuples:
                 if self._is_graph_edge(t):
                     await self._guard_against_cycle(t)
@@ -136,6 +200,28 @@ class Client:
             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,
@@ -143,15 +229,163 @@ class Client:
         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, []
+            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,
@@ -159,58 +393,166 @@ class Client:
         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(f"{namespace}:{object_id}#{relation}")
+            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]
+            rule,
+            subject,
+            namespace,
+            object_id,
+            relation,
+            path + [node],
+            context=context,
+            collector=collector,
+            read_cache=read_cache,
         )
 
     async def _eval_rule(
         self,
-        rule,
+        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)
+            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:
-                if await self._eval_rule(child, subject, namespace, object_id, relation, path):
+                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):
+                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):
-            if not await self._eval_rule(rule.base, subject, namespace, object_id, relation, path):
+            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
-            return not await self._eval_rule(
-                rule.subtract, subject, namespace, object_id, relation, path
+            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)
+            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._storage.read_tuples(
-                namespace, object_id=object_id, relation=rule.tupleset_relation
+            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
+                    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}")
 
@@ -221,25 +563,48 @@ class Client:
         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._storage.read_tuples(namespace, object_id=object_id, relation=relation)
+        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}", t.condition.context
+                    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
+                    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":

authz/errors.py

@@ -48,3 +48,28 @@ class DepthLimitExceeded(AuthError):
     def __init__(self, max_depth: int):
         super().__init__(f"recursion exceeded max_depth={max_depth}")
         self.max_depth = max_depth
+
+
+class CardinalityViolationError(AuthError):
+    """Raised when writing a tuple would exceed a relation's max_subjects limit (e.g. singleton org_admin)."""
+
+    def __init__(
+        self,
+        namespace: str,
+        object_id: str,
+        relation: str,
+        max_subjects: int,
+        existing_subjects: tuple[str, ...],
+        attempted_subject: str,
+    ) -> None:
+        self.namespace = namespace
+        self.object_id = object_id
+        self.relation = relation
+        self.max_subjects = max_subjects
+        self.existing_subjects = existing_subjects
+        self.attempted_subject = attempted_subject
+        super().__init__(
+            f"Cardinality violation on {namespace}:{object_id}#{relation}: "
+            f"max_subjects={max_subjects}, existing={list(existing_subjects)}, "
+            f"attempted={attempted_subject!r}"
+        )

authz/integrations/fastapi.py

@@ -1,28 +1,51 @@
 import inspect
-from typing import Awaitable, Callable
+from typing import Any, Awaitable, Callable, Mapping
 
 from fastapi import Depends, HTTPException, Request
 
-from authz.engine import Client
+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):
-        return resource.format(**request.path_params)
+        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(
@@ -31,7 +54,33 @@ def requires(
         subject: str = Depends(get_subject),
     ) -> None:
         resolved = await _resolve_resource(resource, request)
-        if not await client.check(subject, permission, resolved):
+        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

authz/schema.py

@@ -1,3 +1,4 @@
+from collections.abc import Iterable, Mapping, Sequence
 from typing import Iterator
 
 from authz.errors import SchemaCycleDetected
@@ -55,9 +56,57 @@ class TupleToUserset(RewriteRule):
 
 
 class Namespace:
-    def __init__(self, name: str, relations: dict[str, RewriteRule]):
+    def __init__(
+        self,
+        name: str,
+        relations: Mapping[str, RewriteRule],
+        singleton_relations: Iterable[str] | None = None,
+        max_subjects: Mapping[str, int] | None = None,
+    ) -> None:
         self.name = name
-        self.relations = relations
+        self.relations = relations  # type: ignore[assignment]
+        self.singleton_relations: frozenset[str] = (
+            frozenset(singleton_relations) if singleton_relations is not None else frozenset()
+        )
+        self.max_subjects: Mapping[str, int] = (
+            dict(max_subjects) if max_subjects is not None else {}
+        )
+
+    def max_subjects_for(self, relation: str) -> int | None:
+        if relation in self.singleton_relations:
+            return 1
+        return self.max_subjects.get(relation)
+
+
+def build_role_hierarchy(
+    roles_high_to_low: Sequence[str],
+    *,
+    extra_relations: Mapping[str, RewriteRule] | None = None,
+) -> dict[str, RewriteRule]:
+    """Build a role hierarchy with transitive downward inheritance and strict upward override relations.
+
+    Given an ordered sequence of roles from highest to lowest (e.g. ['org_admin', 'org_manager', ...]):
+    - Index 0 (top role): Direct() and override_<top_role> = From(<top_role>)
+    - Index i > 0: Union(Direct(), From(<superior_role>)) and override_<role> = From(<superior_role>)
+    - Merges any extra_relations provided.
+    """
+    if len(roles_high_to_low) != len(set(roles_high_to_low)):
+        raise ValueError("Role hierarchy must not contain duplicate roles")
+
+    relations: dict[str, RewriteRule] = {}
+    for i, role in enumerate(roles_high_to_low):
+        if i == 0:
+            relations[role] = Direct()
+            relations[f"override_{role}"] = From(role)
+        else:
+            superior_role = roles_high_to_low[i - 1]
+            relations[role] = Union(Direct(), From(superior_role))
+            relations[f"override_{role}"] = From(superior_role)
+
+    if extra_relations is not None:
+        relations.update(extra_relations)
+
+    return relations
 
 
 def _from_edges(rule: RewriteRule) -> Iterator[str]:

{python_authz-0.5.0.dist-info → python_authz-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-authz
-Version: 0.5.0
+Version: 0.7.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,17 @@ kept in agreement with each other.
 
 ## Status
 
-Early release, version 0.5:
+Release, version 0.7.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/`)
+- **Singleton & Cardinality Constraints**: Enforce subject limits on relations (e.g. at most 1 `org_admin`) via `singleton_relations` and `max_subjects` on `Namespace`, raising `CardinalityViolationError` on violations while maintaining idempotent rewrites.
+- **Declarative Role Hierarchies & Strict Upward Overrides**: `build_role_hierarchy(roles_high_to_low, extra_relations=...)` creates multi-tier role hierarchies with transitive downward inheritance and strict upward override relations (`override_<role>`).
+- **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
 
@@ -126,6 +130,37 @@ It covers schema vs. data cycles, which rewrite rule (`Union`,
 situation, and when a depth-limit error means your data is legitimately
 deep versus something bypassed the guards.
 
+## Role Hierarchies & Cardinality Constraints
+
+v0.7.0 adds first-class support for ordered role tiers with upward override relations and singleton limits:
+
+```python
+from authz import Namespace, build_role_hierarchy, RelationTuple, CardinalityViolationError
+
+# Build 5-tier role relations with downward inheritance and override_<role> relations
+roles = build_role_hierarchy([
+    "org_admin",
+    "org_manager",
+    "tpa_coordinator",
+    "org_user",
+    "diagnostic_billing_staff",
+])
+
+# Enforce singleton constraint: an organization can have at most ONE org_admin
+org_ns = Namespace("org", roles, singleton_relations={"org_admin"})
+client.register_schema(org_ns)
+
+# Alice is assigned org_admin -> inherits org_manager, tpa_coordinator, etc.
+await client.write([RelationTuple("org", "acme", "org_admin", "user:alice")])
+assert await client.check("user:alice", "org_user", "org:acme") is True
+
+# Bob cannot also be assigned org_admin on the same org
+try:
+    await client.write([RelationTuple("org", "acme", "org_admin", "user:bob")])
+except CardinalityViolationError as e:
+    print(f"Singleton violation: {e}")
+```
+
 ## FastAPI Integration Example
 
 A route needs one thing from an authorization library: block the request

python_authz-0.7.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+authz/__init__.py,sha256=yGOq69ryEECmnSAVOgvGC5f5E2oLs6Xr2Z3TgkqBTFw,1565
+authz/conditions.py,sha256=3MxE524bsdwjkCR-9yTyri_OstWpsHFFrjNr9n5cQQ4,3449
+authz/engine.py,sha256=TcJycywjSXN5zcMn-WKt0IXpAD00VdkSlUQf52AVo8c,23995
+authz/errors.py,sha256=gzYBGjnn7bSU81S-13LMVVTBBmDeCVzTykM0QUtppSw,2388
+authz/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authz/integrations/fastapi.py,sha256=PR0RLH0Xs5vg9c2ZZJXKh0N8nBTyNjPj4I0DLQejk8U,2749
+authz/schema.py,sha256=WBRMhEE63l7fXZBfNO-_1lvcTeP8urgekImOcqqrywg,5068
+authz/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authz/storage/base.py,sha256=I0My-ByzNnVjH_UH37YnRfVQl8_EtCurA-UtJfcviL8,723
+authz/storage/postgres.py,sha256=x_9OxEKkD1Glp-luaFfHWzq4KQfc-H92z2ggBOOCgR8,6595
+authz/storage/sqlite.py,sha256=Ua4vWSvsOtbfdEEv4UDfB8NVJaaZ4T9dKU3DkmUi6Cc,5248
+authz/tuples.py,sha256=NR4WpFxMj_9u2bPMyrVC8ajxbqoMUGLYIq3Rt8HZmM0,2005
+python_authz-0.7.0.dist-info/licenses/LICENSE,sha256=1e3AR9C0E8RKy14RPFwHKLoYHryFj4Gwiio0vyQtDVQ,1069
+python_authz-0.7.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+python_authz-0.7.0.dist-info/entry_points.txt,sha256=74k2ityJQ4AAFVFhVZddedlmWS4P4ZLAqrj8XTMD9Nk,38
+python_authz-0.7.0.dist-info/METADATA,sha256=spvE3nRZRDIzTz-p5Q5vXB2bc63wNl6yTs1pZRmvPfQ,8585
+python_authz-0.7.0.dist-info/RECORD,,

{python_authz-0.5.0.dist-info → python_authz-0.7.0.dist-info}/WHEEL

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

python_authz-0.5.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-authz/__init__.py,sha256=X_-rK75ArWRx48dc7MMa9pHUua-S8_n-bCPfahOews0,1310
-authz/conditions.py,sha256=5_LPWmtLQtf7S6wwSq0sp7ndJYHWvSmv3CsDNZCktmM,1128
-authz/engine.py,sha256=x2jQmWLBh51DLKFxEs2b2N3G1T1Rtq7lBE3Q7roUDas,11137
-authz/errors.py,sha256=6DXssJp_KvCWY-DwKEtS4gnHXBl4Tbg1io84eLhL-SQ,1522
-authz/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-authz/integrations/fastapi.py,sha256=SB3IAQ1yQDyAh5NW9hFfXx_psBWFZ7HSABJ5FJ7iYew,1091
-authz/schema.py,sha256=ALRdTg2CuUa7mjwN30zgAN3V2iYPUMq6ICv6IppUUeg,3118
-authz/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-authz/storage/base.py,sha256=I0My-ByzNnVjH_UH37YnRfVQl8_EtCurA-UtJfcviL8,723
-authz/storage/postgres.py,sha256=x_9OxEKkD1Glp-luaFfHWzq4KQfc-H92z2ggBOOCgR8,6595
-authz/storage/sqlite.py,sha256=Ua4vWSvsOtbfdEEv4UDfB8NVJaaZ4T9dKU3DkmUi6Cc,5248
-authz/tuples.py,sha256=NR4WpFxMj_9u2bPMyrVC8ajxbqoMUGLYIq3Rt8HZmM0,2005
-python_authz-0.5.0.dist-info/licenses/LICENSE,sha256=1e3AR9C0E8RKy14RPFwHKLoYHryFj4Gwiio0vyQtDVQ,1069
-python_authz-0.5.0.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
-python_authz-0.5.0.dist-info/entry_points.txt,sha256=74k2ityJQ4AAFVFhVZddedlmWS4P4ZLAqrj8XTMD9Nk,38
-python_authz-0.5.0.dist-info/METADATA,sha256=MswIj_E9TjAb5UvhxRAA2nj1ZDW3T9jNZhgd5TTvlSo,6287
-python_authz-0.5.0.dist-info/RECORD,,