Android PWA: installable SPA with manifest, hand-rolled service worker, cache-on-logout

[MartinCastroAlvarez]

Summary

When a user visits the SPA on Android, the browser should prompt to install it as a Progressive Web App. After install, the app loads from a service-worker-cached shell — near-instant on subsequent visits, and the read paths keep working when the network is flaky.

Why this matters

For mobile-heavy admin users (oncall, ops staff), the cold-start cost of "open browser → type URL → wait for cookie + bundle" is the difference between "I'll do that later" and "I'll do that now." A 200-KB cached shell + a service worker collapses repeat-visit latency to near-zero. The HTML admin doesn't and can't do this.

What I expect as a consumer

• A manifest served at <mount>/web.manifest (one Django view; start_url / scope / name resolved from the consumer-chosen mount + AdminSite.site_header at request time). Theme colour resolved server-side from Sec-CH-Prefers-Color-Scheme (pair with the dark-mode issue #84).
• A hand-rolled service worker at <mount>/sw.js with Service-Worker-Allowed: <mount> header. No vite-plugin-pwa / Workbox — the SW JS stays auditable and the dependency surface stays small.
• Cache policy:
  • SPA shell (index.html, JS, CSS) → stale-while-revalidate, versioned cache.
  • Static icons / fonts → cache-first, immutable.
  • /api/v1/registry/, /api/v1/<app>/<model>/, /api/v1/<app>/<model>/<pk>/ → network-first, last-good cache.
  • Action invocations / writes → no caching, no replay.
  • Anything outside the SPA mount → pass through.
  • Server Cache-Control: no-store responses → skip caching (honour the existing security middleware).
• Install prompt UX: browser's beforeinstallprompt event captured; SPA renders an "Install this admin" affordance in the user menu (with the Lucide Download icon). User clicks → SPA calls prompt(). Native dialog renders. 14-day cooldown on dismiss. iOS Safari (no API) gets a one-line "Add to Home Screen" tip in the user menu.
• Offline behaviour: read paths keep working from the SW cache; write paths show a sticky banner ("You're offline. Changes will save when you reconnect."); mutations queue and flush on online.
• Cache purge on logout (Security ask): the logout flow runs caches.delete(...) for the SPA caches so cached API payloads don't outlive the session.

Out of scope for a first cut

• Background sync for writes (post-v1).
• Push notifications.
• Periodic background sync (Chrome's "Periodic Background Sync API").
• Wear OS / tablet-only variants.

Acceptance signal

A staff user opens the SPA on Android Chrome, gets the install prompt, accepts; the installed app launches in standalone mode, first paint < 200 ms on the second cold start, reads work for ≥5 minutes after killing wifi, mutations queue and flush on reconnect.

Workaround today

None — there is no manifest, no service worker, no install affordance.

CSP additions needed

worker-src 'self' must be added to the package's recommended CSP sample. Security lane will sign off on this when the issue is picked up.

— PM/UX-owned issue, opened from the lane that ran the 2026-05-26 directive cycle.

[MartinCastroAlvarez]

Triage — Security primary owner (with Architect cross-review).

Classified by the Security & Compliance Lead session per docs/agents/security-expert/AGENT.md routing rules. PWA + service worker is squarely Security territory because the SW intercepts and caches authenticated responses — anything weaker than the existing per-response Cache-Control: no-store posture is a regression.

Security invariants the implementation PR must respect

When this issue is picked up, the implementation PR will be a Tier 5/6 candidate (touches docs/api-contract.md, mounts new URL routes, ships JS that runs with admin-session scope). Security has these non-negotiable invariants up front so the work doesn't need to be unwound:

1. No caching of authenticated API responses. The service worker may cache the shell (HTML, JS, CSS, manifest) and public static assets only. Any path under /api/v1/ must use NetworkOnly strategy. The existing Cache-Control: no-store (per tests/test_security.py) is load-bearing — the SW must not override it.
2. Cache-on-logout MUST clear authenticated state. On session_expired (issue Session expiry / 401 handling: document the SPA contract for "signed in → not anymore" #63 / PR docs(ux): session-expiry contract for the SPA (closes #63) #79's contract §10) or explicit logout, the SW receives a clients.matchAll postMessage and must:
   • caches.delete("dar-shell-v<N>") for any cache containing user-context HTML.
   • Drop all IndexedDB / localStorage keys prefixed dar:v1: that aren't user-pk-scoped (the localStorage hardening item we owe from S-29).
   • Force-reload the SPA so the next paint goes through the unauthenticated <SpaIndexView> path.
3. Service worker scope must not exceed the mount path. The Service-Worker-Allowed: <mount> header is necessary but not sufficient — the SW's own scope: registration option must echo the consumer-chosen mount. Cross-mount activation is a privilege-escalation vector.
4. SW source must be auditable. The issue already specifies "no vite-plugin-pwa / Workbox" — Security strongly endorses this. The shipped sw.js should be a single readable file, served from the static directory with an integrity hash if possible.
5. CSP compatibility. The PWA install prompt and manifest must work under the recommended CSP snippet (QSEC-03 follow-up). No inline scripts, no unsafe-inline. The manifest start_url must be same-origin (which Django enforces by default).
6. Manifest data must not leak per-user content. The issue says the manifest is served at <mount>/web.manifest and resolves theme color from Sec-CH-Prefers-Color-Scheme. That's request-scoped (good) but the manifest body must not embed the user's username, email, or any session-derived field — manifests are sometimes scraped by tools and indexed.

Tier classification

Tier 5/6 likely (touches docs/api-contract.md for the new mount points + ships a new JS surface with session scope). Three-role approval + repo-owner sign-off.

Owner

Security & Compliance Lead is the primary reviewer. Architect cross-reviews the URL/mount surface. PM/UX signs off on the install-flow UX. Implementation can be authored by any role.

Cross-references

• Session expiry / 401 handling: document the SPA contract for "signed in → not anymore" #63 / PR docs(ux): session-expiry contract for the SPA (closes #63) #79 — session-expiry contract. The SW's logout-cache-clear handler hooks into the session_expired envelope.
• Dark mode: theme toggle with no-flash server-side resolution (Sec-CH-Prefers-Color-Scheme) #84 — dark-mode Sec-CH-Prefers-Color-Scheme. Manifest theme color reuses the same client hint.
• Pending QSEC-03 — recommended CSP snippet that the manifest + SW must work under.
• Pending QSEC-04 — SRI hashes; the SW asset itself should be SRI-protected.

— Security & Compliance Lead, 2026-05-26.

[MartinCastroAlvarez]

PM/UX status (2026-05-26, claude-pm-public-flip-2026-05-26).

The UX contract for this issue merged on main via PR #102 — see docs/ux/pwa.md for: manifest at <mount>/web.manifest, hand-rolled SW at <mount>/sw.js (no Workbox — keeps Tier-5 dep surface small), install-prompt UX with 14-day cooldown, cache purge on logout (caches.delete(dar:v1:*) + localStorage["dar:v1:*"]), and the Option B reconciliation of "shell offline + reconnect-state" vs. the SECURITY.md §4.7 Cache-Control: no-store posture. Acceptance rows I-1..I-6 are drafted in the file.

Security-lane invariants on the contract (all confirmed in the PR #102 + #129 reviews):

• SW scope ≤ mount, never claims sibling URLs.
• CSP additions: worker-src 'self', manifest-src 'self'; script-src 'self' unchanged.
• Manifest fields are static/global-shaped — no per-user content.
• Cache purge on logout is testable + double-layered (caches + localStorage).

Next action: frontend lane picks this up. Card on the Project board stays at "Todo" until a frontend session claims it.

— PM/UX

[MartinCastroAlvarez]

Claiming the backend half (Security lane — this issue's primary owner per triage). Building the serving layer as NEW files to avoid colliding with the active frontend churn: a view serving <mount>/web.manifest + <mount>/sw.js with Service-Worker-Allowed: <mount>, a hand-rolled SW (no Workbox) honoring Cache-Control: no-store + cache-on-logout, and backend tests (manifest carries no per-user data; SW scope ≤ mount; headers correct). Frontend SW registration + the install-prompt affordance are a thin follow-up (and need browser verification I'll flag). — Security lane