feat: enforce research participation consent (#524)

Author: FelixTJDietrich

.github/workflows/ci-quality-gates.yml

@@ -185,10 +185,7 @@ jobs:
         run: |
           echo "🔍 Running intelligence-service quality checks..."
           cd server/intelligence-service
-
-          if [ ! -d ".venv" ]; then
-            poetry install --no-interaction --no-root
-          fi
+          poetry install --no-interaction --no-root --with dev
 
           ISSUES_FOUND=()
 
@@ -225,10 +222,7 @@ jobs:
         run: |
           echo "🔍 Running webhook-ingest quality checks..."
           cd server/webhook-ingest
-
-          if [ ! -d ".venv" ]; then
-            poetry install --no-interaction --no-root
-          fi
+          poetry install --no-interaction --no-root --with dev
 
           ISSUES_FOUND=()
 
@@ -270,9 +264,7 @@ jobs:
 
           # Setup Python environments
           cd server/intelligence-service
-          if [ ! -d ".venv" ]; then
-            poetry install --no-interaction --no-root
-          fi
+          poetry install --no-interaction --no-root --with dev
           cd ../..
 
           # Setup application-server environment

AGENTS.md

@@ -32,7 +32,7 @@ Run the relevant commands locally before opening a PR:
 | Intelligence service lint/type check | `poetry run black --check .`, `poetry run flake8 .`, `poetry run mypy .` inside `server/intelligence-service`. |
 | Webhook ingest lint | `poetry run black --check .` and `poetry run flake8 .` inside `server/webhook-ingest`. |
 
-Document any skipped gate in the PR description with a rationale.
+Document any skipped gate in the PR description with a rationale. Always finish a change set by running `npm run format` followed by `npm run lint` so both styling and type checks reflect the final state.
 
 ## 4. Code generation & forbidden edits
 We rely heavily on generated artifacts. Never hand-edit these directories—regenerate instead:
@@ -54,6 +54,7 @@ Regeneration is destructive; stash local edits before running these commands. Ch
   1. Spin up PostgreSQL through Docker (ensure Docker is running or set `CI=true` with a ready Postgres).
   2. Snapshot the schema, run Liquibase diff, and create a timestamped changelog file.
   3. Tear down the temporary container.
+- Trim the generated changelog to only the real schema deltas (e.g., new columns). Never commit the raw diff wholesale—prune back to the minimal change set before renaming it into `db/changelog/`.
 - After drafting a changelog, run `npm run db:generate-erd-docs` and `npm run db:generate-models:intelligence-service` to keep ERD docs and SQLAlchemy models in sync.
 - Never manually edit generated Liquibase diff sections unless you fully understand the implications. Prefer creating a follow-up changelog to fix mistakes.
 
@@ -76,6 +77,7 @@ Regeneration is destructive; stash local edits before running these commands. Ch
 - Reuse existing DTO converters/mappers instead of duplicating mapping logic. Look at `gitprovider.team` for established patterns.
 - Security: new endpoints must enforce permissions using the existing security utilities (`EnsureAdminUser`, etc.).
 - Keep Liquibase changelog IDs monotonic and descriptive. Align entity annotations with the generated change sets.
+- Annotate record components in DTOs with `@NonNull` whenever the API should require them so the generated OpenAPI schema matches the backend contract.
 - When integrating with the intelligence-service client, always regenerate (`npm run generate:api:intelligence-service:client`) after touching the spec and commit the updated Java files.
 
 ## 8. Python services expectations

docker/compose.app.yaml

@@ -12,6 +12,7 @@ services:
       LEGAL_PRIVACY_HTML: ${LEGAL_PRIVACY_HTML}
       SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT}
       SENTRY_DSN: ${SENTRY_DSN}
+      POSTHOG_ENABLED: ${POSTHOG_ENABLED:-false}
       POSTHOG_PROJECT_API_KEY: ${POSTHOG_PROJECT_API_KEY}
       POSTHOG_API_HOST: ${POSTHOG_API_HOST}
     ports:
@@ -90,6 +91,10 @@ services:
       LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY}
       LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY}
       LANGFUSE_HOST: ${LANGFUSE_HOST}
+      POSTHOG_ENABLED: ${POSTHOG_ENABLED:-false}
+      POSTHOG_API_HOST: ${POSTHOG_API_HOST:-https://app.posthog.com}
+      POSTHOG_PROJECT_ID: ${POSTHOG_PROJECT_ID:-}
+      POSTHOG_PERSONAL_API_KEY: ${POSTHOG_PERSONAL_API_KEY:-}
     depends_on:
       - postgres
     restart: unless-stopped

docs/contributor/erd/schema.mmd

@@ -314,6 +314,7 @@ erDiagram
         VARCHAR(255) type
         INTEGER league_points "NOT NULL"
         BOOLEAN notifications_enabled "NOT NULL"
+        BOOLEAN participate_in_research "NOT NULL"
     }
 
     Workspace {

server/application-server/openapi.yaml

@@ -2749,8 +2749,13 @@ components:
     UserSettings:
       type: object
       properties:
+        participateInResearch:
+          type: boolean
         receiveNotifications:
           type: boolean
+      required:
+      - participateInResearch
+      - receiveNotifications
     UserTeams:
       type: object
       properties:

server/application-server/src/main/java/de/tum/in/www1/hephaestus/gitprovider/pullrequestreviewcomment/github/GitHubPullRequestReviewCommentSyncService.java

@@ -123,11 +123,13 @@ public PullRequestReviewComment processPullRequestReviewComment(
 
         pullRequestReviewRepository
             .findById(ghPullRequestReviewComment.getPullRequestReviewId())
-            .ifPresentOrElse(result::setReview, () -> logger.error(
-                "Failed to link review for pull request review comment {}: {}",
-                ghPullRequestReviewComment.getId(),
-                "Review not found"
-            ));
+            .ifPresentOrElse(result::setReview, () ->
+                logger.error(
+                    "Failed to link review for pull request review comment {}: {}",
+                    ghPullRequestReviewComment.getId(),
+                    "Review not found"
+                )
+            );
 
         attachAuthor(ghPullRequestReviewComment, result);
 
@@ -143,10 +145,7 @@ public PullRequestReviewComment processPullRequestReviewComment(
         return persisted;
     }
 
-    private PullRequestReviewComment updateIfNewer(
-        GHPullRequestReviewComment source,
-        PullRequestReviewComment target
-    ) {
+    private PullRequestReviewComment updateIfNewer(GHPullRequestReviewComment source, PullRequestReviewComment target) {
         try {
             if (target.getUpdatedAt() == null || target.getUpdatedAt().isBefore(source.getUpdatedAt())) {
                 return pullRequestReviewCommentConverter.update(source, target);
@@ -158,10 +157,7 @@ private PullRequestReviewComment updateIfNewer(
         }
     }
 
-    private void attachAuthor(
-        GHPullRequestReviewComment ghPullRequestReviewComment,
-        PullRequestReviewComment comment
-    ) {
+    private void attachAuthor(GHPullRequestReviewComment ghPullRequestReviewComment, PullRequestReviewComment comment) {
         try {
             GHUser user = ghPullRequestReviewComment.getUser();
             if (user == null) {
@@ -258,7 +254,10 @@ public void deletePullRequestReviewComment(long commentId) {
             .findById(commentId)
             .ifPresent(comment -> {
                 var thread = comment.getThread();
-                boolean isRootComment = thread != null && thread.getRootComment() != null && thread.getRootComment().getId().equals(commentId);
+                boolean isRootComment =
+                    thread != null &&
+                    thread.getRootComment() != null &&
+                    thread.getRootComment().getId().equals(commentId);
 
                 if (isRootComment) {
                     pullRequestReviewThreadRepository.delete(thread);

server/application-server/src/main/java/de/tum/in/www1/hephaestus/gitprovider/pullrequestreviewthread/github/GitHubPullRequestReviewThreadSyncService.java

@@ -69,7 +69,10 @@ public PullRequestReviewThread processThreadEvent(GHEventPayloadPullRequestRevie
             .toList();
 
         for (GHPullRequestReviewComment comment : sortedComments) {
-            PullRequestReviewComment persisted = commentSyncService.processPullRequestReviewComment(comment, ghPullRequest);
+            PullRequestReviewComment persisted = commentSyncService.processPullRequestReviewComment(
+                comment,
+                ghPullRequest
+            );
             if (persisted != null) {
                 thread = persisted.getThread();
             }

server/application-server/src/main/java/de/tum/in/www1/hephaestus/gitprovider/user/User.java

@@ -98,6 +98,9 @@ public class User extends BaseGitServiceEntity {
     @NonNull
     private boolean notificationsEnabled = true;
 
+    @NonNull
+    private boolean participateInResearch = true;
+
     // Current ranking points for the leaderboard leagues
     private int leaguePoints;
 

server/application-server/src/main/java/de/tum/in/www1/hephaestus/gitprovider/user/UserController.java

@@ -1,12 +1,17 @@
 package de.tum.in.www1.hephaestus.gitprovider.user;
 
+import de.tum.in.www1.hephaestus.integrations.posthog.PosthogClientException;
 import java.util.Optional;
 import org.keycloak.admin.client.Keycloak;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.security.oauth2.core.oidc.StandardClaimNames;
 import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationToken;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -46,20 +51,33 @@ public ResponseEntity<UserProfileDTO> getUserProfile(@PathVariable String login)
     }
 
     @DeleteMapping
-    public ResponseEntity<Void> deleteUser(JwtAuthenticationToken auth) {
-        if (auth == null) {
-            logger.error("No authentication token found.");
-            return ResponseEntity.badRequest().body(null);
+    public ResponseEntity<Void> deleteUser(@AuthenticationPrincipal JwtAuthenticationToken auth) {
+        JwtAuthenticationToken token = resolveAuthentication(auth);
+        if (token == null) {
+            logger.error("No authentication token found");
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
         }
 
-        String userId = auth.getToken().getClaimAsString(StandardClaimNames.SUB);
-        logger.info("Deleting user {}", userId);
-        var response = keycloak.realm(realm).users().delete(userId);
+        String keycloakUserId = token.getToken().getClaimAsString(StandardClaimNames.SUB);
+        var gitUser = userRepository.getCurrentUser();
+        if (gitUser.isEmpty()) {
+            logger.warn("Could not resolve Git provider user for Keycloak subject {}", keycloakUserId);
+        }
+
+        try {
+            userService.deleteUserTrackingData(gitUser, keycloakUserId);
+        } catch (PosthogClientException exception) {
+            logger.error("Failed to remove analytics data before deleting user {}", keycloakUserId, exception);
+            return ResponseEntity.status(HttpStatus.BAD_GATEWAY).build();
+        }
+
+        logger.info("Deleting user {}", keycloakUserId);
+        var response = keycloak.realm(realm).users().delete(keycloakUserId);
         if (response.getStatus() != 204) {
             logger.error("Failed to delete user account: {}", response.getStatusInfo().getReasonPhrase());
-            return ResponseEntity.badRequest().body(null);
+            return ResponseEntity.status(HttpStatus.BAD_GATEWAY).build();
         }
-        return ResponseEntity.ok().build();
+        return ResponseEntity.noContent().build();
     }
 
     @GetMapping("/settings")
@@ -74,13 +92,39 @@ public ResponseEntity<UserSettingsDTO> getUserSettings() {
     }
 
     @PostMapping("/settings")
-    public ResponseEntity<UserSettingsDTO> updateUserSettings(@RequestBody UserSettingsDTO userSettings) {
+    public ResponseEntity<UserSettingsDTO> updateUserSettings(
+        @AuthenticationPrincipal JwtAuthenticationToken auth,
+        @RequestBody UserSettingsDTO userSettings
+    ) {
         var user = userRepository.getCurrentUser();
         if (user.isEmpty()) {
             return ResponseEntity.notFound().build();
         }
 
-        UserSettingsDTO updatedUserSettings = userService.updateUserSettings(user.get(), userSettings);
+        JwtAuthenticationToken token = resolveAuthentication(auth);
+        String keycloakUserId = null;
+        if (token != null) {
+            keycloakUserId = token.getToken().getClaimAsString(StandardClaimNames.SUB);
+        } else {
+            logger.warn("Updating user settings without an authenticated principal");
+            boolean switchingOffResearch =
+                Boolean.FALSE.equals(userSettings.participateInResearch()) && user.get().isParticipateInResearch();
+            if (switchingOffResearch) {
+                return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+            }
+        }
+        UserSettingsDTO updatedUserSettings = userService.updateUserSettings(user.get(), userSettings, keycloakUserId);
         return ResponseEntity.ok(updatedUserSettings);
     }
+
+    private JwtAuthenticationToken resolveAuthentication(JwtAuthenticationToken injectedToken) {
+        if (injectedToken != null) {
+            return injectedToken;
+        }
+        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+        if (authentication instanceof JwtAuthenticationToken jwtAuthenticationToken) {
+            return jwtAuthenticationToken;
+        }
+        return null;
+    }
 }

server/application-server/src/main/java/de/tum/in/www1/hephaestus/gitprovider/user/UserService.java

@@ -9,18 +9,25 @@
 import de.tum.in.www1.hephaestus.gitprovider.pullrequestreview.PullRequestReviewRepository;
 import de.tum.in.www1.hephaestus.gitprovider.repository.RepositoryInfoDTO;
 import de.tum.in.www1.hephaestus.gitprovider.repository.RepositoryRepository;
+import de.tum.in.www1.hephaestus.integrations.posthog.PosthogClient;
+import de.tum.in.www1.hephaestus.integrations.posthog.PosthogClientException;
 import jakarta.transaction.Transactional;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Comparator;
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 import java.util.stream.Collectors;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.HttpStatus;
 import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+import org.springframework.web.server.ResponseStatusException;
 
 @Service
 public class UserService {
@@ -45,6 +52,9 @@ public class UserService {
     @Autowired
     private PullRequestReviewInfoDTOConverter pullRequestReviewInfoDTOConverter;
 
+    @Autowired
+    private PosthogClient posthogClient;
+
     @Transactional
     public Optional<UserProfileDTO> getUserProfile(String login) {
         logger.info("Getting user profile with login: " + login);
@@ -90,13 +100,71 @@ public Optional<UserProfileDTO> getUserProfile(String login) {
 
     public UserSettingsDTO getUserSettings(User user) {
         logger.info("Getting user settings with userId: " + user);
-        return new UserSettingsDTO(user.isNotificationsEnabled());
+        return new UserSettingsDTO(user.isNotificationsEnabled(), user.isParticipateInResearch());
     }
 
-    public UserSettingsDTO updateUserSettings(User user, UserSettingsDTO userSettings) {
+    public UserSettingsDTO updateUserSettings(User user, UserSettingsDTO userSettings, String keycloakUserId) {
         logger.info("Updating user settings with userId: " + user);
-        user.setNotificationsEnabled(userSettings.receiveNotifications());
+        user.setNotificationsEnabled(
+            Objects.requireNonNull(userSettings.receiveNotifications(), "receiveNotifications must not be null")
+        );
+        boolean previousParticipation = user.isParticipateInResearch();
+        boolean participatesInResearch = Objects.requireNonNull(
+            userSettings.participateInResearch(),
+            "participateInResearch must not be null"
+        );
+        user.setParticipateInResearch(participatesInResearch);
         userRepository.save(user);
-        return new UserSettingsDTO(user.isNotificationsEnabled());
+        if (previousParticipation && !participatesInResearch) {
+            if (!StringUtils.hasText(keycloakUserId)) {
+                throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Missing authentication subject");
+            }
+            try {
+                boolean anyDeleted = deletePosthogIdentities(user, keycloakUserId);
+                if (!anyDeleted) {
+                    logger.warn("No PostHog person matched the provided identifiers for user {}", user.getLogin());
+                }
+            } catch (PosthogClientException exception) {
+                throw new ResponseStatusException(
+                    HttpStatus.BAD_GATEWAY,
+                    "Failed to revoke analytics consent",
+                    exception
+                );
+            }
+        }
+        return new UserSettingsDTO(user.isNotificationsEnabled(), user.isParticipateInResearch());
+    }
+
+    public void deleteUserTrackingData(Optional<User> user, String keycloakUserId) {
+        try {
+            boolean anyDeleted = deletePosthogIdentities(user.orElse(null), keycloakUserId);
+            if (!anyDeleted) {
+                logger.warn(
+                    "No PostHog person matched the provided identifiers for user {} during account deletion",
+                    user.map(User::getLogin).orElse("unknown")
+                );
+            }
+        } catch (PosthogClientException exception) {
+            throw exception;
+        }
+    }
+
+    private boolean deletePosthogIdentities(User user, String primaryDistinctId) {
+        Set<String> distinctIds = new LinkedHashSet<>();
+        if (StringUtils.hasText(primaryDistinctId)) {
+            distinctIds.add(primaryDistinctId);
+        }
+        if (user != null) {
+            distinctIds.add(String.valueOf(user.getId()));
+        }
+
+        boolean anyDeleted = false;
+        for (String distinctId : distinctIds) {
+            if (!StringUtils.hasText(distinctId)) {
+                continue;
+            }
+            anyDeleted = posthogClient.deletePersonData(distinctId) || anyDeleted;
+        }
+        return anyDeleted;
     }
 }