Plan PWA foundation before JMAP push

docs/README.md

@@ -23,6 +23,8 @@ partial, and planned work.
 - [Storage and backup](storage.md) explains where mail and metadata live.
 - [JMAP and the Store](jmap.md) defines the future canonical object model,
   protocol mappings, and migration contract.
+- [Web PWA and Push staging](web-pwa.md) separates the installable 0.8 Web
+  application from 0.9 JMAP/VAPID background notifications.
 - [Development](development.md) covers CMake, tests, sanitizers, and timezone
   maintenance.
 - [Bongo 0.7.0 release test matrix](release-testing-0.7.md) is the mandatory

docs/jmap.md

@@ -90,6 +90,9 @@ unversioned database contract before the specifications stabilise.
 JMAP Submission complements SMTP submission; it does not replace SMTP server
 delivery. Similarly, JMAP Sieve complements ManageSieve and does not remove
 the latter from supported Thunderbird and legacy-client configurations.
+The installable client and privacy boundary are prepared in 0.8 as described
+in [Web PWA and Push staging](web-pwa.md); 0.9 supplies its JMAP/VAPID server
+integration.
 
 ## Store migration
 

docs/roadmap.md

@@ -68,6 +68,13 @@ simple redesign:
   their distinct Store types and protocol semantics;
 - complete calendar sharing, invitations, free/busy, delegation, and resource
   calendars such as rooms;
+- make the complete Web interface an installable PWA with a manifest,
+  responsive standalone navigation, a strictly scoped Service Worker,
+  cache-safe upgrades, offline/error recovery, foreground notifications, and
+  a transport-neutral notification/state contract ready for later Web Push;
+  private mail, calendar, contact, task, quarantine, authentication, and
+  administration responses are never placed in a persistent offline cache,
+  and 0.9 must not require another Web application rewrite;
 - provide clear restart/reload indications, service health, queue summaries,
   scanner state, useful logs, and safe certificate deployment hooks;
 - finish maintained translations and the gettext workflow.
@@ -91,8 +98,8 @@ fit Bongo; it is not a reason to rewrite working server code.
   trusted relay mapping, Fail2ban, and setup validation;
 - a full JMAP service backed by the existing Store: Core, Mail, Submission,
   MDN, Sieve, Quotas, Contacts/JSContact, Calendars/JSCalendar, Blob
-  Management, push, principals, and the common sharing model, while retaining
-  IMAP/POP3/SMTP, CalDAV, and CardDAV for old and current clients;
+  Management, VAPID Web Push, principals, and the common sharing model, while
+  retaining IMAP/POP3/SMTP, CalDAV, and CardDAV for old and current clients;
 - shared files and mailboxes through the JMAP FileNode and mail-sharing
   extensions once their Standards Track specifications are stable; draft
   versions may be exercised behind experimental capabilities but are not part
@@ -103,7 +110,9 @@ fit Bongo; it is not a reason to rewrite working server code.
   future clients.
 
 The [JMAP Store design](jmap.md) defines the one-Store architecture,
-compatibility metadata, migration, and release gates.
+compatibility metadata, migration, and release gates. The
+[PWA and Push design](web-pwa.md) makes the installable 0.8 Web application a
+prerequisite for 0.9 background notifications.
 
 Native Exchange/MAPI or ActiveSync compatibility remains research after the
 open-protocol work. It is not a 0.9 or 1.0 release gate.

docs/web-pwa.md

@@ -0,0 +1,102 @@
+# Web PWA and Push staging
+
+Bongo stages Progressive Web App support separately from server-side Web
+Push. The 0.8 Web redesign must be a secure, installable PWA. Bongo 0.9 then
+connects that 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](https://www.w3.org/TR/appmanifest/),
+[Service Workers](https://www.w3.org/TR/service-workers/), and the
+[Push API](https://www.w3.org/TR/push-api/).