..
  This file is part of PEPSI.
  Copyright (C) 2026 GNUnet e.V.

  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
``<CONTROL_LOCAL_PART>@<controlled-domain>`` (default local part ``pepsi``, the
domains being ``[pepsi-ingress] ACCEPTED_DOMAINS``); 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 top of the operator's configuration
  for the sender (``domain:``/``address:`` overrides included).
* **Own whitelists only:** a ``WHITELIST_NAME`` the sender sets for
  :doc:`pepsi-stage-auto-whitelist` or :doc:`pepsi-stage-secretary` -- the stages
  that write a whitelist on the owner's behalf -- must name one in their own
  ``<login>/...`` namespace, or the one the operator's configuration already
  names for them. A shared list or another user's is refused, since it would let
  the owner fill it with addresses of their choosing. A value already stored in
  the row (the operator may have set it with :doc:`pepsi-settings`) does not
  block edits to other options. This stage is the only way an account owner
  writes ``pepsi.settings``, so the rule is enforced here, and the operator's
  own layers may name any whitelist.
* **All or nothing:** 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.
* **Localised replies:** the framing prose comes from the
  ``edit-settings.<lang>.body`` template under ``[pepsi]`` **TEMPLATE_DIR**,
  chosen from the sender's detected language (``state.language``, as
  :doc:`pepsi-stage-detect-language` recorded it) and falling back to English.
* **Safe by default:** an e-mail may only point a stage's ``PROGRAM`` at a
  ``pepsi-stage-*`` command, and may not touch the options that decide which
  identity a message is signed or sent as (``SIGNING_DOMAIN``). Both restrictions
  are lifted by the operator's ``UNRESTRICTED_UNSAFE_STAGES = YES``, which is
  what its name says it is.

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

``[stage-<name>]``: ``PROGRAM = pepsi-stage-edit-settings``, ``NEXT_STAGE``
*(required — nearly every message is not a control message and is advanced
unchanged)*, ``EDITABLE_STAGES`` *(required, whitespace/comma-separated stage
names)*, ``RESPONSE_STAGE`` *(required, where the reply is injected)*,
``SUBJECT`` (default ``Pepsi``), ``CONTROL_LOCAL_PART`` (default ``pepsi``),
``RESPONSE_FROM`` (the reply's ``From:``; by default
``<CONTROL_LOCAL_PART>@<matched domain>``) and ``UNRESTRICTED_UNSAFE_STAGES``
(default ``no``). ``pepsi-setup`` checks that every ``EDITABLE_STAGES`` entry and
``RESPONSE_STAGE`` name a real stage, and that the ``edit-settings.en.body``
fallback template exists. The stage reads its **own** options from the base
configuration, never from the per-address overrides, so a correspondent cannot
e-mail themselves a wider allowlist. See :manpage:`pepsi-stage-edit-settings(1)`.

State
=====

* **Inputs:** ``state.local_origin`` (a message that is not locally originated is
  never a control message) and ``state.language`` (the reply's language).
* **Outputs:** none — a control message's row is **deleted** once the reply has
  been injected; any other message is advanced with its ``state``, including
  ``state.dsn``, untouched.

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)`.