Merge pull request #306 from spoo-me/feat/account-deletion

feat: self-serve account deletion with scheduled erasure

Author: Zingzy

.github/workflows/tests.yaml

@@ -52,6 +52,19 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
+    # Real MongoDB for tests/db — that suite fails loudly (never skips)
+    # when CI is set, so this container is load-bearing.
+    services:
+      mongo:
+        image: mongo:8
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --quiet --eval 'db.runCommand({ping: 1})'"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -70,6 +83,7 @@ jobs:
       - name: Run tests with coverage
         env:
           MONGODB_URI: "mongodb://localhost:27017/"
+          MONGO_TEST_URI: "mongodb://localhost:27017/?directConnection=true"
         run: |
           uv run python -m pytest \
             -n auto \

config.py

@@ -87,6 +87,39 @@ class EmailSettings(BaseSettings):
     zepto_from_name: str = "spoo.me"
 
 
+class PostHogErasureSettings(BaseSettings):
+    """PostHog person deletion for the account-erasure cascade (GDPR Art. 17).
+
+    Off unless both ``api_key`` and ``project_id`` are set — the cascade
+    then skips the step via the Noop eraser. The key is a personal API key
+    with person-deletion scope, NOT the public project key. Env vars
+    prefixed ``POSTHOG_ERASURE_`` (same convention as ``R2_``).
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        extra="ignore",
+        env_prefix="POSTHOG_ERASURE_",
+    )
+
+    api_key: str = ""
+    project_id: str = ""
+    host: str = "https://eu.posthog.com"
+
+    @field_validator("host")
+    @classmethod
+    def _host_must_be_https(cls, v: str) -> str:
+        # The key is a person-deletion-scoped personal API key — a config
+        # typo must never send it over plaintext. Fail at boot, not mid-sweep.
+        if not v.startswith("https://"):
+            raise ValueError("POSTHOG_ERASURE_HOST must be an https:// URL")
+        return v
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.api_key and self.project_id)
+
+
 class LoggingSettings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 
@@ -694,6 +727,18 @@ def blocked_self_domains(self) -> tuple[str, ...]:
     max_active_api_keys: int = 20
     max_date_range_days: int = 90
     http_client_timeout: float = 5.0
+    # Account deletion (GDPR Art. 17): days between the deletion request
+    # and the erasure sweep purging the account (0 = purge on the next
+    # sweep — integration smoke only), and how many due accounts one
+    # sweep run erases (the */10 cron drains any backlog).
+    account_deletion_grace_days: int = 7
+    account_erasure_batch_limit: int = 25
+    # Sweep-run budget: stop STARTING erasures past this (80% of the 600s
+    # scheduler lease) so a batch of heavy cascades never outruns the lease.
+    account_erasure_time_budget_seconds: int = 480
+    # Erasure-claim lease: ERASING accounts re-claim only after this — must
+    # exceed the sweep budget plus one heavy cascade (prod whale ~305s).
+    account_erasure_claim_lease_seconds: int = 900
 
     # Validator constraints (overridable by self-hosters via env vars)
     blocked_url_regex_timeout: float = 0.2
@@ -723,13 +768,24 @@ def blocked_self_domains(self) -> tuple[str, ...]:
         "max_emoji_alias_length",
         "emoji_generated_alias_length",
         "geo_rules_max_countries",
+        "account_erasure_batch_limit",
+        "account_erasure_time_budget_seconds",
+        "account_erasure_claim_lease_seconds",
     )
     @classmethod
     def _must_be_positive_int(cls, v: int, info) -> int:
         if v < 1:
             raise ValueError(f"{info.field_name} must be >= 1, got {v}")
         return v
 
+    @field_validator("account_deletion_grace_days")
+    @classmethod
+    def _grace_days_non_negative(cls, v: int) -> int:
+        # 0 is legal (purge on the next sweep) — negatives are not.
+        if v < 0:
+            raise ValueError(f"account_deletion_grace_days must be >= 0, got {v}")
+        return v
+
     @field_validator("emoji_accept_max_version", "emoji_generate_max_version")
     @classmethod
     def _emoji_version_cap_sane(cls, v: float, info) -> float:
@@ -791,6 +847,7 @@ def _password_max_length_sane(cls, v: int) -> int:
     safety: SafetySettings | None = None
     scheduler: SchedulerSettings | None = None
     llm: LlmSettings | None = None
+    posthog_erasure: PostHogErasureSettings | None = None
 
     @model_validator(mode="after")
     def _populate_sub_configs_and_secret(self) -> AppSettings:
@@ -838,6 +895,8 @@ def _populate_sub_configs_and_secret(self) -> AppSettings:
             self.safety = SafetySettings()
         if self.scheduler is None:
             self.scheduler = SchedulerSettings()
+        if self.posthog_erasure is None:
+            self.posthog_erasure = PostHogErasureSettings()
         if self.webhooks.enabled and not self.secret_key:
             # Signing secrets are encrypted with a key derived from
             # SECRET_KEY; an empty master would mean a predictable key.
@@ -851,6 +910,11 @@ def _populate_sub_configs_and_secret(self) -> AppSettings:
                 "CUSTOM_DOMAINS_MOCK_DCV must not be enabled in production"
             )
 
+        # Zero grace purges on the next sweep — a smoke-test convenience
+        # that in production would void the restore window. Refuse to boot.
+        if self.env == "production" and self.account_deletion_grace_days < 1:
+            raise ValueError("ACCOUNT_DELETION_GRACE_DAYS must be >= 1 in production")
+
         return self
 
     @property

dependencies/__init__.py

@@ -53,6 +53,7 @@
     get_settings,
 )
 from dependencies.services import (
+    AccountDeletionSvc,
     ApiKeySvc,
     AppGrantRepo,
     BulkUrlSvc,
@@ -78,6 +79,7 @@
     VerificationSvc,
     WebhookSvc,
     fetch_user_profile,
+    get_account_deletion_service,
     get_api_key_service,
     get_app_grant_repo,
     get_bulk_url_service,
@@ -112,6 +114,7 @@
     "URL_MANAGEMENT_SCOPES",
     "URL_READ_SCOPES",
     # services (aliases)
+    "AccountDeletionSvc",
     "ApiKeySvc",
     "AppGrantRepo",
     # infra
@@ -155,6 +158,7 @@
     "check_credential_scopes",
     # services (getters)
     "fetch_user_profile",
+    "get_account_deletion_service",
     "get_api_key_service",
     "get_app_grant_repo",
     "get_app_registry",

dependencies/auth.py

@@ -17,13 +17,19 @@
 from fastapi import Depends, Request
 
 from dependencies.infra import get_db, get_settings
-from errors import AuthenticationError, EmailNotVerifiedError, ForbiddenError
+from errors import (
+    AccountPendingDeletionError,
+    AuthenticationError,
+    EmailNotVerifiedError,
+    ForbiddenError,
+)
 from infrastructure.crypto import hash_token
 from infrastructure.logging import get_logger
 from repositories.api_key_repository import ApiKeyRepository
 from repositories.user_repository import UserRepository
 from schemas.dto.requests.api_key import ApiKeyScope
 from schemas.models.api_key import ApiKeyDoc
+from schemas.models.user import UserStatus
 from shared.datetime_utils import as_aware_utc
 
 log = get_logger(__name__)
@@ -76,7 +82,11 @@ async def get_current_user(
       3. access_token cookie               →  JWT path
       4. None                              →  anonymous
 
-    Returns None for anonymous requests; never raises.
+    Returns None for anonymous requests. Never raises for malformed or
+    invalid credentials — the one exception is a VALID API key whose
+    account is pending deletion, which raises
+    ``AccountPendingDeletionError`` (403 + ``X-Error-Code``) so keys go
+    dark for the grace window instead of degrading to anonymous.
     """
     settings = get_settings(request)
     jwt_cfg = settings.jwt
@@ -129,6 +139,23 @@ async def get_current_user(
             except Exception:
                 return None
 
+            # Keys go dark during the deletion grace window — same error
+            # surface as the login gate (INACTIVE stays ungated: login parity).
+            if user is not None and user.status in (
+                UserStatus.PENDING_DELETION,
+                UserStatus.ERASING,
+            ):
+                log.warning(
+                    "api_key_auth_blocked",
+                    reason="pending_deletion",
+                    key_prefix=key.token_prefix,
+                    key_id=str(key.id),
+                    user_id=str(key.user_id),
+                )
+                raise AccountPendingDeletionError(
+                    "this account is scheduled for deletion"
+                )
+
             # Best-effort last-used stamp — debounced so a busy key costs at
             # most one extra write per hour, and never fails the request.
             last_used = as_aware_utc(key.last_used_at)

dependencies/services.py

@@ -17,6 +17,7 @@
 from repositories.app_grant_repository import AppGrantRepository
 from repositories.user_repository import UserRepository
 from schemas.models.user import UserDoc
+from services.account_deletion_service import AccountDeletionService
 from services.api_key_service import ApiKeyService
 from services.auth.credentials import CredentialService
 from services.auth.device import DeviceAuthService
@@ -95,6 +96,10 @@ def get_user_repo(request: Request) -> UserRepository:
     return request.app.state.user_repo
 
 
+def get_account_deletion_service(request: Request) -> AccountDeletionService:
+    return request.app.state.account_deletion_service
+
+
 async def fetch_user_profile(user_repo: UserRepository, user_id: ObjectId) -> UserDoc:
     """Fetch a user by ID or raise NotFoundError.
 
@@ -174,6 +179,9 @@ def get_webhook_service(request: Request) -> WebhookService:
 PasswordSvc = Annotated[PasswordService, Depends(get_password_service)]
 DeviceAuthSvc = Annotated[DeviceAuthService, Depends(get_device_auth_service)]
 UserRepo = Annotated[UserRepository, Depends(get_user_repo)]
+AccountDeletionSvc = Annotated[
+    AccountDeletionService, Depends(get_account_deletion_service)
+]
 OAuthSvc = Annotated[OAuthService, Depends(get_oauth_service)]
 ProfilePictureSvc = Annotated[
     ProfilePictureService, Depends(get_profile_picture_service)