Public Webforms authentication and deep-link handling

[nospame]

Product Description

Adds formplayer support for public Web Apps sessions — a one-time link that lets a recipient with no HQ account open and submit a single, pre-designated Web Apps form. There is no effect on existing sessions, and this code is not reachable until the coordinated HQ change is deployed and begins issuing public sessions.

Technical Summary

Encompasses several tickets:
SAAS-19925, SAAS-19926, SAAS-19927, SAAS-19928, SAAS-19929, SAAS-19930

A public session authenticates with a public_form_session_key cookie and a CommCare-Public-Session: true header instead of the Django sessionid, and its session_details lookup is keyed by publicSessionKey. Every trust decision hangs off the HMAC-authenticated public field HQ returns — the client header is only a routing hint and is never trusted on its own.

• Authorization reuses the existing HqUserDetails path. A public session skips the per-user username check (there is no real account) but stays confined to the single domain HQ bound the link to, mirroring HQ's PublicFormUser.
• Containment is HQ-authoritative and fail-closed. Both the app build and the session endpoint are taken from the authenticated session details, not the request. The lock aspect overwrites any client-supplied app_id/endpoint_id/endpointArgs and rejects the request if HQ hasn't supplied them, so a valid key cannot be repointed at another form in the domain.
• Route access is default-deny in the security layer, not per-controller. A public session may only reach get_endpoint, answer, and submit-all; any other route — existing or added later — returns the standard 403 until explicitly allowlisted.
• Endpoint navigation is decoupled from the SESSION_ENDPOINTS toggle for public sessions. That toggle only exposes app-builder UI and won't necessarily be enabled for a domain using public webforms; a public session is itself a deep link, so it uses the endpoint machinery directly rather than forcing HQ to enable an unrelated flag.
• app_build_id is a pinned build doc id, not the canonical app id, so a link always runs the exact build it was published from.

HQ dependency

The session_details endpoint already implements most of the changes necessary to support this work, but must be modified to include an app_build_id and endpoint_id when responding to a valid public session request.

Code and this PR description were written by AI, reviewed and edited by human. Recommend reviewing by commit.

Safety Assurance

Safety story

Every new path is gated on the HMAC public flag and early-returns for normal sessions, so regular traffic is unaffected. Containment fails closed rather than falling back to client-supplied values. The feature is inert until HQ deploys its side and starts returning public session details, which bounds the blast radius to zero for current users. Verified with the full local test suite plus the targeted suites below.

Automated test coverage

• Credential routing and domain-scoped authorization across public, regular, and superuser sessions.
• Outbound HQ calls carry the public credential.
• Route allowlist: 403 on non-allowlisted routes for public sessions; allowed routes reachable; regular sessions unaffected.
• App/endpoint lock: client-supplied values (including tampered ones) are overwritten with the authoritative values and args cleared; non-public beans left untouched; missing authoritative values fail closed.
• get_endpoint reachable without a sessionid, and endpoint launch for a public session with the toggle off.
• Deserialization of the new session_details fields.

QA Plan

End-to-end once the HQ change is live: open a one-time link → land directly on the designated form → submit successfully; confirm the same link cannot be reused to reach any other form/app/domain, and that non-allowlisted endpoints are rejected.

Special deploy instructions

• This PR can be deployed after merge with no further considerations.

Because this code is unused until changes to allow creation of public webforms and public form sessions are implemented in HQ, this can be deployed at any time before that change, which is still estimated at several weeks out.

Rollback instructions

• This PR can be reverted after deploy with no further considerations.

Review

• The set of people pinged as reviewers is appropriate for the level of risk of the change.

[kaapstorm]

This looks fine to me. But I'm not familiar enough with this codebase to know whether this is the best way to do this. Keen to hear @shubham1g5 or @avazirna 's opinion.

[kaapstorm]

Does a session key contain the string "A public form session key is required"? Or am I misunderstanding what's happening here?

[nospame]

This is asserting that sessionKey is not null or blank, and "A public form session key is required" is the message thrown if sessionKey is null or blank.

[kaapstorm]

I leant on Claude for a review, and his/its/their feedback:

The core mechanism (crediential routing, HQ-authoritative app/endpoint locking via PublicSessionLockAspect, and a route allowlist in WebSecurityConfig) is well-designed, fails closed, and is thoroughly unit-tested. However, the same rigor that locked down app_id/endpoint_id was not applied to restore identity — the client-supplied restoreAs/username fields still flow unmodified into the outbound HQ restore call, which I independently verified by reading UserRestoreAspect.configureRestoreFactory → RestoreFactory.configure(AuthenticatedRequestBean, auth) (RestoreFactory.java:187-190, which unconditionally does setAsUsername(authenticatedRequestBean.getRestoreAs())). That's a plausible cross-user impersonation/data-exposure path and the standout issue here.

Findings

#: 1
Sev: 🔴
Finding: Public session can request restore-as impersonation via
client-supplied restoreAs/username
Location: UserRestoreAspect.java:87-101, RestoreFactory.java:187-190
────────────────────────────────────────
#: 2
Sev: 🟠
Finding: /validate_form bypasses the public-session route allowlist entirely
Location: WebSecurityConfig.java:57-73,110-121
────────────────────────────────────────
#: 3
Sev: 🟠
Finding: PublicSessionLockAspect — the sole enforcement mechanism — is never
exercised through real Spring AOP wiring; only mocked-JoinPoint unit tests
exist
Location: PublicSessionLockAspectTest.java, BaseTestClass.java,
TestContext.java
────────────────────────────────────────
#: 4
Sev: 🟠
Finding: Aspect silently no-ops (no log/throw) if a future @AppInstall
method's first arg isn't an InstallRequestBean, contradicting its own
fail-closed design
Location: PublicSessionLockAspect.java:34-37
────────────────────────────────────────

Those were the highest-priority issues.

[nospame]

@kaapstorm Thank you, those are good points and I'll plan to address them, along with a few others real gaps that have come up in doing so. I might end up breaking this into multiple PRs as it's gotten pretty large locally, not quite sure yet. In either case, moving back to draft for now since there will be more changes coming.

[nospame]

Replaced by #1791, #1792, #1793