M4-T05: add TOTP service and setup/enable/disable/status API

app/schemas/totp.py

@@ -0,0 +1,59 @@
+"""Pydantic schemas for TOTP setup / enable / disable / status endpoints (M4-T05)."""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+# ---------------------------------------------------------------------------
+# Setup (POST /api/auth/totp/setup) — response
+# ---------------------------------------------------------------------------
+
+
+class TotpSetupResponse(BaseModel):
+    """Returned once after a setup call.
+
+    ``secret`` and ``recovery_codes`` are **one-time plaintext values**.
+    They are never returned again by any subsequent API call.
+    The frontend must display and instruct the user to save them before confirming.
+    """
+
+    secret: str
+    otpauth_uri: str
+    recovery_codes: list[str]
+
+
+# ---------------------------------------------------------------------------
+# Enable (POST /api/auth/totp/enable) — request
+# ---------------------------------------------------------------------------
+
+
+class TotpEnableRequest(BaseModel):
+    """The user confirms setup by providing the 6-digit TOTP code."""
+
+    code: str
+
+
+# ---------------------------------------------------------------------------
+# Disable (POST /api/auth/totp/disable) — request
+# ---------------------------------------------------------------------------
+
+
+class TotpDisableRequest(BaseModel):
+    """Disable TOTP by proving identity.
+
+    Exactly one of ``password`` or ``code`` must be provided.
+    """
+
+    password: str | None = None
+    code: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Status (GET /api/auth/totp) — response
+# ---------------------------------------------------------------------------
+
+
+class TotpStatusResponse(BaseModel):
+    """Minimal status response — never exposes secret or recovery codes."""
+
+    enabled: bool