Attach public session credentials on outbound HQ calls

For a public web apps session, formplayer's outbound calls to HQ must send the
`public_form_session_key` cookie together with the `CommCare-Public-Session:
true` header, and must NOT send the Django `sessionid`.

- New `PublicFormSessionAuth` (an `HqAuth`) emits exactly that cookie+header
  pair and nothing else; its key is guarded and never logged.
- `UserRestoreAspect.getHqAuth` now selects the credential for the request:
  if the authenticated user is a public session it returns a
  `PublicFormSessionAuth` built from the session key, otherwise the existing
  `DjangoAuth`/null.

Gated on the HMAC-authenticated `public` field (`isPublicSession()`), never
on the client-supplied header; the public credential is preferred when both
signals are present.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nospame

src/main/java/org/commcare/formplayer/aspects/UserRestoreAspect.java

@@ -5,9 +5,12 @@
 import io.sentry.Sentry;
 import org.commcare.formplayer.auth.DjangoAuth;
 import org.commcare.formplayer.auth.HqAuth;
+import org.commcare.formplayer.auth.PublicFormSessionAuth;
 import org.commcare.formplayer.beans.AuthenticatedRequestBean;
 import org.commcare.formplayer.beans.SessionRequestBean;
+import org.commcare.formplayer.beans.auth.HqUserDetailsBean;
 import org.commcare.formplayer.objects.SerializableFormSession;
+import org.commcare.formplayer.util.RequestUtils;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.aspectj.lang.JoinPoint;
@@ -23,6 +26,7 @@
 import org.commcare.formplayer.services.RestoreFactory;
 
 import java.util.Arrays;
+import java.util.Optional;
 
 import datadog.trace.api.interceptor.MutableSpan;
 
@@ -115,7 +119,15 @@ public void closeRestoreFactory(JoinPoint joinPoint) throws Throwable {
         restoreFactory.getSQLiteDB().closeConnection();
     }
 
-    private HqAuth getHqAuth(String sessionToken) {
+    // Package-private for testing.
+    HqAuth getHqAuth(String sessionToken) {
+        // A public web apps session has no Django sessionid; authenticate its outbound HQ calls
+        // with the public session key instead. Gate this on the HMAC-authenticated `public` field
+        // from HQ's session_details response, never on the client-supplied header.
+        Optional<HqUserDetailsBean> userDetails = RequestUtils.getUserDetails();
+        if (userDetails.isPresent() && userDetails.get().isPublicSession()) {
+            return new PublicFormSessionAuth(userDetails.get().getAuthToken());
+        }
         if (sessionToken != null) {
             return new DjangoAuth(sessionToken);
         }

src/main/java/org/commcare/formplayer/auth/PublicFormSessionAuth.java

@@ -0,0 +1,37 @@
+package org.commcare.formplayer.auth;
+
+import org.commcare.formplayer.util.Constants;
+import org.springframework.http.HttpHeaders;
+import org.springframework.util.Assert;
+
+/**
+ * {@link HqAuth} for a public web apps session.
+ *
+ * Emits the credential pair HQ requires to recognize a public session on its receiver/restore
+ * endpoints: the {@code public_form_session_key} cookie carrying the session key together with the
+ * {@code CommCare-Public-Session: true} header.
+ */
+public class PublicFormSessionAuth implements HqAuth {
+
+    private final String sessionKey;
+
+    public PublicFormSessionAuth(String sessionKey) {
+        Assert.hasText(sessionKey, "A public form session key is required");
+        this.sessionKey = sessionKey;
+    }
+
+    @Override
+    public HttpHeaders getAuthHeaders() {
+        return new HttpHeaders() {
+            {
+                add("Cookie", Constants.PUBLIC_FORM_SESSION_COOKIE_NAME + "=" + sessionKey);
+                add(Constants.PUBLIC_FORM_SESSION_HEADER, Constants.PUBLIC_FORM_SESSION_HEADER_VALUE);
+            }
+        };
+    }
+
+    @Override
+    public String toString() {
+        return "PublicFormSessionAuth";
+    }
+}

src/test/java/org/commcare/formplayer/aspects/UserRestoreAspectTest.java

@@ -0,0 +1,89 @@
+package org.commcare.formplayer.aspects;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.commcare.formplayer.auth.DjangoAuth;
+import org.commcare.formplayer.auth.HqAuth;
+import org.commcare.formplayer.auth.PublicFormSessionAuth;
+import org.commcare.formplayer.beans.auth.HqUserDetailsBean;
+import org.commcare.formplayer.util.RequestUtils;
+import org.junit.jupiter.api.Test;
+import org.mockito.MockedStatic;
+import org.mockito.Mockito;
+
+import java.util.Optional;
+
+/**
+ * Unit tests for {@link UserRestoreAspect#getHqAuth} credential selection, in particular the
+ * choice between a Django session and a public web apps session.
+ */
+public class UserRestoreAspectTest {
+
+    private final UserRestoreAspect aspect = new UserRestoreAspect();
+
+    private HqUserDetailsBean bean(boolean isPublicSession, String authToken) {
+        HqUserDetailsBean bean = new HqUserDetailsBean("domain", new String[]{"domain"}, "user",
+                false, new String[]{}, new String[]{});
+        bean.setPublicSession(isPublicSession);
+        bean.setAuthToken(authToken);
+        return bean;
+    }
+
+    @Test
+    public void publicSession_usesPublicFormSessionAuthWithTheSessionKey() {
+        try (MockedStatic<RequestUtils> mocked = Mockito.mockStatic(RequestUtils.class)) {
+            mocked.when(RequestUtils::getUserDetails).thenReturn(Optional.of(bean(true, "pkey")));
+
+            HqAuth auth = aspect.getHqAuth(null);
+
+            assertTrue(auth instanceof PublicFormSessionAuth);
+            assertEquals("public_form_session_key=pkey", auth.getAuthHeaders().getFirst("Cookie"));
+        }
+    }
+
+    @Test
+    public void publicSession_winsEvenWhenASessionidCookieIsAlsoPresent() {
+        try (MockedStatic<RequestUtils> mocked = Mockito.mockStatic(RequestUtils.class)) {
+            mocked.when(RequestUtils::getUserDetails).thenReturn(Optional.of(bean(true, "pkey")));
+
+            // Both signals present: the public credential must win, matching inbound selection.
+            HqAuth auth = aspect.getHqAuth("sessionid-value");
+
+            assertTrue(auth instanceof PublicFormSessionAuth);
+        }
+    }
+
+    @Test
+    public void regularSession_usesDjangoAuth() {
+        try (MockedStatic<RequestUtils> mocked = Mockito.mockStatic(RequestUtils.class)) {
+            mocked.when(RequestUtils::getUserDetails).thenReturn(Optional.of(bean(false, null)));
+
+            HqAuth auth = aspect.getHqAuth("sessionid-value");
+
+            assertTrue(auth instanceof DjangoAuth);
+        }
+    }
+
+    @Test
+    public void noUserDetailsWithSessionToken_usesDjangoAuth() {
+        try (MockedStatic<RequestUtils> mocked = Mockito.mockStatic(RequestUtils.class)) {
+            mocked.when(RequestUtils::getUserDetails).thenReturn(Optional.empty());
+
+            HqAuth auth = aspect.getHqAuth("sessionid-value");
+
+            assertTrue(auth instanceof DjangoAuth);
+        }
+    }
+
+    @Test
+    public void noUserDetailsNoSessionToken_returnsNull() {
+        try (MockedStatic<RequestUtils> mocked = Mockito.mockStatic(RequestUtils.class)) {
+            mocked.when(RequestUtils::getUserDetails).thenReturn(Optional.empty());
+
+            // SMS requests have neither a public session nor a sessionid cookie.
+            assertNull(aspect.getHqAuth(null));
+        }
+    }
+}

src/test/java/org/commcare/formplayer/auth/PublicFormSessionAuthTest.java

@@ -0,0 +1,35 @@
+package org.commcare.formplayer.auth;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.http.HttpHeaders;
+
+public class PublicFormSessionAuthTest {
+
+    @Test
+    public void getAuthHeaders_emitsPublicCookieAndHeaderOnly() {
+        HttpHeaders headers = new PublicFormSessionAuth("session-key-123").getAuthHeaders();
+
+        assertEquals("public_form_session_key=session-key-123", headers.getFirst("Cookie"));
+        assertEquals("true", headers.getFirst("CommCare-Public-Session"));
+
+        // Exactly the two public headers — no Django sessionid/Authorization leaks out.
+        assertEquals(2, headers.size());
+        assertFalse(headers.containsKey("sessionid"));
+        assertFalse(headers.containsKey("Authorization"));
+    }
+
+    @Test
+    public void toString_doesNotLeakTheKey() {
+        assertFalse(new PublicFormSessionAuth("super-secret-key").toString().contains("super-secret-key"));
+    }
+
+    @Test
+    public void constructor_rejectsMissingKey() {
+        assertThrows(IllegalArgumentException.class, () -> new PublicFormSessionAuth(null));
+        assertThrows(IllegalArgumentException.class, () -> new PublicFormSessionAuth(""));
+    }
+}

src/test/java/org/commcare/formplayer/tests/RestoreFactoryTest.java

@@ -12,6 +12,7 @@
 
 import org.commcare.cases.util.CaseDBUtils;
 import org.commcare.formplayer.auth.DjangoAuth;
+import org.commcare.formplayer.auth.PublicFormSessionAuth;
 import org.commcare.formplayer.beans.AuthenticatedRequestBean;
 import org.commcare.formplayer.configuration.CacheConfiguration;
 import org.commcare.formplayer.junit.RestoreFactoryAnswer;
@@ -265,6 +266,29 @@ public void testGetRequestHeaders() {
         );
     }
 
+    @Test
+    public void testGetRequestHeaders_PublicSession() {
+        String syncToken = "synctoken";
+        Mockito.doReturn(syncToken).when(restoreFactorySpy).getSyncToken();
+        // A public web apps session authenticates outbound calls with the public session key.
+        restoreFactorySpy.setHqAuth(new PublicFormSessionAuth("pkey"));
+
+        HttpHeaders headers = restoreFactorySpy.getRequestHeaders(null);
+
+        assertEquals(6, headers.size());
+        validateHeaders(headers, Arrays.asList(
+                hasEntry("Cookie", singletonList("public_form_session_key=pkey")),
+                hasEntry("CommCare-Public-Session", singletonList("true")),
+                hasEntry("X-OpenRosa-Version", singletonList("3.0")),
+                hasEntry("X-OpenRosa-DeviceId", singletonList("WebAppsLogin")),
+                hasEntry("X-CommCareHQ-LastSyncToken", singletonList(syncToken)),
+                hasEntry(equalTo("X-CommCareHQ-Origin-Token"), new ValueIsUUID()))
+        );
+        // The Django sessionid must never travel on a public session's outbound calls.
+        Assertions.assertFalse(headers.containsKey("sessionid"));
+        Assertions.assertFalse(headers.containsKey("Authorization"));
+    }
+
     @Test
     public void testGetRequestHeaders_HmacAuth() throws Exception {
         mockHmacRequest();