..
  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-secure-link
=======================

*Hold a message that could not be encrypted, and mail out the link.*

Role
====

``pepsi-stage-secure-link`` is the far end of ``[stage-encrypt] ON_NO_KEY =
secure-link``. When encryption is required and the recipient publishes no usable
key, ``pepsi-stage-encrypt`` routes the message here rather than sending it in
the clear or bouncing it.

The stage takes the message off the wire entirely: it seals it under a freshly
generated PIN, stores only the ciphertext in ``pepsi.secure_message``, injects a
notification mail carrying the link (and, by default, a second mail carrying the
PIN to the *sender*, to be relayed out of band), and then **deletes the queue
row**. Advancing it would transmit the cleartext to the recipient who must not
receive cleartext; the message's continuation is the notification, which takes
the ordinary outbound path from ``[pepsi-secure-link] NOTIFY_STAGE``. Reference:
:manpage:`pepsi-stage-secure-link(1)`.

A message with several keyless recipients produces one stored message **per
recipient**, each with its own token, PIN and ciphertext.

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

The ``[stage-<name>]`` section carries only ``PROGRAM``; everything else is in the
global ``[pepsi-secure-link]`` section, which is deliberately out of reach of the
per-address override layer. See :ref:`secure-link` for the whole feature, and
:manpage:`pepsi.conf(5)` for the options.

Failure
=======

Everything that can fail happens before the queue row is deleted, and a failure
**fails the message** rather than dropping it — a message that reached this stage
is one the operator said must not go out unprotected.