50. pepsi-stage-check-whitelist

Mark mail from trusted senders as non-spam.

50.1. Role

pepsi-stage-check-whitelist consults a named whitelist of trusted senders and, when the message’s From: header matches, records state.spam = false so a later pepsi-stage-anti-spam lets the message through without payment. Place it ahead of the anti-spam stage. It only annotates the state and advances; it never drops, bounces or pauses a message. Reference: pepsi-stage-check-whitelist(1).

50.2. Features

  • Database-backed whitelists: the pepsi.whitelist table groups rows under a whitelist_name. WHITELIST_NAME is a comma-separated list of the groups to consult, and an entry may be a template containing {localpart} or {login}, expanded per envelope recipient. WHITELIST_NAME = correspondents, {localpart}/correspondents thus consults the operator’s shared list and each recipient’s own list, in the namespace that pepsi-whitelist lets that user manage. Only a recipient at a local domain may name a whitelist (otherwise an attacker-chosen co-recipient would expand to any local user’s list), and {login} additionally needs the address to resolve to a passwd account, so place the stage after pepsi-stage-aliases when using it. Every applicable name is checked in one query.

  • POSIX ERE matching: each whitelist_regex is an extended POSIX regular expression, matched case-insensitively against the field that the row’s match_field names. The match uses PostgreSQL’s ~* operator in a single round-trip and is cancelled after five seconds; a cancelled match counts as no match, so a pathological pattern cannot tie up a database backend. The fields are:

    • from (the default) — the addr-spec parsed out of the From: header, never the raw header value: otherwise a whitelisted address sitting in the display-name position would spoof a match. RFC 5322 comments and CFWS are removed, and a From: naming more than one mailbox matches nothing (the DKIM/DMARC verdict is computed for the first address, so matching a later one would answer two questions about two senders).

    • list-id — the RFC 2919 identifier of the message’s List-Id: header. A mailing list’s postings carry arbitrary From: addresses, so no from pattern can say “anything that came through this list”.

    The expression itself is unanchored; anchor it with ^/$ to match a whole address (which is what pepsi-stage-auto-whitelist writes).

    A row whose expression is one exact address or list identifier, or any mailbox at one domain (the shapes pepsi-whitelist and pepsi-stage-auto-whitelist write, when the text is ASCII), is found through an index rather than by evaluating the expression. The result is the same; only the other rows are evaluated one by one, so the cost of the check does not grow with the number of learnt correspondents.

  • Optional conditions per row:

    • dkim_required → matches only if the From: domain is authenticated: state.auth.dkim = pass, or an ARC pass that DMARC also confirms (state.auth.arc = pass and state.auth.dmarc = pass). ARC pass alone is only chain integrity (a one-hop chain can be self-minted over a forged From:), so it does not satisfy the row by itself. The column defaults to true, as pepsi-whitelist add does.

    • dmarc_required → matches only if the message passed DMARC at ingress on either aligned identifier, an aligned DKIM signature or an aligned SPF pass (state.auth.dmarc = pass), or a trusted ARC sealer let it through a DMARC failure (state.auth.arc_override). This is the level for a correspondent whose domain does not DKIM-sign; an unaligned SPF pass does not count, and every dkim_required pass satisfies it. When a row sets several conditions, all of them must hold.

    • signature_required → matches only if state.signature_verified is true, which pepsi-stage-decrypt sets for a message whose end-to-end signature verified against a trusted key. A valid-untrusted verdict deliberately does not set it, so such a row is a genuine “this correspondent signs, verifiably” gate rather than a “someone signed this” one. Place a decrypt stage before this one, or the row never matches. A signature from an S/MIME EnvelopedData (AES-CBC) does not count: whether a modified CBC ciphertext still verifies depends on its padding, and the verdict decides whether the sender is asked to pay or to confirm (CBC padding and format oracles against unauthenticated S/MIME).

    • sealer_domain → matches only if the message arrived with an ARC chain that validated and the named ADMD is among its sealers (state.auth.arc = pass and the domain in state.auth.arc_sealers). This is what makes a list-id row safe: List-Id: is unauthenticated text that anyone can copy, and a valid ARC chain conveys no trust by itself (RFC 8617 §8.4). Naming the sealer is what turns the pair into evidence.

  • Expiring list rows: a list-id row learnt by pepsi-stage-auto-whitelist matches only until last_seen + max_idle; each authenticated posting it matches moves last_seen forward (at most daily), and pepsi-queue gc deletes it once it lapses.

  • Recording confirmation requests: with RECORD_LIST_CONFIRMATIONS, a message that looks like a list’s subscription confirmation request (a single Message-ID:, confirm in the Subject:, a -request / -confirm / -join / -subscribe sender or Reply-To:) is recorded per local recipient for LIST_CONFIRMATION_DAYS (7), so the auto-whitelist stage can learn the list from that recipient’s reply. Recording trusts nothing.

  • Non-destructive: on a match it merges spam: false and advances to NEXT_STAGE; on no match it advances unchanged. A message with no From: header, and one to which no configured whitelist name applies, match nothing.

50.3. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-check-whitelist, WHITELIST_NAME (required; the comma-separated list of whitelist_name groups, literal or templated), NEXT_STAGE (required, because the stage always hands the message on), and the shared locality options LOCAL_DOMAINS (defaulting to [pepsi-ingress] ACCEPTED_DOMAINS), TARGETS and RECIPIENT_DELIMITER, which are used to expand the placeholders and to keep confirmation requests to local recipients, and RECORD_LIST_CONFIRMATIONS (default no) / LIST_CONFIRMATION_DAYS (default 7). See pepsi-stage-check-whitelist(1).

50.4. State

  • Inputs: state.auth.dkim / state.auth.arc / state.auth.dmarc (for dkim_required rows), state.auth.dmarc / state.auth.arc_override (for dmarc_required rows), state.auth.arc_sealers (for sealer_domain rows) and state.signature_verified (for signature_required rows; written by pepsi-stage-decrypt). The From: header comes from the from_header column; List-Id: is read from the header block, which is why this stage loads the headers (but never the body).

  • Outputs: on a match, spam: false merged into state; otherwise state is unchanged. Side effects: a matched learnt list row’s last_seen is refreshed, and with RECORD_LIST_CONFIRMATIONS a confirmation request is written to pepsi.list_confirmation.

50.5. See also

pepsi-stage-anti-spam, pepsi-stage-arc, Supported Features, pepsi-stage-check-whitelist(1). Security: the forged mail a whitelist must not admit (A remote sender), the bound on user-written patterns (Availability), why the stage should not be listed in EDITABLE_STAGES when filtering is mandatory (Per-address settings are a trust boundary), and who may write the table (The privilege split).