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

*Sender Rewriting Scheme — make SPF pass at the next hop.*

Role
====

``pepsi-stage-srs`` rewrites the envelope sender into a local address of a
Pepsi-controlled ``SRS_DOMAIN`` so the next hop's SPF check passes. The reverse
direction (decoding bounces returned to an SRS address) is done by
:doc:`pepsi-ingress` at ``RCPT`` time. Both read the shared ``[pepsi-srs]``
section. Reference: :manpage:`pepsi-stage-srs(1)`.

Features
========

* **Forward rewrite:** ``MAIL FROM`` becomes ``SRS0=HHHH=TT=domain=local@srs``,
  HMAC-signing the original sender and stamping a day-granular timestamp; the
  truncated MAC is base32-encoded (RFC 4648).
* **Compact re-signing:** an address that is *already* SRS (mail reached Pepsi
  through another forwarder) is re-signed in the ``SRS1`` form rather than nested,
  so a bounce hops back one forwarder at a time.
* **Idempotent / safe:** the null sender (a returning bounce) is never rewritten,
  and a sender already in ``SRS_DOMAIN`` is left unchanged.
* **Reverse decode (in ingress):** a recipient that is a valid SRS token is
  verified (signature + timestamp) and relayed to the decoded original sender,
  even outside served domains; a forged/expired token is rejected ``550``.
* **Body untouched:** only the envelope sender changes; DKIM body hashes survive.
* **Operator tools:** ``forward``/``reverse`` subcommands compute a rewrite or
  decode an address by hand.

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

``[stage-<name>]``: ``PROGRAM = pepsi-stage-srs`` and ``NEXT_STAGE``. The SRS
parameters are shared in ``[pepsi-srs]``: ``SRS_DOMAIN``,
``SECRET``/``SECRET_FILE`` (the HMAC key; must stay stable and identical across
instances), and ``MAX_AGE_DAYS`` (validity window, default 21). Omitting
``[pepsi-srs]`` disables SRS. See :manpage:`pepsi-stage-srs(1)`.

State
=====

* **Inputs:** none (operates on the ``mail_from`` column).
* **Outputs:** none added; the whole ``state``, including ``state.dsn``, is
  preserved.

See also
========

:doc:`pepsi-ingress`, :doc:`pepsi-stage-relay-to-internet`, :doc:`../features`,
:manpage:`pepsi-stage-srs(1)`.