bongo/docs/web.md

Webmail and user administration

The Python 3 bongo-web service supplies the classic Bongo Webmail layout, user settings, tasks, contacts, calendars, and the restricted administrator view. It talks to the same Store used by IMAP and the delivery agents; it is not a second mailbox database.

Deployment

The suffixless web configuration document is the only Web listener configuration. A normal deployment listens on loopback port 8080 behind Apache, nginx, nginx-proxy-manager, or HAProxy. Set public_base_url, external_https, trusted_proxies, and client_ip_header to describe the real external path. Forwarded client addresses are trusted only from the configured proxies.

Bongo can instead serve HTTPS directly. It loads the configured certificate and private key, binds the privileged HTTPS and redirect ports, then permanently changes to the bongo UID/GID before accepting requests. The HTTP listener redirects to the configured HTTPS base URL except for the narrowly scoped ACME HTTP-01 challenge path. Reverse-proxy examples are installed below /usr/share/bongo/examples/reverse-proxy.

Sessions and security

Login creates a server-side session with an HttpOnly cookie. State-changing API requests require the session's CSRF token. Login attempt windows, session lifetime, second-factor lifetime, and second-factor attempt limits are configurable. TOTP fields are shown only when the account has enabled that optional feature; recovery codes and app passwords are handled by the shared authentication subsystem.

HTML mail is sanitized before display. Safe inline or explicitly permitted images can remain useful for signatures and normal content, while active markup and unwanted remote tracking are blocked. Administrator actions are both role-checked and limited to a fixed command set; selecting the administration view does not create a second login session.

User functions

The current API and interface cover mailbox folders and conversations, reading and sending mail, contacts, calendar events, filters, actionable tasks, external account collection, sending identities, preferences, and signatures. A task is a workflow item: it can be opened for its details and then dismissed, retried, ignored, or completed where the task type permits. English, German, and every installed gettext catalogue use the same API instead of hard-coded interface text.

Calendar users can import a local .ics file into the personal calendar or create a separate named calendar, for example holidays-at. A public HTTPS URL can be imported once or kept as a subscription. The Web service resolves and pins only public destination addresses, revalidates every HTTPS redirect, and bounds connection time, redirect count, and response size. The Collector applies the same public-address, HTTPS-only, timeout, redirect, and size rules when it refreshes subscriptions. Feed-owned events are matched by iCalendar UID so a refresh updates existing events and unlinks events removed by the publisher.

The classic interface includes an optional preset for the public Austrian holiday feed from feiertage-oesterreich.at. Its calendar data is fetched from the publisher and is not copied into the Bongo source or packages. Other providers can be entered as normal HTTPS URLs. A separate calendar is recommended for subscriptions so users can hide or remove the complete feed without modifying their personal events.

The administrator view exposes health and a restricted set of validated actions. Full server configuration remains the responsibility of bongo-admin and the configuration TUI; Webmail must not become an arbitrary root command interface.

The current classic interface is the 0.7 baseline. The responsive PWA redesign is scheduled for 0.8 and documented in web-pwa.md. Its upstream Webmail integration uses a pinned Bulwark submodule, generic upstream-candidate patches and a separate Bongo settings plugin. A minimum standard JMAP slice is implemented before the Webmail is replaced; the complete public JMAP and background Web Push contract remains a 0.9 goal.