policy-pattern 0.1.0__py3-none-any.whl

policy_pattern/models/_schema_validation.py

@@ -0,0 +1,130 @@
+"""
+Shared schema validation for `Model.compile()` and `CompiledModel` construction.
+"""
+
+from collections.abc import Mapping
+
+from policy_pattern.errors import ModelValidationError
+
+from .operators import Exclusion, Intersection, PermissionExpression, Union
+from .reference import Reference
+from .tuple_to_userset import TupleToUserset
+from .type import Type
+
+
+def validate_types(types: Mapping[str, Type]) -> None:
+    """
+    Validates every Type's key against its own name, and every Reference/tupleset it declares.
+
+    Lives in its own module, not inside `Model` or `CompiledModel`, so both
+    can call the exact same check — `Model.compile()` on the normal path,
+    `CompiledModel.__post_init__` against a direct construction that
+    bypassed it. One validator, not two copies that can drift apart.
+
+    Raises:
+        ModelValidationError: If a `Type`'s key doesn't match its own `name`,
+            a `Reference`/`tupleset` name doesn't exist on its own type, or a
+            `tupleset` resolves to a permission instead of a relation.
+
+        ModelValidationError: If a permission expression and relation share the same name on the same type,
+        which is illegal.
+    """
+    for type_name, type_declaration in types.items():
+        if type_name != type_declaration.name:
+            raise ModelValidationError(
+                message=f"model key {type_name!r} does not match Type.name {type_declaration.name!r}",
+                related=f"type={type_name!r}",
+            )
+        if overlap := sorted(type_declaration.relations.keys() & type_declaration.permissions.keys()):
+            raise ModelValidationError(
+                message=f"{type_name} declares {overlap!r} as both a relation and a permission",
+                related=f"type={type_name!r}",
+            )
+
+        for permission_name, expression in type_declaration.permissions.items():
+            _validate_expression(expression, types, type_declaration, type_name, permission_name)
+
+
+def _validate_expression(
+    expression: PermissionExpression,
+    types: Mapping[str, Type],
+    type_declaration: Type,
+    type_name: str,
+    permission_name: str,
+) -> None:
+    """
+    Recursively validates one permission expression against its own type's declarations.
+    """
+    if isinstance(expression, Reference):
+        # Leaf: name must resolve within this type's own namespace.
+        known = type_declaration.relations.keys() | type_declaration.permissions.keys()
+        if expression.name not in known:
+            raise ModelValidationError(
+                message=f"{type_name}.{permission_name} references undeclared name {expression.name!r}",
+                related=f"type={type_name!r}",
+            )
+    elif isinstance(expression, TupleToUserset):
+        # Leaf: tupleset must be a stored edge — nothing to traverse if it were computed.
+        if expression.tupleset not in type_declaration.relations:
+            raise ModelValidationError(
+                message=(
+                    f"{type_name}.{permission_name} tupleset {expression.tupleset!r} "
+                    "must be a relation, not a permission or an undeclared name"
+                ),
+                related=f"type={type_name!r}",
+            )
+        _validate_tuple_to_userset_targets(expression, types, type_declaration, type_name, permission_name)
+    elif isinstance(expression, (Union, Intersection)):
+        # Rewrite combinator: set-algebra, commutative — validate both operands, order doesn't matter.
+        _validate_expression(expression.left, types, type_declaration, type_name, permission_name)
+        _validate_expression(expression.right, types, type_declaration, type_name, permission_name)
+    elif isinstance(expression, Exclusion):
+        # Rewrite combinator, not commutative — include/exclude both required; skipping one is the
+        # classic false-allow bug (an accidental swap would silently invert the exclusion).
+        _validate_expression(expression.include, types, type_declaration, type_name, permission_name)
+        _validate_expression(expression.exclude, types, type_declaration, type_name, permission_name)
+    else:
+        raise ModelValidationError(
+            message=f"{type_name}.{permission_name} contains unknown expression type {type(expression).__name__!r}",
+            related=f"type={type_name!r}",
+        )
+
+
+def _validate_tuple_to_userset_targets(
+    expression: TupleToUserset,
+    types: Mapping[str, Type],
+    type_declaration: Type,
+    type_name: str,
+    permission_name: str,
+) -> None:
+    """
+    Validates `expression.computed` against every plain-type traversal target the tupleset relation allows.
+
+    Every plain-type entry in the tupleset relation's allowed_subject_types
+    is a traversal target `_check_tuple_to_userset` can actually land on at
+    runtime — unlike a subject-only leaf type, it is always used as the
+    *object* of the next check(), so `computed` must resolve there too. A
+    userset-shaped entry ("type#relation") is never followed by traversal
+    (only DirectSubject entries are), so it carries nothing to validate.
+    """
+    tupleset_relation = type_declaration.relations[expression.tupleset]
+    for target_type_name in tupleset_relation.allowed_subject_types:
+        if "#" in target_type_name:
+            continue
+        target_type = types.get(target_type_name)
+        if target_type is None:
+            raise ModelValidationError(
+                message=(
+                    f"{type_name}.{permission_name} tupleset {expression.tupleset!r} "
+                    f"allows undeclared type {target_type_name!r}"
+                ),
+                related=f"type={type_name!r}",
+            )
+        if expression.computed not in target_type.relations and expression.computed not in target_type.permissions:
+            raise ModelValidationError(
+                message=(
+                    f"{type_name}.{permission_name} computed {expression.computed!r} is not declared as a "
+                    f"relation or permission on {target_type_name!r}"
+                ),
+                related=f"type={type_name!r}",
+            )

policy_pattern/models/compiled_model.py

@@ -0,0 +1,43 @@
+"""
+Value Object representing an immutable, validated authorization schema.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType  # Immutable dict wrapper
+
+from ._schema_validation import validate_types
+from .type import Type
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledModel:
+    """
+    Immutable, validated result of `Model.compile()` — the only thing `Evaluator` accepts.
+
+    The intended path is always `Model.compile()`, but Python has no real
+    private constructor — calling `CompiledModel(types=...)` directly is
+    possible. `__post_init__` re-runs `validate_types()`, the same check
+    `Model.compile()` relies on, so a direct call can never hand the
+    `Evaluator` an object holding an undeclared `Reference`, a `tupleset`
+    resolving to a permission, or a mismatched type name — it either
+    produces the same result `compile()` would have, or raises the same
+    `ModelValidationError`.
+
+    `types` is wrapped in `MappingProxyType` on construction — a mutable
+    `dict` field would let that guarantee be violated after the fact
+    (`compiled.types["x"] = Type(...)` sneaking an unvalidated `Type` past
+    validation entirely).
+
+    Example:
+        compiled = model.compile()
+    """
+
+    types: Mapping[str, Type]
+
+    def __post_init__(self) -> None:
+        """
+        Validates `types`, then makes it a read-only view over a copy of the input mapping.
+        """
+        validate_types(self.types)
+        object.__setattr__(self, "types", MappingProxyType(dict(self.types)))

policy_pattern/models/direct_subject.py

@@ -0,0 +1,47 @@
+"""
+Value Object representing a reference to a concrete subject in the authorization graph.
+"""
+
+from dataclasses import dataclass
+
+from .object_reference import ObjectReference
+
+
+@dataclass(frozen=True, slots=True)
+class DirectSubject:
+    """
+    Value Object representing a concrete subject in the authorization graph.
+
+    A direct subject is theoretically the same kind of entity as an
+    `ObjectReference` — Zanzibar's own data model defines a "user" (a
+    direct subject) as exactly the same `<namespace>:<id>` shape as an
+    object. The only difference is the *role* it plays inside a `Tuple`
+    (subject side, not object side), never what kind of thing it is —
+    the same entity can be the object of one tuple
+    (`user:john#manager@user:jane`, where `user:john` is the object) and
+    the direct subject of another (`document:42#owner@user:john`).
+
+    Because of that, `DirectSubject` wraps an `ObjectReference` instead of
+    redeclaring `type`/`id` and their validation: any invalid `type`/`id`
+    already fails inside the `ObjectReference(...)` call, before
+    `DirectSubject` is ever constructed — there is nothing left for this
+    class to validate on its own.
+
+    This is one half of `Subject` (`Subject = DirectSubject | SubjectSet`)
+    — the other half, `SubjectSet`, is a genuinely
+    different concept: not a single entity, but a reference to *a relation
+    on an object* (`group:eng#member`), i.e. a set of subjects rather than
+    one.
+
+    Example:
+        DirectSubject(object=ObjectReference(type="user", id="john"))
+    Equals:
+        ObjectReference(type="user", id="john") -> Identifier(
+            value="user", field="type"
+        ) and Identifier(value="john", field="id") -> user:john
+
+    Raises:
+        InvalidIdentifierError: Propagated from `ObjectReference` if `type` or `id` is invalid.
+    """
+
+    object: ObjectReference

policy_pattern/models/identifier.py

@@ -0,0 +1,55 @@
+"""
+Value Object representing an entity identifier.
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from ..errors import InvalidIdentifierError
+
+
+@dataclass(frozen=True, slots=True)
+class Identifier:
+    """
+    Value Object representing an entity identifier.
+
+    An identifier contains the value that identifies an entity and
+    the field/type associated with that identifier.
+
+    Example:
+        Identifier(value="42", field="document")
+    """
+
+    value: str
+    field: str
+
+    _MIN_VALUE_LENGTH: ClassVar[int] = 1
+    _MAX_VALUE_LENGTH: ClassVar[int] = 255
+
+    def __post_init__(self) -> None:
+        """
+        Validates the identifier after initialization.
+
+        Raises:
+            InvalidIdentifierError: If the identifier value or field is invalid.
+        """
+        if not self._MIN_VALUE_LENGTH <= len(self.value) <= self._MAX_VALUE_LENGTH:
+            raise InvalidIdentifierError(
+                message=f"identifier value length must be between {self._MIN_VALUE_LENGTH!r} and {self._MAX_VALUE_LENGTH!r}",  # noqa: E501
+                related=f"field={self.field!r}",
+            )
+
+        if not self.value.isprintable():
+            raise InvalidIdentifierError(
+                message=f"identifier value {self.value!r} must contain printable characters only",
+                related=f"field={self.field!r}",
+            )
+
+        if self.value != self.value.strip():
+            raise InvalidIdentifierError(
+                message=f"identifier value {self.value!r} cannot contain leading or trailing whitespace",
+                related=f"field={self.field!r}",
+            )
+
+        if not self.field:
+            raise InvalidIdentifierError(message="identifier field cannot be empty")

policy_pattern/models/model.py

@@ -0,0 +1,46 @@
+"""
+Value Object representing the whole authorization schema.
+"""
+
+from dataclasses import dataclass, field
+
+from .compiled_model import CompiledModel
+from .type import Type
+
+
+@dataclass(slots=True)
+class Model:
+    """
+    The whole authorization schema — a mutable, authoring-time collection of `Type` declarations.
+
+    Unlike every other class in this package, `Model` is deliberately **not**
+    frozen. `architecture.md` already says why: "mutable, authoring-time" —
+    it exists to be built up incrementally (`model.types["document"] =
+    Type(...)`) before `.compile()` produces the immutable `CompiledModel`
+    that `Evaluator` actually accepts. There is no `check()` here, only
+    `compile()` — evaluating a bare `Model` is an illegal state the type
+    system doesn't even offer a method for.
+
+    Example:
+        model = Model()
+        model.types["document"] = Type(name="document", relations={...}, permissions={...})
+        compiled = model.compile()
+    """
+
+    types: dict[str, Type] = field(default_factory=dict[str, Type])
+
+    def compile(self) -> CompiledModel:
+        """
+        Returns an immutable, validated CompiledModel.
+
+        Validation itself lives in `CompiledModel.__post_init__`, not here —
+        the only way both this normal path and a direct `CompiledModel(...)`
+        call get the same guarantee. See `CompiledModel`'s docstring.
+
+        Raises:
+            ModelValidationError: If a `Type`'s key in `types` doesn't match
+                its own `name`, a `Reference`/`tupleset` name doesn't exist
+                on its own type, or a `tupleset` resolves to a permission
+                instead of a relation.
+        """
+        return CompiledModel(types=dict(self.types))

policy_pattern/models/mutation.py

@@ -0,0 +1,52 @@
+"""
+Value Object representing an atomic write to the authorization store.
+"""
+
+from dataclasses import dataclass
+
+from policy_pattern.errors import InvalidMutationError
+
+from .tuple import Tuple
+
+
+@dataclass(frozen=True, slots=True)
+class Mutation:
+    """
+    Value Object representing one atomic write: a set of additions and a
+    set of deletions applied together, or not at all.
+
+    S' = (S - deletions) | additions
+
+    `additions`/`deletions` must be disjoint — a tuple present in both has
+    no defined meaning (`semantics.md`). An empty mutation
+    (`additions=frozenset(), deletions=frozenset()`) is valid: a no-op,
+    not a special case to reject.
+
+    Unlike every other Value Object so far, `Mutation` has no
+    identifier-shaped field of its own to delegate to `Identifier` — its
+    only rule is structural (the two sets don't overlap), not a bounds/
+    charset check.
+
+    Example:
+        Mutation(additions=frozenset({tuple_a}), deletions=frozenset({tuple_b}))
+
+    Raises:
+        InvalidMutationError: If `additions` and `deletions` are not disjoint.
+
+    Attributes:
+        additions (frozenset[Tuple]): The set of tuples to add.
+        deletions (frozenset[Tuple]): The set of tuples to delete.
+    """
+
+    additions: frozenset[Tuple]
+    deletions: frozenset[Tuple]
+
+    def __post_init__(self) -> None:
+        """
+        Validates that additions and deletions are disjoint.
+
+        An empty mutation (no additions, no deletions) is valid — a no-op,
+        not an error.
+        """
+        if self.additions & self.deletions:
+            raise InvalidMutationError(message="additions and deletions must be disjoint")

policy_pattern/models/object_reference.py

@@ -0,0 +1,42 @@
+"""
+Value Object representing a reference to a concrete object in the authorization graph.
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from .identifier import Identifier
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectReference:
+    """
+    Value Object representing a concrete object.
+
+    An object reference identifies a specific entity by its type and id —
+    e.g. "document:42" is the type "document" with id "42". Both `type`
+    and `id` are validated as identifiers (see `Identifier`): non-empty,
+    bounded length, printable characters only.
+
+    Example:
+        ObjectReference(type="document", id="42")
+
+    Both components are validated as `Identifier` values with fields
+    `"type"` and `"id"`, respectively.
+    """
+
+    type: str
+    id: str
+
+    _FIELD_TYPE_VALUE: ClassVar[str] = "type"
+    _FIELD_ID_VALUE: ClassVar[str] = "id"
+
+    def __post_init__(self) -> None:
+        """
+        Validates the object reference after initialization by delegating to Identifier.
+
+        Raises:
+            InvalidIdentifierError: If `type` or `id` is invalid.
+        """
+        Identifier(value=self.type, field=self._FIELD_TYPE_VALUE)
+        Identifier(value=self.id, field=self._FIELD_ID_VALUE)

policy_pattern/models/operators.py

@@ -0,0 +1,116 @@
+"""
+Base class and node types for computed permission expressions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class PermissionExpression:
+    r"""
+    Base class for a computed permission expression — never storable.
+
+    A `Relation` is a stored fact (`document:42#owner@user:john` can exist
+    as a `Tuple`). A `Permission` is the opposite: a *rule* for combining
+    relations/other permissions, computed at evaluation time, never
+    written to the store. `PermissionExpression` is the AST of that rule —
+    the same set-theory operations Zanzibar's `userset rewrite` describes,
+    expressed as data instead of prose:
+
+        - viewer(o) = owner(o) ∪ editor(o)                Union
+        - can_edit(o) = editor(o) ∩ active_member(o)      Intersection
+        - viewer(o) = member(o) \ blocked(o)             Exclusion
+
+    Composed via real Python operators instead of nested constructor
+    calls — an operator-overloaded composite, not named factory methods:
+
+        viewer = Reference(name="owner") | (
+            Reference(name="member") - Reference(name="blocked")
+        )
+
+    `__or__`/`__and__`/`__sub__` return new `PermissionExpression` nodes;
+    they never mutate `self` — every node here is frozen, an expression
+    tree is built bottom-up once and never changes shape afterward.
+    """  # noqa: D301, RUF002
+
+    __slots__ = ()
+
+    def __or__(self, other: PermissionExpression) -> Union:
+        """
+        Combine with `other` as a Union — true if either side is true.
+        """
+        return Union(left=self, right=other)
+
+    def __and__(self, other: PermissionExpression) -> Intersection:
+        """
+        Combine with `other` as an Intersection — true only if both sides are true.
+        """
+        return Intersection(left=self, right=other)
+
+    def __sub__(self, other: PermissionExpression) -> Exclusion:
+        """
+        Combine with `other` as an Exclusion — true if `self` is true and `other` is false.
+        """
+        return Exclusion(include=self, exclude=other)
+
+
+@dataclass(frozen=True, slots=True)
+class Union(PermissionExpression):
+    """
+    Union of two permission expressions — true if either side is true.
+
+    `viewer = owner | editor`: a subject only needs to satisfy one branch,
+    not both. The evaluator is free to short-circuit here (stop as soon as
+    one side is `True`) — unlike `Exclusion`, a `Union` has no case where
+    an error on the untaken branch could hide a false allow.
+
+    Example:
+        Union(left=Reference(name="owner"), right=Reference(name="editor"))
+    """
+
+    left: PermissionExpression
+    right: PermissionExpression
+
+
+@dataclass(frozen=True, slots=True)
+class Intersection(PermissionExpression):
+    """
+    Intersection of two permission expressions — true only if both sides are true.
+
+    `can_edit = editor & active_member`: a subject must satisfy both
+    branches. Unlike `Union`, the evaluator can short-circuit on the first
+    `False` branch — a `False` on either side is enough to decide the
+    whole node is `False`, regardless of what the other side would have
+    evaluated to.
+
+    Example:
+        Intersection(left=Reference(name="editor"), right=Reference(name="active_member"))
+    """
+
+    left: PermissionExpression
+    right: PermissionExpression
+
+
+@dataclass(frozen=True, slots=True)
+class Exclusion(PermissionExpression):
+    """
+    Set difference: true if `include` is true and `exclude` is false.
+
+    `viewer = member - blocked`: the one node the evaluator must *never*
+    short-circuit. If evaluating `exclude` fails (a storage error, a
+    cycle, a budget overrun) while `include` is already known to be
+    `False`, that failure still has to propagate — treating the failed
+    `exclude` as "assume False" would compute `False - False = True`, a
+    false allow manufactured entirely out of an evaluation failure on the
+    branch that was never actually checked. This is `docs/semantics.md`'s
+    "storage errors are not empty results" rule, restated as an evaluation
+    rule instead of a storage one: both sides are always evaluated,
+    unconditionally.
+
+    Example:
+        Exclusion(include=Reference(name="member"), exclude=Reference(name="blocked"))
+    """
+
+    include: PermissionExpression
+    exclude: PermissionExpression

policy_pattern/models/reference.py

@@ -0,0 +1,36 @@
+"""
+Value object representing a reference to a relation or permission on the same type.
+"""
+
+from dataclasses import dataclass
+
+from .identifier import Identifier
+from .operators import PermissionExpression
+
+
+@dataclass(frozen=True, slots=True)
+class Reference(PermissionExpression):
+    """
+    Names a relation or permission on the same type — the leaf case.
+
+    `Reference` is deliberately the *only* leaf node type, unifying what
+    an earlier draft of this design split into two (`This`, for stored
+    relations, and `ComputedUserset`, for other permissions). At authoring
+    time there is no way to tell which one `name` refers to without
+    looking at the rest of the type's declarations — so the distinction is
+    resolved once, by the evaluator, at evaluation time: if `name` is a
+    declared `Relation`, look it up in the `TupleStore`; if it is another
+    `Permission`, recurse into its own expression tree. Neither case is
+    knowable — or needs to be knowable — from `Reference` alone.
+
+    Example:
+        Reference(name="owner")
+    """
+
+    name: str
+
+    def __post_init__(self) -> None:
+        """
+        Validates `name` by delegating to `Identifier`.
+        """
+        Identifier(value=self.name, field="name")

policy_pattern/models/relation.py

@@ -0,0 +1,44 @@
+"""
+Value Object representing a storable relation on an object type.
+"""
+
+from dataclasses import dataclass
+
+from policy_pattern.errors import InvalidRelationError
+
+from .identifier import Identifier
+
+
+@dataclass(frozen=True, slots=True)
+class Relation:
+    """
+    Value Object representing a storable relation.
+
+    A relation is a storable edge — a fact that can exist directly in the
+    TupleStore, e.g. `document:42#owner@user:alice`. It carries no rewrite
+    algebra (that's `PermissionExpression`'s job); it only restricts which
+    subject types are allowed to hold it. Each entry is a type name
+    ("user") or a userset restriction ("organization#member") — the same
+    textual shape as a SubjectSet.
+
+    Example:
+        Relation(allowed_subject_types=("user", "organization#member"))
+
+    Each allowed subject type is validated as an `Identifier` with
+    `field="allowed_subject_types"`.
+    """
+
+    allowed_subject_types: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        """
+        Validates the relation after initialization.
+
+        Raises:
+            InvalidRelationError: If `allowed_subject_types` is empty or contains an invalid entry.
+        """
+        if not self.allowed_subject_types:
+            raise InvalidRelationError(message="relation must declare at least one allowed subject type")
+
+        for subject_type in self.allowed_subject_types:
+            Identifier(value=subject_type, field="allowed_subject_types")

policy_pattern/models/subject.py

@@ -0,0 +1,22 @@
+"""
+Type alias for a subject in the authorization graph.
+
+A subject is either a `DirectSubject` (a reference to one concrete entity,
+e.g. `user:john`) or a `SubjectSet` (a reference to a relation on an
+object — a computed set of subjects, e.g. `group:eng#member`). Deliberately
+a type alias, not a wrapper class: `DirectSubject`/`SubjectSet` are already
+distinguishable by `isinstance`, and a wrapper with two `Optional` fields
+would allow two illegal states a real union can't represent — neither set,
+or both set at once. Anywhere a `Subject` is expected, construct one of the
+two variants directly (`DirectSubject(...)` / `SubjectSet(...)`) and narrow
+with `isinstance`/`match` where it matters, e.g. inside the evaluator.
+
+Example:
+    subject: Subject = DirectSubject(object=ObjectReference(type="user", id="john"))
+    subject: Subject = SubjectSet(object=ObjectReference(type="group", id="eng"), relation="member")
+"""
+
+from .direct_subject import DirectSubject
+from .subject_set import SubjectSet
+
+type Subject = DirectSubject | SubjectSet