UmbraTrans/umbratrans_web/schemas.py

"""Pydantic request and response models for the phase-1 API.

Two rules shape every model here:

* Request models forbid unknown fields. A ``password`` field sent to
  ``POST /api/uadmin/accounts`` is therefore rejected by the schema itself, so
  a one-time password can never arrive through a normal JSON body.
* Response models contain no credential material. Accounts are serialized from
  :class:`umbratrans_web.models.AccountView`, which exposes a
  :class:`~umbratrans_web.models.CredentialSummary` and never a hash.
"""

from __future__ import annotations

from datetime import datetime
from uuid import UUID

from pydantic import BaseModel, ConfigDict, Field

from .models import (
    AccountStatus,
    AccountView,
    AuditEvent,
    CredentialSummary,
    CredentialType,
    EnrollmentMode,
    OrganizationStatus,
    OrganizationView,
    RoleName,
)


class RequestModel(BaseModel):
    """Base for request bodies: strict, no silent field coercion."""

    model_config = ConfigDict(extra="forbid", str_strip_whitespace=False)


class ErrorBody(BaseModel):
    code: str
    message: str


class ErrorResponse(BaseModel):
    error: ErrorBody


class HealthResponse(BaseModel):
    status: str
    service: str
    version: str
    environment: str
    repository: str
    cookie_secure: bool
    csrf_required: bool
    time: datetime


class CredentialSummaryResponse(BaseModel):
    credential_type: CredentialType
    must_change_password: bool
    failed_login_count: int
    locked: bool
    last_login_at: datetime | None = None
    password_changed_at: datetime | None = None

    @classmethod
    def from_summary(cls, summary: CredentialSummary) -> CredentialSummaryResponse:
        return cls(
            credential_type=summary.credential_type,
            must_change_password=summary.must_change_password,
            failed_login_count=summary.failed_login_count,
            locked=summary.locked,
            last_login_at=summary.last_login_at,
            password_changed_at=summary.password_changed_at,
        )


class UserResponse(BaseModel):
    id: UUID
    username: str
    display_name: str
    role: RoleName
    status: AccountStatus
    organization_id: UUID | None = None
    email: str | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

    @classmethod
    def from_view(cls, view: AccountView) -> UserResponse:
        return cls(
            id=view.id,
            username=view.username,
            display_name=view.display_name,
            role=view.role,
            status=view.status,
            organization_id=view.organization_id,
            email=view.email,
            created_at=view.created_at,
            updated_at=view.updated_at,
        )


class AccountResponse(UserResponse):
    credential: CredentialSummaryResponse
    active_session_count: int

    @classmethod
    def from_view(cls, view: AccountView) -> AccountResponse:
        return cls(
            id=view.id,
            username=view.username,
            display_name=view.display_name,
            role=view.role,
            status=view.status,
            organization_id=view.organization_id,
            email=view.email,
            created_at=view.created_at,
            updated_at=view.updated_at,
            credential=CredentialSummaryResponse.from_summary(view.credential),
            active_session_count=view.active_session_count,
        )


class AccountListResponse(BaseModel):
    items: list[AccountResponse]
    total: int
    limit: int
    offset: int


class SessionUserResponse(BaseModel):
    """``GET /api/auth/me``. Includes the CSRF token the browser must echo."""

    user: UserResponse
    role: RoleName
    organization_id: UUID | None = None
    must_change_password: bool
    csrf_token: str
    idle_expires_at: datetime | None = None
    absolute_expires_at: datetime | None = None


class LoginResponse(BaseModel):
    user: UserResponse
    must_change_password: bool
    csrf_token: str
    idle_expires_at: datetime
    absolute_expires_at: datetime


class LogoutResponse(BaseModel):
    revoked_sessions: int


class RevokeSessionsResponse(BaseModel):
    revoked_sessions: int


class AuditEventResponse(BaseModel):
    # A store-owned identifier, so a string rather than the UUID the
    # development repository happens to use.
    id: str
    occurred_at: datetime
    action: str
    outcome: str
    actor_user_id: UUID | None = None
    target_user_id: UUID | None = None
    organization_id: UUID | None = None
    request_id: str | None = None
    detail: dict[str, str]

    @classmethod
    def from_event(cls, event: AuditEvent) -> AuditEventResponse:
        return cls(
            id=event.id,
            occurred_at=event.occurred_at,
            action=event.action,
            outcome=event.outcome,
            actor_user_id=event.actor_user_id,
            target_user_id=event.target_user_id,
            organization_id=event.organization_id,
            request_id=event.request_id,
            detail=dict(event.detail),
        )


class AuditListResponse(BaseModel):
    items: list[AuditEventResponse]
    total: int
    limit: int
    offset: int


class LoginRequest(RequestModel):
    username: str = Field(min_length=1, max_length=64)
    password: str = Field(min_length=1, max_length=1024)


class ChangeFirstPasswordRequest(RequestModel):
    current_password: str = Field(min_length=1, max_length=1024)
    new_password: str = Field(min_length=1, max_length=1024)


class CreateAccountRequest(RequestModel):
    """Administrator account creation for either enrollment mode.

    The request never carries a password: the schema forbids unknown fields, so
    a submitted ``password`` is rejected outright. For
    ``enrollment_mode="temporary_password"`` the service generates the one-time
    password itself and returns it once in :class:`CreateAccountResponse`.

    ``email`` is required because the control plane declares ``users.email`` as
    ``NOT NULL UNIQUE``. Making it mandatory here means a missing address is a
    clear field-level rejection rather than a failure that only appears once
    the authoritative store is in use.
    """

    username: str = Field(min_length=1, max_length=64)
    display_name: str = Field(min_length=1, max_length=120)
    email: str = Field(min_length=3, max_length=254)
    enrollment_mode: EnrollmentMode = EnrollmentMode.OIDC
    role: RoleName = RoleName.MEMBER
    organization_id: UUID | None = None


class CreateAccountResponse(BaseModel):
    """Result of ``POST /api/uadmin/accounts``.

    ``temporary_password`` is populated only when the account was enrolled with
    a one-time local password. It is the single response that ever contains
    that value, it is served with ``Cache-Control: no-store``, and it is never
    persisted, logged, or retrievable again: the account must replace it on its
    first login. It is ``None`` for OIDC enrollment.
    """

    account: AccountResponse
    temporary_password: str | None = None

    @classmethod
    def from_oidc(cls, view: AccountView) -> CreateAccountResponse:
        return cls(account=AccountResponse.from_view(view))

    @classmethod
    def from_temporary_password(cls, view: AccountView, temporary_password: str) -> CreateAccountResponse:
        return cls(account=AccountResponse.from_view(view), temporary_password=temporary_password)


class SetAccountStatusRequest(RequestModel):
    status: AccountStatus
    reason: str | None = Field(default=None, max_length=200)


class StatusChangeResponse(BaseModel):
    account: AccountResponse
    revoked_sessions: int


class OrganizationResponse(BaseModel):
    """An organization as returned by the administrator API."""

    id: UUID
    name: str
    slug: str
    status: OrganizationStatus
    member_count: int
    created_at: datetime | None = None
    updated_at: datetime | None = None

    @classmethod
    def from_view(cls, view: OrganizationView) -> OrganizationResponse:
        return cls(
            id=view.id,
            name=view.name,
            slug=view.slug,
            status=view.status,
            member_count=view.member_count,
            created_at=view.created_at,
            updated_at=view.updated_at,
        )


class OrganizationListResponse(BaseModel):
    items: list[OrganizationResponse]
    total: int
    limit: int
    offset: int


class CreateOrganizationRequest(RequestModel):
    """Create a tenant. Platform administrators only.

    ``slug`` is optional and derived from ``name`` when omitted. A supplied
    slug is validated as written, so a rejected value reports the slug rule.
    """

    name: str = Field(min_length=1, max_length=120)
    slug: str | None = Field(default=None, max_length=63)


class UpdateOrganizationRequest(RequestModel):
    """Rename or re-slug an organization. At least one field is required."""

    name: str | None = Field(default=None, min_length=1, max_length=120)
    slug: str | None = Field(default=None, max_length=63)


class SetOrganizationStatusRequest(RequestModel):
    status: OrganizationStatus
    reason: str | None = Field(default=None, max_length=200)


class OrganizationStatusChangeResponse(BaseModel):
    organization: OrganizationResponse
    revoked_sessions: int


class OrganizationSummaryResponse(BaseModel):
    """Counts for the administrator dashboard.

    Derived from the caller's visible scope on every request, so it can never
    report a number the caller could not obtain from the list endpoints.
    """

    total_organizations: int
    active_organizations: int
    total_accounts: int
    active_accounts: int
    suspended_accounts: int
    pending_first_login: int
    organization_admin_count: int


__all__ = [
    "AccountListResponse",
    "AccountResponse",
    "AuditEventResponse",
    "AuditListResponse",
    "ChangeFirstPasswordRequest",
    "CreateAccountRequest",
    "CreateAccountResponse",
    "CredentialSummaryResponse",
    "ErrorResponse",
    "HealthResponse",
    "LoginRequest",
    "LoginResponse",
    "LogoutResponse",
    "CreateOrganizationRequest",
    "OrganizationListResponse",
    "OrganizationResponse",
    "OrganizationStatusChangeResponse",
    "OrganizationSummaryResponse",
    "RevokeSessionsResponse",
    "SessionUserResponse",
    "SetAccountStatusRequest",
    "SetOrganizationStatusRequest",
    "StatusChangeResponse",
    "UpdateOrganizationRequest",
    "UserResponse",
]