rbac

Role-Based Access Control (RBAC) Manager

Provides a comprehensive framework for handling user permissions, roles, and group management within the PlantDB ecosystem. It supports fine‑grained access control for scans and user accounts, allowing administrators to create, modify, and revoke permissions with ease.

Key Features

• Role and permission hierarchy with ADMIN, CONTRIBUTOR, and READER roles.
• Group‑based sharing of scans and dynamic membership handling.
• Decorator‑based permission checks (requires_permission) for method protection.
• User account lifecycle operations: activation, deactivation, unlocking.
• Full scan access control: ownership, group sharing, and global role fallback.

Usage Examples

from plantdb.commons.auth.rbac import RBACManager, Permission, User rbac = RBACManager()

Create a new user and assign a role

user = rbac.create_user('alice', roles={'CONTRIBUTOR'})

Create a group and add the user

rbac.create_group(user, 'researchers') rbac.add_user_to_group(user, 'researchers', 'alice')

Check if the user can read a scan

scan_meta = {'owner': 'bob', 'sharing': ['researchers']} can_read = rbac.can_access_scan(user, scan_meta, Permission.READ) print(can_read) True

RBACManager

RBACManager(users_file='users.json', groups_file='groups.json', max_login_attempts=3, lockout_duration=900)

Manage Role-Based Access Control (RBAC) for users and permissions.

This class provides methods to determine which permissions a user has,
check if a user has a specific permission, and verify if a user can access
or perform operations on scans based on their roles and permissions.

Attributes

logger : logging.logger
    The logger to use with this class.
users : plantdb.commons.auth.manager.UserManager
    Manager for handling user operations.
groups : plantdb.commons.auth.manager.GroupManager
    Manager for handling group operations.

Examples

>>> from plantdb.commons.auth.rbac import RBACManager
>>> rbac = RBACManager()
>>> # Get the 'guest' user and have a look at its permissions
>>> guest = rbac.get_guest_user()

v >>> rbac.get_user_permissions(guest) {} >>> rbac.can_create_group(guest) False >>> # Get the 'admin' user and create a new user >>> admin = rbac.users.get_user('admin') >>> rbac.can_create_user(admin) True >>> rbac.create_user(admin, 'butcher', 'Billy Butcher', 'terror') >>> # The user database JSON file now has this user registered >>> import json >>> with open(rbac.users.users_file, 'r') as f: user_db = json.load(f) >>> 'butcher' in [entry['username'] for entry in user_db]

Initialize the RBACManager.

Parameters:

Name	Type	Description	Default
users_file	str | Path	Path to the JSON file acting as users' database. Default is 'users.json'.	'users.json'
groups_file	str | Path	Path to the JSON file acting as groups' database. Defaults to "groups.json".	'groups.json'
max_login_attempts	int	Maximum number of failed login attempts before account lockout. Defaults to 3.	3
lockout_duration	int or timedelta	Account lockout duration in seconds. Defaults to 900 (15 minutes).	900

Source code in plantdb/commons/auth/rbac.py

def __init__(self, users_file: str | Path = 'users.json', groups_file: str | Path = "groups.json",
             max_login_attempts=3, lockout_duration=900):
    """
    Initialize the RBACManager.

    Parameters
    ----------
    users_file : str | Path, optional
        Path to the JSON file acting as users' database. Default is 'users.json'.
    groups_file : str | Path, optional
        Path to the JSON file acting as groups' database. Defaults to "groups.json".
    max_login_attempts : int, optional
        Maximum number of failed login attempts before account lockout. Defaults to ``3``.
    lockout_duration : int or timedelta, optional
        Account lockout duration in seconds. Defaults to ``900`` (15 minutes).
    """
    self.logger = get_logger(__class__.__name__)
    self.users = UserManager(users_file, max_login_attempts, lockout_duration)
    self.groups = GroupManager(groups_file)

activate

activate(requesting_user, username)

Activate a user account - requires MANAGE_USERS permission

Source code in plantdb/commons/auth/rbac.py

@requires_permission(Permission.MANAGE_USERS)
def activate(self, requesting_user: User, username: str) -> bool:
    """Activate a user account - requires MANAGE_USERS permission"""
    if not self.users.exists(username):
        self.logger.warning(f"Attempt to activate non-existent user: {username}")
        return False

    user = self.users.get_user(username)
    if user.is_active:
        self.users.activate(user)
        self.logger.info(f"User {username} activated by {requesting_user.username}")
        return True
    else:
        self.logger.info(f"User {username} was already active")
    return True

add_user_to_group

add_user_to_group(user, group_name, username_to_add)

Add a user to a group if the requesting user has permission.

Parameters:

Name	Type	Description	Default
user	User	The user requesting to add a member.	required
group_name	str	The name of the group.	required
username_to_add	str	The username to add to the group.	required

Returns:

Type	Description
bool	True if the user was added successfully. False if the permission was denied or the operation failed.

Source code in plantdb/commons/auth/rbac.py

def add_user_to_group(self, user: User, group_name: str, username_to_add: str) -> bool:
    """Add a user to a group if the requesting user has permission.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to add a member.
    group_name : str
        The name of the group.
    username_to_add : str
        The username to add to the group.

    Returns
    -------
    bool
        ``True`` if the user was added successfully.
        ``False`` if the permission was denied or the operation failed.
    """
    if not self.can_add_to_group(user, group_name):
        self.logger.error(
            f"Insufficient permission to add user '{username_to_add}' to group '{group_name}' by user '{user.username}!")
        return False
    self.logger.info(f"Adding user '{username_to_add}' from group '{group_name}' by user '{user.username}'!")
    return self.groups.add_user_to_group(group_name, username_to_add)

can_access_scan

can_access_scan(user, scan_metadata, operation)

Check if a user can perform a specific operation on a scan dataset.

This method implements the complete access control logic, including:

• Owner-based access (owners get a CONTRIBUTOR role for their scans)
• Group-based access (shared group members get a CONTRIBUTOR role)
• Global role-based access (fallback to user's global role)
• Admin override (admins can do everything)

Parameters:

Name	Type	Description	Default
user	User | TokenUser	The user requesting access.	required
scan_metadata	dict	The scan metadata containing 'owner' and optional 'sharing' fields.	required
operation	Permission	The operation/permission being requested.	required

Returns:

Type	Description
bool	True if the user can perform the operation, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_access_scan(self, user: User | TokenUser, scan_metadata: dict, operation: Permission) -> bool:
    """Check if a user can perform a specific operation on a scan dataset.

    This method implements the complete access control logic, including:

    - Owner-based access (owners get a `CONTRIBUTOR` role for their scans)
    - Group-based access (shared group members get a `CONTRIBUTOR` role)
    - Global role-based access (fallback to user's global role)
    - Admin override (admins can do everything)

    Parameters
    ----------
    user : plantdb.commons.auth.models.User | plantdb.commons.auth.models.TokenUser
        The user requesting access.
    scan_metadata : dict
        The scan metadata containing 'owner' and optional 'sharing' fields.
    operation : plantdb.commons.auth.models.Permission
        The operation/permission being requested.

    Returns
    -------
    bool
        ``True`` if the user can perform the operation, ``False`` otherwise.
    """
    scan_permissions = self.get_scan_permissions(user, scan_metadata)
    return operation in scan_permissions

can_add_to_group

can_add_to_group(user, group_name)

Check if a user can add members to a specific group.

Users can add members to a group if: 1. They are an admin (MANAGE_GROUPS permission), OR 2. They are a member of the group

Parameters:

Name	Type	Description	Default
user	User	The user requesting to add members.	required
group_name	str	The name of the group.	required

Returns:

Type	Description
bool	True if the user can add members to the group, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_add_to_group(self, user: User, group_name: str) -> bool:
    """Check if a user can add members to a specific group.

    Users can add members to a group if:
    1. They are an admin (MANAGE_GROUPS permission), OR
    2. They are a member of the group

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to add members.
    group_name : str
        The name of the group.

    Returns
    -------
    bool
        ``True`` if the user can add members to the group, ``False`` otherwise.
    """
    # Admins can manage any group
    if self.has_role(user, Role.ADMIN):
        return True

    # Group members can add users to their groups
    group = self.groups.get_group(group_name)
    return group is not None and group.has_user(user.username)

can_create_group

can_create_group(user)

Check if a user can create groups.

Any user with a role that has a MANAGE_GROUPS permission can create groups.

Parameters:

Name	Type	Description	Default
user	User	The user to check.	required

Returns:

Type	Description
bool	True if the user can create groups, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_create_group(self, user: User) -> bool:
    """Check if a user can create groups.

    Any user with a role that has a ``MANAGE_GROUPS`` permission can create groups.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user to check.

    Returns
    -------
    bool
        ``True`` if the user can create groups, ``False`` otherwise.
    """
    return self.has_permission(user, Permission.MANAGE_GROUPS)

can_create_user

can_create_user(user)

Check if a user can create new users.

Parameters:

Name	Type	Description	Default
user	User	The user to check.	required

Returns:

Type	Description
bool	True if the user can create new users, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_create_user(self, user: User) -> bool:
    """Check if a user can create new users.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user to check.

    Returns
    -------
    bool
        ``True`` if the user can create new users, ``False`` otherwise.
    """
    return self.has_permission(user, Permission.MANAGE_USERS)

can_delete_group

can_delete_group(user)

Check if a user can delete a group.

Only users with the MANAGE_GROUPS permission can delete groups.

Parameters:

Name	Type	Description	Default
user	User	The user requesting to delete the group.	required

Returns:

Type	Description
bool	True if the user can delete the group, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_delete_group(self, user: User) -> bool:
    """Check if a user can delete a group.

    Only users with the `MANAGE_GROUPS` permission can delete groups.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to delete the group.

    Returns
    -------
    bool
        ``True`` if the user can delete the group, ``False`` otherwise.
    """
    # Admins can manage any group
    if self.has_role(user, Role.ADMIN):
        return True

    return self.has_permission(user, Permission.MANAGE_GROUPS)

can_manage_groups

can_manage_groups(user)

Check if a user can manage groups (create/delete groups).

Any user with a role that has a MANAGE_GROUPS permission can create groups.

Parameters:

Name	Type	Description	Default
user	User	The user to check.	required

Returns:

Type	Description
bool	True if the user can manage groups, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_manage_groups(self, user: User) -> bool:
    """Check if a user can manage groups (create/delete groups).

    Any user with a role that has a ``MANAGE_GROUPS`` permission can create groups.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user to check.

    Returns
    -------
    bool
        ``True`` if the user can manage groups, ``False`` otherwise.
    """
    return self.has_permission(user, Permission.MANAGE_GROUPS)

can_modify_scan_owner

can_modify_scan_owner(user, scan_metadata)

Check if a user can modify the 'owner' field of a scan.

Only users with permission to MANAGE_USERS can modify scan ownership.

Parameters:

Name	Type	Description	Default
user	User	The user requesting to modify ownership.	required
scan_metadata	dict	The scan metadata.	required

Returns:

Type	Description
bool	True if the user can modify the owner field, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_modify_scan_owner(self, user: User, scan_metadata: dict) -> bool:
    """Check if a user can modify the 'owner' field of a scan.

    Only users with permission to ``MANAGE_USERS`` can modify scan ownership.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to modify ownership.
    scan_metadata : dict
        The scan metadata.

    Returns
    -------
    bool
        ``True`` if the user can modify the owner field, ``False`` otherwise.
    """
    return self.has_permission(user, Permission.MANAGE_USERS)

can_modify_scan_sharing

can_modify_scan_sharing(user, scan_metadata)

Check if a user can modify the 'sharing' field of a scan.

Users can modify sharing if they have WRITE permission for the scan (i.e., they are the owner, in a shared group, or have a global CONTRIBUTOR+ role).

Parameters:

Name	Type	Description	Default
user	User	The user requesting to modify sharing.	required
scan_metadata	dict	The scan metadata.	required

Returns:

Type	Description
bool	True if the user can modify the sharing field, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def can_modify_scan_sharing(self, user: User, scan_metadata: dict) -> bool:
    """Check if a user can modify the 'sharing' field of a scan.

    Users can modify sharing if they have WRITE permission for the scan
    (_i.e._, they are the owner, in a shared group, or have a global CONTRIBUTOR+ role).

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to modify sharing.
    scan_metadata : dict
        The scan metadata.

    Returns
    -------
    bool
        ``True`` if the user can modify the sharing field, ``False`` otherwise.
    """
    return self.can_access_scan(user, scan_metadata, Permission.WRITE)

create_group

create_group(user, group_name, users=None, description=None)

Create a new group if the user has permission.

Parameters:

Name	Type	Description	Default
user	User	The user creating the group.	required
group_name	str	The unique name for the group.	required
users	Optional[Set[str]]	Initial set of users to add to the group.	None
description	Optional[str]	Optional description of the group.	None

Returns:

Type	Description
Optional[Group]	The created group object if successful, None if the permission was denied.

Raises:

Type	Description
ValueError	If a group with the same name already exists.

Source code in plantdb/commons/auth/rbac.py

def create_group(self, user: User, group_name: str, users: Optional[Set[str]] = None,
                 description: Optional[str] = None) -> Optional[Group]:
    """Create a new group if the user has permission.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user creating the group.
    group_name : str
        The unique name for the group.
    users : Optional[Set[str]]
        Initial set of users to add to the group.
    description : Optional[str]
        Optional description of the group.

    Returns
    -------
    Optional[Group]
        The created group object if successful, ``None`` if the permission was denied.

    Raises
    ------
    ValueError
        If a group with the same name already exists.
    """
    if not self.can_manage_groups(user):
        self.logger.error(f"Insufficient permission to create group '{group_name}' by user '{user.username}!")
        return None
    self.logger.info(f"Creating group '{group_name}' by user '{user.username}, with users '{users}'")
    return self.groups.create_group(group_name, user.username, users, description)

create_user

create_user(requesting_user, username, fullname, password, roles=None)

Create a new user account.

This method verifies that the requesting user has the MANAGE_USERS permission, logs the creation attempt, and forwards the actual creation to the underlying UserManager. It returns the newly created User object on success or None if the operation is not permitted.

Parameters:

Name	Type	Description	Default
requesting_user	User	The user performing the creation request.	required
username	str	Desired username for the new account.	required
fullname	str	The full name of the user to create.	required
password	str	Password for the new account.	required
roles	Role | set[Role] | None	Set of roles to assign to the new user. If None (default), use the Role.READER role.	None

Returns:

Type	Description
User | None	The created User instance, or None if creation was denied.

Source code in plantdb/commons/auth/rbac.py

def create_user(self, requesting_user: User, username: str, fullname: str, password: str,
                roles: Role | set[Role] | None = None) -> User | None:
    """Create a new user account.

    This method verifies that the requesting user has the ``MANAGE_USERS`` permission,
    logs the creation attempt, and forwards the actual creation to the underlying
    ``UserManager``.  It returns the newly created ``User`` object on success or ``None``
    if the operation is not permitted.

    Parameters
    ----------
    requesting_user : plantdb.commons.auth.models.User
        The user performing the creation request.
    username : str
        Desired username for the new account.
    fullname : str
        The full name of the user to create.
    password : str
        Password for the new account.
    roles : Role | set[Role] | None
        Set of roles to assign to the new user.
        If ``None`` (default), use the `Role.READER` role.

    Returns
    -------
    User | None
        The created ``User`` instance, or ``None`` if creation was denied.
    """
    if not self.can_create_user(requesting_user):
        self.logger.error(
            f"User '{requesting_user.username}' attempted to create user '{username}' without sufficient permission."
        )
        return None

    self.logger.info(
        f"User '{requesting_user.username}' is creating new user '{username}' with {roles=}."
    )
    return self.users.create(username, fullname, password, roles=roles)

deactivate

deactivate(requesting_user, username)

Deactivate a user account - requires MANAGE_USERS permission

Source code in plantdb/commons/auth/rbac.py

@requires_permission(Permission.MANAGE_USERS)
def deactivate(self, requesting_user: User, username: str) -> bool:
    """Deactivate a user account - requires MANAGE_USERS permission"""
    if not self.users.exists(username):
        self.logger.warning(f"Attempt to deactivate non-existent user: {username}")
        return False

    user = self.users.get_user(username)
    if user.is_active:
        self.users.deactivate(user)
        self.logger.info(f"User {username} deactivated by {requesting_user.username}")
        return True
    else:
        self.logger.info(f"User {username} was already inactive")
    return True

delete_group

delete_group(user, group_name)

Delete a group if the user has permission.

Parameters:

Name	Type	Description	Default
user	User	The user requesting to delete the group.	required
group_name	str	The name of the group to delete.	required

Returns:

Type	Description
bool	True if the group was deleted successfully. False if the permission was denied or the group is not found.

Source code in plantdb/commons/auth/rbac.py

def delete_group(self, user: User, group_name: str) -> bool:
    """Delete a group if the user has permission.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to delete the group.
    group_name : str
        The name of the group to delete.

    Returns
    -------
    bool
        ``True`` if the group was deleted successfully.
        ``False`` if the permission was denied or the group is not found.
    """
    if not self.can_delete_group(user):
        self.logger.error(f"Insufficient permission to delete group '{group_name}' by user '{user.username}!")
        return False
    self.logger.warning(f"Deleting group '{group_name}' by user '{user.username}'!")
    return self.groups.delete_group(group_name)

ensure_scan_owner

ensure_scan_owner(scan_metadata)

Ensure a scan has an owner field, defaulting to guest if missing.

This method should be called when loading or creating scans to ensure the owner field is always present.

Parameters:

Name	Type	Description	Default
scan_metadata	dict	The scan metadata to check and potentially modify.	required

Returns:

Type	Description
dict	The metadata updated with the 'owner' field.

Source code in plantdb/commons/auth/rbac.py

def ensure_scan_owner(self, scan_metadata: dict) -> dict:
    """Ensure a scan has an owner field, defaulting to guest if missing.

    This method should be called when loading or creating scans to ensure
    the owner field is always present.

    Parameters
    ----------
    scan_metadata : dict
        The scan metadata to check and potentially modify.

    Returns
    -------
    dict
        The metadata updated with the 'owner' field.
    """
    if 'owner' not in scan_metadata:
        scan_metadata = scan_metadata.copy()
        scan_metadata['owner'] = self.users.GUEST_USERNAME
    return scan_metadata

get_accessible_scans_for_user

get_accessible_scans_for_user(user, all_scan_metadata)

Filter scans to only include those the user has READ access to.

This method can be used to implement scan listing with proper access control.

Parameters:

Name	Type	Description	Default
user	User	The user requesting scan access.	required
all_scan_metadata	Dict[str, dict]	Dictionary mapping scan IDs to their metadata.	required

Returns:

Type	Description
Dict[str, dict]	Dictionary of scan IDs to metadata for scans the user can read.

Source code in plantdb/commons/auth/rbac.py

def get_accessible_scans_for_user(self, user: User, all_scan_metadata: Dict[str, dict]) -> Dict[str, dict]:
    """Filter scans to only include those the user has READ access to.

    This method can be used to implement scan listing with proper access control.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting scan access.
    all_scan_metadata : Dict[str, dict]
        Dictionary mapping scan IDs to their metadata.

    Returns
    -------
    Dict[str, dict]
        Dictionary of scan IDs to metadata for scans the user can read.
    """
    accessible_scans = {}

    for scan_id, metadata in all_scan_metadata.items():
        # Ensure owner field is present
        metadata = self.ensure_scan_owner(metadata)

        # Check if the user has READ access to this scan
        if self.can_access_scan(user, metadata, Permission.READ):
            accessible_scans[scan_id] = metadata

    return accessible_scans

get_effective_role_for_scan

get_effective_role_for_scan(user, scan_metadata)

Get the effective role a user has for a specific scan dataset.

This method determines the user's role based on: 1. Dataset ownership (an owner gets CONTRIBUTOR role) 2. Group sharing (shared group members get CONTRIBUTOR role) 3. User's global role (fallback)

Parameters:

Name	Type	Description	Default
user	User | TokenUser	The user to check.	required
scan_metadata	dict	The scan metadata containing 'owner' and optional 'sharing' fields.	required

Returns:

Type	Description
Role	The effective role for this specific scan dataset.

Source code in plantdb/commons/auth/rbac.py

def get_effective_role_for_scan(self, user: User | TokenUser, scan_metadata: dict) -> Role:
    """Get the effective role a user has for a specific scan dataset.

    This method determines the user's role based on:
    1. Dataset ownership (an owner gets CONTRIBUTOR role)
    2. Group sharing (shared group members get CONTRIBUTOR role)
    3. User's global role (fallback)

    Parameters
    ----------
    user : plantdb.commons.auth.models.User | plantdb.commons.auth.models.TokenUser
        The user to check.
    scan_metadata : dict
        The scan metadata containing 'owner' and optional 'sharing' fields.

    Returns
    -------
    plantdb.commons.models.Role
        The effective role for this specific scan dataset.
    """
    # Get the scan owner, default to guest if not specified
    scan_owner = scan_metadata.get('owner', self.users.GUEST_USERNAME)

    # If the user is the owner, it gets the CONTRIBUTOR role (unless admin)
    if user.username == scan_owner:
        # Admins keep their admin privileges
        if Role.ADMIN in user.roles:
            return Role.ADMIN
        # Owners get at least CONTRIBUTOR privileges
        current_roles = user.roles
        if Role.ADMIN in current_roles:
            return Role.ADMIN
        elif Role.CONTRIBUTOR in current_roles or Role.READER in current_roles:
            return Role.CONTRIBUTOR
        else:
            # Fallback to CONTRIBUTOR for owners
            return Role.CONTRIBUTOR

    # Check if the user belongs to any shared groups
    shared_groups = scan_metadata.get('sharing', [])
    if shared_groups:
        user_groups = self.groups.get_user_groups(user.username)
        user_group_names = {group.name for group in user_groups}

        # If the user belongs to any shared group, they get the CONTRIBUTOR role for this scan
        if any(group_name in user_group_names for group_name in shared_groups):
            # Admins keep their admin privileges
            if Role.ADMIN in user.roles:
                return Role.ADMIN
            # Shared group members get CONTRIBUTOR privileges for this scan
            return Role.CONTRIBUTOR

    # Fall back to user's highest global role
    if Role.ADMIN in user.roles:
        return Role.ADMIN
    elif Role.CONTRIBUTOR in user.roles:
        return Role.CONTRIBUTOR
    else:
        return Role.READER

get_guest_user

get_guest_user()

Retrieves the guest user from the user repository.

Returns:

Type	Description
User	The User object corresponding to the guest username.

Source code in plantdb/commons/auth/rbac.py

def get_guest_user(self) -> User:
    """Retrieves the guest user from the user repository.

    Returns
    -------
    User
        The User object corresponding to the guest username.
    """
    return self.users.get_user(self.users.GUEST_USERNAME)

get_scan_permissions

get_scan_permissions(user, scan_metadata)

Get the set of permissions a user has for a specific scan dataset.

This method considers the user's effective role for the specific scan, taking into account ownership and group sharing.

Parameters:

Name	Type	Description	Default
user	User | TokenUser	The user to check permissions for.	required
scan_metadata	dict	The scan metadata containing 'owner' and optional 'sharing' fields.	required

Returns:

Type	Description
Set[Permission]	The set of permissions the user has for this specific scan.

Source code in plantdb/commons/auth/rbac.py

def get_scan_permissions(self, user: User | TokenUser, scan_metadata: dict) -> Set[Permission]:
    """Get the set of permissions a user has for a specific scan dataset.

    This method considers the user's effective role for the specific scan,
    taking into account ownership and group sharing.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User | plantdb.commons.auth.models.TokenUser
        The user to check permissions for.
    scan_metadata : dict
        The scan metadata containing 'owner' and optional 'sharing' fields.

    Returns
    -------
    Set[Permission]
        The set of permissions the user has for this specific scan.
    """
    effective_role = self.get_effective_role_for_scan(user, scan_metadata)
    return effective_role.permissions

get_user_groups

get_user_groups(username)

Get all groups that a user belongs to.

Parameters:

Name	Type	Description	Default
username	str	The username to search for.	required

Returns:

Type	Description
List[Group]	A list of Group objects that the user belongs to.

Source code in plantdb/commons/auth/rbac.py

def get_user_groups(self, username: str) -> List[Group]:
    """Get all groups that a user belongs to.

    Parameters
    ----------
    username : str
        The username to search for.

    Returns
    -------
    List[Group]
        A list of Group objects that the user belongs to.
    """
    return self.groups.get_user_groups(username)

get_user_permissions

get_user_permissions(user)

Get the set of permissions a user has based on their assigned roles.

This function returns a set containing all permissions directly assigned to the user as well as those inherited from any roles they are part of. The resulting set is a union of both direct and indirect permissions.

Parameters:

Name	Type	Description	Default
user	User | TokenUser	A User object representing the user whose permissions will be checked. This user must have attributes permissions and roles.	required

Returns:

Type	Description
Set[Permission]	A set containing all permissions that the specified user has access to, including those inherited from roles.

Notes

The result depends on the role_permissions attribute of the class instance. Ensure that this dictionary is properly initialized before calling this method.

See Also

plantdb.commons.auth.models.User : Represents a user with permissions and roles. plantdb.commons.auth.models.Permission : Represents a permission that can be assigned to users or roles. plantdb.commons.auth.models.Role : Represents a role with specific permissions.

Examples:

>>> from plantdb.commons.auth.models import Permission
>>> from plantdb.commons.auth.models import User
>>> role_admin = Role('admin')
>>> role_user = Role('user')
>>> permission_a = Permission()  # Mocking a specific permission
>>> permission_b = Permission()  # Mocking another specific permission
>>> user = User(permissions={permission_a}, roles={role_user})
>>> role_permissions = {Role('admin'): {permission_b}}
>>> user.get_user_permissions(user)
{<__main__.Permission object at 0x...>}

Source code in plantdb/commons/auth/rbac.py

def get_user_permissions(self, user: User | TokenUser) -> Set[Permission]:
    """Get the set of permissions a user has based on their assigned roles.

    This function returns a set containing all permissions directly assigned to
    the user as well as those inherited from any roles they are part of. The
    resulting set is a union of both direct and indirect permissions.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User | plantdb.commons.auth.models.TokenUser
        A `User` object representing the user whose permissions will be checked.
        This user must have attributes `permissions` and `roles`.

    Returns
    -------
    Set[Permission]
        A set containing all permissions that the specified user has access to,
        including those inherited from roles.

    Notes
    -----
    The result depends on the `role_permissions` attribute of the class instance.
    Ensure that this dictionary is properly initialized before calling this method.

    See Also
    --------
    plantdb.commons.auth.models.User : Represents a user with permissions and roles.
    plantdb.commons.auth.models.Permission : Represents a permission that can be assigned to users or roles.
    plantdb.commons.auth.models.Role : Represents a role with specific permissions.

    Examples
    --------
    >>> from plantdb.commons.auth.models import Permission
    >>> from plantdb.commons.auth.models import User
    >>> role_admin = Role('admin')
    >>> role_user = Role('user')
    >>> permission_a = Permission()  # Mocking a specific permission
    >>> permission_b = Permission()  # Mocking another specific permission
    >>> user = User(permissions={permission_a}, roles={role_user})
    >>> role_permissions = {Role('admin'): {permission_b}}
    >>> user.get_user_permissions(user)  # doctest: +SKIP
    {<__main__.Permission object at 0x...>}
    """
    permissions = set(user.permissions) if user.permissions else set()
    return permissions

get_user_scan_role_summary

get_user_scan_role_summary(user, scan_metadata)

Get a summary of the user's access to a specific scan.

This is useful for debugging and user interfaces to show access levels.

Parameters:

Name	Type	Description	Default
user	User	The user to analyze.	required
scan_metadata	dict	The scan metadata.	required

Returns:

Type	Description
dict	A dictionary containing access information including: - 'effective_role': the user's effective role for this scan - 'permissions': list of permissions the user has - 'access_reason': why the user has this level of access - 'is_owner': a boolean flag indicating if the user is the owner of the scan - 'shared_groups': a list of groups that share this scan, if any

Source code in plantdb/commons/auth/rbac.py

def get_user_scan_role_summary(self, user: User, scan_metadata: dict) -> dict:
    """Get a summary of the user's access to a specific scan.

    This is useful for debugging and user interfaces to show access levels.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user to analyze.
    scan_metadata : dict
        The scan metadata.

    Returns
    -------
    dict
        A dictionary containing access information including:

            - 'effective_role': the user's effective role for this scan
            - 'permissions': list of permissions the user has
            - 'access_reason': why the user has this level of access
            - 'is_owner': a boolean flag indicating if the user is the owner of the scan
            - 'shared_groups': a list of groups that share this scan, if any
    """
    metadata = self.ensure_scan_owner(scan_metadata)
    effective_role = self.get_effective_role_for_scan(user, metadata)
    permissions = list(self.get_scan_permissions(user, metadata))

    # Determine access reason
    scan_owner = metadata.get('owner', self.users.GUEST_USERNAME)
    shared_groups = metadata.get('sharing', [])
    user_groups = {group.name for group in self.groups.get_user_groups(user.username)}

    access_reason = []

    if Role.ADMIN in user.roles:
        access_reason.append("admin_role")

    if user.username == scan_owner:
        access_reason.append("owner")

    shared_group_matches = [g for g in shared_groups if g in user_groups]
    if shared_group_matches:
        access_reason.append(f"group_member: {', '.join(shared_group_matches)}")

    if not access_reason:
        access_reason.append("global_role")

    return {
        'effective_role': effective_role.value,
        'permissions': [p.value for p in permissions],
        'access_reason': access_reason,
        'is_owner': user.username == scan_owner,
        'shared_groups': shared_group_matches if shared_groups else []
    }

has_permission

has_permission(user, permission)

Check if a user has a specific permission.

This function determines whether the given user has the specified permission, including administrative privileges.

Parameters:

Name	Type	Description	Default
user	User | TokenUser	The User object to check for permissions.	required
permission	Permission	The permission level or type to verify against the user's permissions.	required

Returns:

Type	Description
bool	True if the user has the given permission, False otherwise.

Notes

The function checks for the specific permission in the user's permission set.

See Also

get_user_permissions : Retrieve the list of permissions a user has.

Source code in plantdb/commons/auth/rbac.py

def has_permission(self, user: User | TokenUser, permission: Permission) -> bool:
    """Check if a user has a specific permission.

    This function determines whether the given user has the specified permission,
    including administrative privileges.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User | plantdb.commons.auth.models.TokenUser
        The User object to check for permissions.
    permission : plantdb.commons.auth.models.Permission
        The permission level or type to verify against the user's permissions.

    Returns
    -------
    bool
        ``True`` if the user has the given permission, ``False`` otherwise.

    Notes
    -----
    The function checks for the specific permission in the user's permission set.

    See Also
    --------
    get_user_permissions : Retrieve the list of permissions a user has.
    """
    user_permissions = self.get_user_permissions(user)
    return permission in user_permissions

has_role

has_role(user, role)

Check if a user has a specific role.

Parameters:

Name	Type	Description	Default
user	User	The user object to check for roles.	required
role	Role	The role to verify against the user's roles.	required

Returns:

Type	Description
bool	True if the user has the given role, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def has_role(self, user: User, role: Role) -> bool:
    """Check if a user has a specific role.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user object to check for roles.
    role : plantdb.commons.auth.models.Role
        The role to verify against the user's roles.

    Returns
    -------
    bool
        ``True`` if the user has the given role, ``False`` otherwise.
    """
    return role in user.roles

is_guest_user

is_guest_user(user)

Check if the given user is the guest user.

Parameters:

Name	Type	Description	Default
user	User	The user object to check.	required

Returns:

Type	Description
bool	True if the user is the guest user, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def is_guest_user(self, user: User) -> bool:
    """Check if the given user is the guest user.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user object to check.

    Returns
    -------
    bool
        ``True`` if the user is the guest user, ``False`` otherwise.
    """
    return user.username == self.users.GUEST_USERNAME

list_groups

list_groups(user)

List all groups if the user has permission.

Parameters:

Name	Type	Description	Default
user	User	The user requesting the group list.	required

Returns:

Type	Description
Optional[List[Group]]	A list of all groups if the user has permission, None otherwise.

Source code in plantdb/commons/auth/rbac.py

def list_groups(self, user: User) -> Optional[List[Group]]:
    """List all groups if the user has permission.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting the group list.

    Returns
    -------
    Optional[List[Group]]
        A list of all groups if the user has permission, None otherwise.
    """
    # For now, any authenticated user can list groups
    # This can be restricted later if needed
    return self.groups.list_groups()

remove_user_from_group

remove_user_from_group(user, group_name, username_to_remove)

Remove a user from a group if the requesting user has permission.

Parameters:

Name	Type	Description	Default
user	User	The user requesting to remove a member.	required
group_name	str	The name of the group.	required
username_to_remove	str	The username to remove from the group.	required

Returns:

Type	Description
bool	True if the user was removed successfully. False if the permission was denied or the operation failed.

Source code in plantdb/commons/auth/rbac.py

def remove_user_from_group(self, user: User, group_name: str, username_to_remove: str) -> bool:
    """Remove a user from a group if the requesting user has permission.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user requesting to remove a member.
    group_name : str
        The name of the group.
    username_to_remove : str
        The username to remove from the group.

    Returns
    -------
    bool
        ``True`` if the user was removed successfully.
        ``False`` if the permission was denied or the operation failed.
    """
    if not self.can_add_to_group(user, group_name):  # Same permission as adding
        self.logger.error(
            f"Insufficient permission to remove user '{username_to_remove}' from group '{group_name}' by user '{user.username}!")
        return False
    self.logger.warning(
        f"Removing user '{username_to_remove}' from group '{group_name}' by user '{user.username}'!")
    return self.groups.remove_user_from_group(group_name, username_to_remove)

unlock

unlock(requesting_user, username)

Unlock a user account - requires MANAGE_USERS permission

Source code in plantdb/commons/auth/rbac.py

@requires_permission(Permission.MANAGE_USERS)
def unlock(self, requesting_user: User, username: str) -> bool:
    """Unlock a user account - requires MANAGE_USERS permission"""
    if not self.users.exists(username):
        self.logger.warning(f"Attempt to unlock non-existent user: {username}")
        return False

    user = self.users.get_user(username)
    if user.locked_until:
        self.users.unlock_user(user)
        self.logger.info(f"User {username} unlocked by {requesting_user.username}")
    else:
        self.logger.info(f"User {username} was not locked")
    return True

valid_sharing_groups

valid_sharing_groups(sharing_groups)

Validate groups in the sharing list if they exist.

Parameters:

Name	Type	Description	Default
sharing_groups	List[str]	List of group names to validate.	required

Returns:

Type	Description
list	The list of valid groups; can be empty if none of the provided groups exist.

Source code in plantdb/commons/auth/rbac.py

def valid_sharing_groups(self, sharing_groups: List[str]) -> List[str]:
    """Validate groups in the sharing list if they exist.

    Parameters
    ----------
    sharing_groups : List[str]
        List of group names to validate.

    Returns
    -------
    list
        The list of valid groups; can be empty if none of the provided groups exist.
    """
    valid_groups = []
    sharing_groups = set(sharing_groups)
    for group_name in sharing_groups:
        if not self.groups.group_exists(group_name):
            self.logger.warning(f"Group '{group_name}' does not exist, can not share to non-existent group!")
        valid_groups.append(group_name)
    return valid_groups

validate_scan_metadata_access

validate_scan_metadata_access(user, old_metadata, new_metadata)

Validate that a user can make the proposed metadata changes.

This method checks if the user has permission to modify specific fields like 'owner' and 'sharing' based on the RBAC rules.

Parameters:

Name	Type	Description	Default
user	User	The user attempting to modify metadata.	required
old_metadata	dict	The current scan metadata.	required
new_metadata	dict	The proposed new metadata.	required

Returns:

Type	Description
bool	True if all proposed changes are allowed, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def validate_scan_metadata_access(self, user: User, old_metadata: dict, new_metadata: dict) -> bool:
    """Validate that a user can make the proposed metadata changes.

    This method checks if the user has permission to modify specific fields
    like 'owner' and 'sharing' based on the RBAC rules.

    Parameters
    ----------
    user : plantdb.commons.auth.models.User
        The user attempting to modify metadata.
    old_metadata : dict
        The current scan metadata.
    new_metadata : dict
        The proposed new metadata.

    Returns
    -------
    bool
        ``True`` if all proposed changes are allowed, ``False`` otherwise.
    """
    # Check if the owner field is being modified
    old_owner = old_metadata.get('owner', self.users.GUEST_USERNAME)
    new_owner = new_metadata.get('owner', self.users.GUEST_USERNAME)

    if old_owner != new_owner:
        if not self.can_modify_scan_owner(user, old_metadata):
            return False

    # Check if the sharing field is being modified
    old_sharing = old_metadata.get('sharing', [])
    new_sharing = new_metadata.get('sharing', [])

    if old_sharing != new_sharing:
        if not self.can_modify_scan_sharing(user, old_metadata):
            return False

    return True

validate_sharing_groups

validate_sharing_groups(sharing_groups)

Validate that all groups in the sharing list exist.

Parameters:

Name	Type	Description	Default
sharing_groups	List[str]	List of group names to validate.	required

Returns:

Type	Description
bool	True if all groups exist, False otherwise.

Source code in plantdb/commons/auth/rbac.py

def validate_sharing_groups(self, sharing_groups: List[str]) -> bool:
    """Validate that all groups in the sharing list exist.

    Parameters
    ----------
    sharing_groups : List[str]
        List of group names to validate.

    Returns
    -------
    bool
        True if all groups exist, False otherwise.
    """
    for group_name in sharing_groups:
        if not self.groups.group_exists(group_name):
            return False
    return True

requires_permission

requires_permission(required_permissions)

Decorator to check if the specified user has the required permission(s).

Parameters:

Name	Type	Description	Default
required_permissions	Union[Permission, List[Permission]]	A single permission string or list of permission that the user must have to access the decorated method.	required

Source code in plantdb/commons/auth/rbac.py

def requires_permission(required_permissions: Union[Permission, List[Permission]]):
    """Decorator to check if the specified user has the required permission(s).

    Parameters
    ----------
    required_permissions: Union[Permission, List[Permission]]
        A single permission string or list of permission that the user must have to access the decorated method.
    """

    def decorator(func: Callable) -> Callable:
        @wraps(func)
        def wrapper(self, requesting_user: User, *args, **kwargs) -> Any:
            # Ensure required_permissions is always a list
            perms_to_check = (
                required_permissions if isinstance(required_permissions, list)
                else [required_permissions]
            )

            # Get user's permissions (assuming you are calling from a class who as a `_get_user_permissions` method)
            user_permissions = self.get_user_permissions(requesting_user)

            # Check if the requesting user has all the required permissions
            has_permission = all(perm in user_permissions for perm in perms_to_check)

            if not has_permission:
                perm_names = [perm.name if hasattr(perm, 'name') else str(perm) for perm in perms_to_check]
                raise PermissionError(
                    f"User '{requesting_user.username}' does not have required permission(s): {', '.join(perm_names)}"
                )

            return func(self, requesting_user, *args, **kwargs)

        return wrapper

    return decorator