..
  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-autocrypt-learn
===========================

*Learn correspondents' keys from the mail they send us.*

Role
====

``pepsi-stage-autocrypt-learn`` is where an inbound message teaches Pepsi a public
key: the sender's ``Autocrypt:`` header, an attached ``application/pgp-keys``
part, the certificates an S/MIME signature carries, and — for a message that
arrived encrypted — the ``Autocrypt-Gossip:`` fields introducing the *other*
recipients (Autocrypt Level 1 §5.3). It learns and advances; it never drops,
pauses, bounces or rewrites a message, so ``NEXT_STAGE`` is mandatory. Reference:
:manpage:`pepsi-stage-autocrypt-learn(1)`.

Features
========

* **Placement is the feature.** This used to live inside
  :doc:`pepsi-stage-decrypt`, which runs *first* on the inbound path so everything
  downstream sees plaintext — and therefore before any stage has an opinion about
  whether the message is junk. Level 1 §5.3 says peer state *SHOULD* be ignored
  for a message believed to be spam, so the rule was unimplementable there. As a
  stage of its own it goes after the spam checks and before delivery.
* **Honours the spam verdict:** a message with ``state.spam = true`` teaches
  nothing, unless ``LEARN_FROM_SPAM`` says otherwise.
* **Only the sender's own key** from a message's headers and attachments;
  introducing a third party is what gossip is for, and gossip lands on a lower
  rung.
* **Gossip only from ciphertext:** believed only when
  :doc:`pepsi-stage-decrypt` recorded that the message arrived encrypted *and*
  that its arriving header block carried no ``Autocrypt-Gossip:`` field of its
  own. Neither is visible from the committed plaintext, so both are read from
  ``state.crypto.in``.
* **Never a key for an address this host serves:** a peer key for a local address
  is what our own outbound mail to that user would be encrypted with, so a gossip
  field naming one is a key substitution rather than an introduction.
* **Unprivileged:** it writes only *public* key material, so unlike the crypto
  stages it needs no setuid bit and is folded into the multi-call ``pepsi``
  binary.

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

``LEARN_KEYS``, ``LEARN_GOSSIP``, ``LEARN_FROM_SPAM``, the ``LOCAL_DOMAINS``
locality options and a mandatory ``NEXT_STAGE``. See :doc:`../configuration`.

.. code-block:: ini

   [stage-autocrypt-learn]
   PROGRAM = pepsi-stage-autocrypt-learn
   NEXT_STAGE = local

What a learnt key is worth
==========================

Little, deliberately. Harvested keys sit at rank ``inbound`` and gossiped ones at
``gossip`` — the bottom two rungs of the trust ladder. Such a key can never
displace one from discovery or from an operator; a signature checked against one
is reported ``valid-untrusted`` at best, so it never sets
``state.signature_verified``; and a ``peer_key`` row is ignored entirely for an
address this host holds an identity for. Within those two rungs the rule is
**newest wins** on the message's Autocrypt effective date, so a correspondent who
reinstalls their client stops receiving mail encrypted to a key they no longer
hold — protection against a passive adversary, which is all Autocrypt claims.