python-authz 0.5.0__py3-none-any.whl

authz/__init__.py

@@ -0,0 +1,61 @@
+from authz.conditions import ConditionEvaluator, PythonCallableEvaluator
+from authz.engine import Client, UsersetTree
+from authz.errors import (
+    AuthError,
+    ConditionNotFound,
+    CycleDetected,
+    DepthLimitExceeded,
+    NamespaceNotFound,
+    RelationNotFound,
+    SchemaCycleDetected,
+    WouldCreateCycle,
+)
+from authz.schema import (
+    Direct,
+    Exclusion,
+    From,
+    Intersection,
+    Namespace,
+    RewriteRule,
+    TupleToUserset,
+    Union,
+)
+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
+
+__all__ = [
+    "AuthError",
+    "Client",
+    "Condition",
+    "ConditionEvaluator",
+    "ConditionNotFound",
+    "CycleDetected",
+    "DepthLimitExceeded",
+    "Direct",
+    "Exclusion",
+    "From",
+    "Intersection",
+    "Namespace",
+    "NamespaceNotFound",
+    "ObjectRef",
+    "PostgresStorage",
+    "PythonCallableEvaluator",
+    "RelationNotFound",
+    "RelationTuple",
+    "RewriteRule",
+    "SchemaCycleDetected",
+    "SqliteStorage",
+    "Storage",
+    "SubjectRef",
+    "Token",
+    "TupleToUserset",
+    "Union",
+    "UsersetTree",
+    "WouldCreateCycle",
+]
+
+
+def main() -> None:
+    print("Hello from authz!")

authz/conditions.py

@@ -0,0 +1,37 @@
+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)

authz/engine.py

@@ -0,0 +1,297 @@
+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),
+        )

authz/errors.py

@@ -0,0 +1,50 @@
+class AuthError(Exception):
+    """Base class for all authz errors."""
+
+
+class NamespaceNotFound(AuthError):
+    def __init__(self, namespace: str):
+        super().__init__(f"namespace {namespace!r} is not registered")
+        self.namespace = namespace
+
+
+class RelationNotFound(AuthError):
+    def __init__(self, namespace: str, relation: str):
+        super().__init__(
+            f"relation {relation!r} is not defined on namespace {namespace!r}"
+        )
+        self.namespace = namespace
+        self.relation = relation
+
+
+class ConditionNotFound(AuthError):
+    def __init__(self, name: str):
+        super().__init__(f"condition {name!r} is not registered")
+        self.name = name
+
+
+class SchemaCycleDetected(AuthError):
+    def __init__(self, namespace: str, path: list[str]):
+        super().__init__(
+            f"schema cycle in namespace {namespace!r}: {' -> '.join(path)}"
+        )
+        self.namespace = namespace
+        self.path = path
+
+
+class WouldCreateCycle(AuthError):
+    def __init__(self, tuple_, description: str):
+        super().__init__(f"writing {tuple_} would create a cycle: {description}")
+        self.tuple = tuple_
+
+
+class CycleDetected(AuthError):
+    def __init__(self, path: list[str]):
+        super().__init__(f"cycle detected during check: {' -> '.join(path)}")
+        self.path = path
+
+
+class DepthLimitExceeded(AuthError):
+    def __init__(self, max_depth: int):
+        super().__init__(f"recursion exceeded max_depth={max_depth}")
+        self.max_depth = max_depth

authz/integrations/fastapi.py

@@ -0,0 +1,37 @@
+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

authz/schema.py

@@ -0,0 +1,109 @@
+from typing import Iterator
+
+from authz.errors import SchemaCycleDetected
+
+
+class RewriteRule:
+    """Base class for relation-rewrite expressions."""
+
+
+class Direct(RewriteRule):
+    def __repr__(self) -> str:
+        return "Direct()"
+
+
+class Union(RewriteRule):
+    def __init__(self, *children: RewriteRule):
+        self.children = children
+
+    def __repr__(self) -> str:
+        return f"Union{self.children!r}"
+
+
+class Intersection(RewriteRule):
+    def __init__(self, *children: RewriteRule):
+        self.children = children
+
+    def __repr__(self) -> str:
+        return f"Intersection{self.children!r}"
+
+
+class Exclusion(RewriteRule):
+    def __init__(self, base: RewriteRule, subtract: RewriteRule):
+        self.base = base
+        self.subtract = subtract
+
+    def __repr__(self) -> str:
+        return f"Exclusion({self.base!r}, {self.subtract!r})"
+
+
+class From(RewriteRule):
+    def __init__(self, relation: str):
+        self.relation = relation
+
+    def __repr__(self) -> str:
+        return f"From({self.relation!r})"
+
+
+class TupleToUserset(RewriteRule):
+    def __init__(self, tupleset_relation: str, computed_relation: str):
+        self.tupleset_relation = tupleset_relation
+        self.computed_relation = computed_relation
+
+    def __repr__(self) -> str:
+        return f"TupleToUserset({self.tupleset_relation!r}, {self.computed_relation!r})"
+
+
+class Namespace:
+    def __init__(self, name: str, relations: dict[str, RewriteRule]):
+        self.name = name
+        self.relations = relations
+
+
+def _from_edges(rule: RewriteRule) -> Iterator[str]:
+    if isinstance(rule, From):
+        yield rule.relation
+    elif isinstance(rule, (Union, Intersection)):
+        for child in rule.children:
+            yield from _from_edges(child)
+    elif isinstance(rule, Exclusion):
+        yield from _from_edges(rule.base)
+        yield from _from_edges(rule.subtract)
+
+
+def check_schema_cycles(namespace: Namespace) -> None:
+    graph: dict[str, list[str]] = {
+        relation: list(_from_edges(rule))
+        for relation, rule in namespace.relations.items()
+    }
+
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def dfs(relation: str, path: list[str]) -> None:
+        if relation in visiting:
+            raise SchemaCycleDetected(namespace.name, path + [relation])
+        if relation in visited or relation not in graph:
+            return
+        visiting.add(relation)
+        for neighbor in graph[relation]:
+            dfs(neighbor, path + [relation])
+        visiting.discard(relation)
+        visited.add(relation)
+
+    for relation in graph:
+        if relation not in visited:
+            dfs(relation, [])
+
+
+def tupleset_relations(rule: RewriteRule) -> set[str]:
+    if isinstance(rule, TupleToUserset):
+        return {rule.tupleset_relation}
+    if isinstance(rule, (Union, Intersection)):
+        result: set[str] = set()
+        for child in rule.children:
+            result |= tupleset_relations(child)
+        return result
+    if isinstance(rule, Exclusion):
+        return tupleset_relations(rule.base) | tupleset_relations(rule.subtract)
+    return set()

authz/storage/base.py

@@ -0,0 +1,26 @@
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol, Sequence
+
+from authz.tuples import RelationTuple
+
+Token = str
+
+
+class Storage(Protocol):
+    async def write_tuples(self, tuples: Sequence[RelationTuple]) -> Token: ...
+
+    async def delete_tuples(self, tuples: Sequence[RelationTuple]) -> Token: ...
+
+    async def read_tuples(
+        self,
+        namespace: str,
+        object_id: str | None = None,
+        relation: str | None = None,
+        subject: str | None = None,
+    ) -> list[RelationTuple]: ...
+
+    async def current_token(self) -> Token: ...
+
+    async def wait_for_token(self, token: Token) -> None: ...
+
+    def transaction(self) -> AbstractAsyncContextManager[None]: ...

authz/storage/postgres.py

@@ -0,0 +1,184 @@
+import json
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import Sequence
+
+import asyncpg
+
+from authz.storage.base import Token
+from authz.tuples import Condition, RelationTuple
+
+_active_conn: ContextVar[asyncpg.Connection | None] = ContextVar(
+    "_active_conn", default=None
+)
+
+_SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS tuples (
+    change_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    namespace TEXT NOT NULL,
+    object_id TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    condition_name TEXT,
+    condition_context JSONB,
+    UNIQUE(namespace, object_id, relation, subject)
+);
+CREATE INDEX IF NOT EXISTS idx_tuples_forward
+    ON tuples(namespace, object_id, relation);
+CREATE INDEX IF NOT EXISTS idx_tuples_reverse
+    ON tuples(namespace, subject);
+"""
+
+_UPSERT_SQL = """
+INSERT INTO tuples (namespace, object_id, relation, subject, condition_name, condition_context)
+VALUES ($1, $2, $3, $4, $5, $6)
+ON CONFLICT (namespace, object_id, relation, subject) DO UPDATE SET
+    condition_name = excluded.condition_name,
+    condition_context = excluded.condition_context
+"""
+
+_DELETE_SQL = """
+DELETE FROM tuples WHERE namespace = $1 AND object_id = $2 AND relation = $3 AND subject = $4
+"""
+
+
+def _row_to_tuple(row) -> RelationTuple:
+    condition = None
+    if row["condition_name"] is not None:
+        context = json.loads(row["condition_context"]) if row["condition_context"] else {}
+        condition = Condition(row["condition_name"], context)
+    return RelationTuple(
+        row["namespace"], row["object_id"], row["relation"], row["subject"],
+        condition=condition,
+    )
+
+
+class PostgresStorage:
+    def __init__(self, dsn: str, *, min_size: int = 1, max_size: int = 10):
+        self._dsn = dsn
+        self._min_size = min_size
+        self._max_size = max_size
+        self._pool: asyncpg.Pool | None = None
+
+    async def connect(self) -> None:
+        self._pool = await asyncpg.create_pool(
+            self._dsn, min_size=self._min_size, max_size=self._max_size
+        )
+        async with self._pool.acquire() as conn:
+            await conn.execute(_SCHEMA_SQL)
+
+    async def close(self) -> None:
+        if self._pool is not None:
+            await self._pool.close()
+            self._pool = None
+
+    async def __aenter__(self) -> "PostgresStorage":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self.close()
+
+    async def _connection(self) -> tuple[asyncpg.Connection, bool]:
+        conn = _active_conn.get()
+        if conn is not None:
+            return conn, False
+        return await self._pool.acquire(), True
+
+    @asynccontextmanager
+    async def transaction(self):
+        if _active_conn.get() is not None:
+            yield
+            return
+        async with self._pool.acquire() as conn:
+            token = _active_conn.set(conn)
+            try:
+                async with conn.transaction():
+                    yield
+            finally:
+                _active_conn.reset(token)
+
+    async def write_tuples(self, tuples: Sequence[RelationTuple]) -> Token:
+        async with self.transaction():
+            conn, must_release = await self._connection()
+            try:
+                for t in tuples:
+                    condition_name = t.condition.name if t.condition else None
+                    condition_context = (
+                        json.dumps(dict(t.condition.context)) if t.condition else None
+                    )
+                    await conn.execute(
+                        _UPSERT_SQL,
+                        t.namespace, t.object_id, t.relation, t.subject,
+                        condition_name, condition_context,
+                    )
+            finally:
+                if must_release:
+                    await self._pool.release(conn)
+        return await self.current_token()
+
+    async def delete_tuples(self, tuples: Sequence[RelationTuple]) -> Token:
+        async with self.transaction():
+            conn, must_release = await self._connection()
+            try:
+                for t in tuples:
+                    await conn.execute(
+                        _DELETE_SQL, t.namespace, t.object_id, t.relation, t.subject
+                    )
+            finally:
+                if must_release:
+                    await self._pool.release(conn)
+        return await self.current_token()
+
+    async def read_tuples(
+        self,
+        namespace: str,
+        object_id: str | None = None,
+        relation: str | None = None,
+        subject: str | None = None,
+    ) -> list[RelationTuple]:
+        conn, must_release = await self._connection()
+        try:
+            query = (
+                "SELECT namespace, object_id, relation, subject, condition_name, "
+                "condition_context FROM tuples WHERE namespace = $1"
+            )
+            params: list[str] = [namespace]
+            if object_id is not None:
+                params.append(object_id)
+                query += f" AND object_id = ${len(params)}"
+            if relation is not None:
+                params.append(relation)
+                query += f" AND relation = ${len(params)}"
+            if subject is not None:
+                params.append(subject)
+                query += f" AND subject = ${len(params)}"
+            rows = await conn.fetch(query, *params)
+            return [_row_to_tuple(row) for row in rows]
+        finally:
+            if must_release:
+                await self._pool.release(conn)
+
+    async def current_token(self) -> Token:
+        conn, must_release = await self._connection()
+        try:
+            # last_value alone is misleading: Postgres pre-seeds a freshly
+            # created (or RESTART IDENTITY-reset) sequence's last_value to
+            # its start value even before anything has actually consumed
+            # it. is_called distinguishes "really advanced" from "just
+            # initialized" -- only count it once nextval() has actually run.
+            value = await conn.fetchval(
+                "SELECT CASE WHEN is_called THEN last_value ELSE 0 END "
+                "FROM tuples_change_id_seq"
+            )
+            return str(value)
+        finally:
+            if must_release:
+                await self._pool.release(conn)
+
+    async def wait_for_token(self, token: Token) -> None:
+        current = await self.current_token()
+        if int(current) < int(token):
+            raise RuntimeError(
+                f"storage is behind token {token!r} (current: {current!r})"
+            )

authz/storage/sqlite.py

@@ -0,0 +1,154 @@
+import json
+from contextlib import asynccontextmanager
+from typing import Sequence
+
+import aiosqlite
+
+from authz.storage.base import Token
+from authz.tuples import Condition, RelationTuple
+
+_SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS tuples (
+    change_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    namespace TEXT NOT NULL,
+    object_id TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    condition_name TEXT,
+    condition_context TEXT,
+    UNIQUE(namespace, object_id, relation, subject)
+);
+CREATE INDEX IF NOT EXISTS idx_tuples_forward
+    ON tuples(namespace, object_id, relation);
+CREATE INDEX IF NOT EXISTS idx_tuples_reverse
+    ON tuples(namespace, subject);
+"""
+
+_UPSERT_SQL = """
+INSERT INTO tuples (namespace, object_id, relation, subject, condition_name, condition_context)
+VALUES (?, ?, ?, ?, ?, ?)
+ON CONFLICT(namespace, object_id, relation, subject) DO UPDATE SET
+    condition_name = excluded.condition_name,
+    condition_context = excluded.condition_context
+"""
+
+_DELETE_SQL = """
+DELETE FROM tuples WHERE namespace = ? AND object_id = ? AND relation = ? AND subject = ?
+"""
+
+
+def _row_to_tuple(row: tuple) -> RelationTuple:
+    namespace, object_id, relation, subject, condition_name, condition_context = row
+    condition = None
+    if condition_name is not None:
+        condition = Condition(condition_name, json.loads(condition_context or "{}"))
+    return RelationTuple(namespace, object_id, relation, subject, condition=condition)
+
+
+class SqliteStorage:
+    def __init__(self, path: str):
+        self._path = path
+        self._conn: aiosqlite.Connection | None = None
+        self._in_transaction = False
+
+    async def connect(self) -> None:
+        self._conn = await aiosqlite.connect(self._path)
+        await self._conn.executescript(_SCHEMA_SQL)
+        await self._conn.commit()
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+
+    async def __aenter__(self) -> "SqliteStorage":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self.close()
+
+    @asynccontextmanager
+    async def transaction(self):
+        if self._in_transaction:
+            yield
+            return
+        self._in_transaction = True
+        try:
+            yield
+            await self._conn.commit()
+        except Exception:
+            await self._conn.rollback()
+            raise
+        finally:
+            self._in_transaction = False
+
+    async def write_tuples(self, tuples: Sequence[RelationTuple]) -> Token:
+        async with self.transaction():
+            for t in tuples:
+                condition_name = t.condition.name if t.condition else None
+                condition_context = (
+                    json.dumps(dict(t.condition.context)) if t.condition else None
+                )
+                await self._conn.execute(
+                    _UPSERT_SQL,
+                    (
+                        t.namespace,
+                        t.object_id,
+                        t.relation,
+                        t.subject,
+                        condition_name,
+                        condition_context,
+                    ),
+                )
+        return await self.current_token()
+
+    async def delete_tuples(self, tuples: Sequence[RelationTuple]) -> Token:
+        async with self.transaction():
+            for t in tuples:
+                await self._conn.execute(
+                    _DELETE_SQL, (t.namespace, t.object_id, t.relation, t.subject)
+                )
+        return await self.current_token()
+
+    async def read_tuples(
+        self,
+        namespace: str,
+        object_id: str | None = None,
+        relation: str | None = None,
+        subject: str | None = None,
+    ) -> list[RelationTuple]:
+        query = (
+            "SELECT namespace, object_id, relation, subject, condition_name, "
+            "condition_context FROM tuples WHERE namespace = ?"
+        )
+        params: list[str] = [namespace]
+        if object_id is not None:
+            query += " AND object_id = ?"
+            params.append(object_id)
+        if relation is not None:
+            query += " AND relation = ?"
+            params.append(relation)
+        if subject is not None:
+            query += " AND subject = ?"
+            params.append(subject)
+        async with self._conn.execute(query, params) as cursor:
+            rows = await cursor.fetchall()
+        return [_row_to_tuple(row) for row in rows]
+
+    async def current_token(self) -> Token:
+        # MAX(change_id) over the live table would go backwards after a
+        # delete empties it; sqlite_sequence tracks the AUTOINCREMENT
+        # high-water mark, which only ever increases.
+        async with self._conn.execute(
+            "SELECT seq FROM sqlite_sequence WHERE name = 'tuples'"
+        ) as cursor:
+            row = await cursor.fetchone()
+        return str(row[0] if row else 0)
+
+    async def wait_for_token(self, token: Token) -> None:
+        current = await self.current_token()
+        if int(current) < int(token):
+            raise RuntimeError(
+                f"storage is behind token {token!r} (current: {current!r})"
+            )

authz/tuples.py

@@ -0,0 +1,75 @@
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class ObjectRef:
+    namespace: str
+    object_id: str
+
+    def __str__(self) -> str:
+        return f"{self.namespace}:{self.object_id}"
+
+    @classmethod
+    def parse(cls, raw: str) -> "ObjectRef":
+        namespace, colon, object_id = raw.partition(":")
+        if not colon:
+            raise ValueError(
+                f"invalid object reference {raw!r}; expected 'namespace:object_id'"
+            )
+        return cls(namespace, object_id)
+
+
+@dataclass(frozen=True)
+class SubjectRef:
+    namespace: str
+    object_id: str
+    relation: str | None = None
+
+    @property
+    def is_userset(self) -> bool:
+        return self.relation is not None
+
+    def __str__(self) -> str:
+        base = f"{self.namespace}:{self.object_id}"
+        return f"{base}#{self.relation}" if self.relation else base
+
+    @classmethod
+    def parse(cls, raw: str) -> "SubjectRef":
+        obj_part, sep, relation = raw.partition("#")
+        namespace, colon, object_id = obj_part.partition(":")
+        if not colon:
+            raise ValueError(
+                f"invalid subject reference {raw!r}; expected 'namespace:object_id' "
+                "or 'namespace:object_id#relation'"
+            )
+        return cls(namespace, object_id, relation if sep else None)
+
+
+@dataclass(frozen=True)
+class Condition:
+    name: str
+    context: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RelationTuple:
+    namespace: str
+    object_id: str
+    relation: str
+    subject: str
+    condition: Condition | None = None
+
+    @property
+    def object(self) -> ObjectRef:
+        return ObjectRef(self.namespace, self.object_id)
+
+    @property
+    def subject_ref(self) -> SubjectRef:
+        return SubjectRef.parse(self.subject)
+
+    def __str__(self) -> str:
+        return (
+            f"({self.namespace}, {self.object_id!r}, "
+            f"{self.relation!r}, {self.subject!r})"
+        )

python_authz-0.5.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: python-authz
+Version: 0.5.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>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+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
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: fastapi[all]>=0.141.1 ; extra == 'fastapi'
+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
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# authz
+
+A framework-agnostic ReBAC/RBAC/ABAC authorization engine.
+
+## About
+
+Most systems end up with three separate authorization mechanisms: roles
+for admin/editor/viewer distinctions (RBAC), attribute rules for things
+like "only during business hours" (ABAC), and some hand-rolled traversal
+for hierarchies like folders or nested groups (ReBAC). `authz` implements
+all three on one data structure instead: a graph of relationship facts,
+each one a `(namespace, object, relation, subject)` tuple, in the style
+of Google's Zanzibar paper.
+
+A role is just a relation on an object, so "alice is an editor of
+document:roadmap" is a tuple like any other. A folder hierarchy is a
+traversal between tuples: "you can view a document if you can view its
+parent folder" is one rule, applied uniformly no matter how deep the
+folder tree goes. An attribute check is a condition attached to a
+specific tuple, evaluated against the current subject and context at
+check time. Because all three live in the same graph, a single `check()`
+call can walk through a role, into a group, and across a parent/child
+boundary in one pass, all using the same traversal logic, instead of
+three separate mechanisms that would each need to be kept correct and
+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/`)
+
+## Roadmap
+
+- DuckDB and MongoDB storage backends
+- a standalone HTTP service mode beyond the sample app's admin routes
+- a SAML auth integration recipe (OAuth2 and JWT are already covered)
+- 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
+```
+
+## Quickstart
+
+A schema declares, per namespace, how each relation is computed: `Direct()`
+means "true when a matching tuple exists," `Union` combines several rules
+with OR, and `TupleToUserset` re-checks a relation on a related object (the
+mechanism behind "viewer of the parent folder implies viewer of the
+document"). Once the schema is registered, `write()` adds facts to the
+graph and `check()` answers a yes/no access question against it:
+
+```python
+from authz import (
+    Client, Direct, From, Namespace, PythonCallableEvaluator,
+    RelationTuple, SqliteStorage, TupleToUserset, Union,
+)
+
+async with SqliteStorage(":memory:") as storage:
+    client = Client(storage=storage, condition_evaluator=PythonCallableEvaluator())
+
+    folder = Namespace("folder", {
+        "owner": Direct(),
+        "viewer": Union(Direct(), From("owner")),
+    })
+    document = Namespace("document", {
+        "parent": Direct(),
+        "viewer": Union(Direct(), TupleToUserset("parent", "viewer")),
+    })
+
+    client.register_schema(folder, document)
+
+    await client.write([
+        RelationTuple("folder", "workspace", "owner", "user:alice"),
+        RelationTuple("document", "roadmap", "parent", "folder:workspace"),
+    ])
+
+    await client.check("user:alice", "viewer", "document:roadmap")  # True
+```
+
+See [`docs/quickstart.md`](docs/quickstart.md) for the full walkthrough
+(groups, ABAC conditions, consistency tokens, `expand()`), and
+[`examples/seed_data.py`](examples/seed_data.py) for a runnable version of
+it: `python -m examples.seed_data`.
+
+Before designing your own schema, read [`docs/pitfalls.md`](docs/pitfalls.md).
+It covers schema vs. data cycles, which rewrite rule (`Union`,
+`Intersection`, `Exclusion`, `From`, `TupleToUserset`) fits which
+situation, and when a depth-limit error means your data is legitimately
+deep versus something bypassed the guards.
+
+## FastAPI Integration Example
+
+A route needs one thing from an authorization library: block the request
+before the handler runs if the caller lacks permission. `authz.integrations.fastapi`
+does that as a single `Depends()`, so the check happens the same way
+FastAPI already resolves any other dependency. It's an optional adapter
+built as a proof of concept; a Django, Flask, or plain-script consumer
+should call the same `Client` directly instead.
+
+```python
+from fastapi import Depends
+from authz.integrations.fastapi import requires
+
+
+@app.get("/documents/{document_id}")
+async def read_document(
+    document_id: str,
+    _: None = Depends(requires(
+        "viewer", "document:{document_id}",
+        get_client=get_authz_client, get_subject=get_current_user,
+    )),
+):
+    ...
+```
+
+`requires()` makes the route depend on a `check()` call: when that call
+returns `False`, the request never reaches the handler body, and the
+caller receives a 403 automatically. See
+[`docs/fastapi_integration.md`](docs/fastapi_integration.md) for the full
+example, including how `get_client`/`get_subject` compose with your app's
+own database and auth setup.
+
+## Development
+
+```bash
+uv sync --extra fastapi
+uv run pytest
+```

python_authz-0.5.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+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,,

python_authz-0.5.0.dist-info/WHEEL

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

python_authz-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+authz = authz:main
+

python_authz-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anupam Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.