grantr 0.1.0__py3-none-any.whl

grantr/__init__.py

@@ -0,0 +1,84 @@
+"""grantr: identity and access for artifactr, reflexr and portalr.
+
+Tenants, their members, groups, roles and service principals, and the grants that bind them to
+tenants, workspaces, threads, artifacts and rules. The libraries ask it, through their own hooks,
+before every command and read; it imports neither library, and neither imports it.
+
+The model and its rules are in :mod:`grantr.core`, with no I/O; :class:`Grants` answers checks
+and changes access over a storage, such as :class:`InMemoryStorage`. The documentation, with its
+decisions and the plan that builds grantr, is at <https://lattice.alexnodeland.com/grantr/>.
+"""
+
+from importlib.metadata import version
+
+from grantr.core import (
+    DEPLOYMENT,
+    TENANT,
+    Agent,
+    AuditEntry,
+    AuditEvent,
+    AuditFilter,
+    AuditType,
+    BuiltInRole,
+    CatalogView,
+    Forbidden,
+    Grant,
+    Grantee,
+    GrantrError,
+    Group,
+    Invalid,
+    Member,
+    Membership,
+    Resource,
+    ResourceKind,
+    Role,
+    RulePrincipal,
+    ServicePrincipal,
+    Subject,
+    TenantId,
+    User,
+    UserId,
+    Visibility,
+    WorkspaceId,
+)
+from grantr.grants import Access, Grants, Hooks, InMemoryStorage, Storage, SubjectOf
+
+__version__ = version("grantr")
+
+__all__ = [
+    "DEPLOYMENT",
+    "TENANT",
+    "Access",
+    "Agent",
+    "AuditEntry",
+    "AuditEvent",
+    "AuditFilter",
+    "AuditType",
+    "BuiltInRole",
+    "CatalogView",
+    "Forbidden",
+    "Grant",
+    "Grantee",
+    "GrantrError",
+    "Grants",
+    "Group",
+    "Hooks",
+    "InMemoryStorage",
+    "Invalid",
+    "Member",
+    "Membership",
+    "Resource",
+    "ResourceKind",
+    "Role",
+    "RulePrincipal",
+    "ServicePrincipal",
+    "Storage",
+    "Subject",
+    "SubjectOf",
+    "TenantId",
+    "User",
+    "UserId",
+    "Visibility",
+    "WorkspaceId",
+    "__version__",
+]

grantr/core/__init__.py

@@ -0,0 +1,123 @@
+"""grantr's model, and the rules a check and a grant follow: no I/O, no async.
+
+:class:`~grantr.grants.Grants` loads what a decision needs from storage, and decides with these.
+"""
+
+from grantr.core.audit import (
+    AuditEntry,
+    AuditEvent,
+    AuditFilter,
+    AuditType,
+    DeploymentTenantCreated,
+    Granted,
+    GroupDefined,
+    GroupDeleted,
+    KeyIssued,
+    KeyRevoked,
+    MemberAdded,
+    MemberRemoved,
+    Restricted,
+    Revoked,
+    RoleDefined,
+    RoleDeleted,
+    TenantCreated,
+    TenantDeleted,
+    Unrestricted,
+)
+from grantr.core.errors import Forbidden, GrantrError, Invalid
+from grantr.core.grants import Grant, Membership, Visibility, memberships
+from grantr.core.ids import PRINCIPAL_ID, TENANT_ID, PrincipalId, TenantId, UserId, WorkspaceId
+from grantr.core.keys import Key, issue, key_id, verify
+from grantr.core.resources import (
+    DEPLOYMENT,
+    ITEMS,
+    TENANT,
+    ListableKind,
+    Resource,
+    ResourceKind,
+)
+from grantr.core.roles import (
+    APPLICATION,
+    BUILT_IN,
+    GRANTR_ACTIONS,
+    MEMBER,
+    OPERATOR,
+    BuiltInRole,
+    Catalog,
+    CatalogView,
+    Level,
+    Role,
+)
+from grantr.core.subjects import (
+    Agent,
+    Grantee,
+    Group,
+    Member,
+    RulePrincipal,
+    ServicePrincipal,
+    Subject,
+    User,
+)
+
+__all__ = [
+    "APPLICATION",
+    "BUILT_IN",
+    "DEPLOYMENT",
+    "GRANTR_ACTIONS",
+    "ITEMS",
+    "MEMBER",
+    "OPERATOR",
+    "PRINCIPAL_ID",
+    "TENANT",
+    "TENANT_ID",
+    "Agent",
+    "AuditEntry",
+    "AuditEvent",
+    "AuditFilter",
+    "AuditType",
+    "BuiltInRole",
+    "Catalog",
+    "CatalogView",
+    "DeploymentTenantCreated",
+    "Forbidden",
+    "Grant",
+    "Granted",
+    "Grantee",
+    "GrantrError",
+    "Group",
+    "GroupDefined",
+    "GroupDeleted",
+    "Invalid",
+    "Key",
+    "KeyIssued",
+    "KeyRevoked",
+    "Level",
+    "ListableKind",
+    "Member",
+    "MemberAdded",
+    "MemberRemoved",
+    "Membership",
+    "PrincipalId",
+    "Resource",
+    "ResourceKind",
+    "Restricted",
+    "Revoked",
+    "Role",
+    "RoleDefined",
+    "RoleDeleted",
+    "RulePrincipal",
+    "ServicePrincipal",
+    "Subject",
+    "TenantCreated",
+    "TenantDeleted",
+    "TenantId",
+    "Unrestricted",
+    "User",
+    "UserId",
+    "Visibility",
+    "WorkspaceId",
+    "issue",
+    "key_id",
+    "memberships",
+    "verify",
+]

grantr/core/audit.py

@@ -0,0 +1,242 @@
+"""The audit log's events: every change to access, typed.
+
+grantr appends one entry per change, in the same transaction as the change, with a sequence
+number, the time, the tenant and who made it. Refusals aren't recorded. A key's secret, and its
+digest, never are. A read of the log may keep only some types of event, or one subject's
+changes (:class:`AuditFilter`).
+"""
+
+from collections.abc import Set
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from grantr.core.grants import Grant
+from grantr.core.ids import TenantId, UserId
+from grantr.core.resources import Resource
+from grantr.core.roles import Role
+from grantr.core.subjects import Member, ServicePrincipal, Subject
+
+
+class TenantCreated(BaseModel):
+    """A tenant was created, with its first owner."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["tenant_created"] = "tenant_created"
+    owner: UserId
+
+
+class DeploymentTenantCreated(BaseModel):
+    """A tenant was created: the deployment's record of it, beside the tenant's own.
+
+    Its entry is in no tenant's log, the deployment's, and names who created the tenant, so an
+    operator who isn't a member of the tenant it created is seen to have created it. The owner is
+    a user's id, never an email.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["deployment_tenant_created"] = "deployment_tenant_created"
+    tenant: TenantId
+    owner: UserId
+
+
+class TenantDeleted(BaseModel):
+    """A tenant was deleted, with everything grantr held for it but its audit log."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["tenant_deleted"] = "tenant_deleted"
+
+
+class MemberAdded(BaseModel):
+    """A user or service principal joined the tenant."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["member_added"] = "member_added"
+    member: Member
+
+
+class MemberRemoved(BaseModel):
+    """A member left the tenant, with its grants, its places in groups, and its keys."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["member_removed"] = "member_removed"
+    member: Member
+
+
+class GroupDefined(BaseModel):
+    """A group was created, or its members replaced."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["group_defined"] = "group_defined"
+    group: str
+    members: frozenset[Member]
+
+
+class GroupDeleted(BaseModel):
+    """A group was deleted, with its grants."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["group_deleted"] = "group_deleted"
+    group: str
+
+
+class RoleDefined(BaseModel):
+    """A custom role was created, or its actions replaced."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["role_defined"] = "role_defined"
+    role: Role
+
+
+class RoleDeleted(BaseModel):
+    """A custom role was deleted, with its grants."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["role_deleted"] = "role_deleted"
+    role: str
+
+
+class Granted(BaseModel):
+    """A role was granted."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["granted"] = "granted"
+    grant: Grant
+
+
+class Revoked(BaseModel):
+    """A grant was revoked."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["revoked"] = "revoked"
+    grant: Grant
+
+
+class KeyIssued(BaseModel):
+    """A key was issued to a service principal."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["key_issued"] = "key_issued"
+    principal: ServicePrincipal
+    key: str
+    """The key's public id."""
+
+
+class KeyRevoked(BaseModel):
+    """A key was revoked."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["key_revoked"] = "key_revoked"
+    principal: ServicePrincipal
+    key: str
+
+
+class Restricted(BaseModel):
+    """A thread or artifact was restricted to those granted a role on it."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["restricted"] = "restricted"
+    on: Resource
+
+
+class Unrestricted(BaseModel):
+    """A thread or artifact's restriction was lifted: its workspace's roles hold on it again."""
+
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal["unrestricted"] = "unrestricted"
+    on: Resource
+
+
+type AuditEvent = Annotated[
+    TenantCreated
+    | DeploymentTenantCreated
+    | TenantDeleted
+    | MemberAdded
+    | MemberRemoved
+    | GroupDefined
+    | GroupDeleted
+    | RoleDefined
+    | RoleDeleted
+    | Granted
+    | Revoked
+    | KeyIssued
+    | KeyRevoked
+    | Restricted
+    | Unrestricted,
+    Field(discriminator="type"),
+]
+"""A change to access."""
+
+
+class AuditEntry(BaseModel):
+    """An event in the audit log, with its place in it."""
+
+    model_config = ConfigDict(frozen=True)
+
+    seq: int
+    """Its place in the deployment's one log, from 1."""
+
+    at: datetime
+    tenant: TenantId | None
+    """The tenant it changed; ``None`` for the deployment's operators, and a tenant's creation."""
+
+    by: Subject | None
+    """Who made the change; ``None`` for the first operator, whom no one granted."""
+
+    event: AuditEvent
+
+
+type AuditType = Literal[
+    "tenant_created",
+    "deployment_tenant_created",
+    "tenant_deleted",
+    "member_added",
+    "member_removed",
+    "group_defined",
+    "group_deleted",
+    "role_defined",
+    "role_deleted",
+    "granted",
+    "revoked",
+    "key_issued",
+    "key_revoked",
+    "restricted",
+    "unrestricted",
+]
+"""An audit event's ``type``: what a read of the log may keep."""
+
+
+@dataclass(frozen=True)
+class AuditFilter:
+    """Which entries a read of the log keeps: of some types, by one subject, or every one.
+
+    Args:
+        types: The event types to keep; every type when empty.
+        by: The subject whose changes to keep, such as a user or a rule; anyone's when None.
+    """
+
+    types: Set[AuditType] = frozenset()
+    by: Subject | None = None
+
+    def keeps(self, entry: AuditEntry) -> bool:
+        """Whether an entry passes the filter."""
+        return (not self.types or entry.event.type in self.types) and (
+            self.by is None or entry.by == self.by
+        )

grantr/core/errors.py

@@ -0,0 +1,13 @@
+"""Why grantr refuses a command that changes access."""
+
+
+class GrantrError(Exception):
+    """A command grantr refused. Checks never raise: they answer ``False``."""
+
+
+class Forbidden(GrantrError):
+    """The actor may not do this: it lacks the action, or holds less than it would give."""
+
+
+class Invalid(GrantrError):
+    """The command can't apply: an unknown tenant, role, group or key, or a duplicate."""

grantr/core/grants.py

@@ -0,0 +1,98 @@
+"""Grants, and what they hold: the rule every check follows.
+
+A grant is a role, on a resource, to a grantee. A grant on a resource holds on everything in
+it: a workspace's grants hold on its threads, artifacts and rules, and a tenant's on its
+workspaces. A grant on an item adds to the workspace's.
+"""
+
+from collections.abc import Iterable, Mapping
+from itertools import groupby
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from grantr.core.ids import TenantId, UserId
+from grantr.core.resources import Resource
+from grantr.core.roles import RESTRICT, Catalog, Role
+from grantr.core.subjects import Grantee, User
+
+
+class Grant(BaseModel):
+    """A role, on a resource, to a grantee: in a tenant, or on the deployment."""
+
+    model_config = ConfigDict(frozen=True)
+
+    tenant: TenantId | None
+    """The tenant it is in; ``None`` for a grant on the deployment, which is in none."""
+
+    role: str
+    on: Resource
+    to: Grantee
+
+    @model_validator(mode="after")
+    def _only_the_deployment_is_in_no_tenant(self) -> Self:
+        if (self.tenant is None) != (self.on.kind == "deployment"):
+            raise ValueError("a grant is in a tenant, unless it is on the deployment")
+        return self
+
+
+class Membership(BaseModel):
+    """A user's place in a tenant: the roles granted to them on it."""
+
+    model_config = ConfigDict(frozen=True)
+
+    tenant: TenantId
+    user: UserId
+    roles: tuple[str, ...]
+    """Their tenant roles, by name, sorted: ``member``, and ``owner`` or ``admin`` if held."""
+
+
+class Visibility(BaseModel):
+    """The threads and artifacts an actor may not see in one workspace.
+
+    It has the fields of artifactr's ``Visibility``, which grantr doesn't import.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    threads: frozenset[str] = frozenset()
+    artifacts: frozenset[str] = frozenset()
+
+
+def held(
+    grants: Iterable[Grant],
+    on: Resource,
+    catalog: Catalog,
+    custom: Mapping[str, Role],
+    *,
+    restricted: bool = False,
+) -> frozenset[str]:
+    """The actions some grants hold on a resource: those of each grant on it or around it.
+
+    On a restricted thread or artifact, a grant around it holds only if its role may restrict:
+    the workspace's admins, and the tenant's owners and admins. Grants on the item itself hold
+    as ever.
+    """
+    chain = on.chain()
+    found: set[str] = set()
+    for grant in grants:
+        if grant.on not in chain:
+            continue
+        actions = catalog.role(grant.role, grant.on.kind, custom) or frozenset[str]()
+        if restricted and grant.on != on and RESTRICT not in actions:
+            continue
+        found |= actions
+    return frozenset(found)
+
+
+def memberships(user: UserId, grants: Iterable[Grant]) -> list[Membership]:
+    """A user's memberships, from the grants on tenants made to them directly, by tenant."""
+    tenant_roles = sorted(
+        (grant.tenant, grant.role)
+        for grant in grants
+        if grant.tenant is not None and grant.on.kind == "tenant" and grant.to == User(id=user)
+    )
+    return [
+        Membership(tenant=tenant, user=user, roles=tuple(role for _, role in roles))
+        for tenant, roles in groupby(tenant_roles, key=lambda pair: pair[0])
+    ]

grantr/core/ids.py

@@ -0,0 +1,31 @@
+"""The ids grantr shares with the libraries, and its own.
+
+A tenant and a workspace have the same ids as in artifactr and reflexr. A user is a Supabase Auth
+``sub``: grantr stores the id, and no password or profile.
+"""
+
+import re
+from typing import Annotated, Final
+
+from pydantic import StringConstraints
+
+TENANT_ID: Final = re.compile(r"^[^~]+$")
+"""A tenant id's form."""
+
+type TenantId = Annotated[str, StringConstraints(pattern=TENANT_ID.pattern)]
+"""The isolation boundary, as the libraries name it: not empty, and with no ``~``, which
+grantr's storage keeps for the deployment."""
+
+PRINCIPAL_ID: Final = re.compile(r"^[^:~\s]+$")
+"""A service principal's id's form."""
+
+type PrincipalId = Annotated[str, StringConstraints(pattern=PRINCIPAL_ID.pattern)]
+"""A service principal: not empty, and with no ``:``, ``~`` or whitespace. The ids the
+libraries' own actors take hold a ``:``, as relayr's code rules' do (``reflexr:<rule>``), so no
+principal a tenant makes, and no key it issues, can pass for one (grantr ADR-0028)."""
+
+type WorkspaceId = str
+"""A workspace in a tenant, as the libraries name it."""
+
+type UserId = str
+"""A person, by the identity provider's id for them."""

grantr/core/keys.py

@@ -0,0 +1,59 @@
+"""Service principal keys: ``grantr_sk_<id>_<secret>``, shown once.
+
+A key is a public id and 32 random bytes, both in hex. grantr stores the id, the key's tenant
+and principal, and a SHA-256 digest of the secret: 32 random bytes need no salt. A key is found
+by its id and checked by comparing digests in constant time.
+"""
+
+import hashlib
+import hmac
+import re
+import secrets
+from typing import Final
+
+from pydantic import BaseModel, ConfigDict
+
+from grantr.core.ids import TenantId
+from grantr.core.subjects import ServicePrincipal
+
+KEY: Final = re.compile(r"grantr_sk_([0-9a-f]{16})_([0-9a-f]{64})")
+"""A key's form: the prefix, an 8-byte id and a 32-byte secret, in hex."""
+
+
+class Key(BaseModel):
+    """What grantr stores of a key: never its secret."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    tenant: TenantId
+    principal: ServicePrincipal
+    digest: str
+    """The SHA-256 digest of the secret, in hex."""
+
+
+def _digest(secret: str) -> str:
+    return hashlib.sha256(bytes.fromhex(secret)).hexdigest()
+
+
+def issue(tenant: TenantId, principal: ServicePrincipal) -> tuple[str, Key]:
+    """A new key for a principal: the key to show once, and what to store of it."""
+    key_id, secret = secrets.token_hex(8), secrets.token_hex(32)
+    stored = Key(id=key_id, tenant=tenant, principal=principal, digest=_digest(secret))
+    return f"grantr_sk_{key_id}_{secret}", stored
+
+
+def key_id(key: str) -> str | None:
+    """A key's public id, or None if it isn't a key."""
+    match = KEY.fullmatch(key)
+    return match[1] if match else None
+
+
+def verify(key: str, stored: Key) -> bool:
+    """Whether a key is the one stored: its id and its secret's digest match."""
+    match = KEY.fullmatch(key)
+    return (
+        match is not None
+        and match[1] == stored.id
+        and hmac.compare_digest(_digest(match[2]), stored.digest)
+    )