25. The administration console¶
Pepsi ships a small browser console, served by pepsi-httpd under /ui. It
exists for the things that are painful on the command line: watching the queue,
browsing keys and correspondents, reading the audit log, and changing
configuration with validation and provenance visible.
It is a client of the documented administrative API (The administrative API) and
nothing more. Every page calls the same library functions that the /api/v1
endpoints call, through the same authentication, the same scope checks and the
same audit log. So anything that the console can do can also be done with
curl, and the two cannot disagree about what the queue contains or about
whether a configuration value is valid.
Note
There are two HTTP APIs in this server and they are not the same.
/api/v1 is Pepsi’s own (The administrative API), of which this console is a
client: accounts, scopes, sessions and CSRF, gated on ADMIN = yes.
/3.0/ and /3.1/ are the GNU Mailman 3 REST API
(The GNU Mailman 3 REST API), reimplemented so that Mailman software works against
Pepsi: one shared password, no scopes, somebody else’s shapes, gated on
LIST_API = yes. An operator will meet both; they share the server and
nothing else, and neither is a version of the other.
25.1. Three listener flags, and two of them have opposite advice¶
pepsi-httpd serves four things and gates three of them, each on its own
[pepsi-httpd-listener-*] flag. Getting these the wrong way round is the
single easiest way to mis-deploy Pepsi’s HTTP surface, so they are in one table:
Flag |
What it serves |
Who it is for |
Where to put it |
|---|---|---|---|
|
|
The operator. Bearer tokens, password sessions, |
Behind a tunnel. A UNIX socket, or loopback with a reverse proxy.
|
|
|
Mailing-list software ( |
Loopback or TLS. Same refusal as |
|
|
The anonymous public. No credential at all. |
On the open internet. This is the one surface meant to be reachable, so the cleartext restriction is deliberately not applied. But a subscribe form carries somebody’s address, so use the TLS listener. |
(none) |
MTA-STS, Web Key Directory, mail autoconfiguration, the secure-link
portal, |
Anybody who needs them, by design. |
Wherever the public listener is. |
On a listener without its flag, every gated route answers a plain 404, byte
for byte what an unknown path answers. That is why publishing the public
HTTPS listener does not publish administration, and why a public listener cannot
be probed for what else this server runs.
25.2. Reaching it safely¶
The console mounts on exactly the listeners that the API mounts on: those
flagged ADMIN = yes (see pepsi-httpd(1)). On every other listener
the /ui paths answer a plain 404, byte for byte what an unknown path
answers, so publishing the public listener does not publish the console and a
public listener cannot be probed for whether administration is enabled here.
pepsi-httpd refuses to serve it on a flagged listener that would carry it in
cleartext off this host: plaintext TCP is accepted only on a loopback address,
while TLS listeners and UNIX sockets always qualify. A socket-activated listener
(SERVE = systemd) without TLS never qualifies, whatever its unit binds. The
passed descriptor could be anything, and treating it as permitted would let the
strictest case through the loosest check, so give administration a listener of
its own. This is not only about eavesdropping. The session cookie carries the
__Host- prefix (RFC 6265bis §4.1.3.2) only when it is set Secure, that
is, only when the client’s connection is HTTPS, since a browser refuses a
__Host- cookie that is not Secure. On the plaintext loopback bootstrap
path neither is used, so the
console’s own authentication is weaker by construction on a cleartext origin. A
browser cannot open a UNIX socket, so a typical deployment either
binds an administrative listener to
127.0.0.1and reaches it over an SSH tunnel (ssh -L 8443:127.0.0.1:8443 mail.example.com), orgives the administrative listener TLS and a name of its own, and treats it like any other internet-facing administrative surface.
25.3. Signing in¶
Two of the API’s three mechanisms are useful from a browser:
A local operator over the administrative UNIX socket is identified by
SO_PEERCRED and needs no password at all. Browsers cannot speak to a UNIX
socket, so this path is for curl and for the first-run bootstrap; it is also
why the strict session policy below is affordable.
A remote administrator signs in at /ui/login with an account from
pepsi.admin_account (create one with POST /api/v1/accounts). Sessions have
a 30-minute idle timeout and a 12-hour hard lifetime regardless of
activity, and there is no “remember me”. This console can revoke a key, read who
corresponds with whom and rewrite the pipeline; a forgotten browser tab should not
still hold that power tomorrow, and a stolen laptop should not be a standing
administrative session.
Bearer tokens work too, but a browser has no way to attach one; they are for
automation against /api/v1.
A password check is Argon2id, run off the request executor with at most one
verification per CPU at a time; a sign-in that finds no free slot within five
seconds is answered as rate-limited ([pepsi-admin] LOGIN_RATE_LIMIT limits
attempts per account and per source address on top, and LOGIN_DAILY_LIMIT
limits the failed sign-ins per account per day). An account with a second factor
(pepsi-keys otp enroll --console LOGIN) also needs the current six-digit
code in the form’s code field, which the setup applier checks before the
session is opened; a missing or wrong code is answered exactly like a wrong
password. An unknown account is checked against a dummy hash, so the answer’s
timing does not say which accounts exist. What a guessed or stolen password
gives an attacker is stated in A delegated administrator.
25.3.1. Security keys¶
A console account (and an end user who signs in by e-mail, below) may register security keys as a second factor beside the TOTP code. Security keys are WebAuthn credentials: a hardware key, a phone or the platform authenticator of a laptop. Any one registered key completes a sign-in, as does the TOTP code where the account has one and the operator has not required keys. A key is never a password replacement.
What a key adds over a code is resistance to phishing. A TOTP code is a secret that the user types, and a convincing look-alike page can ask for it and relay it to the real console within its thirty seconds. A key signs the page’s real origin and this server’s name, both supplied by the browser rather than by the page, so an answer obtained on a look-alike site does not verify here (A phishing proxy (adversary in the middle)).
Registering. Signed in, open Security keys (/ui/security, linked
beside the sign-out button), name the key, enter the account’s password and
press Register security key; the browser asks for the key. An account that
already has a key adds another in two steps: the password and Confirm with
security key (one of the existing keys, or the TOTP code where it may stand
in), then the registration of the new key on the page that follows. A stolen
session cookie therefore cannot add the thief’s key. From the next
sign-in on, a correct password leads to a second page that asks for one of the
keys (or offers the code field where TOTP may stand in).
Removing a key needs the password and a confirmation with one of the
account’s keys (the one being removed is fine) or the account’s TOTP
code; a stolen session cookie can therefore neither swap the key for its
thief’s nor strip it. The operator’s recovery for a lost key is
DELETE /api/v1/accounts/{id}/webauthn (which also ends the account’s
sessions), the counterpart of pepsi-keys otp reset --console.
Requiring keys. [pepsi-httpd] REQUIRE_WEBAUTHN = admins (or users,
members, all) makes a key the only second factor of that kind of
account: the TOTP code no longer completes a sign-in, an account without a key
is led through registering one as the last step of its next sign-in, and its
last key cannot be removed. The default is no.
Keys are bound to [pepsi-admin] CONSOLE_URL (default ENROL_URL), the
public https:// origin under which the console is reached; without either,
the console offers no keys. A key signs for the host with which it was
registered, so a change of host makes the registered keys unusable. Choose a
name that users will keep. Pepsi asks for no attestation (it does not judge
authenticator models) and accepts ES256 and Ed25519 keys; the mechanism is in
Security keys (WebAuthn).
25.4. What the console can and cannot do¶
The actions are message-level and key-level only:
requeue a stuck message at its current stage, route it to a bounce stage, or delete it without delivering;
release or delete a message that a quarantine stage holds (Quarantine);
allow or deny a client, a domain or a sender for greylisting, and remove such a rule (Greylisting);
publish or withdraw a local identity, make one primary, delete it, or request its upload to the key server;
ask the applier for a server-managed key, to register a user’s own public key, to revoke an identity, to build a certificate request over an S/MIME identity’s key, or to install the certificate that a CA issued from it (all five through the privileged applier, below);
import a correspondent’s key by hand, queue a discovery lookup, re-check a cached correspondent key (expire it and queue a forced lookup) and forget one; add a trust anchor, set or lift its scope (the mail domains for which it is trusted; an anchor that vouches for every domain is flagged), and remove one. Each form calls the same function as its API endpoint (
POST /api/v1/peers,.../discover,.../{id}/recheck,POST /api/v1/ca-trust,PUT /api/v1/ca-trust/{id}/scope), so the console cannot accept what the API refuses: a blob that is not a key, a key naming another address, a certificate that is not a CA’s. A domain-wide*@domainkey stays pepsi-keys(1)’s;revoke a secure-link message;
configure the managed PKI of a domain and edit its users: approve or correct a name, select a user, opt one out or delete one (Managed certificates); the orders themselves, and the CA’s credential, stay with
pepsi-keys mpki;set or remove one configuration override;
answer the setup interview, and ask the privileged applier to run certbot, install the schema, provision roles, check DNS or rotate a domain’s DKIM keys.
There is deliberately no restart, no shutdown and no backup button. A web
console that can stop the mail server is one that can be tricked into stopping
the mail server, and systemd already owns that job. Restart a component with
systemctl restart pepsi-ingress (the configuration pages name the unit when a
change needs one).
Everything privileged here has that shape: the console records what should
happen and a separate root program does it. The console cannot write
/etc, run certbot or create a database role, and must not be able to. We do
this so that a flaw in request handling cannot become command execution as root
(see Command injection and XXE in mail gateway management interfaces). See “Setup in the browser” below.
Two further things that the console cannot do, because the server cannot:
Generate or revoke key material itself. That needs the
pepsi-cryptodatabase role, which holds the grant on the private column and which pepsi-httpd deliberately does not hold. A web tier that can mint signing keys is a web tier whose compromise mints signing keys. The identities page’s Generate a server-managed key form therefore only asks: it enqueues agenerate-identitytask thatpepsi-setup applyre-validates and performs aspepsi-crypto. Register my own key (paste an armoured OpenPGP public key) enqueuesregister-client-keythe same way, and an identity’s Revoke button, once confirmed, enqueuesrevoke-identity, because revoking a signing-only key destroys its private half, which is a write to that column. Each answers with the queued task’s own page,/ui/setup/tasks/<id>, which the user who asked may open whatever their scopes. That page shows the outcome (done, failed with the reason, or refused) as soon as the applier records it. All three answer503when the applier package is not installed. Each form also has a Second-factor code field: a user who enrolled a second factor (Key management) types the current code from their authenticator app there, and the applier checks it, because the console cannot. An S/MIME identity’s page adds Request a certificate (PKCS#10) and Install the issued certificate, which enqueueidentity-csrandidentity-certificatethe same way: the request is signed with the identity’s private key and the install re-wraps it. The task page shows the PEM request on its own, ready for the CA, and the install’s outcome, or why the install was refused (a certificate over another key, for another address, a CA certificate, the wrong key usage).Write the configuration overlay, unless
[pepsi-admin] CONFIG_DBnames a connection that authenticates as thepepsi-configrole. Without it the configuration pages are read-only and say why.
The console also never shows a message’s headers or body. The queue pages load
the envelope, the stage, the status and the state JSON, and nothing else.
This is structural: the query behind them does not select those columns.
Reading mail is not an administrative function.
25.5. The pages¶
Path |
Scope |
What it shows |
|---|---|---|
|
|
Dashboard: queue depth by |
|
|
Filterable listing (by stage and status), paginated, with an opt-in 30-second reload. |
|
|
One message: envelope, stage, status and pretty-printed |
|
|
The messages that a quarantine stage holds, oldest first, with who sent each there and why (Quarantine). |
|
|
One held message: envelope, |
|
|
The greylisting decisions of the last 24 hours, the recent triplets
(filterable by state, domain, client and recipient) and the rules. The
allow, deny and remove forms need |
|
|
The mail that greylisting deferred to the user’s own address, with Allow this sender (Greylisting). |
|
|
Local key pairs, filterable by address, with the Generate a
server-managed key and Register my own key forms ( |
|
|
One identity, with its custody (server-managed or the user’s own key)
and key-server state, and publish / withdraw / Upload to the key
server / make-primary / revoke ( |
|
|
Cached correspondent keys: source, DNSSEC flag, validity, pin state.
With |
|
|
The S/MIME trust anchors and their scopes; adding ( |
|
|
The domains whose S/MIME certificates are ordered from a CA, whether
each is on, its enrolment mode and its number of users; adding a domain
( |
|
|
One domain: its settings, its users with their newest order and what it
waits for, and its recent orders. Saving the settings, adding a user
( |
|
|
The orders placed with the CA, newest first, filterable by domain and address, or open orders only. |
|
|
The notices for administrators, or the unread ones only (the bell in
the page header links here). Marking them read
( |
|
|
Every section of the effective configuration for a scope, with how a change takes effect. |
|
|
One section: each option’s value, where it came from (file, global,
domain, address), and the forms to set or remove an override
( |
|
|
The audit log, filterable by kind and actor. |
|
|
The opt-in per-message log, filterable by address; says so plainly when
|
|
|
Outbound TLS session outcomes per policy domain. |
|
|
MX addresses that the resolver cache currently marks as failing. |
|
|
The sources of the DMARC aggregate reports that other receivers sent
about the served domains ( |
|
|
The served domains, the MTA-STS mode, how many identities are published
under each, and the DNS records to publish with the last live verdict for
each. The “check DNS now” button needs |
|
|
Secure-link messages that the portal is holding: correspondents, expiry,
reads, wrong PINs, lockouts. Revoking needs |
|
|
One message with its access history. |
|
|
The setup interview’s entry point; each step is |
|
|
What has been asked of the privileged applier, and a form to ask for more.
Without |
|
|
One action with the applier’s streamed progress, updated as soon as the applier writes something. |
No page loads an unbounded result set: every listing goes through a query
carrying its own LIMIT/OFFSET, so that is a property of the SQL rather
than of what the renderer draws. The queue and the log views
paginate with ?limit=/?offset= (clamped to [pepsi-admin] PAGE_LIMIT,
at most 1000). The key-store listings (identities, correspondents, trust
anchors) fetch one page’s worth, plus one row to learn whether there is more,
and say plainly when they were cut short; narrow them with the address filter,
or use pepsi-keys(1). The console asks for a COUNT(*) only where
it shows a total (the two log views); the API always does, because its clients
page programmatically. See The administrative API.
Every destructive action goes through an explicit confirmation page first:
deleting a queued message, releasing or deleting a quarantined one, revoking or
deleting an identity, removing a trust anchor, removing a configuration
override or a greylisting rule, and opting a user of the managed PKI out or
deleting one, which revokes their certificates. Every mutation is written to the
audit log with the same event kind that the API records, so /ui/logs shows
changes made from the console, from curl and from the command-line tools
alike.
Configuration values that could carry a secret are shown as ***, never as
values, by the same rule that the API uses. The list is deliberately generous: a
value wrongly masked costs an operator a look in the file, while a value wrongly
shown is published to everyone holding config:read.
25.5.1. Setup in the browser¶
/ui/setup renders the same interview that pepsi-setup --wizard asks at a
terminal. It is literally the same, because the questions, their shapes, their
defaults and the conditions under which they are asked live in one place as data
(pepsi-setup-model) and both front-ends render it. A question added to one is
a question added to both.
Two separate mechanisms keep it safe:
Answers are drafts. Each step writes into pepsi.config_override with the
draft flag, which every configuration reader filters out structurally.
Nothing takes effect while the interview is in progress, so a session that times
out half way through has not half-configured a mail server, and reopening the
page resumes where it left off. A step with a bad answer re-renders with the
message beside the field and stores nothing, not even the good answers on
the same page, because a half-stored step is one that an operator has to
reconstruct from memory.
Actions are intents. /ui/setup/tasks shows what has been asked of the
privileged applier and offers a form to ask for more, from its closed set:
run-preflight, obtain-certificate, install-schema,
provision-roles. The set is closed so that the doorbell is not a general
root command channel (see Mail appliances store secrets world-readable or unprotected). A button
writes a pepsi.setup_task row and rings a doorbell; pepsi-setup apply,
running as root, does the work and streams its
progress back into the row, which /ui/setup/tasks/<id> shows. While the
task runs the page reloads itself (a <meta http-equiv="refresh">, not a timer
in script), and the reload does not poll: it asks for the page again with what it
already showed, and the server holds that request for up to 20 seconds until the
applier’s notification says there is a new progress line or an outcome. The
result therefore appears the moment it exists. If the server has lost its
database listener connection it answers at once and the page falls back to
reloading every five seconds. There is no restart or shutdown action; a change
that needs a component restarted ends with you restarting it.
Both need setup:write, the reads included: the staged answers are the shape
of a deployment being built and the task list is a record of privileged work.
The one exception is a user’s own requests: the key actions on the identities
pages queue tasks too, and whoever queued one may open it and find it in
/ui/setup/tasks, which for them lists nothing else. Somebody else’s task is
“not found”.
Two independent things must hold before anything can be saved, and the page tells you which one is missing:
the privileged applier must exist: the separate
pepsi-httpd-adminDebian package, holdingpepsi-setup-apply.socketand its service. It is aRecommends, so it is installed by default and can be removed without taking Pepsi with it; and[pepsi-admin] CONFIG_DBmust name a connection authenticating as thepepsi-configrole, because the applier refuses any row not written by it.
The applier is checked first, because without an applier, configuring
CONFIG_DB would not help. When either is missing, the interview degrades
to read-only rather than storing answers that nothing will apply: every value
still renders, the inputs come back disabled/readonly, the save button
is gone, and a flash names the reason. The corresponding API calls answer 503
setup_applier_unavailable or 503 setup_write_unavailable (see
The administrative API). The one deliberate exception is discarding a draft: that
cannot cause a privileged change, and a wedged interview must stay clearable.
Note that the /ui/config pages are not affected by a missing applier:
they write pepsi.config_override, a database table, not /etc. They need
CONFIG_DB and nothing else.
A password-shaped answer is rendered blank every time, never echoed back into
a value= attribute, and submitting the step with it blank leaves whatever is
stored alone. The audit entry for a step names the question identifiers and no
values at all.
25.5.2. Secure links¶
/ui/secure lists the messages that the secure-link portal is holding for
recipients who had no key: who they are from and for, when they expire, how often
the PIN was entered correctly and wrongly, and whether a lockout is in force.
/ui/secure/<token> adds the access log.
The message itself is not on either page, and cannot be. pepsi-httpd is
the portal, so it is the one database role granted the ciphertext column. That
is exactly why the operator pages do not read it. The queries behind them name
every column except that one and report only its length, so the discipline lives
in the SQL rather than in a struct field that somebody remembered to leave out.
Revoking destroys the only copy of the message and therefore needs
secure:write, a separate capability from secure:read.
25.5.3. DNS on the domains page¶
/ui/domains shows, beside each served domain, every DNS record that Pepsi
expects it to publish: the name, the value to publish, whether live DNS carries
it, and what to do when it does not. The zone text at the foot of the page is
the same block that pepsi-setup run prints.
The verdict comes from the applier, not from this server: working out what should
be published means reading the validated configuration and the DKIM signing
daemon’s status, and comparing it means querying DNS. The page therefore always
shows when the answer was computed, and “check DNS now” (setup:write)
asks for a fresh one rather than blocking the request on a resolver.
25.5.4. DKIM keys¶
/ui/dkim (keys:read, linked from the domains page; refused to an
address-confined principal) shows what the signing daemon
pepsi-dkim(1) reports in its public status file, the same document
with which GET /api/v1/keys/dkim answers: whether rotation is on, and per
signing domain every key with its selector, algorithm, RSA size, state
(next, current, retiring, retired), TXT record and whether every
authoritative server serves it, the DNS changes owed (records to add, records
that can go) and a rotation waiting for DNS. A domain with no current key is
marked. The page says so when the daemon has not written its status yet.
This server never holds or reads a DKIM key. The rotate now buttons (soft:
switch once the next key’s records are visible; hard: switch at once) only
ask: each enqueues a dkim-rotate task that pepsi-setup apply
performs by running pepsi-dkim rotate as root, since the daemon takes
administrative requests from root and its own account only. They need
setup:write and a running applier, and are drawn only where both are.
25.5.5. Managed certificates¶
The Certificates pages show and change the managed PKI: the domains whose
users get S/MIME certificates from a CA (Certificates from a commercial CA: the managed PKI). Reading needs
keys:read. Every change needs keys:write: the settings, adding a
domain, adding a user, correcting or approving a name, selecting a user,
opting one out or deleting one, and marking notices read. These settings decide
what the CA bills the organisation for and whose name a certificate carries,
which is why they need the scope that changes keys. An address-confined
(own:) principal sees none of this: no link, no bell, and every page and
form is refused, since the settings and the user list belong to the deployment,
not to one address.
/ui/mpki lists the managed domains and has the form that adds one. A new
domain starts switched off, with the defaults, and the browser goes on to its
page. /ui/mpki/domains/<domain> has three parts:
Settings: the switch, who gets a certificate (the enrolment mode), what happens to names taken from the
From:header, one or two certificates per user, the key algorithm, the validity, the renewal window, the daily limit, the notify address, and the CA’s product, organisation id and API URL. Saving them is the same change aspepsi-keys mpki domain set.Users: one row per user with the name, where it came from, whether it is confirmed, the selection, whether the user gets a certificate, the newest order, what it waits for, and its last error. Per user, Approve name confirms the name as it is, Save name corrects it (which confirms it too), Always enrol and Let the domain decide set the selection, and Opt out and Delete user revoke the user’s certificates at the next run of the order job. Those two go through a confirmation page first, since a revoked certificate cannot be brought back. Add a user creates a user under the name that the administrator types, which confirms it.
Orders: the domain’s twenty newest orders, with a link to
/ui/mpki/orders, which lists them all and filters by address or by open orders.
/ui/mpki/notices lists the notices that the order job writes (an order
submitted, installed, held with its reason, failed or revoked), with Mark
read per notice and Mark all read. A notice marked read is read for every
administrator, and the console records who marked it. For a principal with
keys:read, the page header carries a bell, Notices, with the number of
unread notices; it costs one count per page view, and a failure to count costs
the bell only, never the page.
The console never talks to the CA and never sees or sets the CA credential, a
file that only pepsi-keys mpki credential set writes and that
pepsi-httpd cannot read. It cannot act on an order either: releasing,
retrying and cancelling orders are pepsi-keys mpki order commands, because
pepsi-httpd holds no grant to write mpki_order. The forms call the same
functions as /api/v1/mpki (The administrative API), so the console accepts and
refuses what the API does, and both record the audit kinds that the command
line records (mpki.domain.set, mpki.user.add, mpki.user.set,
mpki.user.delete; an opt-out or a deletion at warning), plus
mpki.notice.read.
25.5.6. Quarantine¶
/ui/quarantine lists the messages that a
pepsi-stage-quarantine(1) stage holds, as pepsi-queue quarantine
list does: the token, the stage, when the message arrived and since when it
is held, its envelope, and the by and reason of its quarantine record
(milter:<name> for a filter). A message’s page adds the From: and
Subject: that ingress stored with the envelope and the end of the hold
(MAX_HOLD). Like the queue pages, these never show a message’s headers or
body: pepsi-httpd cannot read them. Look at the content on the server with
pepsi-queue --headers --body.
With queue:write the page offers Release and Delete without
delivering, each behind a confirmation page, since a released message is
delivered and a deleted one is gone. Release hands the message back to its
quarantine stage, which sends it on to its RELEASE_STAGE; it does not go
through workqueue_resume, which refuses held mail. A deletion is recorded
in the opt-in mail log. Both call the functions of pepsi-queue quarantine
and record its audit kinds
(queue.quarantine-release, queue.quarantine-delete). When no stage runs
pepsi-stage-quarantine, the page says that nothing can be held.
25.5.7. Greylisting¶
Where pepsi-greylist(1) runs, the navigation has Greylisting
(logs:read) for an operator and Deferred mail for a user signed in for
their own address. The server decides once, at start-up, whether the
deployment greylists: a [pepsi-greylist] section, or an ingress milter
section that names the daemon’s socket.
/ui/greylist shows the decisions of the last 24 hours by outcome, as
pepsi-greylist stats counts them (from the daemon’s hourly counters, so the
page does not scan the triplets), the recent triplets and the rules. The
triplets can be filtered by state (waiting for a retry, passed, tried only
once), by domain, by client address or network, and by recipient. With
config:write each triplet has a rule form: choose its sender, the client’s
domain or the sender’s, or the client’s network or address, and Allow or
Deny. Another form adds any rule, with a note and a duration, and each rule
can be removed after a confirmation. The rules are written by
greylist_rule_add with origin = console and the operator’s identity,
and are audited as greylist.rule.added and greylist.rule.removed, as
from the command line. A domain rule also matches the envelope sender’s domain,
which anybody can write; the page says so.
/ui/deferred is the user’s page: the senders that greylisting asked to wait
before their mail to the user’s own address was accepted, with the first and
last attempt, the number of attempts and whether a retry passed. Allow this
sender, beside a deferral or for an address typed in advance, puts the sender
on the user’s own whitelist. That is the whitelist that the daemon’s
WHITELIST_BYPASS consults for the user, so the sender is not delayed again
for this user, and it is not a rule, which would let the sender through for
everybody. The row is the one that pepsi-whitelist add writes for an
address, with DKIM required, so it counts only for mail that the sender’s
domain authenticates. When the daemon consults no whitelist of the user’s own
([pepsi-greylist] WHITELIST_NAME or a whitelist stage with a
{localpart} or {login} name), the page says that allowing a sender is
not available and offers no form. Audited as whitelist.sender.added.
The server cannot write the greylisting tables or read any whitelist: a rule
changes only through the two SECURITY DEFINER rule functions, and a
whitelist row only through whitelist_add_user_sender, which takes one
literal address and refuses a shared whitelist.
25.5.8. End-user pages¶
The own:<address> scope is defined and enforced, and a
principal holding only it reaches the identity and correspondent pages narrowed
to its own address. Another address’s pages answer 404, and the shared
objects (changes to the correspondent-key cache, the trust anchors) are refused
outright.
It also reaches the mail log, narrowed to its own address; asking for another
address there is refused with 403. Where greylisting runs, it reaches the
mail that greylisting deferred to its address and may put a sender on its own
whitelist (Greylisting). The navigation links these pages for it. On its own identities it may also act:
ask for a server-managed key, register its own public key, request a key-server
upload, publish, withdraw, make a key primary, ask for a revocation, and ask
for a certificate request or the install of an issued certificate on its S/MIME
identity: everything except deleting a row (see Key management). Every
one of these is asked of the setup applier, which checks the address’s second
factor when one is enrolled (the forms take the code), and the answer is the
task’s page, which says when the change is made.
25.5.8.1. Signing in by e-mail¶
An end user obtains such a principal by proving control of the mailbox. With
[pepsi-admin] ENROL_STAGE set, the login page offers “sign in with a link
sent to your e-mail address”, which leads to /ui/enrol:
The user enters an address. When this server serves the address, a one-time link is mailed to it, injected at
ENROL_STAGEfrom the null sender. The server serves an address when it holds a key-store identity for it that is not revoked, or when the address is a local account to which a Maildir or.forwardstage delivers. The page says the same thing whether or not that happened (“if this server handles that address, a sign-in link has been sent to it”), and the lookup runs after the answer has been sent, so neither the text nor the response time reveals which addresses exist.The link (
ENROL_URL/ui/enrol/<token>) opens a confirmation page; opening it changes nothing, because link scanners fetch links. Submitting it opens a browser session holding exactlyown:<address>, with the same cookies, lifetimes and CSRF protection as a password sign-in, and lands on the user’s own identities. When a second factor is enrolled (see Key management), the submission needs the address’s current TOTP code. When the address has a security key (registered on the user’s own Security keys page, as above), submitting leads to a page that asks for it instead; the TOTP code still stands in where the address has one andREQUIRE_WEBAUTHNdoes not nameusers, and only when the applier reports that it actually checked a code. Removing an end user’s last key takes an assertion by it; the operator’s recovery isDELETE /api/v1/webauthn/{address}.
The link works once, for ENROL_LIFETIME (30 minutes by default), accepts at
most five submissions, and is replaced by the next link mailed to the same
address. Only the SHA-256 of its token is stored (pepsi.own_enrolment), as
only the digest of the session cookie is (pepsi.own_session); both tables
belong to pepsi-httpd alone. Requests are limited per target address
(ENROL_MAIL_PER_HOUR, default 3 links an hour) and per client address
(ENROL_RATE_LIMIT, default 20 an hour).
The second factor is checked by the privileged applier, not by this server:
otp_key and the key that wraps its secrets are out of the web tier’s
reach. The confirmation queues a confirm-enrolment task carrying the code,
under the address’s own scope, and the session is opened only when that task
ends done. The applier passes an address that has no second factor, so the
web tier never even learns whether one is enrolled. Enrolment therefore needs
the applier (the pepsi-httpd-admin package and [pepsi-admin]
CONFIG_DB); without it the address form answers that signing in by e-mail is
unavailable here and mails nothing.
The mechanism and what it does not protect against are in Signing in to the console by e-mail; the threat model’s account of a stolen mailbox is Someone who can read a user’s mailbox.
The console has to be reachable by the users for any of this to help:
ENROL_URL names the https:// origin of an ADMIN = yes listener (or of
the TLS reverse proxy in front of one), and the link always points there. It
never points at whatever Host the request carried, since an attacker could
choose that.
What an end user can do there is what own:<address> allows: read their own
identities, correspondent keys, mail log and greylisted mail, the key
operations above, and allowing a sender that greylisting deferred. The
pages are otherwise read-only: users still change their own settings by e-mail,
through pepsi-stage-edit-settings(1), and can manage their keys by
e-mail through the encrypt stage’s pepsi-keys@ control address.
25.6. Two templating engines, two purposes¶
Pepsi renders two quite different kinds of text, and uses a different engine for each. So do not try to override a console page the way you override a bounce.
Mail bodies are Mustache templates, shipped as files under
[pepsi] TEMPLATE_DIR (bounce-<name>.<lang>.body,
payment-request.<lang>.body, edit-settings.<lang>.body,
wallet.<lang>.body). They are operator-editable and per-language: an
operator is expected to rewrite the prose a correspondent will read, and to add a
language, without rebuilding anything. Logic-less templating is the right choice
there: there is nothing to compute, and an operator can safely be handed a
template that cannot run code.
Console pages are askama templates, compiled into the binary and type-checked at build time against the Rust structs that they render. There is nothing to install at runtime, nothing to keep in sync with the binary, and a renamed field is a build error rather than a blank cell in production. The console is mostly tables and conditionals, which logic-less templating makes painful.
The practical consequence: there is no way to override a console page, and there is not meant to be. If a page says the wrong thing, that is a bug to report, not a file to edit.
25.7. No scripting, no remote assets¶
The console ships no JavaScript, with one exception. Every action is a form
or a link, so it works with scripting disabled. That includes the queue’s
optional auto-refresh, which is a <meta http-equiv="refresh"> that the
reader turns on and off with a link rather than a timer. The charts are small
hand-written inline SVG generated on the server, so they render in the same
request as the rest of the page.
Nothing is loaded from another host: one stylesheet, compiled into the binary and
served from /ui/static/console.css. The Content-Security-Policy therefore
forbids script outright rather than allowlisting the console’s own, and forbids
framing (frame-ancestors 'none', with X-Frame-Options: DENY beside it).
The exception is a security-key ceremony, which no form can run:
navigator.credentials is a script interface. Three pages run one: the
second step of a sign-in, the e-mail sign-in’s confirmation when it asks for a
key, and Security keys. They load one static script, webauthn.js,
compiled into the binary like the stylesheet. Their policy allows that file by
its SHA-256 (which the tag also carries as integrity) and its exact URL on
CONSOLE_URL, and nothing else: no inline script, no 'self', no eval.
The script reads the ceremony’s parameters from the button’s data-
attributes, puts the browser’s answer into hidden fields and submits the
ordinary form; the button stays hidden without script, so such a browser sees
the TOTP field where there is one. Every other page keeps the policy without
script-src. We do this so that a missed escape still cannot execute script
(see Missing HTTPS and HTTP security-header hardening on webmail). Pages are sent Cache-Control:
no-store, so administrative data does not sit in a shared cache or in the back
button after a sign-out.
Cross-site request forgery is refused twice over. Every form carries the session’s
CSRF token as a hidden field, checked against a digest stored with the session;
and a mutating request whose Origin header names another host is refused
before its body is even read. That second check covers the login form, the one
form that by definition has no session yet (see
Reflected and stored XSS or HTML injection in portals and admin mails).
Values that arrive from outside (a subject, a sender’s display name, a header value, a bounce reply text, a key’s user id) are escaped by default when they are rendered, and the tests exercise that with hostile input rather than trusting it. The only markup that the console emits unescaped is the SVG of its own charts, which contains numbers and nothing else by construction (see Reflected and stored XSS or HTML injection in portals and admin mails).
25.8. Accessibility¶
The console is plain HTML: a skip link to the main content, one <h1> per
page, tables with <caption> and <th scope=…>, a label for every form
field, and aria-current="page" on the navigation entry you are on. Every
action is a real <button> inside a form, so it is reachable and operable from
the keyboard with no key bindings to learn, and the focus ring is drawn
explicitly because the default one disappears against some backgrounds. Light and
dark both come from prefers-color-scheme; there is no theme switch, because a
switch needs script or a cookie and the operating system already knows the answer.
The charts carry aria-hidden and are never the only presentation of anything:
the same numbers are in the table beside every figure.
Navigation offers only what your credentials allow, because a link that answers
403 is worse than no link.
25.9. The public mailing-list pages¶
A second, separate browser surface, gated on LISTS = yes (see
Three listener flags, and two of them have opposite advice) and documented here because an operator meets both:
/listsThe index of advertised lists, grouped by domain. A list whose
advertisedattribute is false is absent from the index and still reachable by URL. That is upstream’s meaning of the attribute, and it is not a security boundary. “Unadvertised” reads like “hidden”; it is not./lists/<list-id>A list’s description, its
infotext, its posting address, the subscribe and unsubscribe forms, a link to the archive when the policy allows one, and the roster only whenmember_roster_visibilityispublic./lists/<list-id>/confirm/<token>What a confirmation link points at. A ``GET`` completes nothing: it renders what the token is for and asks for one
POST. Mail clients, link previewers and security scanners fetch links, several of them before the person does. This is a deliberate difference from the-confirm+<token>mail address, where arrival is the confirmation because the token travelled in the envelope and only its owner could have put it there./archives/list/<list@domain>/…The archive: overview, month, thread, message, attachment, search. The URL shapes are HyperKitty’s, so every
Archived-At:header that a migrated deployment ever emitted keeps working. See Archives.
Three things about these pages are worth knowing before deploying them.
They ship no JavaScript, except on the two member pages that run a
security-key ceremony (below). The Content-Security-Policy therefore has
no script-src (not even 'self') and says default-src 'none'. The
cost is the interactive parts of HyperKitty: thread collapsing is <details>,
there is no live search and no in-page reply. That was decided deliberately, and
a policy that allows what is not used is a policy that will one day allow what is
injected (see Missing HTTPS and HTTP security-header hardening on webmail).
Message bodies are escaped text, never markup. Upstream’s
archive_rendering_mode attribute offers text or markdown. Pepsi
stores and exposes the attribute, because the attribute set is the
compatibility contract, and renders text for both. Rendering user-supplied
markdown into our own origin is precisely what the policy above exists to make
impossible, and a markdown renderer is an HTML-injection surface with extra
steps. Rendering text leaves no sanitiser to get wrong, which avoids injected
markup and forms (see Hand-written or single-pass HTML sanitisers let active content survive and
Hand-written or single-pass HTML sanitisers let active content survive).
Addresses are obscured for anonymous viewers. An archive page shows
alice@... rather than the whole address, for the sender and for every
address in a message body or search snippet, except the list’s own posting and
role addresses (list@domain, list-request@domain and the rest), which
are published by design; attachments are served as stored. A signed-in member
sees them whole. The archive keeps the real addresses, because obscuring on
the way in cannot be undone and the bounce processor needs the real address.
Obscuring is therefore a rendering decision. It is not a security control, and
it is not meant to be one: somebody who is on the list has the address in their
own copy of the message. What it stops is the bulk harvest that makes a public
archive a spam source.
25.9.1. Forms that make the server send mail¶
Subscribing is a request for the server to send a message to an address that nobody has proved they control. Without throttling, somebody could use it to harass a stranger with mail, and Pepsi ships no CAPTCHA, by the same decision that rules out JavaScript. So:
each such form is rate-limited on the target address (two mails per address per hour) as well as on the client address;
a second submission while a token is still live re-uses that token rather than minting another, so ten submissions are not ten messages;
the answer is identical whether or not the address is already a member, so the form is not a membership oracle.
The last one is why the page says “if that address can be subscribed, a confirmation has been sent to it” rather than anything more helpful. These rules limit address enumeration through the forms; a timing difference between the two paths is not excluded (see Portals and APIs disclosing user data or key material without auth).
Warning
The web tier sends no mail of its own. The forms, the List API and the
member pages run the same subscription workflow as the -join and
-leave mail commands and park the same token in pepsi.list_pending,
but only the mail command stage injects the confirmation request; the web
tier records the token and answers as if it had been sent. Until that is
wired (docs/ROADMAP.md), a visitor who subscribes, registers or resets
a password through the web is waiting for a message that does not come. An
operator can read the token from the table and pass the link on, add the
member with pepsi-list members add, or reset a password with
pepsi-list owner reset-password.
25.10. Two account systems, and neither grants the other anything¶
This is the single most misunderstandable thing about the web tier, so it is stated as plainly as possible.
Pepsi has two kinds of browser account, in two tables, with two sets of cookies, and they are not related:
The operator’s console |
The list member’s account |
|
|---|---|---|
Who it is for |
Whoever runs the mail server |
Anybody who subscribes to a list, and the owners and moderators of those lists |
Account table |
|
|
Session table |
|
|
Cookies |
|
|
Listener flag |
|
|
Where it should be reachable |
Loopback, over an SSH tunnel |
The public internet |
Created by |
An operator, through |
Registering at |
What it can do |
The configuration, the queue, the keys and the logs. Not the lists:
those are managed with pepsi-list(1) or through the Mailman
|
Its own subscriptions, plus whichever lists its address is an owner or moderator of |
Neither is a weaker version of the other. An operator account is not a member of anything, and a member account, even a list owner’s, cannot read the queue, the configuration or anybody’s keys. The two are separate because their deployment advice is opposite: the console is the thing that the manual tells you to keep off the internet, and a list owner obviously cannot be asked to open an SSH tunnel to approve a held message.
25.10.2. If you serve both surfaces from one hostname¶
The wizard warns against it and cannot prevent it. Cookies are scoped by host,
not by listener, so a deployment that puts ADMIN = yes and LISTS = yes
behind one name has exactly two things keeping the surfaces apart: the cookie
names, and the guard’s check of which table a session came from.
That is a thin line, and it is thin by design rather than by accident. It is
tested in both directions: a member session presented to an operator route is
refused exactly as no cookie would be, and an operator session presented to a
member route likewise, with neither producing a distinguishable error. Still,
prefer two names, or better, two listeners: ADMIN on loopback and LISTS
in public is the layout the rest of this chapter assumes.
25.11. The member’s pages¶
/lists/registerCreates an account and mints a verification token, in one database statement that is the same whether or not the address was known (the reset form below likewise), so neither the answer nor the work behind it says which addresses have accounts. Non-oracular and throttled, like the subscribe form above and for the same reason. With
[pepsi-list] WEB_REGISTRATION = nothe page and its handler do not exist (404) and the sign-in page does not offer them; signing in, password resets and verification links of existing accounts keep working, and accounts come frompepsi-list, an import or a list owner. The token is not mailed (see the warning above): it sits inpepsi.list_pending(payload->>'account' = 'verify') until the operator passes the link on or it expires./lists/verify/<token>Confirms the address and sets the password, in one step. There is no separate “choose a password” page, because a verification link that only verifies leaves an account that nobody can sign in to. The password must be at least ten characters, not on the shipped list of common passwords and not contain the address; a refused one costs the link, and the page says to ask for a new one.
/lists/sign-in,/lists/sign-outSign in with any verified address of the account and the account’s one password. A member may hold several addresses (upstream’s model is one user with many addresses), and that is what makes “I subscribed with my work address” work. An unverified address cannot sign in: it has proved nothing.
/lists/resetMints a reset link (
payload->>'account' = 'reset'), not mailed either. A link, never a password: a mailed password is a password in a mailbox for ever.pepsi-list owner reset-passwordis the operator’s path, and it prints rather than mails by default for exactly that reason. There is no knowledge-based recovery such as security questions (see Weak passwords and guessable account recovery questions)./lists/meTheir addresses, and their subscriptions across every list, each with its delivery mode and status.
/lists/me/securityThe member’s security keys (WebAuthn), a second factor that phishing pages cannot use. Registering one needs the password; from then on signing in needs the password and one of the keys, answered on a second page (
/lists/sign-in/second-factor). Adding a further key, and removing one, need the password and an assertion by one of the existing keys; an addition then registers the new key on the page that follows. A member account has no TOTP, so a member who loses every key is restored by the operator (DELETE /api/v1/webauthn/members/{address}); a password reset does not remove a key, or the mailbox alone would get around it. Keys are bound to[pepsi-list] BASE_URL, which must be anhttps://URL for any to be offered; with[pepsi-httpd] REQUIRE_WEBAUTHNnamingmembersevery member registers one at the next sign-in. The two pages that run the ceremony load the one static script, as the console’s do; every other page here stays script-free.
25.11.1. Why a preference may not apply where you expect¶
The six delivery preferences are looked up through a chain: this subscription, then this address, then this account, then the list’s own default. Any level may be unset. So a member who sets a preference on their account and finds it not applying to one list has usually set it at a level that a more specific one overrides.
/lists/me therefore shows, for each subscription, which level the value
came from. That column is the answer to the only question that this design
reliably provokes.
25.12. The owner and moderator console¶
/lists/<list-id>/adminThe one page to start from: the held messages, the subscription requests, and (for an owner) links to the settings screens and the roster.
/lists/<list-id>/admin/held/<request-id>One held message, with its exact bytes shown as text. Accepting releases those bytes, not a re-rendering of them: a held message is kept in its wire form precisely so that a release can be delivered for real, signatures and attachments intact.
The page is the most hostile one on the site: a stranger’s mail, rendered where a moderator’s click can act. So the body is escaped text inside a
<pre>, the policy allows no script, and every button carries a CSRF token. We do this to avoid stored cross-site scripting through mail (see Hand-written or single-pass HTML sanitisers let active content survive)./lists/<list-id>/admin/settings/<screen>The writable list settings, on eleven screens in Postorius’ own grouping, because a migrating owner will look for a setting where it used to be. The help text beside each field is Postorius’ own, imported; see the attribution note in Mailing lists.
The screens are generated from the same declaration that drives the REST API and the CLI, so a value refused here is refused there, in the same words, and a setting cannot be present in one place and missing from another. A twelfth screen,
pepsi, holds the settings that Pepsi invented (hold_dmarc_failuresamong them; Settings Pepsi invented), validated aspepsi-list list set-extvalidates them; an empty value returns a setting to its default.The six
*_uritemplate attributes are on these screens too, so an owner who wants their own welcome message or footer sets the URI where every other setting lives rather than on a page of its own./lists/<list-id>/admin/rosterMembers, owners and moderators; the list’s bans; and its header matches, with the site-wide bans and matches shown read-only beside them. The site-wide ones take precedence, and an owner who debugs a rule that never fires needs to see the one that fired first.
Adding an address is the one action in this tier that subscribes somebody who has not agreed. It is an owner action, it is written to the audit log with the owner as the actor, and the added address is not marked verified: an owner’s say-so is not proof that a mailbox exists.
Everything in this console is audited through the same log as every operator
action, with the member’s account as the actor. detail never carries message
content: a held-message accept records the request and the message’s hash, not
the body. The log is pruned on the operator’s
[pepsi-admin] EVENT_RETENTION_DAYS timer, which is worth checking against how
long you want moderation history kept.
25.13. The interfaces’ languages¶
Every page that pepsi-httpd serves picks its language from the request’s
Accept-Language header, by one rule: a regional tag is served its language
(de-CH gets the German pages, because one variant of a language is closer to
it than English is), the header’s q order is honoured rather than its
document order, a q=0 is read as a refusal (so de, en;q=0 means German
and not “German, then whatever”), and a header naming nothing that the server
has falls back to English.
What differs is how many languages each surface has. The administration
console and the secure-link portal are served in the ten languages in which the
notice templates ship: English, German, Spanish, French, Hungarian, Italian,
Russian, Swedish, Turkish and Ukrainian. The console’s labels are one catalogue
per language (pepsi-httpd/src/ui/strings/), the portal’s likewise
(pepsi-secure-link/src/strings/), and a test refuses a catalogue in which
a sentence was left in English. The portal’s three mails (the notification,
the PIN and the read receipt) are templates in the same ten languages, with
their subject lines translated alongside; see The secure-link fallback portal.
The public mailing-list pages are served in English, German or French, the three languages in which the manual exists, and this gap is stated rather than hidden. The notice templates (the welcome message, the confirmation request, the bounce warnings) exist in ten, because they came from GNU Mailman, which has them in thirty-four (see Mailing lists). A member who reads a German welcome message and follows its link lands on a German page; a Swedish one lands on an English page. Adding a language to the public pages is translating about 170 short labels, which is an afternoon and a patch, not a project.
The choice is made from the header alone, before any database access. That is deliberate: a public page is reachable by anybody, and picking a word by reading a row would mean an unauthenticated request touching the database, on a server whose worker pool is one connection. A signed-in member’s own stored preference therefore does not override the header.