112 lines
4.9 KiB
Markdown
112 lines
4.9 KiB
Markdown
# govoplan-mail
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** module (domain).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
GovOPlaN Mail is the mail transport module. It owns reusable SMTP/IMAP profile management, mail profile policy enforcement, mock mail infrastructure, and the mail WebUI package.
|
|
|
|
## Ownership
|
|
|
|
This repository owns:
|
|
|
|
- backend module manifest `mail`
|
|
- mail permissions such as `mail:profile:read`, `mail:profile:write`, `mail:profile:use`, `mail:profile:test`, and `mail:mailbox:read`
|
|
- SMTP/IMAP profile models, policy checks, encrypted credential storage, and profile resolution
|
|
- SMTP send and IMAP append adapters, including mock transports for development
|
|
- development mock mailbox endpoints used by test-send flows
|
|
- WebUI package `@govoplan/mail-webui` with profile management, policy management, and read-only mailbox components
|
|
|
|
Core owns auth, tenants, RBAC evaluation, database/session primitives, secret helpers, CSRF/API helpers, and shell layout.
|
|
|
|
## Profile and credential ownership
|
|
|
|
Mail profiles are separate governed definitions. Mail owns their SMTP/IMAP
|
|
endpoints, encrypted credentials, tests, scope, and policy. Consumers such as
|
|
Campaign store only a stable profile identifier and resolve the authorized,
|
|
active profile through `mail.campaign_delivery`; they never copy or override
|
|
transport settings or credentials in their own JSON.
|
|
|
|
The campaign capability returns read-only availability flags and random,
|
|
persisted Mail-owned transport revisions without decrypting secrets. Effect calls perform authorization,
|
|
revision comparison, credential resolution, policy checks, and SMTP/IMAP
|
|
effects inside Mail. Consumer-visible outcomes are sanitized: provider banners,
|
|
raw response bytes, hosts, account identities, and credentials are not returned.
|
|
|
|
A remaining observability slice, tracked in [govoplan-mail#17](https://git.add-ideas.de/add-ideas/govoplan-mail/issues/17), is a Mail-owned durable outbox and transport-attempt store with
|
|
restricted diagnostic access, retention controls, and correlation identifiers.
|
|
Until that exists, Campaign retains only sanitized delivery evidence; raw
|
|
provider diagnostics must not be copied into consumer records.
|
|
|
|
SMTP effects decrypt only SMTP credentials; Sent-folder effects decrypt only
|
|
IMAP credentials. A connection loss after an effect starts is surfaced as an
|
|
unknown outcome. Campaign does not automatically retry an unknown IMAP append,
|
|
preventing silent duplicate Sent copies while an operator inspects the mailbox.
|
|
|
|
The existing SMTP/IMAP credential-inheritance policy remains part of the Mail
|
|
policy model for compatibility. Campaign delivery requires effective
|
|
inheritance: a policy that requires campaign-local credentials now fails
|
|
closed with guidance to store those credentials on a Mail profile and enable
|
|
inheritance.
|
|
|
|
Deleting a profile deactivates its non-secret tombstone metadata and scrubs
|
|
both encrypted SMTP and IMAP passwords immediately in the same transaction as
|
|
a non-secret audit event. Destructive module retirement applies the same rule
|
|
to every remaining profile before any Mail table is dropped; a scrub or audit
|
|
failure blocks retirement.
|
|
|
|
## Development
|
|
|
|
Install through the core environment:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core
|
|
./.venv/bin/python -m pip install -r requirements-dev.txt
|
|
```
|
|
|
|
Run the WebUI from the core host:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core/webui
|
|
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev
|
|
```
|
|
|
|
## Module integration
|
|
|
|
Backend entry point:
|
|
|
|
```toml
|
|
[project.entry-points."govoplan.modules"]
|
|
mail = "govoplan_mail.backend.manifest:get_manifest"
|
|
```
|
|
|
|
Frontend package:
|
|
|
|
```text
|
|
@govoplan/mail-webui
|
|
```
|
|
|
|
The campaign module consumes `mail.campaign_delivery` for authorized runtime
|
|
profile resolution, sending, append-to-Sent behavior, profile selection, and
|
|
policy checks. Mail does not
|
|
import campaign internals; campaign-scoped policy and owner context are resolved
|
|
through the core `campaigns.mailPolicyContext` capability when the campaign
|
|
module is installed.
|
|
|
|
Development mailbox routes are registered by the mail module only when the
|
|
core runtime is in `dev` mode and `dev_mailbox_api_enabled` is enabled. Core
|
|
does not contribute these routes directly.
|
|
|
|
POP3 and JMAP are deferred. The protocol decision is documented in
|
|
[docs/MAIL_PROTOCOL_ROADMAP.md](docs/MAIL_PROTOCOL_ROADMAP.md): stabilize
|
|
SMTP/IMAP first, prefer JMAP for modern mailbox sync/search later, and add POP3
|
|
only for explicit legacy-download requirements.
|
|
|
|
Platform RBAC and governance rules are documented in `govoplan-core/docs/`.
|
|
The [Mail handbook](docs/MAIL_HANDBOOK.md) provides the adaptive user,
|
|
governance, technical, security, and operations perspectives.
|
|
|
|
## Release packaging
|
|
|
|
The repository root includes a `package.json` for git-based WebUI installs. It exports the package `@govoplan/mail-webui` from `webui/src` so release builds can depend on tagged git refs instead of local `file:` paths.
|