IdentityProtocol

Protocol defining the contract for identity management.

This is the primary port for user management in the hexagonal
architecture. Implementations can be:

- LocalIdentityProvider: SQL-backed user table (Indie mode)
- FederatedIdentityProvider: Hydrates from auth headers (Enterprise)
- MockIdentityProvider: For testing

All methods are async for consistency with the framework.

Example usage:
    identity: IdentityProtocol = container.get(IdentityProtocol)

    # Authenticate user
    token = await identity.authenticate(
        PasswordCredentials(username="user@example.com", password="secret")
    )

    # Get user by ID
    user = await identity.get_user("user-123")

    # Get user's ABAC attributes
    attrs = await identity.get_attributes("user-123")
    # Returns: {"roles": ["Employee"], "teams": ["Sales"], "department": "EMEA"}

Source: identity.py

Methods

get_user

async def get_user(self, user_id: str) -> UserContext | None

Get user by their unique identifier.

    Args:
        user_id: The user's unique identifier

    Returns:
        UserContext if found, None otherwise

get_user_by_email

async def get_user_by_email(self, email: str) -> UserContext | None

Get user by their email address.

    Args:
        email: The user's email address

    Returns:
        UserContext if found, None otherwise

authenticate

async def authenticate(self, credentials: Credentials) -> Token

Authenticate user with provided credentials.

    Args:
        credentials: Authentication credentials (password, API key, etc.)

    Returns:
        Token containing access_token and optional refresh_token

    Raises:
        AuthenticationError: If credentials are invalid

get_attributes

async def get_attributes(self, user_id: str) -> dict[str, Any]

Get user's ABAC (Attribute-Based Access Control) attributes.

    Returns all attributes used for authorization decisions:
    - roles: List of role names
    - teams: List of team memberships
    - tenants: List of accessible tenants
    - department, location, etc.: Custom attributes

    Args:
        user_id: The user's unique identifier

    Returns:
        Dictionary of attribute name -> value(s)

validate_token

async def validate_token(self, token: str) -> UserContext | None

Validate an access token and return the associated user.

    Used by authentication middleware to verify incoming tokens.

    Args:
        token: The access token string to validate

    Returns:
        UserContext if token is valid, None if invalid/expired