messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/auth/identity.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""The resolved identity of an authenticated caller, plus the auth-provider enum.
+
+An :class:`Identity` is built once per request from the session's user and carries the roles already
+flattened to a permission set, so the API authorization dependencies can answer ``has(permission)``
+without touching the store.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+
+from messagefoundry.auth.permissions import Permission, Role, permissions_for_roles
+
+
+class AuthProvider(str, Enum):
+    """How a user authenticates. ``local`` users carry a password hash; ``ad`` users bind to AD."""
+
+    LOCAL = "local"
+    AD = "ad"
+
+
+@dataclass(frozen=True, slots=True)
+class Identity:
+    """An authenticated user with roles resolved to a flat, deny-by-default permission set."""
+
+    user_id: str
+    username: str
+    auth_provider: AuthProvider
+    roles: frozenset[Role]
+    permissions: frozenset[Permission]
+    must_change_password: bool = False
+    #: Per-channel RBAC scope: connections this user's *operational* permissions apply to. ``None``
+    #: = all channels (the default / Administrators). See docs/security/PHASE-8C-RBAC.md.
+    allowed_channels: frozenset[str] | None = None
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        user_id: str,
+        username: str,
+        auth_provider: AuthProvider,
+        roles: Iterable[Role],
+        must_change_password: bool = False,
+        allowed_channels: frozenset[str] | None = None,
+    ) -> Identity:
+        """Construct an identity, resolving ``roles`` to their union of permissions."""
+        role_set = frozenset(roles)
+        return cls(
+            user_id=user_id,
+            username=username,
+            auth_provider=auth_provider,
+            roles=role_set,
+            permissions=permissions_for_roles(role_set),
+            must_change_password=must_change_password,
+            allowed_channels=allowed_channels,
+        )
+
+    def has(self, permission: Permission) -> bool:
+        """True iff one of this identity's roles grants ``permission``."""
+        return permission in self.permissions
+
+    def can_access_channel(self, channel_id: str | None) -> bool:
+        """True iff the user's per-channel scope permits ``channel_id`` (``None`` scope = all)."""
+        if self.allowed_channels is None:
+            return True
+        return channel_id is not None and channel_id in self.allowed_channels

messagefoundry/auth/ldap.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Active Directory authentication: LDAP simple-bind + nested-group resolution, and Kerberos SSO.
+
+Pure (no FastAPI). ``ldap3`` does a service-account bind to locate the user, then a bind *as the
+user* to verify the password, then resolves group membership (optionally nested via the AD matching
+rule ``LDAP_MATCHING_RULE_IN_CHAIN``). Windows SSO is handled by a SPNEGO server step (``pyspnego``)
+that yields the authenticated principal, whose groups are resolved the same way.
+
+All calls here are **synchronous**; :class:`~messagefoundry.auth.service.AuthService` runs them via
+``asyncio.to_thread`` so the event loop never blocks. ``ldap3``/``spnego`` are imported lazily so a
+local-only deployment never touches them.
+"""
+
+from __future__ import annotations
+
+import logging
+import ssl
+from dataclasses import dataclass
+from typing import Any
+
+from messagefoundry.config.settings import (
+    INSECURE_TLS_ESCAPE_ENV,
+    AuthSettings,
+    insecure_tls_allowed,
+)
+
+logger = logging.getLogger(__name__)
+
+_MATCHING_RULE_IN_CHAIN = "1.2.840.113556.1.4.1941"  # AD nested-group ("member in chain")
+
+
+@dataclass(frozen=True)
+class AdPrincipal:
+    """An authenticated AD user: identity attributes + the set of groups governing role mapping.
+
+    ``groups`` holds **lower-cased** identifiers — both each group's DN and its ``sAMAccountName`` —
+    so the admin can map roles by whichever form they configured in ``ad_group_role_map``.
+    """
+
+    username: str
+    display_name: str | None
+    email: str | None
+    dn: str
+    groups: frozenset[str]
+
+
+class LdapError(RuntimeError):
+    """LDAP/Kerberos configuration or connectivity failure (distinct from rejected credentials)."""
+
+
+def _escape_filter(value: str) -> str:
+    """RFC 4515 escaping for values interpolated into an LDAP search filter."""
+    out: list[str] = []
+    for ch in value:
+        if ch in "\\*()\x00":
+            out.append("\\%02x" % ord(ch))
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def _attr(entry: Any, name: str) -> str | None:
+    if name not in entry:
+        return None
+    value = entry[name].value
+    return str(value) if value else None
+
+
+def _multi(entry: Any, name: str) -> list[str]:
+    if name not in entry:
+        return []
+    return [str(v) for v in entry[name].values]
+
+
+def _cn_of(dn: str) -> str | None:
+    head = dn.split(",", 1)[0]
+    return head[3:] if head[:3].upper() == "CN=" else None
+
+
+class LdapAuthenticator:
+    """Binds against Active Directory over LDAPS and resolves a user's (nested) group membership."""
+
+    def __init__(self, settings: AuthSettings) -> None:
+        if not settings.ad_server or not settings.ad_user_search_base:
+            raise LdapError("AD is enabled but ad_server / ad_user_search_base are not configured")
+        if not settings.ad_bind_dn or not settings.ad_bind_password:
+            raise LdapError("AD is enabled but the service-account bind is not configured")
+        self._s = settings
+        # A disabled-cert-verification posture (ad_tls_verify=false over LDAPS) makes the service-
+        # account and user binds MITM-able, so it now REFUSES at startup unless the operator sets the
+        # explicit MEFOR_ALLOW_INSECURE_TLS dev escape — it can no longer be silently turned on in
+        # production (ASVS 12.3.2). With the escape set, we still warn loudly once at startup.
+        if str(settings.ad_server).lower().startswith("ldaps") and not settings.ad_tls_verify:
+            if not insecure_tls_allowed():
+                raise LdapError(
+                    "ad_tls_verify=false disables LDAPS certificate verification (MITM risk). Use a "
+                    f"trusted CA via ad_tls_ca_cert_file, or set {INSECURE_TLS_ESCAPE_ENV}=1 to "
+                    "explicitly allow it for a trusted-network dev/test bind."
+                )
+            logger.warning(
+                "AD LDAPS certificate verification is DISABLED (ad_tls_verify=false, permitted by "
+                "%s) — the service-account and user binds are exposed to MITM; do not use in "
+                "production.",
+                INSECURE_TLS_ESCAPE_ENV,
+            )
+
+    def _server(self) -> Any:
+        import ldap3
+
+        tls = None
+        if str(self._s.ad_server).lower().startswith("ldaps"):
+            validate = ssl.CERT_REQUIRED if self._s.ad_tls_verify else ssl.CERT_NONE
+            tls = ldap3.Tls(validate=validate, ca_certs_file=self._s.ad_tls_ca_cert_file)
+        return ldap3.Server(self._s.ad_server, tls=tls, get_info=ldap3.NONE)
+
+    def _service_conn(self) -> Any:
+        import ldap3
+
+        return ldap3.Connection(
+            self._server(),
+            user=self._s.ad_bind_dn,
+            password=self._s.ad_bind_password,
+            authentication=ldap3.SIMPLE,
+            auto_bind=True,
+        )
+
+    def _find_user(self, conn: Any, username: str) -> dict[str, Any] | None:
+        import ldap3
+
+        upn = f"{username}@{self._s.ad_domain}" if self._s.ad_domain else username
+        conn.search(
+            search_base=self._s.ad_user_search_base,
+            search_filter=(
+                f"(|(sAMAccountName={_escape_filter(username)})"
+                f"(userPrincipalName={_escape_filter(upn)}))"
+            ),
+            search_scope=ldap3.SUBTREE,
+            attributes=[
+                "distinguishedName",
+                "sAMAccountName",
+                "displayName",
+                "mail",
+                "memberOf",
+                "userAccountControl",
+            ],
+        )
+        if not conn.entries:
+            return None
+        e = conn.entries[0]
+        # ACCOUNTDISABLE (0x2): a disabled AD account must not authenticate. The local-user path
+        # checks `disabled` up front; the AD password + Kerberos paths both go through here, so
+        # rejecting a disabled account at the lookup covers both (review M-18).
+        uac = _attr(e, "userAccountControl")
+        if uac and uac.isdigit() and (int(uac) & 0x2):
+            return None
+        return {
+            "dn": str(e.entry_dn),
+            "username": _attr(e, "sAMAccountName") or username,
+            "display_name": _attr(e, "displayName"),
+            "email": _attr(e, "mail"),
+            "memberOf": _multi(e, "memberOf"),
+        }
+
+    def _resolve_groups(self, conn: Any, user_dn: str, member_of: list[str]) -> frozenset[str]:
+        import ldap3
+
+        groups: set[str] = set()
+        for dn in member_of:  # direct membership from the user's memberOf attribute
+            groups.add(dn.lower())
+            cn = _cn_of(dn)
+            if cn:
+                groups.add(cn.lower())
+        if self._s.ad_use_nested_groups and self._s.ad_group_search_base:
+            conn.search(
+                search_base=self._s.ad_group_search_base,
+                search_filter=f"(member:{_MATCHING_RULE_IN_CHAIN}:={_escape_filter(user_dn)})",
+                search_scope=ldap3.SUBTREE,
+                attributes=["distinguishedName", "sAMAccountName"],
+            )
+            for e in conn.entries:
+                groups.add(str(e.entry_dn).lower())
+                sam = _attr(e, "sAMAccountName")
+                if sam:
+                    groups.add(sam.lower())
+        return frozenset(groups)
+
+    def authenticate(self, username: str, password: str) -> AdPrincipal | None:
+        """Verify ``username``/``password`` against AD and return the principal, or ``None`` if the
+        credentials are rejected. Raises :class:`LdapError` on a connectivity/config failure."""
+        import ldap3
+
+        if not password:  # never allow an empty password (it triggers an anonymous bind)
+            return None
+        try:
+            with self._service_conn() as svc:
+                info = self._find_user(svc, username)
+                if info is None:
+                    return None
+                user_dn = str(info["dn"])
+                user_conn = ldap3.Connection(
+                    self._server(), user=user_dn, password=password, authentication=ldap3.SIMPLE
+                )
+                if not user_conn.bind():
+                    return None
+                user_conn.unbind()
+                groups = self._resolve_groups(svc, user_dn, info["memberOf"])
+        except ldap3.core.exceptions.LDAPException as exc:  # pragma: no cover - needs real AD
+            raise LdapError(str(exc)) from exc
+        return AdPrincipal(
+            username=str(info["username"]),
+            display_name=info["display_name"],
+            email=info["email"],
+            dn=user_dn,
+            groups=groups,
+        )
+
+    def resolve_principal(self, username: str) -> AdPrincipal | None:
+        """Look a user up + resolve groups *without* a password — for Kerberos, where SSO already
+        proved the identity. Uses the service-account bind only."""
+        import ldap3
+
+        try:
+            with self._service_conn() as svc:
+                info = self._find_user(svc, username)
+                if info is None:
+                    return None
+                user_dn = str(info["dn"])
+                groups = self._resolve_groups(svc, user_dn, info["memberOf"])
+        except ldap3.core.exceptions.LDAPException as exc:  # pragma: no cover - needs real AD
+            raise LdapError(str(exc)) from exc
+        return AdPrincipal(
+            username=str(info["username"]),
+            display_name=info["display_name"],
+            email=info["email"],
+            dn=user_dn,
+            groups=groups,
+        )
+
+
+def kerberos_principal(token: bytes, settings: AuthSettings) -> str | None:
+    """Complete one SPNEGO server step and return the authenticated sAMAccountName, or ``None``.
+
+    Experimental — **not a supported v0.1 feature**: off by default (``kerberos_enabled=False``),
+    production hardening (CI coverage, keytab/SPN preflight) targeted for 0.2. Single-leg only: no
+    NTLM fallback, no mutual-auth response token, no multi-leg challenge handshake. The server must
+    have a usable keytab/credential for ``kerberos_spn`` in its environment; the realm suffix
+    (``user@REALM``) is stripped to yield the account name.
+    """
+    import spnego
+
+    try:  # pragma: no cover - requires a domain-joined server + keytab
+        server = (
+            spnego.server(service=settings.kerberos_spn)
+            if settings.kerberos_spn
+            else spnego.server()
+        )
+        server.step(token)
+        principal = server.client_principal
+    except spnego.exceptions.SpnegoError as exc:  # pragma: no cover
+        raise LdapError(str(exc)) from exc
+    if not principal:
+        return None
+    return str(principal).split("@", 1)[0]

messagefoundry/auth/notifications.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Security-event notification seam (ASVS 6.3.5 / 6.3.7).
+
+A tiny, dependency-free contract the auth layer uses to push an **out-of-band** notice to the affected
+user when something security-relevant happens to their account — a suspicious login (lockout, or a
+success after repeated failures) or a credential change (password / email / roles / disable).
+
+The contract lives here, in ``auth/``, so :class:`~messagefoundry.auth.service.AuthService` can emit
+events **without importing** ``pipeline/`` (the one-way dependency rule, CLAUDE.md §4). The concrete
+sender — which turns an event into a per-user email over the ``[alerts]`` SMTP transport — lives in
+``pipeline/`` and is injected into ``AuthService``. Emission is always **best-effort**: a notifier
+failure is logged and never breaks authentication or an admin action.
+
+The persistent, pull-based companion (``GET /me/security-events``) is a user-scoped view over the
+existing tamper-evident audit log — these same events are already audited — so a user with no
+deliverable mailbox can still review their security history.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+# Event types (the values double as the audit-action suffix / feed category). PHI-free by construction.
+ACCOUNT_LOCKED = "account_locked"  # 6.3.5 — repeated failures crossed the lockout threshold
+LOGIN_AFTER_FAILURES = (
+    "login_after_failures"  # 6.3.5 — first success following >= N failed attempts
+)
+PASSWORD_CHANGED = "password_changed"  # nosec B105 — event-type label, not a credential (6.3.7)
+PASSWORD_RESET = "password_reset"  # nosec B105 — event label, not a credential; admin-initiated (6.3.7/6.4.6)
+EMAIL_CHANGED = "email_changed"  # 6.3.7 — the account's email address was changed
+ROLES_CHANGED = "roles_changed"  # 6.3.7 — an admin changed the account's roles
+ACCOUNT_DISABLED = "account_disabled"  # 6.3.7 — an admin disabled the account
+MFA_ENABLED = "mfa_enabled"  # 6.3.7 — a second factor (TOTP) was enrolled on the account
+MFA_DISABLED = (
+    "mfa_disabled"  # 6.3.7 — the account's second factor was removed (self-service or admin reset)
+)
+ADMIN_NEW_IP = (
+    "admin_action_new_ip"  # 8.4.2 — a sensitive admin action from a new/unexpected client IP
+)
+
+# First success after this many prior failed attempts is flagged as suspicious (6.3.5). Kept modest and
+# fixed (not an operator knob) so a single fat-fingered password does not generate a notice.
+SUSPICIOUS_LOGIN_FAILURE_THRESHOLD = 3
+
+
+@dataclass(frozen=True)
+class SecurityEvent:
+    """One notifiable security event. Carries only the affected user's own identifiers + non-PHI
+    metadata; the body sent to the user is built from these by the concrete notifier."""
+
+    event_type: str
+    username: str
+    email: str | None = None  # the affected user's address (push target); None = no mailbox on file
+    client_ip: str | None = None  # source IP of the triggering request, when known
+    detail: dict[str, Any] = field(
+        default_factory=dict
+    )  # PHI-free extras (e.g. role from/to counts)
+
+
+@runtime_checkable
+class SecurityNotifier(Protocol):
+    """Push a security event to the affected user out-of-band. Implemented in ``pipeline/`` (email over
+    the ``[alerts]`` SMTP transport) and injected into :class:`AuthService`. Must be best-effort and
+    must not raise into the auth path (the caller still guards it)."""
+
+    async def notify(self, event: SecurityEvent) -> None: ...

messagefoundry/auth/passwords.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""argon2id password hashing (argon2-cffi) for *local* users.
+
+AD users never reach here — they authenticate by binding to the directory. The hash string embeds
+its own salt and cost parameters, so it is self-contained and safe to store in the ``users`` table.
+"""
+
+from __future__ import annotations
+
+from argon2 import PasswordHasher
+from argon2.exceptions import InvalidHashError, VerificationError
+
+# argon2id cost parameters, pinned EXPLICITLY rather than relying on argon2-cffi's library defaults
+# (ASVS 11.4.2). Pinning means a library upgrade can't silently weaken (or change) the work factor,
+# and ``needs_rehash`` transparently upgrades any stored hash that predates a future bump. These
+# values meet/exceed OWASP guidance for argon2id (memory ≥ 19 MiB; here 64 MiB, t=3, p=4) and a unit
+# test asserts them so a drift is caught in CI.
+_ARGON2_TIME_COST = 3
+_ARGON2_MEMORY_COST = 65536  # KiB = 64 MiB
+_ARGON2_PARALLELISM = 4
+_ARGON2_HASH_LEN = 32
+_ARGON2_SALT_LEN = 16
+
+# One shared, stateless hasher with the pinned argon2id parameters above.
+_hasher = PasswordHasher(
+    time_cost=_ARGON2_TIME_COST,
+    memory_cost=_ARGON2_MEMORY_COST,
+    parallelism=_ARGON2_PARALLELISM,
+    hash_len=_ARGON2_HASH_LEN,
+    salt_len=_ARGON2_SALT_LEN,
+)
+
+
+def hash_password(password: str) -> str:
+    """Return an argon2id hash (salt + parameters included) to store for a local user."""
+    return _hasher.hash(password)
+
+
+def verify_password(stored_hash: str, password: str) -> bool:
+    """True iff ``password`` matches ``stored_hash``. Never raises on a bad password or malformed hash."""
+    try:
+        return _hasher.verify(stored_hash, password)
+    except (VerificationError, InvalidHashError):
+        return False
+
+
+def needs_rehash(stored_hash: str) -> bool:
+    """True if ``stored_hash`` uses weaker-than-current parameters and should be upgraded on login."""
+    try:
+        return _hasher.check_needs_rehash(stored_hash)
+    except InvalidHashError:
+        return False

messagefoundry/auth/permissions.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Permission catalog and the fixed built-in roles for RBAC.
+
+Authorization is **deny-by-default**: an action is allowed only when one of the caller's roles grants
+the matching :class:`Permission`. This version ships a *fixed* set of built-in :class:`Role` s (no
+custom-role builder yet), so ``BUILTIN_ROLE_PERMISSIONS`` below is the single source of truth — it is
+seeded into the ``roles`` table on store open and consulted when resolving an
+:class:`~messagefoundry.auth.identity.Identity`.
+
+A few permissions (``config:deploy``, ``config:validate``, ``code:edit``, ``service:configure``) have
+no API endpoint yet; they are defined now so the Deployment/Coding roles are complete and those
+endpoints can be gated the moment they land, without a roles migration.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from enum import Enum
+
+
+class Permission(str, Enum):
+    """A single capability a role may grant. The value is the wire/storage string."""
+
+    MONITORING_READ = "monitoring:read"
+    MONITORING_DIAGNOSE = "monitoring:diagnose"
+    MESSAGES_READ = "messages:read"
+    MESSAGES_VIEW_SUMMARY = "messages:view_summary"  # PHI: patient identifiers in list summaries
+    MESSAGES_VIEW_RAW = "messages:view_raw"  # PHI: the full message body
+    MESSAGES_REPLAY = "messages:replay"
+    MESSAGES_PURGE = "messages:purge"
+    CONNECTIONS_CONTROL = "connections:control"
+    CONNECTIONS_TEST = (
+        "connections:test"  # probe a connection's reachability (POST /connections/{name}/test)
+    )
+    CONFIG_DEPLOY = "config:deploy"  # endpoint lands in a later effort
+    CONFIG_VALIDATE = "config:validate"  # endpoint lands in a later effort
+    CODE_EDIT = "code:edit"  # endpoint lands in a later effort
+    AI_ASSIST = "ai:assist"  # use AI coding assistance (IDE), gated by /ai/policy
+    SERVICE_CONFIGURE = "service:configure"  # endpoint lands in a later effort
+    USERS_READ = "users:read"
+    USERS_MANAGE = "users:manage"
+    AUDIT_READ = "audit:read"
+    APPROVALS_APPROVE = (
+        "approvals:approve"  # release a pending high-value action (dual-control, 2.3.5)
+    )
+
+
+class Role(str, Enum):
+    """A fixed built-in role. The role->permission policy lives in ``BUILTIN_ROLE_PERMISSIONS``."""
+
+    ADMINISTRATOR = "administrator"
+    OPERATOR = "operator"
+    DEPLOYMENT = "deployment"
+    CODING = "coding"
+    VIEWER = "viewer"
+    AUDITOR = "auditor"
+
+
+#: Human-facing (label, description) per role — seeded into the ``roles`` table for listing/admin UI.
+ROLE_METADATA: dict[Role, tuple[str, str]] = {
+    Role.ADMINISTRATOR: (
+        "Administrator",
+        "Full control, including user and service administration.",
+    ),
+    Role.OPERATOR: (
+        "Operator",
+        "Day-to-day monitoring and message operations, including PHI viewing.",
+    ),
+    Role.DEPLOYMENT: ("Deployment", "Deploy and validate the connection/router/handler graph."),
+    Role.CODING: ("Coding", "Author and validate Router/Handler code."),
+    Role.VIEWER: ("Viewer", "Read-only dashboards and non-PHI message metadata."),
+    Role.AUDITOR: ("Auditor", "Read the audit trail (separation of duties)."),
+}
+
+_OPERATOR_PERMISSIONS: frozenset[Permission] = frozenset(
+    {
+        Permission.MONITORING_READ,
+        Permission.MONITORING_DIAGNOSE,
+        Permission.MESSAGES_READ,
+        Permission.MESSAGES_VIEW_SUMMARY,
+        Permission.MESSAGES_VIEW_RAW,
+        Permission.MESSAGES_REPLAY,
+        Permission.MESSAGES_PURGE,
+        Permission.CONNECTIONS_CONTROL,
+        Permission.CONNECTIONS_TEST,
+    }
+)
+
+#: The fixed built-in RBAC policy — which permissions each role grants. Holding multiple roles unions.
+BUILTIN_ROLE_PERMISSIONS: dict[Role, frozenset[Permission]] = {
+    Role.ADMINISTRATOR: frozenset(Permission),  # every permission
+    Role.OPERATOR: _OPERATOR_PERMISSIONS,
+    Role.DEPLOYMENT: frozenset(
+        {
+            Permission.MONITORING_READ,
+            Permission.CONFIG_DEPLOY,
+            Permission.CONFIG_VALIDATE,
+            Permission.CONNECTIONS_TEST,
+        }
+    ),
+    Role.CODING: frozenset(
+        {
+            Permission.MONITORING_READ,
+            Permission.CODE_EDIT,
+            Permission.CONFIG_VALIDATE,
+            Permission.AI_ASSIST,
+        }
+    ),
+    Role.VIEWER: frozenset({Permission.MONITORING_READ, Permission.MESSAGES_READ}),
+    Role.AUDITOR: frozenset({Permission.MONITORING_READ, Permission.AUDIT_READ}),
+}
+
+
+def permissions_for_roles(roles: Iterable[Role]) -> frozenset[Permission]:
+    """Union of the permissions granted by ``roles`` (deny-by-default: unknown roles grant nothing)."""
+    granted: set[Permission] = set()
+    for role in roles:
+        granted |= BUILTIN_ROLE_PERMISSIONS.get(role, frozenset())
+    return frozenset(granted)