loom-kernel 2.9.0__tar.gz → 2.10.0__tar.gz

{loom_kernel-2.9.0 → loom_kernel-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.9.0
+Version: 2.10.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.9.0 → loom_kernel-2.10.0}/src/loom/core/authz/_decide.py

@@ -4,8 +4,9 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 from dataclasses import dataclass
+from datetime import datetime
 
-from loom.core.authz._grants import Grant
+from loom.core.authz._grants import Grant, require_aware
 from loom.core.authz._roles import Permission, RoleCatalog
 from loom.core.authz._scope import Scope
 
@@ -54,8 +55,41 @@ class GrantCheck:
         return self.allowed
 
 
-def _specificity(grant: Grant) -> tuple[int, str, str]:
-    return (-len(grant.scope.path), grant.role, grant.subject)
+_FOREVER = float("-inf")
+
+
+def _rank(grant: Grant) -> tuple[int, str, str, float]:
+    lifetime = _FOREVER if grant.expires_at is None else -grant.expires_at.timestamp()
+    return (-len(grant.scope.path), grant.role, grant.subject, lifetime)
+
+
+def _check_now(now: datetime | None) -> None:
+    if now is not None:
+        require_aware("now", now)
+
+
+def _require_now_for_expiring(grants: tuple[Grant, ...], now: datetime | None) -> None:
+    expiry = next((grant.expires_at for grant in grants if grant.expires_at is not None), None)
+    if now is None and expiry is not None:
+        raise ValueError(
+            f"A grant expires at {expiry.isoformat()}; pass now= to decide whether it is alive."
+        )
+
+
+def _alive(grant: Grant, now: datetime | None) -> bool:
+    return grant.expires_at is None or (now is not None and now < grant.expires_at)
+
+
+def _covering_paths(scope: Scope) -> frozenset[tuple[str, ...]]:
+    return frozenset(scope.path[:depth] for depth in range(len(scope.path) + 1))
+
+
+def _outermost(scopes: set[Scope]) -> frozenset[Scope]:
+    return frozenset(
+        scope
+        for scope in scopes
+        if not any(other != scope and other.covers(scope) for other in scopes)
+    )
 
 
 def evaluate(
@@ -63,6 +97,8 @@ def evaluate(
     grants: Iterable[Grant],
     permission: Permission,
     scope: Scope,
+    *,
+    now: datetime | None = None,
 ) -> Decision:
     """Decide whether a subject holds *permission* on *scope*.
 
@@ -70,30 +106,38 @@ def evaluate(
     scope covering *scope*.  A grant whose role the catalog does not declare
     allows nothing.  When several grants allow, the decision names the one on
     the deepest scope, then the first by role name and subject, regardless of
-    the order of *grants*.
+    the order of *grants*; among grants that tie there, the one that lives
+    longest.  A grant is alive while *now* is before its expiry; an expired
+    grant counts as absent.
 
     Args:
         catalog: The product's roles.
         grants: The grants of one subject.
         permission: The capability being exercised.
         scope: Where it is exercised.
+        now: The timezone-aware instant of the decision; needed only when
+            some grant carries an expiry.
 
     Returns:
         The decision, carrying the grant that allowed it.
 
     Raises:
         UnknownPermission: When *permission* is not declared in the catalog.
+        TypeError: When *now* is not a datetime.
+        ValueError: When *now* is naive, or is ``None`` while some grant
+            carries an expiry.
     """
+    _check_now(now)
+    held = tuple(grants)
+    _require_now_for_expiring(held, now)
     roles = catalog.roles_with(permission)
-    covering = {scope.path[:depth] for depth in range(len(scope.path) + 1)}
-    winner: Grant | None = None
-    for grant in grants:
-        if (
-            grant.role in roles
-            and grant.scope.path in covering
-            and (winner is None or _specificity(grant) < _specificity(winner))
-        ):
-            winner = grant
+    covering = _covering_paths(scope)
+    allowing = [
+        grant
+        for grant in held
+        if grant.role in roles and grant.scope.path in covering and _alive(grant, now)
+    ]
+    winner = min(allowing, key=_rank, default=None)
     return Decision(winner is not None, winner)
 
 
@@ -101,28 +145,36 @@ def scopes_with(
     catalog: RoleCatalog,
     grants: Iterable[Grant],
     permission: Permission,
+    *,
+    now: datetime | None = None,
 ) -> frozenset[Scope]:
     """Return the outermost scopes on which a subject holds *permission*.
 
     A scope covered by another returned scope is left out, so a listing can
-    be filtered with one :meth:`Scope.covers` test per returned scope.
+    be filtered with one :meth:`Scope.covers` test per returned scope.  An
+    expired grant counts as absent.
 
     Args:
         catalog: The product's roles.
         grants: The grants of one subject.
         permission: The capability being listed.
+        now: The timezone-aware instant of the listing; needed only when
+            some grant carries an expiry.
 
     Returns:
         The minimal set of scopes covering everything the subject may reach.
 
     Raises:
         UnknownPermission: When *permission* is not declared in the catalog.
+        TypeError: When *now* is not a datetime.
+        ValueError: When *now* is naive, or is ``None`` while some grant
+            carries an expiry.
     """
+    _check_now(now)
+    held = tuple(grants)
+    _require_now_for_expiring(held, now)
     roles = catalog.roles_with(permission)
-    held = {grant.scope for grant in grants if grant.role in roles}
-    return frozenset(
-        scope for scope in held if not any(other != scope and other.covers(scope) for other in held)
-    )
+    return _outermost({grant.scope for grant in held if grant.role in roles and _alive(grant, now)})
 
 
 def _delegation_check(
@@ -130,10 +182,13 @@ def _delegation_check(
     granter_grants: Iterable[Grant],
     needed: Iterable[Permission],
     scope: Scope,
+    now: datetime | None,
 ) -> GrantCheck:
     held = tuple(granter_grants)
     missing = frozenset(
-        permission for permission in needed if not evaluate(catalog, held, permission, scope)
+        permission
+        for permission in needed
+        if not evaluate(catalog, held, permission, scope, now=now)
     )
     return GrantCheck(not missing, missing)
 
@@ -145,11 +200,12 @@ def can_grant(
     scope: Scope,
     *,
     delegate: Permission,
+    now: datetime | None = None,
 ) -> GrantCheck:
     """Decide whether a granter may assign *role* on *scope*.
 
     The granter needs *delegate* and every permission of *role*, each held on
-    a scope covering *scope*.
+    a scope covering *scope* by a grant that is alive at *now*.
 
     Args:
         catalog: The product's roles.
@@ -157,6 +213,8 @@ def can_grant(
         role: Name of the role to assign.
         scope: Where it would apply.
         delegate: The permission that allows assigning roles at all.
+        now: The timezone-aware instant of the check; needed only when some
+            of the granter's grants carry an expiry.
 
     Returns:
         The check, listing the permissions the granter lacks there.
@@ -164,9 +222,13 @@ def can_grant(
     Raises:
         UnknownRole: When *role* is not declared in the catalog.
         UnknownPermission: When *delegate* is not declared in the catalog.
+        TypeError: When *now* is not a datetime.
+        ValueError: When *now* is naive, or is ``None`` while some of the
+            granter's grants carry an expiry.
     """
+    _check_now(now)
     needed = {delegate, *catalog.role(role).permissions}
-    return _delegation_check(catalog, granter_grants, needed, scope)
+    return _delegation_check(catalog, granter_grants, needed, scope, now)
 
 
 def can_revoke(
@@ -175,23 +237,31 @@ def can_revoke(
     grant: Grant,
     *,
     delegate: Permission,
+    now: datetime | None = None,
 ) -> GrantCheck:
     """Decide whether a granter may remove *grant*.
 
-    Revoking needs what granting it would.  A grant whose role the code does
-    not declare allows nothing, so removing it needs *delegate* only.
+    Revoking needs what granting it would, whether or not *grant* has
+    expired.  A grant whose role the code does not declare allows nothing, so
+    removing it needs *delegate* only.
 
     Args:
         catalog: The product's roles.
         granter_grants: The granter's grants.
         grant: The assignment to remove.
         delegate: The permission that allows assigning roles at all.
+        now: The timezone-aware instant of the check; needed only when some
+            of the granter's grants carry an expiry.
 
     Returns:
         The check, listing the permissions the granter lacks there.
 
     Raises:
         UnknownPermission: When *delegate* is not declared in the catalog.
+        TypeError: When *now* is not a datetime.
+        ValueError: When *now* is naive, or is ``None`` while some of the
+            granter's grants carry an expiry.
     """
+    _check_now(now)
     needed = {delegate, *(catalog.permissions_of(grant.role) or frozenset())}
-    return _delegation_check(catalog, granter_grants, needed, grant.scope)
+    return _delegation_check(catalog, granter_grants, needed, grant.scope, now)

loom_kernel-2.10.0/src/loom/core/authz/_grants.py

@@ -0,0 +1,135 @@
+"""Who holds which role where, and where those assignments come from."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Collection, Iterable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Protocol
+
+from loom.core.authz._roles import require_name
+from loom.core.authz._scope import Scope
+
+
+def require_aware(name: str, moment: datetime) -> None:
+    """Reject a moment that does not name a single instant.
+
+    Args:
+        name: What the moment is, for the error message.
+        moment: The moment to check.
+
+    Raises:
+        TypeError: When *moment* is not a datetime.
+        ValueError: When *moment* is naive.
+    """
+    if not isinstance(moment, datetime):
+        raise TypeError(f"{name} must be a datetime, not {type(moment).__name__}.")
+    if moment.utcoffset() is None:
+        raise ValueError(f"{name} must be timezone-aware: {moment!r}.")
+
+
+def _require_subject(subject: str) -> None:
+    if not subject:
+        raise ValueError("A grant needs a subject.")
+
+
+def _require_scope(scope: object) -> None:
+    if not isinstance(scope, Scope):
+        raise TypeError(f"A grant scope must be a Scope, not {type(scope).__name__}.")
+
+
+def _utc_or_none(name: str, moment: datetime | None) -> datetime | None:
+    if moment is None:
+        return None
+    require_aware(name, moment)
+    return moment.astimezone(UTC)
+
+
+_NEVER = (0,)
+
+
+@functools.total_ordering
+@dataclass(frozen=True, slots=True)
+class Grant:
+    """An assignment of a role to a subject on a scope, possibly until a moment.
+
+    Grants order by subject, role, scope and then expiry, with grants that
+    never expire before those that do, soonest first.
+
+    Attributes:
+        subject: Opaque identifier of the holder, such as an identity subject
+            or a service account id.
+        role: Name of the role; its permissions are looked up in the catalog
+            at decision time.
+        scope: Where the role applies, including everything below it.
+        expires_at: The timezone-aware instant from which the grant allows
+            nothing; ``None`` when it never expires.
+    """
+
+    subject: str
+    role: str
+    scope: Scope
+    expires_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Reject a grant with no holder, an unusable role name, no scope or a naive expiry."""
+        _require_subject(self.subject)
+        require_name("role", self.role)
+        _require_scope(self.scope)
+        object.__setattr__(self, "expires_at", _utc_or_none("A grant expiry", self.expires_at))
+
+    @property
+    def _sort_key(self) -> tuple[str, str, Scope, tuple[int] | tuple[int, datetime]]:
+        expiry = _NEVER if self.expires_at is None else (1, self.expires_at)
+        return (self.subject, self.role, self.scope, expiry)
+
+    def __lt__(self, other: object) -> bool:
+        """Order by subject, role, scope, then expiry."""
+        if not isinstance(other, Grant):
+            return NotImplemented
+        return self._sort_key < other._sort_key
+
+
+class GrantSource(Protocol):
+    """Where the grants of a subject are loaded from.
+
+    Any class with this method satisfies the protocol structurally, with no
+    inheritance required.
+    """
+
+    async def grants_for(self, subject: str) -> Collection[Grant]:
+        """Return every grant held by *subject*.
+
+        Args:
+            subject: Identifier of the holder.
+
+        Returns:
+            The subject's grants; empty when it holds none.
+        """
+        ...
+
+
+class InMemoryGrantSource:
+    """A :class:`GrantSource` over a fixed list, for tests and examples."""
+
+    __slots__ = ("_grants",)
+
+    def __init__(self, grants: Iterable[Grant]) -> None:
+        """Hold *grants*, deduplicated in their original order.
+
+        Args:
+            grants: Grants of any number of subjects.
+        """
+        self._grants = tuple(dict.fromkeys(grants))
+
+    async def grants_for(self, subject: str) -> Collection[Grant]:  # NOSONAR S7503 - protocol
+        """Return the grants of *subject*, in the order they were given.
+
+        Args:
+            subject: Identifier of the holder.
+
+        Returns:
+            The subject's grants.
+        """
+        return tuple(grant for grant in self._grants if grant.subject == subject)

{loom_kernel-2.9.0 → loom_kernel-2.10.0}/src/loom/core/authz/_scope.py

@@ -8,6 +8,22 @@ from dataclasses import dataclass
 _SEPARATOR = "/"
 
 
+def _segments_of(path: Iterable[str]) -> tuple[str, ...]:
+    if isinstance(path, str):
+        raise TypeError("A scope path is a sequence of segments, not a string; use Scope.parse().")
+    return tuple(map(_segment, path))
+
+
+def _segment(value: object) -> str:
+    if not isinstance(value, str):
+        raise TypeError(f"A scope segment must be a string: {value!r}.")
+    if not value or _SEPARATOR in value:
+        raise ValueError(
+            f"A scope segment must be non-empty and free of {_SEPARATOR!r}: {value!r}."
+        )
+    return value
+
+
 @dataclass(frozen=True, slots=True, order=True, init=False)
 class Scope:
     """A node in the product's resource hierarchy.
@@ -43,19 +59,7 @@ class Scope:
             TypeError: When *path* is a single string or holds a non-string.
             ValueError: When a segment is empty or contains ``/``.
         """
-        if isinstance(path, str):
-            raise TypeError(
-                "A scope path is a sequence of segments, not a string; use Scope.parse()."
-            )
-        segments = tuple(path)
-        for segment in segments:
-            if not isinstance(segment, str):
-                raise TypeError(f"A scope segment must be a string: {segment!r}.")
-            if not segment or _SEPARATOR in segment:
-                raise ValueError(
-                    f"A scope segment must be non-empty and free of {_SEPARATOR!r}: {segment!r}."
-                )
-        object.__setattr__(self, "path", segments)
+        object.__setattr__(self, "path", _segments_of(path))
 
     @classmethod
     def root(cls) -> Scope:

loom_kernel-2.9.0/src/loom/core/authz/_grants.py

@@ -1,79 +0,0 @@
-"""Who holds which role where, and where those assignments come from."""
-
-from __future__ import annotations
-
-from collections.abc import Collection, Iterable
-from dataclasses import dataclass
-from typing import Protocol
-
-from loom.core.authz._roles import require_name
-from loom.core.authz._scope import Scope
-
-
-@dataclass(frozen=True, slots=True, order=True)
-class Grant:
-    """An assignment of a role to a subject on a scope.
-
-    Attributes:
-        subject: Opaque identifier of the holder, such as an identity subject
-            or a service account id.
-        role: Name of the role; its permissions are looked up in the catalog
-            at decision time.
-        scope: Where the role applies, including everything below it.
-    """
-
-    subject: str
-    role: str
-    scope: Scope
-
-    def __post_init__(self) -> None:
-        """Reject a grant that names no holder, an unusable role name or no scope."""
-        if not self.subject:
-            raise ValueError("A grant needs a subject.")
-        require_name("role", self.role)
-        if not isinstance(self.scope, Scope):
-            raise TypeError(f"A grant scope must be a Scope, not {type(self.scope).__name__}.")
-
-
-class GrantSource(Protocol):
-    """Where the grants of a subject are loaded from.
-
-    Any class with this method satisfies the protocol structurally, with no
-    inheritance required.
-    """
-
-    async def grants_for(self, subject: str) -> Collection[Grant]:
-        """Return every grant held by *subject*.
-
-        Args:
-            subject: Identifier of the holder.
-
-        Returns:
-            The subject's grants; empty when it holds none.
-        """
-        ...
-
-
-class InMemoryGrantSource:
-    """A :class:`GrantSource` over a fixed list, for tests and examples."""
-
-    __slots__ = ("_grants",)
-
-    def __init__(self, grants: Iterable[Grant]) -> None:
-        """Hold *grants*, deduplicated in their original order.
-
-        Args:
-            grants: Grants of any number of subjects.
-        """
-        self._grants = tuple(dict.fromkeys(grants))
-
-    async def grants_for(self, subject: str) -> Collection[Grant]:
-        """Return the grants of *subject*, in the order they were given.
-
-        Args:
-            subject: Identifier of the holder.
-
-        Returns:
-            The subject's grants.
-        """
-        return tuple(grant for grant in self._grants if grant.subject == subject)