2. Design principles

Pepsi is built to a short list of design principles, in order of importance. Most design decisions are easy and satisfy all of them. The order matters for the hard ones: when two principles pull in different directions, the higher one wins. Each principle below names decisions that were taken because of it, so that the ranking can be checked against what Pepsi actually does, and so that a future decision can be argued from it rather than from taste. docs/ROADMAP.md records the decisions, including the rejected ones.

The list states ends, not means. Compartmentalisation, least privilege and memory-safe code are not on it: they are how Pepsi reaches principles 3 and 8, and ranking a means against an end only produces conflicts that are not real. Neither is feature completeness or configurability, which established MTAs rank highly; Pepsi deliberately does not offer a knob for every behaviour.

2.1. 1. Free Software, under the operator’s control

Pepsi and everything it needs to run are free software (Pepsi is under the GNU Affero General Public License; cargo deny refuses dependencies under other licences, and cargo vet records who read each one). Pepsi does not depend on any service that the operator cannot replace or switch off.

  • Telemetry is opt-in, and its collector (pepsi-telemetry) is free software that an operator can run themselves.

  • The list of compromised keys is fetched from [pepsi-keydiscovery] BADKEYS_URL, which an operator can point elsewhere or stop fetching.

  • Exchange integration stops at SMTP: no EWS or Microsoft Graph, which would mean holding tenant credentials for a proprietary service on the mail server.

  • Where an external service makes Pepsi more secure but could also stop it working (Certificate Transparency logs, key servers), it is consulted without becoming a dependency: when it is unavailable, Pepsi carries on as it would without it.

Behind this principle is the reason Pepsi exists: running your own mail server should remain possible, so that e-mail does not end up concentrated in a few large providers.

2.2. 2. Do no harm to others

Pepsi must never become a tool against third parties. It is not an open relay. It does not send automatic replies or bounces to forged return addresses, never bounces a bounce, and keeps to the protocol standards when it talks to other servers. It honours their published policies (DANE, MTA-STS) and their limits.

  • Submission requires authentication, and SENDER_MAP binds each account, network or client certificate to the addresses it may use. An authenticated account’s recipients are rate-limited too (USER_RECIPIENTS_PER_HOUR), so a stolen password does not turn the server into a spam source.

  • Automatic replies are suppressed on a definite SPF or DMARC failure, and bounces use the null sender.

  • DKIM signing fails closed. A message that the server cannot sign is not sent unsigned, because a receiver enforcing the domain’s DMARC policy would reject it anyway. Sending it would spend the domain’s reputation for no gain.

  • pepsi-setup refuses an SRS_DOMAIN aligned with a served domain, which would let a forwarded message pass DMARC in the name of a domain that never sent it.

Where a standard itself leaves users exposed, Pepsi mitigates within the standard and documents what remains. It does not break the protocol to protect its own users. The issues listed in Who must act on what remains are the consequence, and they are kept visible on purpose.

2.3. 3. Keep faith with users: no security surprises

Pepsi must not surprise its users by violating a clear expectation about the availability, integrity or confidentiality of their mail. Three rules apply, in this order:

  1. Honesty. Never claim or show more protection than there is. Security indicators mean exactly what Threat model says they mean, and the manual states the operator’s position precisely: the operator is trusted. The mail log is not presented as an archive. Residual risks are documented, not hidden.

  2. Prefer the failure that can be recovered from. A delay is better than a lost message, and a lost message is better than an irreversible disclosure or payment.

    • When key discovery cannot reach DNS, the encrypt stage defers the message rather than sending it in clear.

    • DKIM signing fails closed (see above).

    • Once a wallet command or payment has taken effect, the message is dropped rather than retried, because a retry would pay twice.

  3. Act on evidence, not on uncertainty. Uncertainty admits mail.

    • Inbound authentication fails open on DNS and parse errors, and rejects only a definite DMARC failure under DMARC_ENFORCE.

    • Queue admission control admits mail whenever the measurement is uncertain.

    • A lost database connection is not counted as a failure of the message.

    Rule (b) overrides rule (c) only where admitting would be irreversible, which is why encryption defers on uncertainty while inbound delivery does not.

2.4. 4. Collect and keep the minimum

Data that is never collected, or no longer kept, cannot leak. This applies to users’ data and equally to their correspondents’.

  • The mail log records no message content and is pruned after MAIL_LOG_RETENTION_DAYS. Journaling and an archive store were declined.

  • Telemetry is opt-in and counts feature use; it does not describe messages.

  • A secure-link message whose PIN is lost cannot be recovered, because nobody holds a copy of the key, the operator included.

  • Key refresh asks only the source that a key came from, so no single key server learns the deployment’s whole list of correspondents.

  • IP blocklists are downloaded whole rather than asked about each connecting client, so no list operator learns which servers mail this host. This costs coverage: the most widely used lists are available only as per-query DNS services, and Pepsi does not use them for inbound mail.

2.5. 5. Work with what people already run

Pepsi interoperates with the clients, mail delivery agents and list tooling its users already have, using standard formats rather than private ones.

  • Encryption uses PGP/MIME, S/MIME and Autocrypt. The pEp wire format and protocol were declined, because they tie a deployment to one family of clients.

  • maildirsize stays where Dovecot, Courier and Exim read and write it, even though this means a user can tamper with their own quota accounting.

  • Keys harvested from a user’s own mail are believed even for addresses that Pepsi serves, because that is how a user running their own GnuPG gets their key used.

  • The mailing-list manager speaks the GNU Mailman 3 REST API, so Postorius and HyperKitty work against it.

Principles 4 and 5 are close, and Autocrypt shows why. Sending keys in headers gets bodies encrypted, which serves privacy, and it also exposes metadata, which works against it. Such cases are weighed one at a time.

Principle 3 ranks above principle 5. Accepting a key on first use (trust on first use) is acceptable because the alternative is cleartext, not a better key, and because the indicators do not claim more than that.

2.6. 6. Safe by default, easy to set up and use

The easy path is the safe path. pepsi-setup --wizard produces a working, hardened configuration. Secure options are the defaults (DANE = strict) and insecure ones must be asked for explicitly.

  • No option makes a limit softer just for convenience: a grace band over the mailbox quota was declined.

  • Principle 3 wins over convenience: the web console has no restart or shutdown button, because a console that can stop the mail server can be tricked into doing so.

2.7. 7. Operable and evolvable

Failures must be visible to the operator: logs, /metrics, pepsi-status, and docs/ROADMAP.md for the limitations that an operator cannot see from the outside. Decisions are recorded with their reasons (contrib/no-*.md, the ROADMAP), so they are not argued again from scratch. An upgrade must not break a deployment:

  • a schema patch is frozen once released;

  • state JSON keys are only ever added;

  • a renamed option keeps its old name for at least one release.

2.8. 8. Simple enough to verify

Pepsi should have few moving parts and be written so that its behaviour can be checked. It is written in Rust, and its tests must prove what they claim. Privilege separation (the per-role database grants and the setuid helpers) is built into the structure, not added on top. The queue is a single database table driven through one state machine because that is easy to reason about, not because it is the fastest design.

2.9. 9. Reasonably efficient

Pepsi should run comfortably on the modest hardware that a self-hosted mail server typically gets. Efficiency matters, and Benchmark Suite and Performance measure it, but it never outranks any of the principles above.