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

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

@@ -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.5.0 → python_authz-0.7.0}/README.md

@@ -26,13 +26,17 @@ 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.7.0:
+
+- **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
 
@@ -99,6 +103,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.5.0 → python_authz-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-authz"
-version = "0.5.0"
+version = "0.7.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.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-authz"
-version = "0.5.0"
+version = "0.7.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.7.0}/src/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",
 ]
 
 

python_authz-0.7.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,
+    }