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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-authz
-Version: 0.6.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,8 +53,10 @@ kept in agreement with each other.
 
 ## Status
 
-Release, version 0.6.0:
+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.
@@ -128,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.6.0 → python_authz-0.7.0}/README.md

@@ -26,8 +26,10 @@ kept in agreement with each other.
 
 ## Status
 
-Release, version 0.6.0:
+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.
@@ -101,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.6.0 → python_authz-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-authz"
-version = "0.6.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.6.0 → python_authz-0.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-authz"
-version = "0.6.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.6.0 → python_authz-0.7.0}/src/authz/__init__.py

@@ -6,6 +6,7 @@ from authz.conditions import (
 from authz.engine import CheckItem, Client, EvaluationDecision, UsersetTree
 from authz.errors import (
     AuthError,
+    CardinalityViolationError,
     ConditionNotFound,
     CycleDetected,
     DepthLimitExceeded,
@@ -23,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
@@ -31,6 +33,7 @@ from authz.tuples import Condition, ObjectRef, RelationTuple, SubjectRef
 
 __all__ = [
     "AuthError",
+    "CardinalityViolationError",
     "CheckItem",
     "Client",
     "Condition",
@@ -60,6 +63,7 @@ __all__ = [
     "Union",
     "UsersetTree",
     "WouldCreateCycle",
+    "build_role_hierarchy",
     "builtin_conditions",
 ]
 

{python_authz-0.6.0 → python_authz-0.7.0}/src/authz/engine.py

@@ -4,6 +4,7 @@ from typing import Any, Mapping, Sequence
 
 from authz.conditions import ConditionEvaluator, ConditionFn
 from authz.errors import (
+    CardinalityViolationError,
     ConditionNotFound,
     CycleDetected,
     DepthLimitExceeded,
@@ -147,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)

{python_authz-0.6.0 → python_authz-0.7.0}/src/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}"
+        )

{python_authz-0.6.0 → python_authz-0.7.0}/src/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]: