..
  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-reencrypt
=====================

*Seal what the gateway decrypted to the recipient's own key before it is filed.*

Role
====

:doc:`pepsi-stage-decrypt` opens mail encrypted to a user's gateway (MTA) key so
that the stages after it can read the content. ``pepsi-stage-reencrypt`` runs once
they have, immediately before local delivery, and seals the message again — to
the key the user registered for their **own mail client** (a ``custody =
client`` identity, the *MUA key*). The mailbox then holds ciphertext only that
client can open. Reference: :manpage:`pepsi-stage-reencrypt(1)`.

Features
========

* **Only what the gateway opened.** ``state.crypto.in`` must say the message
  arrived encrypted and was decrypted; mail that arrived in plaintext, and mail
  decrypt left unopened for the client, are passed through untouched.
* **One recipient, one key.** A message whose recipients are treated differently
  is split into one row per recipient first; each copy is sealed to that
  recipient's newest active MUA key, OpenPGP or S/MIME.
* **Headers.** The sender's ``Autocrypt:`` header, the transport trace, the
  addressing fields and ``X-Pepsi-Crypto`` stay outside; the content fields and
  ``Autocrypt-Gossip:`` go inside. ``PROTECT_HEADERS`` also hides the subject.
* **No signature** is added: the decrypt stage's verdict is already recorded in
  ``state.crypto.in`` and ``X-Pepsi-Crypto``, and a gateway signature would only
  claim that the gateway sealed the message.
* **A policy for users with no key** (``ON_NO_CLIENT_KEY``): deliver plaintext
  (default) or refuse with a ``5.7.5`` DSN that returns neither body nor subject.
  Settable per recipient through :doc:`pepsi-settings`.
* **Unprivileged:** sealing to a public key needs no private material, so unlike
  the other crypto stages it is folded into the multi-call ``pepsi`` binary and
  runs as the ordinary ``pepsi`` user.

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

A mandatory ``NEXT_STAGE`` (local delivery), ``BOUNCE_STAGE`` (for refusals),
``ON_NO_CLIENT_KEY`` (``plaintext``/``bounce``), ``PROTECT_HEADERS`` (default
*no*), ``ENABLED`` and the locality options ``LOCAL_DOMAINS`` / ``TARGETS`` /
``RECIPIENT_DELIMITER`` / ``REQUIRE_ACCOUNT`` with the decrypt stage's defaults.
The whole message is loaded. See :doc:`../configuration`.

.. code-block:: ini

   [stage-reencrypt]
   PROGRAM = pepsi-stage-reencrypt
   NEXT_STAGE = local
   BOUNCE_STAGE = bounce

Placement
=========

After everything that reads the message or may forward a copy elsewhere —
language detection, the spam gates, :doc:`pepsi-stage-autocrypt-learn`,
aliases, vacation, ``~/.forward`` — and directly in front of
:doc:`pepsi-stage-relay-to-maildir` or :doc:`pepsi-stage-relay-to-lmtp`. The
setup wizard offers it with the cryptography question and places it there;
``pepsi-setup`` warns about any other order.