Harden auth and security controls with session auth and docs

backend/app/schemas/auth.py

@@ -0,0 +1,48 @@
+"""Pydantic schemas for authentication and session API payloads."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from app.models.auth import UserRole
+
+
+class AuthLoginRequest(BaseModel):
+    """Represents credential input used to create one authenticated API session."""
+
+    username: str = Field(min_length=1, max_length=128)
+    password: str = Field(min_length=1, max_length=256)
+
+
+class AuthUserResponse(BaseModel):
+    """Represents one authenticated user identity and authorization role."""
+
+    id: UUID
+    username: str
+    role: UserRole
+
+    class Config:
+        """Enables ORM object parsing for SQLAlchemy model instances."""
+
+        from_attributes = True
+
+
+class AuthSessionResponse(BaseModel):
+    """Represents active session metadata for one authenticated user."""
+
+    user: AuthUserResponse
+    expires_at: datetime
+
+
+class AuthLoginResponse(AuthSessionResponse):
+    """Represents one newly issued bearer token and associated user context."""
+
+    access_token: str
+    token_type: str = "bearer"
+
+
+class AuthLogoutResponse(BaseModel):
+    """Represents logout outcome after current session revocation attempt."""
+
+    revoked: bool