policy-pattern 0.4.0__tar.gz → 0.5.0__tar.gz

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policy-pattern
-Version: 0.4.0
+Version: 0.5.0
 Summary: A minimal, embeddable ReBAC authorization engine for Python, inspired by Google Zanzibar.
 Keywords: python,authorization,access-control,rebac,zanzibar,security
 Author: Guillem Pozo Sebastián
@@ -45,8 +45,7 @@ Description-Content-Type: text/markdown
     </a>
 </p>
 
-`policy-pattern` is a standalone Python library for relationship-based access control (ReBAC). It models
-authorization as relationships between subjects and objects and evaluates those relationships through composable
+`policy-pattern` is a standalone Python library for relationship-based access control (ReBAC). It models authorization as relationships between subjects and objects and evaluates those relationships through composable
 authorization rules.
 
 - **No authorization server**
@@ -131,18 +130,15 @@ evaluator = Evaluator(model=compiled, store=store)
 evaluator.check(alice, "viewer", document_42)  # True — alice owns the parent folder
 ```
 
-`viewer` here means "the document's own owner, or the owner of whatever folder it lives in" — a document under
-`folder:engineering` inherits access from that folder without copying a permission onto every document.
+`viewer` here means "the document's own owner, or the owner of whatever folder it lives in" — a document under `folder:engineering` inherits access from that folder without copying a permission onto every document.
 
-See the [Usage Guide](docs/usage/README.md) for the full, runnable walkthrough — every rewrite operator, nested
-groups, `EvaluationBudget`, and error handling.
+See the [Usage Guide](docs/usage/README.md) for the full, runnable walkthrough — every rewrite operator, nested groups, `EvaluationBudget`, and error handling.
 
 ---
 
 ## Documentation
 
-The repository uses specifications and architecture documents as part of the implementation contract — they
-describe **what must be true**, independent of any one adapter's implementation.
+The repository uses specifications and architecture documents as part of the implementation contract — they describe **what must be true**, independent of any one adapter's implementation.
 
 ```text
 docs/
@@ -153,8 +149,9 @@ docs/
 └── errors.md        — the PPxxx error code ranges and what each one means
 ```
 
-Start with the [Usage Guide](docs/usage/README.md) to see the library working end to end, then
-[Architecture](docs/architecture.md) to understand why the model is shaped the way it is.
+Start with the [Usage Guide](docs/usage/README.md) to see the library working end to end, then [Architecture](docs/architecture.md) to understand why the model is shaped the way it is.
+
+See [`CODE_STYLE.md`](.github/CODE_STYLE.md) and [`TESTING.md`](TESTING.md) for contributor conventions no tool enforces.
 
 ---
 

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/README.md

@@ -20,8 +20,7 @@
     </a>
 </p>
 
-`policy-pattern` is a standalone Python library for relationship-based access control (ReBAC). It models
-authorization as relationships between subjects and objects and evaluates those relationships through composable
+`policy-pattern` is a standalone Python library for relationship-based access control (ReBAC). It models authorization as relationships between subjects and objects and evaluates those relationships through composable
 authorization rules.
 
 - **No authorization server**
@@ -106,18 +105,15 @@ evaluator = Evaluator(model=compiled, store=store)
 evaluator.check(alice, "viewer", document_42)  # True — alice owns the parent folder
 ```
 
-`viewer` here means "the document's own owner, or the owner of whatever folder it lives in" — a document under
-`folder:engineering` inherits access from that folder without copying a permission onto every document.
+`viewer` here means "the document's own owner, or the owner of whatever folder it lives in" — a document under `folder:engineering` inherits access from that folder without copying a permission onto every document.
 
-See the [Usage Guide](docs/usage/README.md) for the full, runnable walkthrough — every rewrite operator, nested
-groups, `EvaluationBudget`, and error handling.
+See the [Usage Guide](docs/usage/README.md) for the full, runnable walkthrough — every rewrite operator, nested groups, `EvaluationBudget`, and error handling.
 
 ---
 
 ## Documentation
 
-The repository uses specifications and architecture documents as part of the implementation contract — they
-describe **what must be true**, independent of any one adapter's implementation.
+The repository uses specifications and architecture documents as part of the implementation contract — they describe **what must be true**, independent of any one adapter's implementation.
 
 ```text
 docs/
@@ -128,8 +124,9 @@ docs/
 └── errors.md        — the PPxxx error code ranges and what each one means
 ```
 
-Start with the [Usage Guide](docs/usage/README.md) to see the library working end to end, then
-[Architecture](docs/architecture.md) to understand why the model is shaped the way it is.
+Start with the [Usage Guide](docs/usage/README.md) to see the library working end to end, then [Architecture](docs/architecture.md) to understand why the model is shaped the way it is.
+
+See [`CODE_STYLE.md`](.github/CODE_STYLE.md) and [`TESTING.md`](TESTING.md) for contributor conventions no tool enforces.
 
 ---
 

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/policy_pattern/adapters/memory.py

@@ -133,3 +133,28 @@ class _MemoryView(View):
             return ReadResult(tuples=frozenset(candidates[:limit]), complete=False)
 
         return ReadResult(tuples=frozenset(candidates), complete=True)
+
+    @override
+    def read_tuples_for_subject(self, subject: Subject, limit: int) -> ReadResult:
+        """Linearly scans the snapshot for tuples with this exact subject.
+
+        Args:
+            subject (Subject): The exact subject to match.
+            limit (int): The maximum number of matching tuples to return.
+
+        Returns:
+            ReadResult: Matching tuples and whether the enumeration is complete.
+
+        Raises:
+            None: This method defines no exception of its own.
+        """
+        candidates: list[Tuple] = nsmallest(
+            limit + 1,
+            (t for t in self.tuples if t.subject == subject),
+            key=repr,
+        )
+
+        if len(candidates) > limit:
+            return ReadResult(tuples=frozenset(candidates[:limit]), complete=False)
+
+        return ReadResult(tuples=frozenset(candidates), complete=True)

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/policy_pattern/adapters/postgres.py

@@ -8,13 +8,16 @@ from importlib.resources import files
 from typing import Any, override
 
 from policy_pattern.errors import IndexEntryTooLargeError
-from policy_pattern.models import Mutation, ObjectReference, Subject
+from policy_pattern.models import Mutation, ObjectReference, Subject, Tuple
 from policy_pattern.ports import ReadResult, TupleStore, View
 
 from ._db_protocols import Connection, ConnectionPool, Cursor
 from ._tuple_mapping import columns, compose, decompose
 
-MIGRATION_RESOURCE: tuple[str, str, str] = ("sql", "postgres", "0001_create_policy_tuples.sql")
+MIGRATION_RESOURCE: tuple[tuple[str, str, str], ...] = (
+    ("sql", "postgres", "0001_create_policy_tuples.sql"),
+    ("sql", "postgres", "0002_add_subject_index.sql"),
+)
 
 # PostgreSQL's B-tree index entry limit for the default 8KB page size
 # (BLCKSZ). Identifier bounds a value to 255 code points, any printable
@@ -68,6 +71,12 @@ _READ_RELATION_SQL: str = """
     ORDER BY subject_type, subject_id, subject_relation LIMIT %s
     """
 
+_READ_TUPLES_FOR_SUBJECT_SQL: str = """
+    SELECT object_type, object_id, relation FROM "authz_tuples"
+    WHERE subject_type=%s AND subject_id=%s AND subject_relation=%s
+    ORDER BY object_type, object_id, relation LIMIT %s
+    """
+
 
 class PostgresTupleStore(TupleStore):
     """
@@ -114,16 +123,17 @@ class PostgresTupleStore(TupleStore):
         failed execute() would otherwise return an aborted transaction to
         the pool for the next caller to trip over.
         """
-        migration_sql = files("policy_pattern").joinpath(*MIGRATION_RESOURCE).read_text(encoding="utf-8")
         with self._pool.connection() as conn:
             cursor = conn.cursor()
-            try:
-                cursor.execute(migration_sql)
-            except Exception:
-                conn.rollback()
-                raise
-            else:
-                conn.commit()
+            for resource in MIGRATION_RESOURCE:
+                migration_sql = files("policy_pattern").joinpath(*resource).read_text(encoding="utf-8")
+                try:
+                    cursor.execute(migration_sql)
+                except Exception:
+                    conn.rollback()
+                    raise
+                else:
+                    conn.commit()
 
     @override
     def write_tuples(self, mutation: Mutation) -> None:
@@ -255,3 +265,34 @@ class _PostgresView(View):
         tuples = frozenset(compose(r, relation, object) for r in rows[:limit])
 
         return ReadResult(tuples=tuples, complete=len(rows) <= limit)
+
+    @override
+    def read_tuples_for_subject(self, subject: Subject, limit: int) -> ReadResult:
+        """Returns up to `limit` tuples whose subject exactly matches, in one query.
+
+        Args:
+            subject (Subject): The exact subject to match.
+            limit (int): The maximum number of matching tuples to return.
+
+        Returns:
+            ReadResult: Matching tuples and whether the enumeration is complete.
+
+        Raises:
+            None: This method defines no exception of its own.
+        """
+        subject_type, subject_id, subject_relation = decompose(subject)
+        cursor: Cursor = self.connection.cursor()
+        cursor.execute(
+            _READ_TUPLES_FOR_SUBJECT_SQL,
+            (subject_type, subject_id, subject_relation, limit + 1),
+        )
+        rows: list[tuple[Any, ...]] = cursor.fetchall()
+        tuples = frozenset(
+            Tuple(
+                subject=subject,
+                relation=row[2],
+                object=ObjectReference(type=row[0], id=row[1]),
+            )
+            for row in rows[:limit]
+        )
+        return ReadResult(tuples=tuples, complete=len(rows) <= limit)

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/policy_pattern/evaluator.py

@@ -2,8 +2,10 @@
 Evaluator: resolves check() over a CompiledModel and a TupleStore.
 """
 
+from collections import deque
 from collections.abc import Sequence
 from dataclasses import dataclass, field
+from functools import cached_property
 
 from .errors import EvaluationError, UnknownNameError, UnknownTypeError
 from .models import (
@@ -148,6 +150,156 @@ class Evaluator:
             context = EvaluationContext(view=view, budget=budget)
             return [self._check_name(subject, name, object, context) for subject, name, object in requests]
 
+    def list_objects(
+        self,
+        subject: Subject,
+        name: str,
+        object_type: str,
+        candidate_ids: frozenset[ObjectReference] | None = None,
+        budget: EvaluationBudget | None = None,
+    ) -> frozenset[ObjectReference]:
+        """Returns objects of `object_type` on which `subject` holds `name`.
+
+        Args:
+            subject (Subject): The subject whose access is queried.
+            name (str): The relation or permission name to check.
+            object_type (str): The type of objects to return.
+            candidate_ids (frozenset[ObjectReference] | None): Optional objects to check instead of discovering them.
+            budget (EvaluationBudget | None): Resource limits for this evaluation.
+
+        Returns:
+            frozenset[ObjectReference]: Objects of `object_type` allowed by the forward check.
+
+        Raises:
+            UnknownTypeError: If `object_type` is not declared in the CompiledModel.
+            UnknownNameError: If `name` is not declared on `object_type`.
+            EvaluationError: If reverse candidate discovery or a candidate check exhausts the evaluation budget.
+        """
+        if object_type not in self._model.types:
+            raise UnknownTypeError(
+                message=f"type {object_type!r} is not declared in this CompiledModel",
+                related=f"object_type={object_type!r}",
+            )
+        declaration = self._model.types[object_type]
+        if name not in declaration.relations and name not in declaration.permissions:
+            raise UnknownNameError(
+                message=f"{name!r} is not declared as a relation or permission on {object_type!r}",
+                related=f"object_type={object_type!r}",
+            )
+
+        if budget is None:
+            budget = EvaluationBudget()
+
+        with self._store.snapshot() as view:
+            context = EvaluationContext(view=view, budget=budget)
+            candidates = self._reverse_candidates(subject, context) if candidate_ids is None else candidate_ids
+
+            return frozenset(
+                object
+                for object in sorted(candidates, key=repr)
+                if object.type == object_type and self._check_name(subject, name, object, context)
+            )
+
+    def _reverse_candidates(self, subject: Subject, context: EvaluationContext) -> frozenset[ObjectReference]:
+        """Walk tuple subject edges to generate possible objects without interpreting permissions.
+
+        Args:
+            subject (Subject): The starting subject for the reverse walk.
+            context (EvaluationContext): The shared view and resource-budget state.
+
+        Returns:
+            frozenset[ObjectReference]: All candidate objects reached by the tuple walk.
+
+        Raises:
+            EvaluationError: If `max_depth` or `max_nodes` is exceeded, or a subject-keyed enumeration is truncated.
+        """
+        queue: deque[tuple[Subject, int]] = deque([(subject, 0)])
+        visited: set[Subject] = {subject}
+        candidates: set[ObjectReference] = set()
+
+        while queue:
+            current, depth = queue.popleft()
+            context.node_count += 1
+            if context.node_count > context.budget.max_nodes:
+                raise EvaluationError(
+                    message=f"max_nodes={context.budget.max_nodes!r} exceeded during reverse lookup",
+                    related=f"subject={current!r}",
+                )
+
+            self._charge_read(context, current.object, "list_objects")
+            result = context.view.read_tuples_for_subject(
+                current,
+                limit=context.budget.max_nodes - context.node_count,
+            )
+
+            if not result.complete:
+                raise EvaluationError(
+                    message=(f"enumeration for subject {current!r} truncated by remaining max_nodes budget"),
+                    related=f"subject={current!r}",
+                )
+
+            if result.tuples and depth >= context.budget.max_depth:
+                raise EvaluationError(
+                    message=(f"max_depth={context.budget.max_depth!r} exceeded during reverse lookup from {current!r}"),
+                    related=f"subject={current!r}",
+                )
+
+            for tuple_ in sorted(result.tuples, key=repr):
+                candidates.add(tuple_.object)
+                for next_subject in self._reverse_frontier(tuple_.object):
+                    if next_subject not in visited:
+                        visited.add(next_subject)
+                        queue.append((next_subject, depth + 1))
+
+        return frozenset(candidates)
+
+    @cached_property
+    def _referenceable_shapes(self) -> frozenset[str]:
+        """Return the subject shapes referenced by any relation in the model.
+
+        Returns:
+            frozenset[str]: Subject type and type/relation shapes allowed by model relations.
+
+        Raises:
+            None.
+        """
+        return frozenset(
+            allowed_shape
+            for type_declaration in self._model.types.values()
+            for relation in type_declaration.relations.values()
+            for allowed_shape in relation.allowed_subject_types
+        )
+
+    def _reverse_frontier(self, object: ObjectReference) -> tuple[Subject, ...]:
+        """Return the declared subject identities that may reference `object`.
+
+        Args:
+            object (ObjectReference): The object whose possible subject identities are generated.
+
+        Returns:
+            tuple[Subject, ...]: Direct and userset identities that model relations may reference.
+
+        Raises:
+            None.
+        """
+        next_subjects: list[Subject] = []
+        if object.type in self._referenceable_shapes:
+            next_subjects.append(DirectSubject(object=object))
+
+        declaration = self._model.types.get(object.type)
+        if declaration is None:
+            return tuple(next_subjects)
+
+        names = (*declaration.relations, *declaration.permissions)
+        next_subjects.extend(
+            [
+                SubjectSet(object=object, relation=name)
+                for name in names
+                if f"{object.type}#{name}" in self._referenceable_shapes
+            ]
+        )
+        return tuple(next_subjects)
+
     def _check_name(self, subject: Subject, name: str, object: ObjectReference, context: EvaluationContext) -> bool:
         """
         Dispatches (object, name) to a relation or permission check, with cycle/memo/budget bookkeeping.

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/policy_pattern/ports/tuple_store.py

@@ -116,3 +116,24 @@ class View(ABC):
         `limit + 1` matching tuples before returning — that would violate the contract.
         """
         raise NotImplementedError
+
+    @abstractmethod
+    def read_tuples_for_subject(self, subject: Subject, limit: int) -> ReadResult:
+        """
+        Enumerates every tuple whose subject exactly matches `subject`, bounded by `limit`.
+
+        Unlike `read_relation`, this is not filtered by relation name or
+        object; callers needing narrower results filter returned tuples.
+        See `ReadResult` for the `complete=False` contract.
+
+        Args:
+            subject (Subject): The exact subject to match.
+            limit (int): The maximum number of matching tuples to return.
+
+        Returns:
+            ReadResult: Matching tuples and whether the enumeration is complete.
+
+        Raises:
+            None: The abstract contract defines no exception of its own.
+        """
+        raise NotImplementedError

policy_pattern-0.5.0/policy_pattern/sql/postgres/0002_add_subject_index.sql

@@ -0,0 +1,5 @@
+-- Index supporting View.read_tuples_for_subject(). Without it, a query
+-- filtered only by the subject columns has no index to use — the
+-- primary key is ordered object-first.
+CREATE INDEX IF NOT EXISTS authz_tuples_subject_idx
+    ON "authz_tuples" (subject_type, subject_id, subject_relation);

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "policy-pattern"
-version = "0.4.0"
+version = "0.5.0"
 description = "A minimal, embeddable ReBAC authorization engine for Python, inspired by Google Zanzibar."
 readme = "README.md"
 license = "Apache-2.0"
@@ -38,7 +38,7 @@ Repository = "https://github.com/guillem-ps/policy-pattern"
 Issues = "https://github.com/guillem-ps/policy-pattern/issues"
 
 [build-system]
-requires = ["uv_build>=0.11.16,<0.13.0"]
+requires = ["uv_build>=0.11.16,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

{policy_pattern-0.4.0 → policy_pattern-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "policy-pattern"
-version = "0.4.0"
+version = "0.5.0"
 description = "A minimal, embeddable ReBAC authorization engine for Python, inspired by Google Zanzibar."
 readme = "README.md"
 authors = [
@@ -37,7 +37,7 @@ Repository = "https://github.com/guillem-ps/policy-pattern"
 Issues = "https://github.com/guillem-ps/policy-pattern/issues"
 
 [build-system]
-requires = ["uv_build>=0.11.16,<0.13.0"]
+requires = ["uv_build>=0.11.16,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]