bongo/docs/webmail-upstream.md

Upstream Webmail integration

Bongo 0.8 uses Bulwark Webmail as its responsive Webmail and PWA foundation. The integration is designed to keep the imported project close to upstream, make security updates reviewable, and avoid a temporary Bongo-only mail API which would have to be removed when JMAP is completed.

This is an integration plan, not a statement that the current 0.7 Web service already supplies JMAP or runs Bulwark.

Architecture and sequencing

Bulwark contains its own JMAP client and a broad IJMAPClient interface. It does not use a replaceable third-party JMAP library. Reimplementing that interface on top of private Bongo Web calls would create a large permanent fork. Bongo therefore implements the JMAP server boundary first and leaves the normal Bulwark client in place:

Bulwark Webmail
       |
       | standard JMAP discovery, method calls, blobs and state changes
       v
/.well-known/jmap
/bongo/jmap/api
/bongo/jmap/upload/...
/bongo/jmap/download/...
/bongo/jmap/event-source
       |
       v
Bongo JMAP service -- internal NMAP/Store API --> bongostore
       |
       +--> Queue and SMTP submission

The Web application and JMAP endpoints should normally share an HTTPS origin. The JMAP session resource advertises the actual API, upload, download and event-source URLs; reverse proxies may route those paths to separate processes without exposing the private NMAP protocol.

The complete public JMAP and interoperability contract remains a 0.9 release goal. A Webmail-compatible slice is nevertheless a prerequisite for the 0.8 Web replacement. That slice starts with:

• Core session discovery, method calls, errors and capability negotiation;
• Mailbox, Email, Thread, Blob and Identity operations;
• EmailSubmission, quota and vacation response;
• stable state values, change recovery and Event Source notifications;
• Sieve once the shared SieveScript Store operations are ready.

Contacts, calendars, principals, sharing and files are enabled in the Webmail only after Bongo implements and advertises their corresponding capabilities. An unsupported capability is omitted rather than emulated incompletely. Stalwart-specific account operations and FileNode behavior are disabled by configuration until a standard or Bongo implementation exists.

Source layout

The target source layout keeps vendor code and Bongo integration separate:

external/bulwark-webmail/          pinned, unmodified Git submodule
web/bulwark/patches/               small ordered upstream-candidate patches
web/plugins/bongo-settings/        Bongo-owned settings integration
web/branding/                      licensed Bongo logos, favicon and PWA icons
contrib/build-webmail.sh           reproducible staging and build helper

The exact directory names may be adjusted when the build is introduced, but the ownership boundaries are part of the design:

• the submodule is never edited in place;
• generated files and dependencies are never committed into the submodule;
• Bongo-specific settings and branding do not become generic Bulwark patches;
• every imported revision, patch and generated bundle is traceable from the Bongo source and binary package.

Build process

The build pins an audited Bulwark commit and its lock file. It performs these steps in a disposable build-directory copy:

1. verify that the submodule is present at the recorded commit and clean;
2. copy or archive it into a build staging directory;
3. run git apply --check for the complete ordered patch series;
4. apply the patches to the staging copy;
5. install the Bongo settings plugin and configured Bongo image assets;
6. use the upstream lock file with the reproducible package-manager install;
7. run type checking, unit tests and the production Web build;
8. package the resulting application with its exact source revision, patches, plugin sources, notices and licences.

A source archive must contain enough material to reproduce the shipped Web application without relying on a moving branch. Network downloads are allowed only in the dependency-fetch phase used by distribution or CI packaging, not when the installed Webmail starts.

Patch policy

Local patches are a queue of proposed upstream improvements, not a Bongo fork hidden inside vendor code. A patch is suitable for the queue when it is useful to other JMAP servers or downstream integrators and can be reviewed independently.

Appropriate upstream changes include:

• constructing protocol clients through a configurable factory instead of scattering concrete new JMAPClient(...) calls;
• selecting optional server integration by capabilities and configuration rather than assuming Stalwart;
• avoiding Stalwart authentication-context writes when that integration is disabled;
• discovering bundled plugins through a configurable build or runtime directory;
• allowing an administrator to preinstall and enable a plugin without modifying the settings page;
• keeping default server URL, feature policy and branding in runtime configuration;
• adding integration tests that can run against any conforming JMAP server.

Generic Bulwark changes must not introduce Bongo names, Bongo Store concepts, private NMAP calls or Bongo-only method semantics. Prefer neutral extension names such as client factory, server integration, bundled plugin directory and vendor features. Once a patch is accepted upstream, Bongo advances the submodule and removes that patch from its queue.

If the queue grows into a long-lived behavioral fork, the design has failed. At that point the integration must be simplified or the affected extension point proposed upstream before more Bongo-specific code is added.

Bongo settings plugin

Bulwark already supports a settings-section plugin slot. Bongo account and server additions use a bundled Bongo plugin in that slot instead of adding permanent tabs to Bulwark core.

The plugin may expose user-owned Bongo settings such as app passwords, external accounts, identities, tasks and Bongo-specific policy status. It uses a documented, authenticated, same-origin Bongoweb API and normal CSRF protection. Administrative operations remain role-checked and narrowly defined; the plugin is not an arbitrary configuration-file or root-command bridge.

The plugin has its own tests, translations, version and Bongo licence metadata. Failure to load it must not prevent standard JMAP mail access.

Logos and application icons

The shipped application uses the existing licensed Bongo logo on the login page and in the normal application shell, together with Bongo favicon and PWA icon assets. Bulwark's layout, colour palette, component styling, themes and light/dark mode remain unchanged so upstream visual fixes and improvements can be adopted without a Bongo theme fork. Upstream copyright, licence and notice information remains available where required.

The image replacement uses Bulwark's existing runtime branding configuration wherever it is sufficient. If a missing image hook requires an upstream change, the patch adds a generic configurable asset field rather than hard-coding Bongo. Bongo-specific files stay in web/branding or package defaults.

The Bongo settings plugin is the home for Bongo-specific Web functionality. That includes Bongo account policy, app passwords, external accounts, identities, tasks, scanner and service status, and other Bongo administration or user features which are not standard JMAP Webmail functions. These features may use multiple plugin slots as Bulwark adds suitable generic extension points; they do not justify a Bongo-owned colour or component fork.

If a required Bongo function cannot be expressed through the current plugin API, Bongo first proposes a generic extension point upstream. A narrowly scoped local patch may bridge the period before acceptance, but it must add the generic hook rather than place Bongo-specific UI in Bulwark core.

The otherwise unchanged login form authenticates against Bongo's advertised JMAP authentication path and follows Bongo policy for optional TOTP, recovery and app-password guidance. It must retain upstream error handling, accessibility, translations, responsive behavior, theme selection and reverse-proxy prefix support. The asset replacement must not weaken CSP, inject remote assets, add a runtime CDN dependency or replace existing licensed Bongo artwork with generated icons.

Upstream workflow

Development uses a public Bulwark fork only as the place from which clean pull requests are prepared:

1. keep an upstream remote for bulwarkmail/webmail;
2. create one topic branch per generic change;
3. preserve upstream formatting, tests and commit scope;
4. test the branch against both the upstream development server and Bongo;
5. submit the topic branch upstream without the Bongo plugin or branding;
6. retain the corresponding local patch until the accepted upstream commit is included in the pinned submodule revision.

The Bongo repository records the reviewed submodule commit. Builds never silently follow the fork's default branch.

Update and release gates

An automated update check may report new Bulwark releases, but it must not move the submodule automatically. An update consists of an explicit commit which advances the submodule, refreshes or removes patches, and records the test result.

The 0.8 Webmail gate includes:

• clean application of every remaining patch;
• upstream unit, type and production-build checks;
• Bongo plugin tests and translation checks;
• login, logout, session expiry, multi-account and optional TOTP behavior;
• Bongo logo, login logo, favicon and PWA icons in both light and dark mode, without changes to Bulwark's layout, colours or themes;
• mail list/read/search/move/delete/draft/send and attachment round trips;
• quota, vacation and Sieve behavior when advertised;
• capability-based hiding of unsupported contacts, calendars, sharing and files;
• PWA, reverse-proxy, CSP, CSRF and persistent-cache privacy tests;
• JMAP and IMAP changes against the same Store account without divergent state.

Bulwark is AGPL-3.0-only. It remains a clearly identified Web component with its upstream copyright, licence and notices. Distribution packages and network deployment must satisfy the corresponding source-availability obligations. Bongo-specific plugin code and packaging retain their own applicable notices without removing Bulwark's.