59. pepsi-stage-edit-settings¶
Let an account owner change their own settings by e-mail.
59.1. Role¶
pepsi-stage-edit-settings lets the owner of an account change their own
per-address overrides (the pepsi.settings table; see pepsi-settings) by
sending a control e-mail. The message must be locally originated, carry the exact
subject SUBJECT (default Pepsi), and be addressed to
<CONTROL_LOCAL_PART>@<controlled-domain> (the default local part is
pepsi; the domains are those in [pepsi-ingress] ACCEPTED_DOMAINS); its
body is an INI snippet
of the options to set.
Any other message is passed through untouched, so the stage is safe to place
anywhere on the local-submission path. Reference:
pepsi-stage-edit-settings(1).
The address whose settings are edited is the envelope sender, and the reply
goes back to it — so the operator’s submission authentication must bind the
envelope sender (pepsi-ingress does so for logins through
USERNAME_MAP, and for MYNETWORKS and client certificates only where
SENDER_MAP names them).
59.2. Features¶
INI body, leniently parsed:
[stage-<name>]sections andOPTION = valuelines; greetings, comments and a trailing signature are ignored. An empty value (OPTION =) unsets an override (reverting to the INI default); any other value adds or overrides it.Operator allowlist: only stages named in EDITABLE_STAGES may be changed.
Validate before adopt: the combined settings (INI defaults + existing overrides + the new INI) are checked by each affected stage’s real configuration parser (shared with pepsi-setup), on top of the operator’s configuration for the sender (
domain:/address:overrides included).Own whitelists only: two stages write a whitelist on the owner’s behalf, pepsi-stage-auto-whitelist and pepsi-stage-secretary. A
WHITELIST_NAMEthat the sender sets for either of them must name one in their own<login>/...namespace, or the one that the operator’s configuration already names for them. A shared list or another user’s is refused, since it would let the owner fill it with addresses of their choosing. A value already stored in the row (the operator may have set it with pepsi-settings) does not block edits to other options. This stage is the only way an account owner writespepsi.settings, so the rule is enforced here, and the operator’s own layers may name any whitelist.All or nothing: on any error nothing is changed and a human-readable reply lists the problems.
Confirming reply: on success the merged overrides are stored and a reply quotes the full effective option set of every editable stage, in INI syntax. Both replies carry
Subject:SUBJECT, use the null sender, and are injected at RESPONSE_STAGE so they are DKIM-signed and relayed.Localised replies: the framing prose comes from the
edit-settings.<lang>.bodytemplate under[pepsi]TEMPLATE_DIR, chosen from the sender’s detected language (state.language, as pepsi-stage-detect-language recorded it) and falling back to English.Safe by default: an e-mail may only point a stage’s
PROGRAMat apepsi-stage-*command, may not set an option that names a program run by a stage or setuid tool (HELPER,SCAN_HELPER,MAILBOX_HELPER,PIN_COMMAND), and may not touch the options that decide which identity a message is signed or sent as (SIGNING_DOMAIN), whose wallet pays (WALLET_MODE,WALLET_SCOPE,WALLET_USERof pepsi-stage-auto-pay) or how much it pays (MAX_TOTAL,MAX_TOTAL_PER_DAY: the limits that bound a stolen password, which also authenticates the control message). The operator can lift all of these restrictions withUNRESTRICTED_UNSAFE_STAGES = YES, which is as unrestricted and unsafe as its name says.Whole sections are quoted back. The confirming reply shows every option of every editable stage, credential-bearing values (names containing
PASS,SECRET,TOKEN,CREDENTIAL,CLIENT_ID,PEPPERorSYSTEM_ID) masked as***but host names and paths verbatim; do not list a stage whose section holds anything a local user should not see.
Per-address settings are a trust boundary explains which stages are safe to list in
EDITABLE_STAGES: an editable stage hands the user every option that it
reads, branch targets included.
59.3. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-edit-settings, NEXT_STAGE
(required — nearly every message is not a control message and is advanced
unchanged), EDITABLE_STAGES (required, whitespace/comma-separated stage
names), RESPONSE_STAGE (required, where the reply is injected),
SUBJECT (default Pepsi), CONTROL_LOCAL_PART (default pepsi),
RESPONSE_FROM (the reply’s From:; by default
<CONTROL_LOCAL_PART>@<matched domain>) and UNRESTRICTED_UNSAFE_STAGES
(default no). pepsi-setup checks that every EDITABLE_STAGES entry and
RESPONSE_STAGE name a real stage, and that the edit-settings.en.body
fallback template exists. The stage reads its own options from the base
configuration, never from the per-address overrides, so a correspondent cannot
e-mail themselves a wider allowlist. See pepsi-stage-edit-settings(1).
59.4. State¶
Inputs:
state.local_origin(a message that is not locally originated is never a control message) andstate.language(the reply’s language).Outputs: none — a control message’s row is deleted once the reply has been injected; any other message is advanced with its
state, includingstate.dsn, untouched.
59.5. See also¶
pepsi-settings, pepsi-dispatch, pepsi-stage-check-whitelist, pepsi-setup, Architecture, pepsi-stage-edit-settings(1), pepsi.conf(5).