From 4f9e66a019a8a5bd803ee442b5f477f6b87b2c4d Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Wed, 22 Jul 2026 15:35:53 +0200 Subject: [PATCH] Plan PWA foundation before JMAP push --- docs/README.md | 2 + docs/jmap.md | 3 ++ docs/roadmap.md | 15 +++++-- docs/web-pwa.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 119 insertions(+), 3 deletions(-) create mode 100644 docs/web-pwa.md diff --git a/docs/README.md b/docs/README.md index c9e4056..932acdd 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/jmap.md b/docs/jmap.md index 5f1f9a9..9c982dc 100644 --- a/docs/jmap.md +++ b/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 diff --git a/docs/roadmap.md b/docs/roadmap.md index 14eff15..0a08814 100644 --- a/docs/roadmap.md +++ b/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. diff --git a/docs/web-pwa.md b/docs/web-pwa.md new file mode 100644 index 0000000..45324f8 --- /dev/null +++ b/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/).