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

*ARC verification, signing and sealing — the entry stage on the inbound path.*

Role
====

``pepsi-stage-arc`` implements ARC (RFC 8617). It verifies any existing inbound
ARC chain and, when an ``ARC_DOMAIN`` and its keys are configured, seals the
message as our ADMD so the boundary authentication verdict survives Pepsi's
forwarding hop. Because it applies only to mail we **receive and forward**, it
must never touch our own submissions (``state.local_origin``) — those are signed
as the author domain by :doc:`pepsi-stage-dkim-sign` instead, and the stage
**skips** any such message. On a host that both receives and submits, place it on
the **inbound branch only**, after the ``state.local_origin`` split (ahead of
SRS); on a receive-only host it is the ``[stage-init]`` stage.
Reference: :manpage:`pepsi-stage-arc(1)`.

Features
========

* **ARC verification** of any inbound chain; the verdict is recorded under
  ``state.auth.arc``.
* **ARC sealing:** prepends a fresh ARC set —
  ``ARC-Authentication-Results`` (AAR), ``ARC-Message-Signature`` (AMS) and
  ``ARC-Seal`` (AS) — as the ``ARC_DOMAIN`` identity, signed with the **single**
  ``ARC_ALGORITHM`` (``rsa`` or ``ed25519``; ARC permits one signature per hop).
* **Faithful AAR:** re-runs SPF/DKIM/DMARC/ARC verification so the AAR mirrors the
  receiver's full assessment and the chain-validation (``cv=``) value is correct
  (it cannot be reconstructed from stored header text).
* **Prepend-only:** the seal is added at the top, so existing lower signatures and
  the ingress ``Received:`` header are undisturbed; only the ``headers`` column is
  rewritten, never the body.
* **Fail-open:** if the origin context, ``[pepsi]`` config or keys are missing, or
  sealing errors, the message is advanced **unsealed** with a warning (the verdict
  is still recorded when computable).

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

``[stage-<name>]``: ``PROGRAM = pepsi-stage-arc``, ``NEXT_STAGE`` *(required)*,
and DNS settings ``DNS_SERVERS`` / ``DNS_TIMEOUT``. The signing identity, keys and
algorithm come from the shared ``[pepsi]`` section (``ARC_DOMAIN``,
``ARC_ALGORITHM``, ``KEY_DIR``, ``DKIM_SELECTOR``). See :manpage:`pepsi-stage-arc(1)`.

State
=====

* **Inputs:** ``state.local_origin`` — when true the message is advanced untouched
  (no ARC on mail we originate); otherwise ``state.origin`` — the ``authserv_id``
  (required to reproduce the AAR identity; without it the stage advances unsealed),
  and ``remote_ip`` / ``helo`` for the re-run verification context.
* **Outputs:** overwrites ``state.auth.arc`` with the re-evaluated chain verdict
  (the rest of ``state``, including ``state.auth`` siblings and ``state.dsn``, is
  preserved).

See also
========

:doc:`pepsi-ingress`, :doc:`pepsi-stage-dkim-sign`, :doc:`../features`,
:manpage:`pepsi-stage-arc(1)`.