95.1.23. pepsi-stage-list-command¶
subscribe, unsubscribe and confirm by e-mail
- Manual section:
1
95.1.23.1.1. Name¶
pepsi-stage-list-command - the mailing-list command stage of the Pepsi pipeline.
95.1.23.1.2. Synopsis¶
pepsi-stage-list-command [GLOBAL-OPTIONS] worker
95.1.23.1.3. Description¶
pepsi-stage-list-command is a stage program run by pepsi-dispatch(1). It handles everything that a mailing list does by mail apart from posts: the seven e-mail commands, both subscription workflows, and the -owner forward.
The sentence that governs the whole stage:
The only path that adds an address without that address proving it wants to be there is an explicit pre_verified and pre_confirmed from an authenticated REST client or the CLI.
Nothing in this stage can set either flag. A message is not an authenticated client, so a join always either asks the named address to confirm or refuses.
95.1.23.1.4. Addresses¶
There are seven addresses, and the first five are not parsed at all:
Address |
What happens |
|---|---|
|
one synthetic |
|
never read, and no results mail is sent |
|
one synthetic |
|
|
|
one synthetic |
|
the Subject and the body are parsed |
|
not a command at all: forwarded to every owner and moderator |
-owner mail never reaches the parser, which is upstream’s behaviour and
matters: a message to the owners whose Subject happens to read unsubscribe
must reach a human, not run a command.
95.1.23.1.5. Commands¶
|
Confirm a pending request using its token. |
|
Echo back the arguments, for testing. |
|
Stop processing commands (alias: |
|
Show the command list, or help for one command. |
|
Subscribe (alias: |
|
Unsubscribe (alias: |
|
Show the roster, if you are allowed to see it. |
Three of them carry a security decision rather than a formatting one:
``confirm`` always stops processing, so a token that a quoting mail client repeats further down the same message is never run a second time. A token that does not match gets the same answer as one that has expired, because distinguishing them is an oracle for which tokens exist.
``leave`` takes no arguments at all.
join address=costs the named address one confirmation message and subscribes nobody; an equivalentleave address=would let a forgedFrom:unsubscribe a stranger outright. The sender’s own address must additionally be verified. “The sender” is the first address inFrom:, falling back to the envelope sender only whenFrom:names none, and it is one address throughout: the one whose verification is checked is the one removed (and the one that a barejoinsubscribes), never an envelope sender that differs from it.``who`` is gated on
member_roster_visibility, and an unauthorised request is refused rather than answered with an empty list. An empty answer is indistinguishable from a list with no members, which tells a harvester that the address is worth trying again.
Whoever writes to these addresses is a remote sender, and a forged From:
costs nothing; the threat-model chapter of the Pepsi manual (“Principals and
how far each is trusted”) treats list members, owners and moderators as hostile
beyond their own lists, and these three rules are what keep a command message
inside that bound.
95.1.23.1.6. Parsing¶
The parser reproduces upstream’s leniency rules, because twenty years of “send the word HELP to…” instructions exist:
An address command wins outright (see the table above).
The
Subject:is the first command line, RFC 2047-decoded and then forced to ASCII.The body contributes only the first ``text/plain`` part, and only its first MAX_COMMAND_LINES lines. A message with no plain part contributes nothing: executing commands out of HTML is a place where being helpful is a security decision.
There is no quote, signature or
--handling whatsoever.Every token is lower-cased; blank lines are skipped silently.
An unknown first word is retried after dropping exactly one word. That is the entire
Re:mechanism, and it is deliberately not a general prefix stripper: with one,Fwd: help mewould runhelp.A command that stops ends the run; the rest is reported as unprocessed.
Before any of that, a message carrying
Precedence: bulk,junkorlistwithoutX-Ack: yesis discarded silently.
Two of these look like bugs and are not. The retry in rule 6 drops one word
and no more. And the cap in rule 3 counts lines, not commands, so eleven
blank lines followed by help executes nothing and reports the help as
ignored. The fix for “my mail client put a header block in front of my command”
is to raise MAX_COMMAND_LINES, not quote detection.
95.1.23.1.7. The reply¶
The reply is a results mail with upstream’s shape: a preamble, the original message’s details, the results, the unprocessed and ignored lines, and “- Done.”
The original message is never attached. A command message’s From: is
forgeable, so a results mail goes to an address that may not have sent
anything; attaching the original would make this stage a backscatter
amplifier. For the same reason, a sender that did not pass SPF or DMARC (and
did not submit locally) gets a results mail that quotes nothing that it wrote: the
original’s From:, Subject:, Date: and Message-ID: are
withheld, the unprocessed and ignored lines are replaced by their counts, and
echo does not repeat its arguments. Otherwise a forger could have the list
deliver text of their choosing to a third party.
95.1.23.1.8. Confirmation tokens¶
A token is 256 bits of randomness in base32. It is also the
-confirm+<token> sub-address and the last path segment of the confirmation
URL, so guessing one means completing somebody else’s subscription.
Its lifetime depends on who is being waited for: a token owned by a moderator lives 180 days, and everything else lives three. A moderator may be on holiday, and a subscription request that expired in three days would be silently lost rather than decided.
Expired tokens are swept by pepsi-list tasks --once, which a systemd timer
runs; see pepsi-list(1). Deleting a token discards its workflow state
with it, which is what makes a replayed confirmation find nothing.
95.1.23.1.9. Configuration¶
- RESPONSE_STAGE (required)
Where replies and confirmation notices are injected. The signing tail, not the list delivery stage: pepsi-stage-list-deliver(1) only accepts a member’s copy from the fan-out and fails anything else, so a notice sent there never goes out. pepsi-setup(1) refuses the wrong value.
- NEXT_STAGE (required)
Where
-ownermail goes once it has been readdressed to the list’s owners. pepsi-setup refuses a value that points back at the router, which would re-route the forward and loop.- MAX_COMMAND_LINES (default 10)
How many lines of the body the parser reads (upstream’s
[mailman] email_commands_max_lines). Counts lines, not commands. pepsi-setup refuses0.- REQUIRE_AUTHENTICATED (default no)
Answer a command message only when its sender’s envelope domain passed SPF or its
From:domain passed DMARC. The commands still run where they can; what is withheld is the results mail and the autoresponder notices, which go to an address that nobody verified. By default only a definitefailwithholds them (the shared RFC 3834 rules ofpepsi_common::autoreply), so a sender at a domain that publishes neither record is answered. With the option on, such a sender never hears back, and a forged sender cannot make the list’s command address mail an address of the forger’s choosing.- BOUNCE_STAGE (optional)
Where the DSN goes for a message whose list was deleted after the router routed it (see Errors and retries). Without it such a message is failed.
pepsi-setup also refuses this section when any of the 28 list notice
templates is missing in English (<name>.en.body in the [pepsi]
TEMPLATE_DIR): a list whose language has no template falls back to en.
95.1.23.1.10. State¶
Inputs: state.list.id and state.list.role (written by
pepsi-stage-list(1)), and state.list.token for a -confirm
address.
Outputs: none. Everything this stage changes is a database row.
Transitions: finishes (every command path), or advances to
NEXT_STAGE (the -owner forward).
95.1.23.1.11. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.
95.1.23.1.12. Global Options¶
The usual set: -c/–config, -L/–log, -v/–verbose, -h/–help and -V/–version, which behave as they do for every Pepsi program; see pepsi-config(1).
95.1.23.1.13. Errors and retries¶
A message that names a list which no longer exists is reported to the sender through the stage’s BOUNCE_STAGE (one DSN per recipient, saying the mailing list no longer exists), or failed when the stage has none; a null-sender message is dropped instead. A message that the MIME parser refuses is failed at once. Any other error is a fault of the host and is retried with back-off until MAX_LIFETIME (see pepsi-dispatch(1)).
The grace-period claim for the results mail is recorded before
list_command_commit commits the commands and the mail, so it is keyed on the
message’s queue token: a message retried after that commit failed is allowed to
send its results again rather than being told it was already answered today.
95.1.23.1.14. Exit Status¶
The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.
- 0
The worker ran until its standard input was closed.
- 1
A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.
- 78
The worker refused to start: a
[stage-*]section it serves does not parse (e.g. a missing RESPONSE_STAGE). The dispatcher requeues what it handed over and retries the stage later.
95.1.23.1.15. Examples¶
[stage-list-command]
PROGRAM = pepsi-stage-list-command
RESPONSE_STAGE = dkim-sign
NEXT_STAGE = local
MAX_COMMAND_LINES = 10
95.1.23.1.16. See Also¶
pepsi-list(1), pepsi-stage-list(1), pepsi-stage-list-post(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.23.1.17. Bugs¶
Report bugs to the Pepsi issue tracker.