Core Service Layer (`AuthTunaAsync`)

The entire library core is exposed through asynchronous manager classes. The main entry point is the auth_service instance from authtuna.integrations.

UserManager

Handles user lifecycle and data management.

# Example: Suspending a user
from authtuna.integrations import auth_service

async def suspend(user_id, admin_id):
    suspended_user = await auth_service.users.suspend_user(
        user_id=user_id,
        admin_id=admin_id,
        reason="Violated ToS"
    )
    return suspended_user.is_active # Returns False

SessionManager

Directly manages database sessions, terminations, and retrieval.

# Example: Terminate all other sessions for a user
async def cleanup_sessions(user_id, current_session_id, ip_address):
    await auth_service.sessions.terminate_all_for_user(
        user_id=user_id,
        ip_address=ip_address,
        except_session_id=current_session_id
    )

RoleManager & PermissionManager

Manages the RBAC system, including creating roles/permissions and assigning them.

Creating Roles and Permissions

# Create a new role
await auth_service.roles.create("editor", "Can edit content", level=30) # do not set any role to level > 49 without understanding the hirearchial rbac system (curr have not yet documented in detail so please use caution when using this feature, i am already using in prod but its not documented so pls wait till using this feature, you may use the core auth system and existing roles which are provisioned by core.defaults)

# Create a new permission
await auth_service.permissions.create("edit:article", "Can edit articles") # same message as above.
                

Adding Permissions to a Role

# Add a permission to a role
await auth_service.roles.add_permission_to_role("editor", "edit:article") # this is more ok to use as less prone to escalation but caution anyway.
                

Role Hierarchy and Levels

AuthTuna supports role hierarchy through a `level` system. A role with a higher level can manage roles with a lower level. For example, an `admin` with level 90 can assign the `editor` role with level 50 to a user.

Grant-Based System

In addition to the hierarchy, AuthTuna has a grant-based system. This allows you to explicitly grant a role the permission to assign other roles or grant specific permissions. This provides a more granular control over the RBAC system.

                        # will add example later
                

Recommended Usage

For most applications, the built-in roles and permissions are sufficient. However, if you need to create custom roles and permissions, it's recommended to do so in a startup script or a dedicated management command. This ensures that your RBAC system is consistent and reproducible across all environments.

TokenManager

The `TokenManager` is responsible for creating, validating, and managing tokens for various purposes, such as email verification and password reset. You can use this manager to create custom tokens for your own features.

OrganizationManager

The `OrganizationManager` handles the logic for creating, managing, and inviting users to organizations. This is useful for multi-tenant applications where users are grouped into different organizations.