bongo/docs/web-pwa.md

Web PWA and Push staging

Bongo stages Progressive Web App support separately from server-side Web Push. The 0.8 Web redesign integrates Bulwark as described in Upstream Webmail integration and must be a secure, installable PWA. A minimum JMAP slice supports that Webmail in 0.8; Bongo 0.9 then completes the public JMAP contract and connects the client foundation to JMAP Web Push and VAPID.

Bongo 0.8: installable Web application

The 0.8 release provides:

• a standards-based Web Application Manifest with a stable application ID, name, start URL, navigation scope, standalone display mode, theme colours, language metadata, and correctly sized variants of existing licensed Bongo artwork;
• a same-origin Service Worker with an explicit version and update lifecycle;
• installable desktop and mobile presentation where the browser supports it;
• responsive and accessible mail, calendar, contact, task, settings, and administration views, including deep links which continue to work when the application is launched outside a normal browser tab;
• an intentional offline/error screen and a reliable return to the requested view after connectivity and authentication are restored;
• Notification API handling for events already received while the Web application is active;
• push-ready user preferences, per-device presentation, and a stable internal Service Worker message contract which treats a notification as an opaque account/state change rather than protocol-specific email content.

PWA support does not mean offline mail storage by default. The Service Worker may cache immutable, versioned application-shell assets such as CSS, JavaScript, fonts, and icons. It must not cache authentication responses, CSRF tokens, API calls, message bodies, attachments, contacts, calendars, tasks, quarantine content, or administration pages. Logout, account changes, and application upgrades clear account-related transient state.

The application is served over HTTPS, except for standards-permitted loopback development. Reverse-proxy deployments must preserve the correct external scheme, host, prefix, and Service Worker scope. Standalone mode retains the same cookie, CSRF, origin, Content Security Policy, and session-expiry rules as the normal Web interface.

Static assets use content-derived names or versions. A new Service Worker is activated coherently, obsolete caches are removed, and the user receives a clear reload prompt when an open application cannot safely mix old and new code. A failed upgrade must leave the previous working shell available rather than producing a permanently blank application.

Notification permission is requested only in response to an explicit user action which explains the categories being enabled. Denial is a normal state; mail, calendar, tasks, and the Web interface continue to work without it.

No client rewrite in 0.9

The 0.8 application separates notification presentation from delivery transport. Page code reports local changes through the same Service Worker message contract that a later background push event uses. After either source, the client resumes its authenticated synchronisation and derives the visible notification from authorized Bongo data.

The contract is intentionally independent of current Web endpoints and future JMAP method names. It carries a schema version, account identity, changed data types, and opaque state tokens. Its shape follows JMAP StateChange where useful without claiming JMAP support in 0.8. Unknown versions cause a normal full refresh. Consequently, 0.9 maps standard StateChange and PushVerification events onto the existing boundary and adds PushManager subscription plus VAPID delivery; it does not replace the manifest, Service Worker, notification UI, cache policy, or application navigation.

Bongo 0.9: background Web Push

Bongo 0.9 adds the server half using Web Push (RFC 8030), VAPID (RFC 8292), and JMAP VAPID Web Push (RFC 9749). Each browser profile has its own user-owned subscription, revocation state, last activity, and descriptive device label.

A push is a wake-up signal, not a copy of an email. Its payload contains only the minimum account and change information needed for the Service Worker to perform an authenticated JMAP synchronisation. Message bodies, attachments, raw HTML, credentials, quarantine content, and full task details are fetched from Bongo only after normal authorization checks.

Subscriptions can be listed and revoked from another signed-in session. They expire after prolonged inactivity, are removed when the push service reports that they are gone, and are never shared between Bongo users. Server retries are bounded and coalesced: a mail flood produces a state-change notification, not one unlimited push job per message.

Release gates

The 0.8 PWA gate includes manifest and icon validation, installation and standalone launch, deep links, reverse-proxy prefixes, offline/error recovery, upgrade and cache cleanup, logout/account switching, denied permissions, CSP, CSRF, and proof that private API responses never enter persistent caches.

The 0.9 Push gate adds subscription creation/revocation, VAPID key rotation, closed-application delivery, expired endpoints, reconnect and missed-event recovery, duplicate coalescing, multiple devices, authorization boundaries, and privacy inspection of push payloads.

The relevant standards are the Web Application Manifest, Service Workers, and the Push API.