51. pepsi-stage-auto-whitelist

Record the recipients of outgoing mail so that they can always reply.

51.1. Role

pepsi-stage-auto-whitelist is the write-side counterpart of pepsi-stage-check-whitelist. As an outgoing message passes through, it inserts each envelope recipient (rcpt_to) into a named whitelist, so that when that person later replies, the check stage recognises their From: header and lets the reply through without payment. Place it on the outbound path (e.g. before a relay stage). It only writes whitelist rows and advances — it never modifies the message or drops, bounces or pauses it. Reference: pepsi-stage-auto-whitelist(1).

51.2. Features

  • Shared whitelist table: writes the same pepsi.whitelist table that the check stage reads, so no schema of its own is needed; the WHITELIST_NAME option selects the whitelist_name group to populate.

  • All envelope recipients: every address in rcpt_to is recorded in a single round-trip, idempotently (ON CONFLICT (whitelist_name, match_field, whitelist_regex) DO NOTHING); the rows are written with match_field = from.

  • Fully anchored patterns: each address is lower-cased, regex-escaped and wrapped in ^/$, so the stored whitelist_regex matches that address and nothing else. The check stage evaluates it (case-insensitively, with the ~* operator) against the addr-spec parsed out of a reply’s From: header, not the raw header value — so bob@example.com (Bob) still matches the row for bob@example.com, while bob@example.com.evil and (bob@example.com)x@attacker.test do not. The anchoring is load-bearing: a boundary class that listed the characters allowed in an address would let an attacker find one character outside the class and use it on either side of a whitelisted address, inside a local part of their own.

  • Whose whitelist: on the outbound path the per-address layers are looked up for the envelope sender. The operator may name any whitelist, including a list shared by every local user, in the INI file, in pepsi.config_override at any scope, or in a pepsi.settings row written with pepsi-settings. An account owner who may edit the stage by mail (pepsi-stage-edit-settings) may only choose a list in their own <login>/... namespace, or keep the operator’s; anything else would let them fill a shared or foreign list with addresses of their choosing.

  • Per-row conditions:

    • dkim_required is set from the DKIM_REQUIRED option (default yes).

    • dmarc_required is set from the DMARC_REQUIRED option (default yes): the reply must pass DMARC, on an aligned DKIM signature or an aligned SPF pass. dkim_required implies it. With DKIM_REQUIRED = no, it still binds the row for a correspondent whose domain does not sign to an authenticated sender.

    • signature_required is set to true iff the message state has encrypted: true — which pepsi-stage-encrypt sets when a recipient’s copy really was encrypted. A correspondent reached under encryption is thereby held to the same standard when they reply. This only works with the stage placed after the encrypt stage; it changes no content, so it may sit between encrypt and pepsi-stage-dkim-sign, which is where the setup wizard puts it.

  • Mailing lists learnt from confirmation replies: with LIST_WHITELIST_NAME set (a template starting {login}/), an outgoing message that answers a list’s subscription confirmation request whitelists that list’s List-Id in the sender’s own namespace; pepsi-stage-check-whitelist records such requests inbound in pepsi.list_confirmation. The reply must come from the address that the request was delivered to, go to the request’s control address and name it in In-Reply-To:; a reply to anything else teaches nothing. The row keeps dkim_required and dmarc_required, names no sealer, and expires after LIST_MAX_IDLE_DAYS (180) without a matching posting, since leaving a list sends no signal.

  • Fail-open: a recording that fails (a database error, a missing grant) is logged and the message advances anyway; the whitelist is a convenience for the reply, not a reason to hold outbound mail.

51.3. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-auto-whitelist, WHITELIST_NAME (required — the single whitelist_name group to populate, a literal name: placeholders are not expanded and are refused), DKIM_REQUIRED and DMARC_REQUIRED (booleans, default yes), LIST_WHITELIST_NAME (unset: no lists are learnt), LIST_MAX_IDLE_DAYS (default 180), the locality options that expand {login}, and NEXT_STAGE (required — the stage records the recipients and always hands the message on). Neither the headers nor the body are loaded, except the header block of a message that the envelope already shows to be a confirmation reply. See pepsi-stage-auto-whitelist(1).

51.4. State

  • Inputs: the envelope recipients from the rcpt_to column, and state.encrypted, which sets the stored signature_required flag, so that a correspondent reached under encryption is later held to the same standard. pepsi-stage-encrypt sets state.encrypted, earlier on the same outbound path, when the outgoing message really was encrypted to a recipient key.

  • Outputs: none on the message — its state is untouched; the side effect is one pepsi.whitelist row per recipient, and one learnt list-id row per list whose confirmation request the message answers.

51.5. See also

pepsi-stage-check-whitelist, pepsi-stage-anti-spam, pepsi-stage-arc, Supported Features, pepsi-stage-auto-whitelist(1). Security: what an owner’s own override may name (Per-address settings are a trust boundary) and the forged mail that its rows must not admit (A remote sender).