User and Role Services

Domain services encapsulating the business logic for User and Role data models.

—

User Service (UserService)

class UserService

Bases: SQLAlchemyAsyncRepositoryService[User, Any]

Handles database operations for users.

default_role: ClassVar[str] = 'application-access'

system_admin_email: ClassVar[str] = 'system.admin@example.com'

async authenticate(username: str, password: str) → User

Authenticate a user.

Parameters:

• username (str) – User email.

• password (str) – User password.

Raises:

UnauthorizedException – If the user is not found, not verified, or inactive.

Returns:

The user object.

Return type:

User

async update_password(data: PasswordUpdate, user_id: UUID) → None

Modify the stored user password.

Parameters:

• data (PasswordUpdate) – The Pydantic schema with current and new passwords.

• user_id (UUID) – The unique ID of the target user.

Raises:

UnauthorizedException – If the current password is incorrect.

check_critical_action_forbidden(target_user: m.User, calling_superuser_id: UUID) → None

Disallow destructive action on self or system admin.

Parameters:

• target_user (User) – The user object targeted for action.

• calling_superuser_id (UUID) – UUID of the superuser calling the action.

Raises:

PermissionDeniedException – If target is the system admin or the caller themselves.

async get_users_paginated_dto(filters: list[StatementFilter]) → OffsetPagination[UserDto]

Retrieve a paginated list of users as DTOs.

Role Service (RoleService)

class RoleService

Bases: SQLAlchemyAsyncRepositoryService[Role, Any]

Handles database operations for roles.

async get_id_and_slug_by_slug(slug: str) → Role

Retrieve the role object with column optimization.

async get_default_role(default_role_slug: str) → Role

Retrieve the default role object with column optimization.

Parameters:

default_role_slug (str) – The slug of the default role (e.g., ‘application-access’).

Returns:

A Role object (with id, name, and slug loaded).

Return type:

Role

Raises:

NotFoundError – Signals a critical infrastructure failure. This role is required, and its absence means that the initial database seeding did not complete.