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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-authz
-Version: 0.7.0
+Version: 0.8.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>
@@ -14,15 +14,16 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: duckdb>=1.5.5
+Classifier: Typing :: Typed
 Requires-Dist: aiosqlite>=0.21.0
-Requires-Dist: asyncpg>=0.31.0
-Requires-Dist: fastapi[all]>=0.141.1 ; extra == 'fastapi'
+Requires-Dist: fastapi>=0.141.1 ; extra == 'fastapi'
+Requires-Dist: asyncpg>=0.31.0 ; extra == 'postgres'
 Requires-Python: >=3.11
-Project-URL: Homepage, https://github.com/mapuna/python-authz
-Project-URL: Repository, https://github.com/mapuna/python-authz
-Project-URL: Issues, https://github.com/mapuna/python-authz/issues
+Project-URL: Homepage, https://github.com/tensor-forge-ai/python-authz
+Project-URL: Repository, https://github.com/tensor-forge-ai/python-authz
+Project-URL: Issues, https://github.com/tensor-forge-ai/python-authz/issues
 Provides-Extra: fastapi
+Provides-Extra: postgres
 Description-Content-Type: text/markdown
 
 # authz
@@ -53,17 +54,18 @@ kept in agreement with each other.
 
 ## Status
 
-Release, version 0.7.0:
+Release, version 0.8.0, a security release. [`docs/security.md`](docs/security.md) analyses the library end to end and records what changed; [`CHANGELOG.md`](CHANGELOG.md) lists the upgrade notes. The library provides:
 
-- **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.
+- **Unified ReBAC + RBAC + ABAC**: Zanzibar-style relationship graphs with conditions evaluated against stored policy and request context. Stored context takes precedence.
+- **Three-Valued Conditions**: a condition may return `None` when its context is missing or invalid; rewrite rules combine `True`, `False`, and `None` with Kleene logic, and a check allows only on `True`, so missing context never grants access, even under `Exclusion`.
+- **Bounded Evaluation**: per-check memoization, `max_depth`, and an evaluation budget (`max_evaluations`) for `check()` and `expand()`.
+- **Singleton and Cardinality Constraints**: `singleton_relations` and `max_subjects` on `Namespace`, enforced under storage locks so concurrent writers cannot exceed them.
+- **Declarative Role Hierarchies**: `build_role_hierarchy(roles_high_to_low, extra_relations=...)` with transitive downward inheritance and `override_<role>` relations.
+- **Audit and Explanation**: `Client.explain()` returns an `EvaluationDecision` with the visited relations, matched tuples, condition results, and a reason.
+- **Batch Evaluation and Introspection**: `check_batch()`, `list_permissions()`, and `list_objects()`.
+- **Built-in Conditions**: `max_amount`, `min_amount`, `equals_attr`, `in_set`, `jurisdiction_match`, `not_same_subject`, all fail-closed.
+- **FastAPI Integration**: `requires()` and `explain_access()`, with resource placeholders resolved from path parameters unless `resource_sources` enables query parameters or headers.
+- **Storage**: async SQLite and PostgreSQL backends with configurable table names and an option to connect without DDL privileges.
 
 ## Roadmap
 
@@ -73,13 +75,13 @@ Release, version 0.7.0:
 - JSON-Logic and CEL `ConditionEvaluator` implementations, alongside the
   existing Python-callable one
 - Java, Kotlin, Rust, and C++ SDKs
-- making `asyncpg`/`duckdb` and `pyjwt`/`httpx2` optional too, the way
-  `fastapi` already is
 
 ## Install
 
 ```bash
-uv add python-authz
+uv add python-authz                # core, with SQLite storage
+uv add "python-authz[postgres]"    # adds PostgresStorage (asyncpg)
+uv add "python-authz[fastapi]"     # adds authz.integrations.fastapi
 ```
 
 ## Quickstart
@@ -132,7 +134,7 @@ 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:
+Version 0.7.0 added first-class support for ordered role tiers with upward override relations and singleton limits:
 
 ```python
 from authz import Namespace, build_role_hierarchy, RelationTuple, CardinalityViolationError
@@ -193,9 +195,15 @@ caller receives a 403 automatically. See
 example, including how `get_client`/`get_subject` compose with your app's
 own database and auth setup.
 
+## Security
+
+Read [`docs/security.md`](docs/security.md) for the threat model, the findings fixed in 0.8.0, and the responsibilities that stay with the application. Report vulnerabilities privately as described in [`SECURITY.md`](SECURITY.md).
+
 ## Development
 
 ```bash
-uv sync --extra fastapi
+uv sync --all-extras
 uv run pytest
 ```
+
+The PostgreSQL tests use the server at `AUTHZ_TEST_POSTGRES_DSN` (a superuser DSN; the tests create and drop their own database), or start one with testcontainers when Docker is available, and are skipped otherwise.

{python_authz-0.7.0 → python_authz-0.8.0}/README.md

@@ -26,17 +26,18 @@ kept in agreement with each other.
 
 ## Status
 
-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.
+Release, version 0.8.0, a security release. [`docs/security.md`](docs/security.md) analyses the library end to end and records what changed; [`CHANGELOG.md`](CHANGELOG.md) lists the upgrade notes. The library provides:
+
+- **Unified ReBAC + RBAC + ABAC**: Zanzibar-style relationship graphs with conditions evaluated against stored policy and request context. Stored context takes precedence.
+- **Three-Valued Conditions**: a condition may return `None` when its context is missing or invalid; rewrite rules combine `True`, `False`, and `None` with Kleene logic, and a check allows only on `True`, so missing context never grants access, even under `Exclusion`.
+- **Bounded Evaluation**: per-check memoization, `max_depth`, and an evaluation budget (`max_evaluations`) for `check()` and `expand()`.
+- **Singleton and Cardinality Constraints**: `singleton_relations` and `max_subjects` on `Namespace`, enforced under storage locks so concurrent writers cannot exceed them.
+- **Declarative Role Hierarchies**: `build_role_hierarchy(roles_high_to_low, extra_relations=...)` with transitive downward inheritance and `override_<role>` relations.
+- **Audit and Explanation**: `Client.explain()` returns an `EvaluationDecision` with the visited relations, matched tuples, condition results, and a reason.
+- **Batch Evaluation and Introspection**: `check_batch()`, `list_permissions()`, and `list_objects()`.
+- **Built-in Conditions**: `max_amount`, `min_amount`, `equals_attr`, `in_set`, `jurisdiction_match`, `not_same_subject`, all fail-closed.
+- **FastAPI Integration**: `requires()` and `explain_access()`, with resource placeholders resolved from path parameters unless `resource_sources` enables query parameters or headers.
+- **Storage**: async SQLite and PostgreSQL backends with configurable table names and an option to connect without DDL privileges.
 
 ## Roadmap
 
@@ -46,13 +47,13 @@ Release, version 0.7.0:
 - JSON-Logic and CEL `ConditionEvaluator` implementations, alongside the
   existing Python-callable one
 - Java, Kotlin, Rust, and C++ SDKs
-- making `asyncpg`/`duckdb` and `pyjwt`/`httpx2` optional too, the way
-  `fastapi` already is
 
 ## Install
 
 ```bash
-uv add python-authz
+uv add python-authz                # core, with SQLite storage
+uv add "python-authz[postgres]"    # adds PostgresStorage (asyncpg)
+uv add "python-authz[fastapi]"     # adds authz.integrations.fastapi
 ```
 
 ## Quickstart
@@ -105,7 +106,7 @@ 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:
+Version 0.7.0 added first-class support for ordered role tiers with upward override relations and singleton limits:
 
 ```python
 from authz import Namespace, build_role_hierarchy, RelationTuple, CardinalityViolationError
@@ -166,9 +167,15 @@ caller receives a 403 automatically. See
 example, including how `get_client`/`get_subject` compose with your app's
 own database and auth setup.
 
+## Security
+
+Read [`docs/security.md`](docs/security.md) for the threat model, the findings fixed in 0.8.0, and the responsibilities that stay with the application. Report vulnerabilities privately as described in [`SECURITY.md`](SECURITY.md).
+
 ## Development
 
 ```bash
-uv sync --extra fastapi
+uv sync --all-extras
 uv run pytest
 ```
+
+The PostgreSQL tests use the server at `AUTHZ_TEST_POSTGRES_DSN` (a superuser DSN; the tests create and drop their own database), or start one with testcontainers when Docker is available, and are skipped otherwise.

{python_authz-0.7.0 → python_authz-0.8.0}/pyproject.toml

@@ -1,16 +1,12 @@
 [project]
 name = "python-authz"
-version = "0.7.0"
+version = "0.8.0"
 description = "A framework-agnostic ReBAC/RBAC/ABAC authorization engine built on one Zanzibar-style relationship graph"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.11"
-dependencies = [
-    "duckdb>=1.5.5",
-    "aiosqlite>=0.21.0",
-    "asyncpg>=0.31.0",
-]
+dependencies = ["aiosqlite>=0.21.0"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -20,6 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 
 [[project.authors]]
@@ -27,22 +24,23 @@ name = "Anupam Gupta"
 email = "anupam@trois.in"
 
 [project.urls]
-Homepage = "https://github.com/mapuna/python-authz"
-Repository = "https://github.com/mapuna/python-authz"
-Issues = "https://github.com/mapuna/python-authz/issues"
+Homepage = "https://github.com/tensor-forge-ai/python-authz"
+Repository = "https://github.com/tensor-forge-ai/python-authz"
+Issues = "https://github.com/tensor-forge-ai/python-authz/issues"
 
 [project.optional-dependencies]
-fastapi = ["fastapi[all]>=0.141.1"]
-
-[project.scripts]
-authz = "authz:main"
+fastapi = ["fastapi>=0.141.1"]
+postgres = ["asyncpg>=0.31.0"]
 
 [dependency-groups]
 dev = [
+    "asyncpg>=0.31.0",
+    "fastapi>=0.141.1",
     "httpx2>=2.12.0",
     "pyjwt>=2.13.0",
     "pytest>=8.3.0",
     "pytest-asyncio>=0.24.0",
+    "python-multipart>=0.0.20",
     "testcontainers[postgres]>=4.15.0",
 ]
 

{python_authz-0.7.0 → python_authz-0.8.0}/pyproject.toml.orig

@@ -1,13 +1,13 @@
 [project]
 name = "python-authz"
-version = "0.7.0"
+version = "0.8.0"
 description = "A framework-agnostic ReBAC/RBAC/ABAC authorization engine built on one Zanzibar-style relationship graph"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Anupam Gupta", email = "anupam@trois.in" }]
 requires-python = ">=3.11"
-dependencies = ["duckdb>=1.5.5", "aiosqlite>=0.21.0", "asyncpg>=0.31.0"]
+dependencies = ["aiosqlite>=0.21.0"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -17,28 +17,30 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 
 [project.urls]
-Homepage = "https://github.com/mapuna/python-authz"
-Repository = "https://github.com/mapuna/python-authz"
-Issues = "https://github.com/mapuna/python-authz/issues"
+Homepage = "https://github.com/tensor-forge-ai/python-authz"
+Repository = "https://github.com/tensor-forge-ai/python-authz"
+Issues = "https://github.com/tensor-forge-ai/python-authz/issues"
 
 [project.optional-dependencies]
-fastapi = ["fastapi[all]>=0.141.1"]
+fastapi = ["fastapi>=0.141.1"]
+postgres = ["asyncpg>=0.31.0"]
 
 [dependency-groups]
 dev = [
+    "asyncpg>=0.31.0",
+    "fastapi>=0.141.1",
     "httpx2>=2.12.0",
     "pyjwt>=2.13.0",
     "pytest>=8.3.0",
     "pytest-asyncio>=0.24.0",
+    "python-multipart>=0.0.20",
     "testcontainers[postgres]>=4.15.0",
 ]
 
-[project.scripts]
-authz = "authz:main"
-
 [tool.uv.build-backend]
 module-name = "authz"
 

{python_authz-0.7.0 → python_authz-0.8.0}/src/authz/__init__.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING, Any
+
 from authz.conditions import (
     ConditionEvaluator,
     PythonCallableEvaluator,
@@ -10,6 +12,7 @@ from authz.errors import (
     ConditionNotFound,
     CycleDetected,
     DepthLimitExceeded,
+    EvaluationBudgetExceeded,
     NamespaceNotFound,
     RelationNotFound,
     SchemaCycleDetected,
@@ -27,10 +30,12 @@ from authz.schema import (
     build_role_hierarchy,
 )
 from authz.storage.base import Storage, Token
-from authz.storage.postgres import PostgresStorage
 from authz.storage.sqlite import SqliteStorage
 from authz.tuples import Condition, ObjectRef, RelationTuple, SubjectRef
 
+if TYPE_CHECKING:
+    from authz.storage.postgres import PostgresStorage
+
 __all__ = [
     "AuthError",
     "CardinalityViolationError",
@@ -42,6 +47,7 @@ __all__ = [
     "CycleDetected",
     "DepthLimitExceeded",
     "Direct",
+    "EvaluationBudgetExceeded",
     "EvaluationDecision",
     "Exclusion",
     "From",
@@ -49,7 +55,6 @@ __all__ = [
     "Namespace",
     "NamespaceNotFound",
     "ObjectRef",
-    "PostgresStorage",
     "PythonCallableEvaluator",
     "RelationNotFound",
     "RelationTuple",
@@ -68,5 +73,14 @@ __all__ = [
 ]
 
 
-def main() -> None:
-    print("Hello from authz!")
+def __getattr__(name: str) -> Any:
+    if name == "PostgresStorage":
+        try:
+            from authz.storage.postgres import PostgresStorage
+        except ImportError as exc:
+            raise ImportError(
+                "PostgresStorage requires asyncpg; install it with "
+                "'pip install python-authz[postgres]'"
+            ) from exc
+        return PostgresStorage
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

python_authz-0.8.0/src/authz/conditions.py

@@ -0,0 +1,159 @@
+import inspect
+import math
+from typing import Any, Awaitable, Callable, Mapping, Protocol, Union
+
+from authz.errors import ConditionNotFound
+
+ConditionResult = Union[bool, None]
+ConditionFn = Callable[..., Union[ConditionResult, Awaitable[ConditionResult]]]
+
+_RESERVED_KEYS = frozenset({"subject", "resource"})
+
+
+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 | None: ...  # None: required context missing or invalid
+
+
+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 | None:
+        try:
+            fn = self._conditions[name]
+        except KeyError:
+            raise ConditionNotFound(name) from None
+        for key in context:
+            if not isinstance(key, str):
+                raise ValueError(
+                    f"condition {name!r}: context keys must be strings, got {key!r}"
+                )
+            if key in _RESERVED_KEYS:
+                raise ValueError(
+                    f"condition {name!r}: context key {key!r} is reserved"
+                )
+        result = fn(subject=subject, resource=resource, **context)
+        if inspect.isawaitable(result):
+            result = await result
+        if result is None or isinstance(result, bool):
+            return result
+        raise TypeError(
+            f"condition {name!r} must return True, False or None, "
+            f"got {type(result).__name__}"
+        )
+
+
+def _number(value: Any) -> float | None:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        number = float(value)
+    except (ValueError, TypeError, OverflowError):
+        return None
+    return number if math.isfinite(number) else None
+
+
+def _collection(value: Any) -> Any:
+    return value if isinstance(value, (list, tuple, set, frozenset)) else None
+
+
+def _attribute(ctx: Mapping[str, Any]) -> Any:
+    name = ctx.get("attribute")
+    if not isinstance(name, str) or not name:
+        return None
+    return ctx.get(name)
+
+
+def _member(value: Any, allowed: Any) -> bool | None:
+    try:
+        return value in allowed
+    except TypeError:
+        return None
+
+
+def _max_amount(*, subject: str, resource: str, **ctx: Any) -> bool | None:
+    amount, limit = _number(ctx.get("amount")), _number(ctx.get("max_amount"))
+    if amount is None or limit is None:
+        return None
+    return amount <= limit
+
+
+def _min_amount(*, subject: str, resource: str, **ctx: Any) -> bool | None:
+    amount, limit = _number(ctx.get("amount")), _number(ctx.get("min_amount"))
+    if amount is None or limit is None:
+        return None
+    return amount >= limit
+
+
+def _equals_attr(*, subject: str, resource: str, **ctx: Any) -> bool | None:
+    actual, expected = _attribute(ctx), ctx.get("expected")
+    if actual is None or expected is None:
+        return None
+    return actual == expected
+
+
+def _in_set(*, subject: str, resource: str, **ctx: Any) -> bool | None:
+    actual, allowed = _attribute(ctx), _collection(ctx.get("allowed_values"))
+    if actual is None or allowed is None:
+        return None
+    return _member(actual, allowed)
+
+
+def _jurisdiction_match(*, subject: str, resource: str, **ctx: Any) -> bool | None:
+    jurisdiction = ctx.get("jurisdiction")
+    if jurisdiction is None:
+        return None
+    allowed, required = ctx.get("allowed_jurisdictions"), ctx.get("required_jurisdiction")
+    if allowed is None and required is None:
+        return None
+    results = []
+    if allowed is not None:
+        allowed = _collection(allowed)
+        results.append(None if allowed is None else _member(jurisdiction, allowed))
+    if required is not None:
+        results.append(jurisdiction == required)
+    if False in results:
+        return False
+    return None if None in results else True
+
+
+def _not_same_subject(*, subject: str, resource: str, **ctx: Any) -> bool | None:
+    excluded = ctx.get("excluded_subject")
+    if not isinstance(excluded, str) or not excluded:
+        return None
+    return subject != excluded
+
+
+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,
+    }