..
  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-helper-token-refresh
==========================

*Refresh OAuth access tokens for the smarthost relay stage.*

Role
====

A smarthost MTA configured with ``AUTH = oauth`` (see
:doc:`pepsi-stage-relay-to-smarthost`) authenticates with a SASL bearer token the
relay stage reads, fresh per delivery, from a ``TOKEN_FILE``. Those access tokens
are short-lived, so the file must be refreshed out of band.

``pepsi-helper-token-refresh`` does that: for every
``[pepsi-stage-relay-to-smarthost-mta-<name>]`` with ``AUTH = oauth`` it pairs the
MTA's ``TOKEN_FILE``/``USERNAME`` with a secret section
``[pepsi-helper-token-refresh-<name>]`` (the OAuth client credentials, kept in a
separate ``@inline-secret@`` file readable only by this service), requests a fresh
token from the provider's ``TOKEN_ENDPOINT``, and writes it atomically to the
token file. ``GRANT`` selects the RFC 6749 grant: ``refresh_token`` (the default,
e.g. Google; it also requires ``REFRESH_TOKEN``) or ``client_credentials``
(e.g. Microsoft 365 app-only; it requires ``SCOPE``); ``CLIENT_ID`` and
``CLIENT_SECRET`` are required either way. A rotated refresh token is persisted
to the private ``[pepsi-helper-token-refresh] STATE_DIR`` (default
``/var/pepsi/token-refresh``). A target whose secret section has no
``TOKEN_ENDPOINT`` is skipped, on the assumption that its token is provided out
of band.

It is **not** a stage and is deliberately **not** part of ``pepsi.target`` — it
is one implementation of the external refresh contract described in
:doc:`../extending`, and a site may substitute its own. Reference:
:manpage:`pepsi-helper-token-refresh(1)`.

Security
========

The service runs as the dedicated ``pepsi-helper-token-refresh`` account, the
sole reader of the client secrets. It writes token files into a directory that is
SGID the ``pepsi-token`` group (default ``/var/pepsi/tokens``), mode ``0640``; the
relay stage binary is installed SGID ``pepsi-token`` so the dispatcher's ``pepsi``
worker can read them. See :doc:`../extending` for the full contract.

Modes
=====

* **service** (the default) — a long-lived process that refreshes each token
  proactively, ahead of expiry by ``REFRESH_MARGIN`` (default 5 min), retrying a
  failing target with back-off while leaving its previous token in place. Runs until
  ``SIGINT``/``SIGTERM``.
* **--once** — refresh every target a single time and exit (a manual run, a
  systemd timer, or cron); non-zero exit if any target failed.

See also
========

:doc:`pepsi-stage-relay-to-smarthost`, :doc:`pepsi-setup`,
:manpage:`pepsi-helper-token-refresh(1)`, :manpage:`pepsi.conf(5)`.