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:

```text
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:

```text
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.