"""Auth domain models: roles and token claims.

UserRole defines the four roles from PPT Slide 12.
UserClaims is what the JWT decodes to — it is the identity object passed
through FastAPI dependency injection to route handlers.
"""

from __future__ import annotations

import enum
from dataclasses import dataclass


class UserRole(str, enum.Enum):
    """Access roles mirroring the four-role RBAC matrix from the product spec.

    ADMIN      — full platform access including system management.
    LEGAL      — knowledge query, document review, compliance checks.
    EHS        — knowledge query, perception/regulatory signals.
    READONLY   — knowledge query only.
    """

    ADMIN = "admin"
    LEGAL = "legal"
    EHS = "ehs"
    READONLY = "readonly"


@dataclass
class UserClaims:
    """Decoded JWT payload representing an authenticated user.

    Instances are created by JWTHandler.decode_token() and injected into
    route handlers via the get_current_user FastAPI dependency.
    """

    # Unique user identifier (UUID string stored in PostgreSQL users table).
    user_id: str
    # Display name used for audit log entries.
    username: str
    # Role determines which resources the user may access.
    role: UserRole