..
  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-edit-settings
=========================

*Let an account owner change their own settings by e-mail.*

Role
====

``pepsi-stage-edit-settings`` lets the owner of an account change their own
per-address overrides (the ``pepsi.settings`` table; see :doc:`pepsi-settings`) by
sending a control e-mail. The message must be locally originated, carry the exact
subject **SUBJECT** (default ``Pepsi``), and be addressed to
``pepsi@<controlled-domain>``; its body is an INI snippet of the options to set.
Any other message is passed through untouched, so the stage is safe to place
anywhere on the local-submission path. Reference:
:manpage:`pepsi-stage-edit-settings(1)`.

The address whose settings are edited is the envelope **sender**, and the reply
goes back to it — so the operator's submission authentication must bind the
envelope sender.

Features
========

* **INI body, leniently parsed:** ``[stage-<name>]`` sections and
  ``OPTION = value`` lines; greetings, comments and a trailing signature are
  ignored. An empty value (``OPTION =``) **unsets** an override (reverting to the
  INI default); any other value adds or overrides it.
* **Operator allowlist:** only stages named in **EDITABLE_STAGES** may be changed.
* **Validate before adopt:** the combined settings (INI defaults + existing
  overrides + the new INI) are checked by each affected stage's real configuration
  parser (shared with :doc:`pepsi-setup`). On any error nothing is changed and a
  human-readable reply lists the problems.
* **Confirming reply:** on success the merged overrides are stored and a reply
  quotes the full effective option set of every editable stage, in INI syntax.
  Both replies carry ``Subject: Pepsi``, use the null sender, and are injected at
  **RESPONSE_STAGE** so they are DKIM-signed and relayed.

The reply messages are English-only for now; internationalising them is tracked
in the roadmap.

See also
========

:doc:`pepsi-settings`, :doc:`pepsi-dispatch`,
:doc:`pepsi-stage-check-whitelist`, :doc:`pepsi-setup`, :doc:`../architecture`,
:manpage:`pepsi-stage-edit-settings(1)`, :manpage:`pepsi.conf(5)`.