"""Validated, immutable permission catalog (roles x permissions x scope kinds)."""
from __future__ import annotations
import json
import re
import tomllib
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from types import MappingProxyType
from typing import Any
from loguru import logger
from auth_middleware.authz.errors import CatalogError, UnknownPermissionError
from auth_middleware.authz.types import GLOBAL_KIND
_PERMISSION_RE = re.compile(r"[a-z][a-z0-9_.]*")
_KIND_RE = re.compile(r"[a-z][a-z0-9_]*")
@dataclass(frozen=True, slots=True)
class ScopeKind:
"""A declared kind of scope.
Args:
name: Kind name, e.g. ``"studio"`` or ``"global"``.
hide_existence: ``True``: no assignment -> not visible (404).
``False``: no assignment -> denied (403).
"""
name: str
hide_existence: bool = True
@dataclass(frozen=True, slots=True)
class PermissionSpec:
"""A permission of the catalog.
Args:
name: Permission name, e.g. ``"design.write"``.
scope_kind: Declared scope kind the permission belongs to.
sensitive: Metadata for audit and UIs; does not change enforcement.
"""
name: str
scope_kind: str
sensitive: bool = False
[docs]
class PermissionCatalog:
"""Immutable catalog: ``role -> permissions`` plus permission and scope metadata.
Build it with :meth:`from_mapping` or :meth:`from_file`. It never reads a
database: a catalog is code/config versioned with the application.
"""
[docs]
def __init__(
self,
scopes: Mapping[str, ScopeKind],
permissions: Mapping[str, PermissionSpec],
roles: Mapping[str, frozenset[str]],
) -> None:
self._scopes = MappingProxyType(dict(scopes))
self._permissions = MappingProxyType(dict(permissions))
self._roles = MappingProxyType(dict(roles))
granting: dict[str, set[str]] = {name: set() for name in permissions}
for role, perms in roles.items():
for perm in perms:
granting[perm].add(role)
self._granting = MappingProxyType(
{k: frozenset(v) for k, v in granting.items()}
)
[docs]
@classmethod
def from_mapping(
cls,
*,
scopes: Sequence[ScopeKind],
permissions: Sequence[PermissionSpec],
roles: Mapping[str, Iterable[str]],
) -> PermissionCatalog:
"""Build and validate a catalog.
``StrEnum`` members are accepted wherever a name is expected.
Args:
scopes: Declared scope kinds.
permissions: Declared permissions.
roles: ``role -> permission names``.
Returns:
The immutable catalog.
Raises:
CatalogError: Listing *all* problems found.
"""
problems: list[str] = []
scope_map = cls._check_scopes(scopes, problems)
perm_map = cls._check_permissions(permissions, scope_map, problems)
role_map = cls._check_roles(roles, perm_map, problems)
if problems:
raise CatalogError("; ".join(problems))
return cls(scope_map, perm_map, role_map)
@staticmethod
def _check_scopes(
scopes: Sequence[ScopeKind], problems: list[str]
) -> dict[str, ScopeKind]:
scope_map: dict[str, ScopeKind] = {}
for sk in scopes:
name = str(sk.name)
if not _KIND_RE.fullmatch(name):
problems.append(f"invalid scope kind name: {name!r}")
elif name in scope_map:
problems.append(f"duplicate scope kind: {name}")
scope_map[name] = ScopeKind(name, sk.hide_existence)
return scope_map
@staticmethod
def _check_permissions(
permissions: Sequence[PermissionSpec],
scope_map: Mapping[str, ScopeKind],
problems: list[str],
) -> dict[str, PermissionSpec]:
perm_map: dict[str, PermissionSpec] = {}
for spec in permissions:
pname = str(spec.name)
kind = str(spec.scope_kind)
if not pname:
problems.append("empty permission name")
continue
if not _PERMISSION_RE.fullmatch(pname):
problems.append(f"invalid permission name: {pname!r}")
if pname in perm_map:
problems.append(f"duplicate permission: {pname}")
if kind not in scope_map:
problems.append(f"permission {pname} uses undeclared scope kind {kind}")
perm_map[pname] = PermissionSpec(pname, kind, spec.sensitive)
return perm_map
@staticmethod
def _check_roles(
roles: Mapping[str, Iterable[str]],
perm_map: Mapping[str, PermissionSpec],
problems: list[str],
) -> dict[str, frozenset[str]]:
role_map: dict[str, frozenset[str]] = {}
for role, perms in roles.items():
rname = str(role)
names = frozenset(str(p) for p in perms)
if not rname:
problems.append("empty role name")
continue
for p in sorted(names):
if p not in perm_map:
problems.append(f"role {rname} grants undeclared permission {p}")
if not names:
logger.debug("role {} has no permissions", rname)
role_map[rname] = names
return role_map
[docs]
@classmethod
def from_file(cls, path: Path) -> PermissionCatalog:
"""Load a catalog from a TOML (``.toml``) or JSON (``.json``) file.
Shape::
[[scopes]]
name = "studio"
hide_existence = true
[[permissions]]
name = "design.write"
scope = "studio"
sensitive = false
[roles]
TIT = ["design.write"]
Raises:
CatalogError: Unreadable file, unknown extension or invalid content.
"""
path = Path(path)
try:
if path.suffix == ".toml":
data = tomllib.loads(path.read_text(encoding="utf-8"))
elif path.suffix == ".json":
data = json.loads(path.read_text(encoding="utf-8"))
else:
raise CatalogError(f"unsupported catalog file type: {path.suffix}")
return cls.from_mapping(
scopes=[
ScopeKind(s["name"], s.get("hide_existence", True))
for s in data.get("scopes", [])
],
permissions=[
PermissionSpec(p["name"], p["scope"], p.get("sensitive", False))
for p in data.get("permissions", [])
],
roles=data.get("roles", {}),
)
except (OSError, ValueError, KeyError, TypeError) as exc:
raise CatalogError(f"cannot load catalog {path}: {exc}") from exc
[docs]
def permissions_for(self, role: str) -> frozenset[str]:
"""Return the permissions granted by ``role``.
Raises:
CatalogError: Unknown role.
"""
try:
return self._roles[str(role)]
except KeyError:
raise CatalogError(f"unknown role: {role}") from None
[docs]
def roles(self) -> frozenset[str]:
"""Return all role names."""
return frozenset(self._roles)
[docs]
def permissions(self) -> frozenset[str]:
"""Return all permission names."""
return frozenset(self._permissions)
[docs]
def spec(self, permission: str) -> PermissionSpec:
"""Return the spec of ``permission``.
Raises:
UnknownPermissionError: Not in the catalog.
"""
try:
return self._permissions[str(permission)]
except KeyError:
raise UnknownPermissionError(f"unknown permission: {permission}") from None
[docs]
def scope_kind(self, name: str) -> ScopeKind:
"""Return the declared scope kind ``name``.
Raises:
CatalogError: Undeclared kind.
"""
try:
return self._scopes[str(name)]
except KeyError:
raise CatalogError(f"unknown scope kind: {name}") from None
[docs]
def roles_granting(self, permission: str) -> frozenset[str]:
"""Return the roles that grant ``permission``.
Raises:
UnknownPermissionError: Not in the catalog.
"""
self.spec(permission)
return self._granting[str(permission)]
[docs]
def to_mapping(self) -> dict[str, Any]:
"""Return a plain dict; ``from_mapping(**...)`` of it rebuilds the catalog."""
return {
"scopes": [
ScopeKind(s.name, s.hide_existence) for s in self._scopes.values()
],
"permissions": list(self._permissions.values()),
"roles": {r: sorted(p) for r, p in self._roles.items()},
}
__all__ = ["GLOBAL_KIND", "PermissionCatalog", "PermissionSpec", "ScopeKind"]