pwaLUPMIS2/docs/SSO_Session_Refresh_Proposal.md

District-reassignment fix — implemented

Status: Implemented in public/index.php, main.js, index.html, public/sw.js (v12). Approach chosen: validate-once-per-session + destroy-session-on-logout (no periodic TTL polling).

---

1. The bug

When an administrator reassigned a user to a different district (e.g. 47 → 238), the PWA kept navigating to the old district even after logout, cache clear, and re-login.

Two compounding causes:

1. public/index.php validated the SSO token only when no PHP session existed. Once $_SESSION['user_id'] was set, the user's fields (district_id, …) were frozen for the life of that PHP session.
2. Nothing ever destroyed the PWA's own PHP session. The PWA (pwa.lupmis4luspa.org) keeps its own PHPSESSID session, independent of the central SSO portal. "Logout" cleared only the sso_auth_token cookie; the PHPSESSID session (holding district 47) survived. Browser "clear cache" does not delete cookies, so the stale PHPSESSID kept being reused — and because a session still existed, SSO was never re-validated.

Net effect: district 47 stayed pinned until the PHPSESSID session was physically destroyed (which nothing did).

2. The fix (as implemented)

A district changes only on transfer — a rare event — so the validated session is correct for the entire session. We therefore do not poll SSO on a timer. Instead:

• Validate once per session, at login — unchanged first-login validation in index.php (if (!isset($_SESSION['user_id']) && isset($_COOKIE['sso_auth_token']))).
• Destroy the session on logout — a new /?logout=1 endpoint in index.php runs session_destroy(), expires the PHPSESSID cookie, clears sso_auth_token, and redirects to the LUSPA portal.

A transferred user logs out → the PHP session is destroyed → on the next login there is no session, so SSO is re-validated and the new district_id is fetched. No periodic SSO calls; the session stays valid the whole time the user is working.

Logout endpoint (public/index.php, immediately after session_start())

if (isset($_GET['logout'])) {
    $_SESSION = [];
    if (ini_get('session.use_cookies')) {
        $cp = session_get_cookie_params();
        setcookie(session_name(), '', time() - 42000,
            $cp['path'], $cp['domain'], $cp['secure'], $cp['httponly']);
    }
    session_destroy();
    setcookie('sso_auth_token', '', time() - 3600, '/', '.lupmis4luspa.org');
    header('Location: https://lupmis4luspa.org/', true, 302);
    exit;
}

The SSO validation block below it is the original first-login-only logic.

3. Client-side changes

• Logout button (index.html / main.js) — the menu's "Logout" button now routes through /?logout=1 instead of only clearing the cookie, and wipes the device's district-scoped SQLite caches first.
• Stale-district guard (main.js enforceDistrictConsistency()) — on load, if the session's district_id differs from the last-seen value in localStorage, all district-scoped caches (boundary, UPN grid, parcels, zones, roads) are cleared so the map repopulates for the new district.
• District-keyed boundary cache — the boundary is cached as district_boundary_<id>, so one district's geometry can never be served for another.

4. Why not a periodic TTL

An earlier draft re-validated SSO on a 5-minute TTL. Rejected because:

• District changes are rare (transfers only), so polling SSO on every load wastes a blocking curl on the page's critical path for no benefit almost all of the time.
• The logout→login cycle is the natural, explicit moment a transfer takes effect, and it is now correct because logout destroys the session.

5. Operational notes

• Existing stale sessions: a transferred user who is still on an old session must log out and log back in (or have their PHPSESSID cleared) once after deploy to pick up the new district. After that the model is self-correcting.
• Assumes the SSO validate endpoint returns the new district — confirmed via an incognito test (fresh session injected the correct district_id: 238).
• Edge case: switching to a different SSO user without logging out of the PWA first would reuse the old PHP session. The Logout button is the supported path; this matches the original single-user-per-device assumption.