..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

==========================
pepsi-stage-auto-whitelist
==========================

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

Role
====

``pepsi-stage-auto-whitelist`` is the write-side counterpart of
:doc:`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:
:manpage:`pepsi-stage-auto-whitelist(1)`.

Features
========

* **Shared whitelist table:** writes the same ``pepsi.whitelist`` table 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,
  whitelist_regex) DO NOTHING``).
* **Boundary-anchored patterns:** each address is lower-cased, regex-escaped and
  anchored on address boundaries, so the stored ``whitelist_regex`` matches the
  address literally wherever it appears in a reply's ``From:`` header (the check
  stage uses the case-insensitive ``~*`` operator) — ``<bob@example.com>`` matches
  but ``bob@example.com.evil`` does not.
* **Per-row conditions:**

  * ``dkim_required`` is set from the **DKIM_REQUIRED** option (default *yes*).
  * ``signature_required`` is set to *true* iff the message state has
    ``encrypted: true`` — which :doc:`pepsi-stage-encrypt` sets when a
    recipient's copy really was encrypted, and :doc:`pepsi-stage-decrypt` sets
    for a message that arrived encrypted. A correspondent reached under
    encryption is thereby held to the same standard when they reply.

Configuration
=============

``[stage-<name>]``: ``PROGRAM = pepsi-stage-auto-whitelist``, ``WHITELIST_NAME``
(required — the ``whitelist_name`` group to populate), ``DKIM_REQUIRED``
(boolean, default *yes*) and ``NEXT_STAGE``. See
:manpage:`pepsi-stage-auto-whitelist(1)`.

State
=====

* **Inputs:** the envelope recipients from the ``rcpt_to`` column, and
  ``state.encrypted`` — set by :doc:`pepsi-stage-encrypt` when the outgoing
  message really was encrypted to a recipient key, and by
  :doc:`pepsi-stage-decrypt` when a message arrived encrypted — which sets the
  stored ``signature_required`` flag, so a correspondent reached under encryption
  is later held to the same standard.
* **Outputs:** none on the message — its ``state`` is untouched; the side effect
  is one ``pepsi.whitelist`` row per recipient.

See also
========

:doc:`pepsi-stage-check-whitelist`, :doc:`pepsi-stage-anti-spam`,
:doc:`pepsi-stage-arc`, :doc:`../features`,
:manpage:`pepsi-stage-auto-whitelist(1)`.