zanzipy 0.1.0__py3-none-any.whl

zanzipy/__init__.py

@@ -0,0 +1,8 @@
+from .models.tuple import InvalidTupleFormatError, RelationTuple
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "InvalidTupleFormatError",
+    "RelationTuple",
+]

zanzipy/models/__init__.py

@@ -0,0 +1,27 @@
+from .errors import (
+    EntityIdValidationError,
+    IdentifierValidationError,
+    InvalidTupleFormatError,
+    SubjectValidationError,
+)
+from .id import EntityId
+from .identifier import Identifier
+from .namespace import Namespace
+from .object import Obj
+from .relation import Relation
+from .subject import Subject
+from .tuple import RelationTuple
+
+__all__ = [
+    "EntityId",
+    "EntityIdValidationError",
+    "Identifier",
+    "IdentifierValidationError",
+    "InvalidTupleFormatError",
+    "Namespace",
+    "Obj",
+    "Relation",
+    "RelationTuple",
+    "Subject",
+    "SubjectValidationError",
+]

zanzipy/models/check.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Self
+
+from .filter import TupleFilter
+from .id import EntityId
+from .namespace import Namespace
+from .object import Obj
+from .relation import Relation
+from .subject import Subject
+
+
+@dataclass(frozen=True, slots=True)
+class CheckRequest:
+    """Request to check if subject has relation to object"""
+
+    object_type: str
+    object_id: str
+    relation: str
+    subject_type: str
+    subject_id: str
+
+    def __post_init__(self) -> None:
+        # Validate components using existing value objects
+        Namespace(self.object_type)
+        EntityId(self.object_id)
+        Relation(self.relation)
+        Namespace(self.subject_type)
+        EntityId(self.subject_id)
+
+    @property
+    def object(self) -> str:
+        return f"{self.object_type}:{self.object_id}"
+
+    @property
+    def subject(self) -> str:
+        return f"{self.subject_type}:{self.subject_id}"
+
+    def __str__(self) -> str:
+        return f"{self.object}#{self.relation}@{self.subject}"
+
+    def to_dict(self) -> dict:
+        return {
+            "object_type": self.object_type,
+            "object_id": self.object_id,
+            "relation": self.relation,
+            "subject_type": self.subject_type,
+            "subject_id": self.subject_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Self:
+        return cls(
+            object_type=data["object_type"],
+            object_id=data["object_id"],
+            relation=data["relation"],
+            subject_type=data["subject_type"],
+            subject_id=data["subject_id"],
+        )
+
+    @classmethod
+    def from_parts(cls, obj: Obj, relation: Relation, subject: Subject) -> Self:
+        """Construct from domain objects.
+
+        Requires a direct subject (no subject relation on the subject set).
+        """
+        if subject.relation is not None:
+            raise ValueError(
+                "CheckRequest requires a direct subject (no subject relation)"
+            )
+        return cls(
+            object_type=str(obj.namespace),
+            object_id=str(obj.id),
+            relation=str(relation),
+            subject_type=str(subject.namespace),
+            subject_id=str(subject.id),
+        )
+
+    @classmethod
+    def from_strings(cls, object_str: str, relation: str, subject_str: str) -> Self:
+        """Construct from 'ns:id', relation, and 'ns:id' strings.
+
+        The subject must be direct (no '#relation' allowed).
+        """
+        if ":" not in object_str:
+            raise ValueError("object must be in 'namespace:id' form")
+        obj_ns, obj_id = object_str.split(":", 1)
+        # Validate using value objects
+        obj_namespace = Namespace(obj_ns)
+        obj_entity_id = EntityId(obj_id)
+
+        # Reuse Subject.parse to leverage validation and detect subject sets
+        subject = Subject.parse(subject_str)
+        if subject.relation is not None:
+            raise ValueError(
+                "CheckRequest requires a direct subject (no subject relation)"
+            )
+
+        return cls(
+            object_type=str(obj_namespace),
+            object_id=str(obj_entity_id),
+            relation=str(Relation(relation)),
+            subject_type=str(subject.namespace),
+            subject_id=str(subject.id),
+        )
+
+    def to_object(self) -> Obj:
+        return Obj(Namespace(self.object_type), EntityId(self.object_id))
+
+    def to_relation(self) -> Relation:
+        return Relation(self.relation)
+
+    def to_subject(self) -> Subject:
+        return Subject(Namespace(self.subject_type), EntityId(self.subject_id))
+
+    def to_filter(self) -> TupleFilter:
+        """Convert to a TupleFilter for backing tuple lookups."""
+        return TupleFilter(
+            object_type=self.object_type,
+            object_id=self.object_id,
+            relation=self.relation,
+            subject_type=self.subject_type,
+            subject_id=self.subject_id,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResponse:
+    """Response with permission decision and optional debug info"""
+
+    allowed: bool
+    debug_trace: list[str] | None = None
+    depth_reached: int = 0
+    tuples_examined: int = 0

zanzipy/models/errors.py

@@ -0,0 +1,14 @@
+class InvalidTupleFormatError(ValueError):
+    """Raised when relation tuple components are invalid or malformed."""
+
+
+class IdentifierValidationError(ValueError):
+    """Raised when an identifier value is invalid."""
+
+
+class EntityIdValidationError(ValueError):
+    """Raised when an entity id value is invalid."""
+
+
+class SubjectValidationError(ValueError):
+    """Raised when a subject string or components are invalid."""

zanzipy/models/filter.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .object import Obj
+    from .relation import Relation as Rel
+    from .subject import Subject
+    from .tuple import RelationTuple
+
+
+@dataclass(frozen=True, slots=True)
+class TupleFilter:
+    """
+    Filter criteria for querying relation tuples.
+    All fields are optional - only specified fields are used for filtering.
+    """
+
+    object_type: str | None = None
+    object_id: str | None = None
+    relation: str | None = None
+    subject_type: str | None = None
+    subject_id: str | None = None
+    subject_relation: str | None = None
+
+    def matches(self, tuple: RelationTuple) -> bool:
+        """Check if a tuple matches this filter."""
+        return (
+            self._matches_object(tuple)
+            and self._matches_relation(tuple)
+            and self._matches_subject(tuple)
+        )
+
+    def _matches_object(self, tuple: RelationTuple) -> bool:
+        if (
+            self.object_type is not None
+            and str(tuple.object.namespace) != self.object_type
+        ):
+            return False
+        return not (
+            self.object_id is not None and str(tuple.object.id) != self.object_id
+        )
+
+    def _matches_relation(self, tuple: RelationTuple) -> bool:
+        return not (self.relation is not None and str(tuple.relation) != self.relation)
+
+    def _matches_subject(self, tuple: RelationTuple) -> bool:
+        if (
+            self.subject_type is not None
+            and str(tuple.subject.namespace) != self.subject_type
+        ):
+            return False
+        if self.subject_id is not None and str(tuple.subject.id) != self.subject_id:
+            return False
+        if self.subject_relation is not None:
+            if tuple.subject.relation is None:
+                return False
+            if str(tuple.subject.relation) != self.subject_relation:
+                return False
+        return True
+
+    @classmethod
+    def from_object(cls, obj: Obj) -> TupleFilter:
+        """Create a filter matching the given object (type and id)."""
+        return cls(
+            object_type=str(obj.namespace),
+            object_id=str(obj.id),
+        )
+
+    @classmethod
+    def from_relation(cls, relation: Rel) -> TupleFilter:
+        """Create a filter matching the given relation name."""
+        return cls(relation=str(relation))
+
+    @classmethod
+    def from_subject(cls, subject: Subject) -> TupleFilter:
+        """Create a filter matching the given subject (type/id and optional rel)."""
+        return cls(
+            subject_type=str(subject.namespace),
+            subject_id=str(subject.id),
+            subject_relation=(
+                str(subject.relation) if subject.relation is not None else None
+            ),
+        )
+
+    @classmethod
+    def from_parts(
+        cls,
+        obj: Obj | None = None,
+        relation: Rel | None = None,
+        subject: Subject | None = None,
+    ) -> TupleFilter:
+        """Create a filter from any subset of object, relation, and subject."""
+        return cls(
+            object_type=str(obj.namespace) if obj is not None else None,
+            object_id=str(obj.id) if obj is not None else None,
+            relation=str(relation) if relation is not None else None,
+            subject_type=str(subject.namespace) if subject is not None else None,
+            subject_id=str(subject.id) if subject is not None else None,
+            subject_relation=(
+                str(subject.relation)
+                if subject is not None and subject.relation is not None
+                else None
+            ),
+        )

zanzipy/models/id.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import ClassVar
+
+from .errors import EntityIdValidationError
+
+
+@dataclass(frozen=True, slots=True)
+class EntityId:
+    """
+    Valid entity id for object_id and subject_id.
+
+    Rules:
+    - Cannot contain '#', '@', ':', or whitespace
+    - Otherwise may contain any unicode characters
+    """
+
+    _ID_CHARS: ClassVar[re.Pattern] = re.compile(r"^[^#@:\s]+$")
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value:
+            raise EntityIdValidationError("id cannot be empty")
+        if not self._ID_CHARS.match(self.value):
+            raise EntityIdValidationError(
+                "id cannot contain '#', '@', ':', or whitespace characters"
+            )
+
+    def __str__(self) -> str:
+        return self.value

zanzipy/models/identifier.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import ClassVar
+
+from .errors import IdentifierValidationError
+
+
+@dataclass(frozen=True, slots=True)
+class Identifier:
+    """
+    Valid Zanzibar identifier for namespaces and relations.
+
+    Rules:
+    - Start with a letter or underscore
+    - Contain letters, digits, underscores, or hyphens
+    """
+
+    _IDENTIFIER: ClassVar[re.Pattern] = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_-]*$")
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not self.value:
+            raise IdentifierValidationError("identifier cannot be empty")
+        if not self._IDENTIFIER.match(self.value):
+            raise IdentifierValidationError(
+                "identifier must be a valid identifier (letters/digits/_/-, start with "
+                "letter/_)"
+            )
+
+    def __str__(self) -> str:
+        return self.value

zanzipy/models/namespace.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .identifier import Identifier
+
+
+@dataclass(frozen=True, slots=True)
+class Namespace(Identifier):
+    """Namespace value object (inherits Identifier validation)."""

zanzipy/models/object.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .id import EntityId
+    from .namespace import Namespace
+
+
+@dataclass(frozen=True, slots=True)
+class Obj:
+    """Object value with namespace and id."""
+
+    namespace: Namespace
+    id: EntityId
+
+    def __str__(self) -> str:
+        return f"{self.namespace}:{self.id}"

zanzipy/models/relation.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .identifier import Identifier
+
+
+@dataclass(frozen=True, slots=True)
+class Relation(Identifier):
+    """Relation value object (inherits Identifier validation)."""

zanzipy/models/subject.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Self
+
+from .errors import (
+    SubjectValidationError,
+)
+from .id import EntityId
+from .namespace import Namespace
+from .relation import Relation
+
+
+@dataclass(frozen=True, slots=True)
+class Subject:
+    """
+    Subject value object that can represent a direct subject or a subject set.
+
+    Forms:
+    - namespace:id
+    - namespace:id#relation
+    """
+
+    namespace: Namespace
+    id: EntityId
+    relation: Relation | None = None
+
+    @classmethod
+    def parse(cls, subject_string: str) -> Self:
+        # Split only once on '#'
+        if "#" in subject_string:
+            base, rel = subject_string.split("#", 1)
+            if rel == "":
+                raise SubjectValidationError("subject_relation cannot be empty string")
+            relation = Relation(rel)
+        else:
+            base = subject_string
+            relation = None
+
+        if ":" not in base:
+            raise SubjectValidationError("subject must be in 'namespace:id' form")
+        ns_str, id_str = base.split(":", 1)
+
+        namespace = Namespace(ns_str)
+        entity_id = EntityId(id_str)
+
+        return cls(namespace, entity_id, relation)
+
+    def __str__(self) -> str:
+        base = f"{self.namespace}:{self.id}"
+        return f"{base}#{self.relation}" if self.relation is not None else base

zanzipy/models/tuple.py

@@ -0,0 +1,206 @@
+from dataclasses import dataclass
+import re
+from typing import ClassVar, Self
+
+from .errors import InvalidTupleFormatError
+from .id import EntityId
+from .namespace import Namespace
+from .object import Obj
+from .relation import Relation
+from .subject import Subject
+
+
+@dataclass(frozen=True, slots=True)
+class RelationTuple:
+    """
+    Represents a Zanzibar relationship tuple.
+
+    Format:
+        `object_namespace:object_id#relation@subject_namespace:subject_id[#subject_relation]`
+
+    Constraints:
+        - Namespaces and relations must be valid identifiers (alphanumeric, underscore,
+          or hyphen, starting with letter or underscore)
+        - IDs may contain any characters except `#`, `@`, `:`, and whitespace
+        - subject_relation follows the same rules as relation
+        - No component may be empty
+
+    Examples:
+        - `document:readme#owner@user:alice`
+        - `folder:docs#viewer@group:eng#member`
+        - `doc:uuid-123-abc#can_read@user:bob`
+
+    Attributes:
+        object: The object being related (contains namespace and id)
+        relation: The relation name (e.g., 'owner', 'viewer', 'can_read')
+        subject: The subject entity (contains namespace, id, and optional
+            relation for subject sets)
+
+    Note:
+        Instances are immutable and hashable, suitable for use in sets and as dict keys.
+    """
+
+    # Complete tuple parsing pattern
+    _TUPLE_PATTERN: ClassVar[re.Pattern] = re.compile(
+        r"^(?P<object_namespace>[a-zA-Z_][a-zA-Z0-9_-]*)"  # object namespace
+        r":(?P<object_id>[^#@:\s]+)"  # object id
+        r"#(?P<relation>[a-zA-Z_][a-zA-Z0-9_-]*)"  # relation
+        r"@(?P<subject_namespace>[a-zA-Z_][a-zA-Z0-9_-]*)"  # subject namespace
+        r":(?P<subject_id>[^#@:\s]+)"  # subject id
+        r"(?:#(?P<subject_relation>[a-zA-Z_][a-zA-Z0-9_-]*))?$"  # optional subject rel
+    )
+
+    object: Obj
+    relation: Relation
+    subject: Subject
+
+    @classmethod
+    def from_string(cls, tuple_string: str) -> "RelationTuple":
+        """Parse a Zanzibar relation tuple string.
+
+        Args:
+            tuple_string:
+                String in format
+                `object_namespace:object_id#relation@subject_namespace:subject_id[#subject_relation]`
+
+        Returns:
+            RelationTuple instance
+
+        Raises:
+            InvalidTupleFormatError: If the string doesn't match the expected format
+
+        Examples:
+            >>> RelationTuple.from_string("document:readme#owner@user:alice")
+            >>> RelationTuple.from_string("folder:docs#viewer@group:eng#member")
+        """
+        match = cls._TUPLE_PATTERN.match(tuple_string)
+        if not match:
+            raise InvalidTupleFormatError(
+                f"Invalid tuple format: '{tuple_string}'. "
+                "Expected: 'object_namespace:object_id#relation@subject_namespace:"
+                "subject_id[#subject_relation]'. "
+                "Namespaces and relations must be valid identifiers "
+                "(letters/digits/_/-, start with letter/_). "
+                "IDs may contain any characters except '#', '@', ':', and whitespace. "
+                "No component may be empty."
+            )
+
+        groups = match.groupdict()
+        subject_relation = groups["subject_relation"]
+        return cls(
+            object=Obj(
+                Namespace(groups["object_namespace"]),
+                EntityId(groups["object_id"]),
+            ),
+            relation=Relation(groups["relation"]),
+            subject=Subject(
+                Namespace(groups["subject_namespace"]),
+                EntityId(groups["subject_id"]),
+                Relation(subject_relation) if subject_relation is not None else None,
+            ),
+        )
+
+    def to_dict(self) -> dict:
+        """Return a dictionary representation of the tuple.
+
+        Returns:
+            dict: Dictionary representation of the tuple
+
+        Examples:
+            ```python
+            >>> RelationTuple.from_string("document:readme#owner@user:alice").to_dict()
+            {
+                'object_namespace': 'document',
+                'object_id': 'readme',
+                'relation': 'owner',
+                'subject_namespace': 'user',
+                'subject_id': 'alice',
+                'subject_relation': None
+            }
+            ```
+        """
+        return {
+            "object_namespace": str(self.object.namespace),
+            "object_id": str(self.object.id),
+            "relation": str(self.relation),
+            "subject_namespace": str(self.subject.namespace),
+            "subject_id": str(self.subject.id),
+            "subject_relation": (
+                str(self.subject.relation)
+                if self.subject.relation is not None
+                else None
+            ),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Self:
+        """Create a RelationTuple from a dictionary.
+
+        Args:
+            data: Dictionary representation of the tuple
+
+        Returns:
+            RelationTuple: RelationTuple instance
+
+        Examples:
+            ```python
+            >>> RelationTuple.from_dict({
+            ...     "object_namespace": "document",
+            ...     "object_id": "readme",
+            ...     "relation": "owner",
+            ...     "subject_namespace": "user",
+            ...     "subject_id": "alice",
+            ... })
+            RelationTuple(
+                object_namespace='document',
+                object_id='readme',
+                relation='owner',
+                subject_namespace='user',
+                subject_id='alice',
+                subject_relation=None
+            )
+            ```
+        """
+        # Treat presence of key with empty string as invalid
+        if "subject_relation" in data and data["subject_relation"] == "":
+            # This will raise IdentifierValidationError
+            subject_rel = Relation("")
+        else:
+            subject_rel = (
+                Relation(data["subject_relation"])
+                if data.get("subject_relation")
+                else None
+            )
+        return cls(
+            object=Obj(
+                Namespace(data["object_namespace"]),
+                EntityId(data["object_id"]),
+            ),
+            relation=Relation(data["relation"]),
+            subject=Subject(
+                Namespace(data["subject_namespace"]),
+                EntityId(data["subject_id"]),
+                subject_rel,
+            ),
+        )
+
+    def __str__(self) -> str:
+        """Return canonical string representation of the tuple."""
+        object_str = str(self.object)
+        subject_str = str(self.subject)
+        return f"{object_str}#{self.relation}@{subject_str}"
+
+    def __repr__(self) -> str:
+        """Return detailed representation for debugging."""
+        subject_relation_repr = (
+            str(self.subject.relation) if self.subject.relation is not None else None
+        )
+        return (
+            f"RelationTuple("
+            f"object_namespace={str(self.object.namespace)!r}, "
+            f"object_id={str(self.object.id)!r}, "
+            f"relation={str(self.relation)!r}, "
+            f"subject_namespace={str(self.subject.namespace)!r}, "
+            f"subject_id={str(self.subject.id)!r}, "
+            f"subject_relation={subject_relation_repr!r})"
+        )

zanzipy/schema/permissions.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+from ..models.relation import Relation as Rel
+from .rules import RewriteRule
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionDef:
+    """Defines a computed permission: rewrite expression only."""
+
+    name: str
+    rewrite: RewriteRule
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        # Validate permission name as a relation identifier
+        Rel(self.name)
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "permission",
+            "name": self.name,
+            "rewrite": self.rewrite.to_dict(),
+            "description": self.description,
+        }

zanzipy/schema/relations.py

@@ -0,0 +1,56 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from ..models.relation import Relation as Rel
+from .rules import RewriteRule
+from .subjects import SubjectReference
+
+
+@dataclass(frozen=True, slots=True)
+class RelationDef:
+    """Defines a relation: allowed subject types and optional rewrite.
+
+    Note: Relations must declare at least one allowed subject.
+    """
+
+    name: str
+    allowed_subjects: tuple[SubjectReference, ...]
+    rewrite: RewriteRule | None = None
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        # Validate relation name
+        Rel(self.name)
+        if not self.allowed_subjects:
+            raise ValueError("Relation must declare at least one allowed subject type")
+
+    @classmethod
+    def with_subjects(
+        cls,
+        name: str,
+        subjects: Iterable[SubjectReference],
+        rewrite: RewriteRule | None = None,
+        description: str | None = None,
+    ) -> "RelationDef":
+        return cls(
+            name=name,
+            allowed_subjects=tuple(subjects),
+            rewrite=rewrite,
+            description=description,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "relation",
+            "name": self.name,
+            "allowed_subjects": [
+                {
+                    "namespace": s.namespace.value,
+                    "relation": (s.relation.value if s.relation else None),
+                    "wildcard": s.wildcard,
+                }
+                for s in self.allowed_subjects
+            ],
+            "rewrite": self.rewrite.to_dict() if self.rewrite else None,
+            "description": self.description,
+        }

zanzipy/schema/rules.py

@@ -0,0 +1,211 @@
+"""Rewrite rules for Zanzibar-style relation/permission definitions.
+
+This module models the minimal set of rewrite rules used to compose
+relations and permissions. Rules are exported to a portable dictionary
+format (for JSON, etc.).
+
+What this models
+----------------
+- A small algebra of rewrite nodes that mirrors Zanzibar:
+  - Leaf nodes:
+    - ThisRule: refers to direct tuple membership of the relation ("this").
+      Only valid in relation rewrites.
+    - ComputedUsersetRule: refers to another relation by name within the same
+      namespace (e.g., "viewer").
+    - TupleToUsersetRule: follows a relation from the object to a relation on
+      the subject (e.g., "parent->viewer").
+  - Operators:
+    - UnionRule: any child grants access ("+").
+    - IntersectionRule: all children required ("&").
+    - ExclusionRule: base minus subtract ("-").
+
+- Permissions are built purely from rewrite nodes; relations can optionally
+  include rewrites and may also include ThisRule to incorporate direct tuples.
+
+Examples
+--------
+- Direct stored relation (no rewrite):
+    relation owner: user
+  Represented as:
+    DirectRule()
+
+- Relation with direct tuples plus a subject-set:
+    relation editor: user | group#member = this + group#member
+  Represented as:
+    UnionRule(
+        children=(ThisRule(), ComputedUsersetRule("group#member"))
+    )
+
+- Permission that any owner or editor may access:
+    permission can_view = owner + editor
+  Represented as:
+    UnionRule(
+        children=(
+            ComputedUsersetRule("owner"),
+            ComputedUsersetRule("editor"),
+        )
+    )
+
+- Permission that requires both member and not banned:
+    permission can_comment = member - banned
+  Represented as:
+    ExclusionRule(
+        base=ComputedUsersetRule("member"),
+        subtract=ComputedUsersetRule("banned"),
+    )
+
+- Permission that requires both viewer and member:
+    permission can_download = viewer & member
+  Represented as:
+    IntersectionRule(
+        children=(
+            ComputedUsersetRule("viewer"),
+            ComputedUsersetRule("member"),
+        )
+    )
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Literal
+
+# Type aliases for readability
+RelationName = str
+
+
+class RewriteRule(ABC):
+    """Base class for relation rewrite rules"""
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        """Serialize to portable JSON format"""
+        pass
+
+
+@dataclass(frozen=True)
+class ThisRule(RewriteRule):
+    """Leaf that references the direct (stored) membership of the relation."""
+
+    type: Literal["this"] = field(default="this", init=False)
+
+    def to_dict(self) -> dict:
+        return {"type": self.type}
+
+
+@dataclass(frozen=True)
+class ComputedUsersetRule(RewriteRule):
+    """Leaf that references another relation by name."""
+
+    relation: RelationName
+
+    type: Literal["computed_userset"] = field(default="computed_userset", init=False)
+
+    def to_dict(self) -> dict:
+        return {"type": self.type, "relation": self.relation}
+
+
+@dataclass(frozen=True)
+class TupleToUsersetRule(RewriteRule):
+    """Tuple-to-userset: follow a relation on the object
+    to a relation on the subject."""
+
+    tuple_relation: RelationName
+    computed_relation: RelationName
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type,
+            "tuple_relation": self.tuple_relation,
+            "computed_relation": self.computed_relation,
+        }
+
+    type: Literal["tuple_to_userset"] = field(default="tuple_to_userset", init=False)
+
+
+@dataclass(frozen=True)
+class DirectRule(RewriteRule):
+    """Direct relation assignment (stored tuples).
+
+    Direct rules indicate that the relation is backed only by stored tuples
+    (no rewrite).
+
+    Example:
+        relation owner: user  ->  DirectRule()
+    """
+
+    type: Literal["direct"] = field(default="direct", init=False)
+
+    def to_dict(self) -> dict:
+        return {"type": self.type}
+
+
+@dataclass(frozen=True)
+class UnionRule(RewriteRule):
+    """Union: access is granted if any of the children relations grant it.
+
+
+    Example:
+        permission can_view = owner + editor
+        -> UnionRule(children=(
+            ComputedUsersetRule("owner"),
+            ComputedUsersetRule("editor"),
+        ))
+    """
+
+    # Children are nested rewrite rules; operands must be typed nodes
+    children: tuple[RewriteRule, ...]
+
+    def to_dict(self) -> dict:
+        return {"type": self.type, "children": [c.to_dict() for c in self.children]}
+
+    type: Literal["union"] = field(default="union", init=False)
+
+
+@dataclass(frozen=True)
+class IntersectionRule(RewriteRule):
+    """Intersection: access requires all children relations to grant it.
+
+
+    Example:
+        permission can_download = viewer & member
+        -> IntersectionRule(children=(
+            ComputedUsersetRule("viewer"),
+            ComputedUsersetRule("member"),
+        ))
+    """
+
+    # Children are nested rewrite rules; operands must be typed nodes
+    children: tuple[RewriteRule, ...]
+
+    def to_dict(self) -> dict:
+        return {"type": self.type, "children": [c.to_dict() for c in self.children]}
+
+    type: Literal["intersection"] = field(default="intersection", init=False)
+
+
+@dataclass(frozen=True)
+class ExclusionRule(RewriteRule):
+    """Exclusion: grant from base but not from subtract.
+
+    The expression is ``base - subtract``.
+
+    Example:
+        permission can_comment = member - banned
+        -> ExclusionRule(
+            base=ComputedUsersetRule("member"),
+            subtract=ComputedUsersetRule("banned"),
+        )
+    """
+
+    # Operands are nested rewrite rules; operands must be typed nodes
+    base: RewriteRule
+    subtract: RewriteRule
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type,
+            "base": self.base.to_dict(),
+            "subtract": self.subtract.to_dict(),
+        }
+
+    type: Literal["exclusion"] = field(default="exclusion", init=False)

zanzipy/schema/subjects.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+
+from ..models.namespace import Namespace
+from ..models.relation import Relation as Rel
+
+
+@dataclass(frozen=True, slots=True)
+class SubjectReference:
+    """Represents an allowed subject type for a relation.
+
+    Forms supported (SpiceDB compatible):
+    - "ns" (e.g., user)
+    - "ns#rel" (e.g., group#member)
+    - "ns:*" (namespace wildcard)
+    """
+
+    namespace: Namespace
+    relation: Rel | None = None
+    wildcard: bool = False
+
+    def __post_init__(self) -> None:
+        # Validate invariant combinations
+        if self.wildcard and self.relation is not None:
+            raise ValueError("wildcard and relation are mutually exclusive")

zanzipy-0.1.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.3
+Name: zanzipy
+Version: 0.1.0
+Summary: Building blocks for zanzibar style ReBAC
+Keywords: rebac,zanzibar,authorization,acl,relations
+Author: Tyler Chambers
+License:                                  Apache License
+                                    Version 2.0, January 2004
+                                 http://www.apache.org/licenses/
+         
+            TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+         
+            1. Definitions.
+         
+               "License" shall mean the terms and conditions for use, reproduction,
+               and distribution as defined by Sections 1 through 9 of this document.
+         
+               "Licensor" shall mean the copyright owner or entity authorized by
+               the copyright owner that is granting the License.
+         
+               "Legal Entity" shall mean the union of the acting entity and all
+               other entities that control, are controlled by, or are under common
+               control with that entity. For the purposes of this definition,
+               "control" means (i) the power, direct or indirect, to cause the
+               direction or management of such entity, whether by contract or
+               otherwise, or (ii) ownership of fifty percent (50%) or more of the
+               outstanding shares, or (iii) beneficial ownership of such entity.
+         
+               "You" (or "Your") shall mean an individual or Legal Entity
+               exercising permissions granted by this License.
+         
+               "Source" form shall mean the preferred form for making modifications,
+               including but not limited to software source code, documentation
+               source, and configuration files.
+         
+               "Object" form shall mean any form resulting from mechanical
+               transformation or translation of a Source form, including but
+               not limited to compiled object code, generated documentation,
+               and conversions to other media types.
+         
+               "Work" shall mean the work of authorship, whether in Source or
+               Object form, made available under the License, as indicated by a
+               copyright notice that is included in or attached to the work
+               (an example is provided in the Appendix below).
+         
+               "Derivative Works" shall mean any work, whether in Source or Object
+               form, that is based on (or derived from) the Work and for which the
+               editorial revisions, annotations, elaborations, or other modifications
+               represent, as a whole, an original work of authorship. For the purposes
+               of this License, Derivative Works shall not include works that remain
+               separable from, or merely link (or bind by name) to the interfaces of,
+               the Work and Derivative Works thereof.
+         
+               "Contribution" shall mean any work of authorship, including
+               the original version of the Work and any modifications or additions
+               to that Work or Derivative Works thereof, that is intentionally
+               submitted to Licensor for inclusion in the Work by the copyright owner
+               or by an individual or Legal Entity authorized to submit on behalf of
+               the copyright owner. For the purposes of this definition, "submitted"
+               means any form of electronic, verbal, or written communication sent
+               to the Licensor or its representatives, including but not limited to
+               communication on electronic mailing lists, source code control systems,
+               and issue tracking systems that are managed by, or on behalf of, the
+               Licensor for the purpose of discussing and improving the Work, but
+               excluding communication that is conspicuously marked or otherwise
+               designated in writing by the copyright owner as "Not a Contribution."
+         
+               "Contributor" shall mean Licensor and any individual or Legal Entity
+               on behalf of whom a Contribution has been received by Licensor and
+               subsequently incorporated within the Work.
+         
+            2. Grant of Copyright License. Subject to the terms and conditions of
+               this License, each Contributor hereby grants to You a perpetual,
+               worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+               copyright license to reproduce, prepare Derivative Works of,
+               publicly display, publicly perform, sublicense, and distribute the
+               Work and such Derivative Works in Source or Object form.
+         
+            3. Grant of Patent License. Subject to the terms and conditions of
+               this License, each Contributor hereby grants to You a perpetual,
+               worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+               (except as stated in this section) patent license to make, have made,
+               use, offer to sell, sell, import, and otherwise transfer the Work,
+               where such license applies only to those patent claims licensable
+               by such Contributor that are necessarily infringed by their
+               Contribution(s) alone or by combination of their Contribution(s)
+               with the Work to which such Contribution(s) was submitted. If You
+               institute patent litigation against any entity (including a
+               cross-claim or counterclaim in a lawsuit) alleging that the Work
+               or a Contribution incorporated within the Work constitutes direct
+               or contributory patent infringement, then any patent licenses
+               granted to You under this License for that Work shall terminate
+               as of the date such litigation is filed.
+         
+            4. Redistribution. You may reproduce and distribute copies of the
+               Work or Derivative Works thereof in any medium, with or without
+               modifications, and in Source or Object form, provided that You
+               meet the following conditions:
+         
+               (a) You must give any other recipients of the Work or
+                   Derivative Works a copy of this License; and
+         
+               (b) You must cause any modified files to carry prominent notices
+                   stating that You changed the files; and
+         
+               (c) You must retain, in the Source form of any Derivative Works
+                   that You distribute, all copyright, patent, trademark, and
+                   attribution notices from the Source form of the Work,
+                   excluding those notices that do not pertain to any part of
+                   the Derivative Works; and
+         
+               (d) If the Work includes a "NOTICE" text file as part of its
+                   distribution, then any Derivative Works that You distribute must
+                   include a readable copy of the attribution notices contained
+                   within such NOTICE file, excluding those notices that do not
+                   pertain to any part of the Derivative Works, in at least one
+                   of the following places: within a NOTICE text file distributed
+                   as part of the Derivative Works; within the Source form or
+                   documentation, if provided along with the Derivative Works; or,
+                   within a display generated by the Derivative Works, if and
+                   wherever such third-party notices normally appear. The contents
+                   of the NOTICE file are for informational purposes only and
+                   do not modify the License. You may add Your own attribution
+                   notices within Derivative Works that You distribute, alongside
+                   or as an addendum to the NOTICE text from the Work, provided
+                   that such additional attribution notices cannot be construed
+                   as modifying the License.
+         
+               You may add Your own copyright statement to Your modifications and
+               may provide additional or different license terms and conditions
+               for use, reproduction, or distribution of Your modifications, or
+               for any such Derivative Works as a whole, provided Your use,
+               reproduction, and distribution of the Work otherwise complies with
+               the conditions stated in this License.
+         
+            5. Submission of Contributions. Unless You explicitly state otherwise,
+               any Contribution intentionally submitted for inclusion in the Work
+               by You to the Licensor shall be under the terms and conditions of
+               this License, without any additional terms or conditions.
+               Notwithstanding the above, nothing herein shall supersede or modify
+               the terms of any separate license agreement you may have executed
+               with Licensor regarding such Contributions.
+         
+            6. Trademarks. This License does not grant permission to use the trade
+               names, trademarks, service marks, or product names of the Licensor,
+               except as required for reasonable and customary use in describing the
+               origin of the Work and reproducing the content of the NOTICE file.
+         
+            7. Disclaimer of Warranty. Unless required by applicable law or
+               agreed to in writing, Licensor provides the Work (and each
+               Contributor provides its Contributions) on an "AS IS" BASIS,
+               WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+               implied, including, without limitation, any warranties or conditions
+               of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+               PARTICULAR PURPOSE. You are solely responsible for determining the
+               appropriateness of using or redistributing the Work and assume any
+               risks associated with Your exercise of permissions under this License.
+         
+            8. Limitation of Liability. In no event and under no legal theory,
+               whether in tort (including negligence), contract, or otherwise,
+               unless required by applicable law (such as deliberate and grossly
+               negligent acts) or agreed to in writing, shall any Contributor be
+               liable to You for damages, including any direct, indirect, special,
+               incidental, or consequential damages of any character arising as a
+               result of this License or out of the use or inability to use the
+               Work (including but not limited to damages for loss of goodwill,
+               work stoppage, computer failure or malfunction, or any and all
+               other commercial damages or losses), even if such Contributor
+               has been advised of the possibility of such damages.
+         
+            9. Accepting Warranty or Additional Liability. While redistributing
+               the Work or Derivative Works thereof, You may choose to offer,
+               and charge a fee for, acceptance of support, warranty, indemnity,
+               or other liability obligations and/or rights consistent with this
+               License. However, in accepting such obligations, You may act only
+               on Your own behalf and on Your sole responsibility, not on behalf
+               of any other Contributor, and only if You agree to indemnify,
+               defend, and hold each Contributor harmless for any liability
+               incurred by, or claims asserted against, such Contributor by reason
+               of your accepting any such warranty or additional liability.
+         
+            END OF TERMS AND CONDITIONS
+         
+            APPENDIX: How to apply the Apache License to your work.
+         
+               To apply the Apache License to your work, attach the following
+               boilerplate notice, with the fields enclosed by brackets "[]"
+               replaced with your own identifying information. (Don't include
+               the brackets!)  The text should be enclosed in the appropriate
+               comment syntax for the file format. We also recommend that a
+               file or class name and description of purpose be included on the
+               same "printed page" as the copyright notice for easier
+               identification within third-party archives.
+         
+            Copyright [yyyy] [name of copyright owner]
+         
+            Licensed under the Apache License, Version 2.0 (the "License");
+            you may not use this file except in compliance with the License.
+            You may obtain a copy of the License at
+         
+                http://www.apache.org/licenses/LICENSE-2.0
+         
+            Unless required by applicable law or agreed to in writing, software
+            distributed under the License is distributed on an "AS IS" BASIS,
+            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+            See the License for the specific language governing permissions and
+            limitations under the License.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Homepage, https://gitlab.com/tylerchambers/zanzipy
+Project-URL: Issues, https://gitlab.com/tylerchambers/zanzipy/-/issues
+Project-URL: Repository, https://gitlab.com/tylerchambers/zanzipy
+Description-Content-Type: text/markdown
+
+# zanzipy
+
+A clean, Pythonic implementation of Google's Zanzibar authorization system. Just add persistence and caching.

zanzipy-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+zanzipy/__init__.py,sha256=MnoTdu1KVnbwLtkaBzHnCwjZNZMSOVez3mn4fDNmgDc,155
+zanzipy/models/__init__.py,sha256=wNT-SJ1ZFfED6SqiyxQud3UhlSVNLR2LLYeY8XtAEbk,605
+zanzipy/models/check.py,sha256=jt1qrEX39jlXPiqhGbnB1tyE478On5cEarOTzxDt18k,4210
+zanzipy/models/errors.py,sha256=5toJP9nImLwtY4E6npkJMtmDU4efP467i1UrPk526xM,426
+zanzipy/models/filter.py,sha256=O_QIE4k6HUS5qxjeSYSXE7MjUGNWbup1MiJPAb2JX3I,3663
+zanzipy/models/id.py,sha256=x_CAZ79f_HPzq2foiJ5D9otlJD7m4uAKIeaQNLqqI6E,836
+zanzipy/models/identifier.py,sha256=8563b39AfPfgu2iZyI8qWFWiQOBGwcWWhM0Dd3zPa9w,915
+zanzipy/models/namespace.py,sha256=59QKJy15lpv40PVISuCBelghaOkA9Maypz-joNMExu0,240
+zanzipy/models/object.py,sha256=v4y7ot67kzPwRzECj0Lpz6kI22FP0lEvFxq92k8X6gU,402
+zanzipy/models/relation.py,sha256=tYC6Gfq2iK_DrBgQbU1b3tgkyL0dfJD1g3ZSttGE_jo,238
+zanzipy/models/subject.py,sha256=WJe2qm5knm-GdVKSbIFG8H3JfDvPZwHSYpXtqNhIV0w,1377
+zanzipy/models/tuple.py,sha256=Vo1Y0TuFt7YyfGzBijTGmH-usbDW4Bnki3DzdJ9nmEc,7328
+zanzipy/schema/permissions.py,sha256=NepF3DdkQBRw8ymFZ48ayifmKRtzQj15vy60CnKSmvE,649
+zanzipy/schema/relations.py,sha256=tf16tagZU_su17rkfGwDIGHIb8qCpnGTDyhSNtRVCCE,1684
+zanzipy/schema/rules.py,sha256=cc-bmt8ZQYy8EU59RGIe5WOHyVJmtk63GCq5y0PLPC0,5961
+zanzipy/schema/subjects.py,sha256=cLHWl2TItkucL6k04bDsU7gBx5tfnXovx48otYxgiWs,685
+zanzipy-0.1.0.dist-info/WHEEL,sha256=ZbtZh9LqsQoZs-WmwRO6z-tavdkb5LzNxvrOv2F_OXE,78
+zanzipy-0.1.0.dist-info/METADATA,sha256=V-yGgzB1yqnxIqeuyw2qNiF1N8ePsZRjOZMmWBbopzk,13993
+zanzipy-0.1.0.dist-info/RECORD,,

zanzipy-0.1.0.dist-info/WHEEL

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