feat(user): add authenticated data purge flow (#1108)

Co-authored-by: Darshan G K <122042809+imDarshanGK@users.noreply.github.com>

Author: bhavyajain0810

backend/app/models.py

@@ -17,6 +17,23 @@ class User(Base):
         DateTime, default=lambda: datetime.now(UTC)
     )
 
+    deletion_status: Mapped[str] = mapped_column(
+        String(32),
+        nullable=False,
+        default="active",
+        server_default="active",
+        index=True,
+    )
+    deletion_requested_at: Mapped[datetime | None] = mapped_column(
+        DateTime,
+        nullable=True,
+    )
+    deletion_scheduled_for: Mapped[datetime | None] = mapped_column(
+        DateTime,
+        nullable=True,
+        index=True,
+    )
+
     histories = relationship(
         "QueryHistory", back_populates="user", cascade="all, delete-orphan"
     )
@@ -56,6 +73,21 @@ class FavoriteResult(Base):
     user = relationship("User", back_populates="favorites")
 
 
+class UserDataPurgeAudit(Base):
+    __tablename__ = "user_data_purge_audit"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    user_id_hash: Mapped[str] = mapped_column(String(128), index=True)
+    email_hash: Mapped[str] = mapped_column(String(128), index=True)
+    history_deleted: Mapped[int] = mapped_column(Integer, default=0)
+    favorites_deleted: Mapped[int] = mapped_column(Integer, default=0)
+    requested_at: Mapped[datetime] = mapped_column(
+        DateTime, default=lambda: datetime.now(UTC)
+    )
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    status: Mapped[str] = mapped_column(String(32), default="completed")
+
+
 class DigestSubscription(Base):
     __tablename__ = "digest_subscriptions"
 

backend/app/routers/auth.py

@@ -59,6 +59,12 @@ def login(payload: LoginRequest, db: Session = Depends(get_db)):
             status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials"
         )
 
+    if getattr(user, "deletion_status", "active") == "pending_deletion":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Account is pending deletion",
+        )
+
     token = create_access_token(user.id)
     return AuthResponse(access_token=token, user_id=user.id, email=user.email)
 

backend/app/routers/user_data.py

@@ -9,12 +9,52 @@
     FavoriteRecord,
     HistoryCreateRequest,
     HistoryRecord,
+    UserDataPurgePreviewResponse,
+    UserDataPurgeRequest,
+    UserDataPurgeResponse,
 )
 from ..security import get_current_user
+from ..services.user_deletion import preview_user_data_purge, purge_user_data
 
 router = APIRouter(prefix="/user", tags=["User Data"])
 
 
+@router.get("/data-purge/preview", response_model=UserDataPurgePreviewResponse)
+def preview_data_purge(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    preview = preview_user_data_purge(db, current_user)
+    return UserDataPurgePreviewResponse(
+        user_id=preview.user_id,
+        history_records=preview.history_records,
+        favorite_records=preview.favorite_records,
+        account_will_be_deleted=preview.account_will_be_deleted,
+        confirmation_phrase=preview.confirmation_phrase,
+        deletion_status=preview.deletion_status,
+        retention_days=preview.retention_days,
+        deletion_scheduled_for=preview.deletion_scheduled_for,
+    )
+
+
+@router.post("/data-purge", response_model=UserDataPurgeResponse)
+def purge_data(
+    payload: UserDataPurgeRequest,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    result = purge_user_data(db, current_user, payload.confirmation)
+    return UserDataPurgeResponse(
+        status=result.status,
+        history_deleted=result.history_deleted,
+        favorites_deleted=result.favorites_deleted,
+        account_deleted=result.account_deleted,
+        audit_recorded=result.audit_recorded,
+        deletion_scheduled_for=result.deletion_scheduled_for,
+        retention_days=result.retention_days,
+    )
+
+
 @router.get("/history", response_model=list[HistoryRecord])
 def list_history(
     limit: int = Query(50, ge=1, le=100),

backend/app/schemas.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+from datetime import datetime
 from typing import Any
 
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -709,6 +710,101 @@ class FavoriteRecord(BaseModel):
     )
 
 
+class UserDataPurgePreviewResponse(BaseModel):
+    """Preview of user-owned data that will be removed by a purge request."""
+
+    user_id: int = Field(
+        ...,
+        description="Authenticated user id.",
+        json_schema_extra={"example": 12},
+    )
+    history_records: int = Field(
+        ...,
+        description="Number of saved history records that will be deleted.",
+        json_schema_extra={"example": 4},
+    )
+    favorite_records: int = Field(
+        ...,
+        description="Number of favorite records that will be deleted.",
+        json_schema_extra={"example": 2},
+    )
+    account_will_be_deleted: bool = Field(
+        ...,
+        description="Whether the user account row will be deleted.",
+        json_schema_extra={"example": True},
+    )
+    confirmation_phrase: str = Field(
+        ...,
+        description="Phrase required to confirm irreversible deletion.",
+        json_schema_extra={"example": "DELETE MY DATA"},
+    )
+    deletion_status: str = Field(
+        ...,
+        description="Current user deletion lifecycle status.",
+        json_schema_extra={"example": "active"},
+    )
+    retention_days: int = Field(
+        ...,
+        description="Number of days before final erase becomes eligible.",
+        json_schema_extra={"example": 30},
+    )
+    deletion_scheduled_for: datetime | None = Field(
+        None,
+        description="Timestamp when final erase becomes eligible, if already scheduled.",
+    )
+
+
+class UserDataPurgeRequest(BaseModel):
+    """Confirmation body for irreversible account and data purge."""
+
+    confirmation: str = Field(
+        ...,
+        min_length=1,
+        max_length=64,
+        description="Must exactly match the confirmation phrase.",
+        json_schema_extra={"example": "DELETE MY DATA"},
+    )
+
+
+class UserDataPurgeResponse(BaseModel):
+    """Result returned after successful user data purge."""
+
+    status: str = Field(
+        ...,
+        description="Purge status.",
+        json_schema_extra={"example": "purged"},
+    )
+    history_deleted: int = Field(
+        ...,
+        description="Deleted history record count.",
+        json_schema_extra={"example": 4},
+    )
+    favorites_deleted: int = Field(
+        ...,
+        description="Deleted favorite record count.",
+        json_schema_extra={"example": 2},
+    )
+    account_deleted: bool = Field(
+        ...,
+        description="Whether the user account was deleted.",
+        json_schema_extra={"example": True},
+    )
+    audit_recorded: bool = Field(
+        ...,
+        description="Whether a non-sensitive audit record was stored.",
+        json_schema_extra={"example": True},
+    )
+    deletion_scheduled_for: datetime | None = Field(
+        None,
+        description="Timestamp when final erase becomes eligible.",
+    )
+    retention_days: int = Field(
+        ...,
+        description="Number of days before final erase becomes eligible.",
+        json_schema_extra={"example": 30},
+    )
+
+
 # ── Share ─────────────────────────────────────────────────────────────────────
 
 

backend/app/security.py

@@ -94,6 +94,12 @@ def get_current_user(
             status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found"
         )
 
+    if getattr(user, "deletion_status", "active") == "pending_deletion":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User is pending deletion",
+        )
+
     return user