Set up document management for Stirling Engine (Stirling-Tools#6476)

# Description of Changes
Change Stirling Engine to support deleting documents automatically. This
happens both on user logout and after an amount of time specified by the
Java when ingesting a document (allowing for personal documents to have
short lifetimes but org documents to be left in the db with no expiry
date). Also sets up an [ACL
policy](https://en.wikipedia.org/wiki/Access-control_list) for the
documents so the database knows which users have access to which
documents. This is not fully implemented in the Java, so currently all
docs are treated as having a single owner, the uploader, but
theoretically when we need to support org storage, we shouldn't need to
change the db schema.

Author: jbrunton96

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/AiEngineController.java

@@ -5,6 +5,7 @@
 import java.util.Map;
 import java.util.concurrent.Executor;
 
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.HttpStatus;
@@ -30,6 +31,7 @@
 import stirling.software.common.model.job.ResultFile;
 import stirling.software.common.service.JobOwnershipService;
 import stirling.software.common.service.TaskManager;
+import stirling.software.common.service.UserServiceInterface;
 import stirling.software.proprietary.model.api.ai.AiWorkflowProgressEvent;
 import stirling.software.proprietary.model.api.ai.AiWorkflowRequest;
 import stirling.software.proprietary.model.api.ai.AiWorkflowResponse;
@@ -58,6 +60,7 @@ public class AiEngineController {
     private final TaskManager taskManager;
     private final JobOwnershipService jobOwnershipService;
     private final AiEngineEndpointResolver endpointResolver;
+    private final UserServiceInterface userService;
 
     /**
      * SSE emitter timeout. Long enough to accommodate multi-gigabyte PDF workflows (OCR on a
@@ -74,22 +77,28 @@ public AiEngineController(
             @Qualifier("aiStreamExecutor") Executor aiStreamExecutor,
             TaskManager taskManager,
             JobOwnershipService jobOwnershipService,
-            AiEngineEndpointResolver endpointResolver) {
+            AiEngineEndpointResolver endpointResolver,
+            @Autowired(required = false) UserServiceInterface userService) {
         this.aiEngineClient = aiEngineClient;
         this.aiWorkflowService = aiWorkflowService;
         this.objectMapper = objectMapper;
         this.aiStreamExecutor = aiStreamExecutor;
         this.taskManager = taskManager;
         this.jobOwnershipService = jobOwnershipService;
         this.endpointResolver = endpointResolver;
+        this.userService = userService;
+    }
+
+    private String currentUserId() {
+        return userService != null ? userService.getCurrentUsername() : null;
     }
 
     @GetMapping("/health")
     @Operation(
             summary = "AI engine health check",
             description = "Returns the health status of the AI engine including configured models")
     public ResponseEntity<String> health() throws IOException {
-        String response = aiEngineClient.get("/health");
+        String response = aiEngineClient.get("/health", currentUserId());
         return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body(response);
     }
 
@@ -243,7 +252,7 @@ public ResponseEntity<String> pdfEdit(@RequestBody String requestBody) throws IO
                     HttpStatus.BAD_REQUEST, "Request body must be a JSON object");
         }
         String forwardedBody = withEnabledEndpoints((ObjectNode) parsed);
-        String response = aiEngineClient.post("/api/v1/pdf/edit", forwardedBody);
+        String response = aiEngineClient.post("/api/v1/pdf/edit", forwardedBody, currentUserId());
         return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body(response);
     }
 

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiDocumentIngestRequest.java

@@ -1,5 +1,6 @@
 package stirling.software.proprietary.model.api.ai;
 
+import java.time.Instant;
 import java.util.List;
 
 import lombok.AllArgsConstructor;
@@ -10,6 +11,12 @@
  * Body for {@code POST /api/v1/documents} on the AI engine. Sent by Java when the engine reports
  * {@code need_ingest} and the requested document's extracted content must be stored before the
  * workflow can continue.
+ *
+ * <p>{@code ownerId} is the tenant the doc belongs to (a user for personal uploads, an org for
+ * shared content). {@code readPrincipals} is the explicit list of principals granted read access.
+ * {@code expiresAt} is when the engine's reaper should delete this doc; {@code null} means
+ * "persistent until explicit delete" (used for org-shared content). Java picks the value per doc;
+ * the engine does not default it.
  */
 @Data
 @NoArgsConstructor
@@ -21,4 +28,10 @@ public class AiDocumentIngestRequest {
     private String source;
 
     private List<AiPageText> pageText;
+
+    private String ownerId;
+
+    private List<String> readPrincipals;
+
+    private Instant expiresAt;
 }

app/proprietary/src/main/java/stirling/software/proprietary/security/CustomLogoutSuccessHandler.java

@@ -8,6 +8,8 @@
 import java.util.Locale;
 
 import org.springframework.core.io.Resource;
+import org.springframework.security.authentication.AuthenticationTrustResolver;
+import org.springframework.security.authentication.AuthenticationTrustResolverImpl;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
@@ -36,6 +38,7 @@
 import stirling.software.proprietary.security.saml2.CertificateUtils;
 import stirling.software.proprietary.security.saml2.CustomSaml2AuthenticatedPrincipal;
 import stirling.software.proprietary.security.service.JwtServiceInterface;
+import stirling.software.proprietary.service.AiUserDataService;
 
 @Slf4j
 @RequiredArgsConstructor
@@ -49,12 +52,22 @@ public class CustomLogoutSuccessHandler extends SimpleUrlLogoutSuccessHandler {
 
     private final JwtServiceInterface jwtService;
 
+    private final AiUserDataService aiUserDataService;
+
+    private static final AuthenticationTrustResolver TRUST_RESOLVER =
+            new AuthenticationTrustResolverImpl();
+
     @Override
     @Audited(type = AuditEventType.USER_LOGOUT, level = AuditLevel.BASIC)
     public void onLogoutSuccess(
             HttpServletRequest request, HttpServletResponse response, Authentication authentication)
             throws IOException {
 
+        String username = resolveUsername(request, authentication);
+        if (username != null) {
+            aiUserDataService.purgeUserDocuments(username);
+        }
+
         if (!response.isCommitted()) {
             if (authentication != null) {
                 if (authentication instanceof Saml2Authentication samlAuthentication) {
@@ -88,6 +101,26 @@ public void onLogoutSuccess(
         }
     }
 
+    /**
+     * Pick the right name to purge under. JWT cookie wins if present and parseable; we fall through
+     * to whatever Spring handed us only when there's no cookie. Spring's anonymous principal is
+     * filtered out via {@link AuthenticationTrustResolver} so we don't purge under that
+     * pseudo-user.
+     */
+    private String resolveUsername(HttpServletRequest request, Authentication authentication) {
+        if (jwtService != null) {
+            String fromCookie = jwtService.extractUsernameFromRequestAllowExpired(request);
+            if (fromCookie != null) {
+                return fromCookie;
+            }
+        }
+        if (authentication == null || TRUST_RESOLVER.isAnonymous(authentication)) {
+            return null;
+        }
+        String name = authentication.getName();
+        return (name != null && !name.isBlank()) ? name : null;
+    }
+
     // Redirect for SAML2 authentication logout
     private void getRedirect_saml2(
             HttpServletRequest request,

app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java

@@ -93,6 +93,7 @@ public class SecurityConfiguration {
             licenseSettingsService;
     private final ClientRegistrationRepository clientRegistrationRepository;
     private final PasswordEncoder passwordEncoder;
+    private final stirling.software.proprietary.service.AiUserDataService aiUserDataService;
 
     public SecurityConfiguration(
             PersistentLoginRepository persistentLoginRepository,
@@ -115,7 +116,8 @@ public SecurityConfiguration(
                     OpenSaml5AuthenticationRequestResolver saml2AuthenticationRequestResolver,
             @Autowired(required = false) ClientRegistrationRepository clientRegistrationRepository,
             stirling.software.proprietary.service.UserLicenseSettingsService licenseSettingsService,
-            PasswordEncoder passwordEncoder) {
+            PasswordEncoder passwordEncoder,
+            stirling.software.proprietary.service.AiUserDataService aiUserDataService) {
         this.userDetailsService = userDetailsService;
         this.userService = userService;
         this.loginEnabledValue = loginEnabledValue;
@@ -135,6 +137,7 @@ public SecurityConfiguration(
         this.clientRegistrationRepository = clientRegistrationRepository;
         this.licenseSettingsService = licenseSettingsService;
         this.passwordEncoder = passwordEncoder;
+        this.aiUserDataService = aiUserDataService;
     }
 
     /**
@@ -322,7 +325,10 @@ private SecurityFilterChain configureSecurity(
                                                     .matcher("/logout"))
                                     .logoutSuccessHandler(
                                             new CustomLogoutSuccessHandler(
-                                                    securityProperties, appConfig, jwtService))
+                                                    securityProperties,
+                                                    appConfig,
+                                                    jwtService,
+                                                    aiUserDataService))
                                     .clearAuthentication(true)
                                     .invalidateHttpSession(true)
                                     .deleteCookies("JSESSIONID", "remember-me", "stirling_jwt"));

app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/AuthController.java

@@ -44,6 +44,7 @@
 import stirling.software.proprietary.security.service.TotpService;
 import stirling.software.proprietary.security.service.UserService;
 import stirling.software.proprietary.security.util.DesktopClientUtils;
+import stirling.software.proprietary.service.AiUserDataService;
 
 /** REST API Controller for authentication operations. */
 @RestController
@@ -62,6 +63,7 @@ public class AuthController {
     private final RefreshRateLimitService refreshRateLimitService;
     private final ApplicationProperties.Security securityProperties;
     private final ApplicationProperties applicationProperties;
+    private final AiUserDataService aiUserDataService;
 
     /**
      * Login endpoint - replaces Supabase signInWithPassword
@@ -281,11 +283,13 @@ public ResponseEntity<?> getCurrentUser() {
      */
     @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
     @PostMapping("/logout")
-    public ResponseEntity<?> logout(HttpServletResponse response) {
+    public ResponseEntity<?> logout(HttpServletRequest request, HttpServletResponse response) {
         try {
+            String username = jwtService.extractUsernameFromRequestAllowExpired(request);
             SecurityContextHolder.clearContext();
+            aiUserDataService.purgeUserDocuments(username);
 
-            log.debug("User logged out successfully");
+            log.debug("User logged out successfully (username={})", username);
 
             return ResponseEntity.ok(Map.of("message", "Logged out successfully"));
 

app/proprietary/src/main/java/stirling/software/proprietary/security/service/JwtService.java

@@ -349,6 +349,21 @@ public String extractToken(HttpServletRequest request) {
         return null;
     }
 
+    @Override
+    public String extractUsernameFromRequestAllowExpired(HttpServletRequest request) {
+        try {
+            String token = extractToken(request);
+            if (token == null || token.isBlank()) {
+                return null;
+            }
+            String username = extractUsernameAllowExpired(token);
+            return (username != null && !username.isBlank()) ? username : null;
+        } catch (Exception e) {
+            log.debug("Could not extract username from request JWT: {}", e.getMessage());
+            return null;
+        }
+    }
+
     @Override
     public boolean isJwtEnabled() {
         return v2Enabled;

app/proprietary/src/main/java/stirling/software/proprietary/security/service/JwtServiceInterface.java

@@ -93,6 +93,19 @@ public interface JwtServiceInterface {
      */
     String extractToken(HttpServletRequest request);
 
+    /**
+     * Read the username off the request's JWT, allowing an expired token. Returns null when no
+     * token is present, the token can't be parsed, or the resulting username is blank.
+     *
+     * <p>Used by flows that need to identify the user without depending on {@code
+     * SecurityContextHolder} - for example logout, where the security filter chain may have left
+     * the anonymous principal in place by the time the handler runs.
+     *
+     * @param request HTTP servlet request
+     * @return username from the token, or null when one can't be safely derived
+     */
+    String extractUsernameFromRequestAllowExpired(HttpServletRequest request);
+
     /**
      * Check if JWT authentication is enabled
      *