84. pepsi-stage-list-command

Subscribe, unsubscribe and confirm by e-mail; forward `-owner` mail.

84.1. Role

pepsi-stage-list-command handles everything that a mailing list does by mail, other than a post: the seven e-mail commands, both subscription workflows, and the -owner forward. Reference: pepsi-stage-list-command(1).

One sentence 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.

This subsystem is a reimplementation of GNU Mailman 3; see Mailing lists, which names what was taken from upstream.

84.2. Addresses

There are seven addresses, and the first five are not parsed at all: -join/-subscribe become one synthetic join (the Subject and body are never read, and no results mail is sent), -leave/-unsubscribe likewise become one synthetic leave, and -confirm+<token> becomes one synthetic confirm whose token is taken from the address and never from the message. -request is the one whose Subject and body are parsed. -owner is not a command at all: it is forwarded to every owner and moderator and never reaches the parser. This is upstream’s behaviour, and it matters, because a message to the owners whose Subject happens to read unsubscribe must reach a human rather than run a command.

84.3. Commands

confirm, echo, end (alias stop), help, join (alias subscribe), leave (alias unsubscribe) and who. 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 an answer that told them apart would reveal which tokens exist.

  • ``leave`` takes no arguments at all. join address= costs the named address one confirmation message and subscribes nobody; an equivalent leave address= would let a forged From: unsubscribe a stranger outright. The sender’s own address must additionally be verified. “The sender” is the first address in From:, falling back to the envelope sender only when From: names none, and it is one address throughout: the one whose verification is checked is the one removed (and the one that a bare join subscribes), 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 would tell a harvester that the address is worth trying again.

Whoever writes to these addresses is a remote sender, and a forged From: costs nothing. Principals and how far each is trusted treats list members, owners and moderators as hostile beyond their own lists, and these three rules keep a command message inside that bound.

84.4. Parsing

The stage reproduces upstream’s leniency rules, because twenty years of “send the word HELP to…” instructions exist. An address command wins outright. 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, because 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. An unknown first word is retried after dropping exactly one word, which is the entire Re: mechanism and deliberately not a general prefix stripper (Fwd: help me would otherwise run help). A command that stops ends the run and the rest is reported as unprocessed. Before any of that, a message carrying Precedence: bulk|junk|list without X-Ack: yes is discarded silently.

Two of these look like bugs and are not: the retry drops one word and no more, and the line cap counts lines, not commands. A message of eleven blank lines followed by help therefore executes nothing and reports the help as ignored. Raising MAX_COMMAND_LINES is the fix for “my mail client put a header block in front of my command”, not quote detection.

84.5. The reply

The stage answers with a results mail in 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 a sender that did not pass SPF or DMARC, the results quote nothing that the sender wrote either: no original details, counts instead of the unprocessed and ignored lines, and no echo of its arguments (Provider notification workflows send attacker-controlled mail).

84.6. 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 whoever guesses one can complete 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. Deleting a token discards its workflow state with it, so a replayed confirmation finds nothing.

84.7. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-list-command, RESPONSE_STAGE (required: the signing tail, not the list delivery stage, which accepts only a member’s copy from the fan-out and would lose a notice), NEXT_STAGE (required: where -owner mail goes once readdressed; never the list router), MAX_COMMAND_LINES (default 10; 0 is refused) and REQUIRE_AUTHENTICATED (default off; when it is on, the results mail and the autoresponder notices go only to a sender that passed SPF or DMARC). The optional BOUNCE_STAGE is where a message for a list deleted in the meantime is turned into a DSN; without it such a message is failed. pepsi-setup checks both targets, and that the English copy of each of the 28 list notice templates is installed, since every language falls back to it.

84.8. State

  • Inputs: state.list, written by pepsi-stage-list: the list id, the role that the address named, and any -confirm token.

  • Outputs: injected reply and notice messages; the command message itself is consumed.

  • Transitions: finish (a command message is answered, not forwarded), or advance for the -owner forward.

84.9. See also

Mailing lists, pepsi-stage-list, pepsi-stage-list-post, pepsi-list, pepsi-stage-list-command(1).