taler-docs

paivana-httpd-manual.rst (52618B)

---

 ..
   This file is part of GNU TALER.
 
   Copyright (C) 2026 Taler Systems SA
 
   TALER 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.0, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
 
 .. _Paivana-httpd:
 
 Paivana-httpd
 =============
 
 This chapter documents the installation and operation of the Paivana
 reverse proxy ``paivana-httpd``.  The reverse proxy sits between the
 public Internet and an upstream Web service, intercepting requests
 that have not yet been paid for and presenting the client with a
 GNU Taler paywall.  Once a payment has been confirmed by the
 configured GNU Taler merchant backend, ``paivana-httpd`` forwards
 subsequent requests of that client to the upstream service.
 
 The full list of command-line options is documented in
 :manpage:`paivana-httpd(1)`; the configuration file is
 documented in :manpage:`paivana.conf(5)`.
 
 
 .. _Paivana-Motivation:
 
 Motivation and use cases
 ------------------------
 
 ``paivana-httpd`` answers a single question for every incoming
 request — *"has the client paid for this?"* — but operators deploy it
 for two rather different reasons.  Which one applies to you mostly
 changes how you *price* the templates (see :ref:`Paivana-Templates`),
 not how you install or run the daemon.
 
 Selling access: a paywall with revenue
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The classic use case is to charge money for access to digital content
 or services: a news article, a research dataset, an API call, a file
 download.  Because Paivana builds on GNU Taler, this comes with
 properties that distinguish it from traditional paywalls:
 
 - **No accounts, no sign-up.**  A visitor pays directly from a Taler
   wallet; there is no registration, no login, and no credit-card form.
   This removes the friction that kills conversion on per-article
   purchases.
 - **Micropayments are practical.**  Taler's costs per transaction are
   low enough that charging fractions of a cent for a single page is
   economically meaningful, enabling true pay-per-article or
   pay-per-request business models.
 - **Privacy for the buyer.**  Taler is privacy-preserving by design:
   the seller (and Paivana) learns that *an* order was paid, not *who*
   paid it.  No tracking profile is required to gate the content.
 - **Subscriptions and discounts.**  A template's ``choices`` can offer
   a one-off payment *or* the purchase/redemption of a subscription
   token, so returning subscribers pass the paywall automatically
   (see :ref:`Paivana-Templates`).
 - **Agentic payments.**  Every paywall response also carries a
   machine-readable ``Paivana:`` HTTP header (see
   :ref:`Paivana-Customizing`).  An automated client — for example an
   AI agent provisioned with a Taler wallet — can therefore pay and
   fetch the resource without rendering the HTML page, while the
   operator caps financial exposure to whatever was loaded into that
   agent's wallet.
 
 Rate-limiting bots and abuse: DDoS and scraper protection
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The second use case treats the payment not as a source of revenue but
 as a *cost imposed on the client* — economic rate limiting.  Here you
 set the price very low (a fraction of a cent, effectively a "CAPTCHA
 token"): negligible for a human visitor reading a handful of pages,
 but ruinous for a botnet or scraper that wants to issue millions of
 requests.  An attacker sending a million requests must spend a million
 micropayments; a legitimate user spends almost nothing.
 
 This is a deliberate alternative to two older defenses whose
 cost-asymmetry has eroded:
 
 - **Proof-of-work puzzles** (as used by tools such as Anubis) ask the
   client to burn CPU before being served.  But CPU is cheap and
   abundant for a well-resourced attacker or botnet, and the puzzle
   burdens low-powered legitimate devices (phones, assistive tech) the
   most.
 - **CAPTCHAs** ask the client to solve a perception task.  Modern
   LLMs and automated solvers now clear text, image and even
   "behavioral" CAPTCHAs cheaply and at scale, so they increasingly
   inconvenience humans while barely slowing down the bots they were
   meant to stop.
 
 A Taler payment sidesteps both problems: it does not rely on a human
 being slow, or on a machine being computationally weak.  It relies on
 the one resource a flooding attacker genuinely cannot conjure for free
 — money.  Bots *can* solve puzzles and CAPTCHAs; they cannot mint
 funds.  For this use case you typically combine a low per-request
 price with a subscription-token ``choice`` so that a paying or
 authenticated user buys a token once and then sails through, while
 anonymous floods keep paying per request.
 
 .. note::
 
    The two use cases are not mutually exclusive: the same deployment
    can earn revenue on premium URLs and simultaneously throttle abuse
    on cheap ones, simply by defining several templates with different
    prices and ``website_regex`` scopes.
 
 
 Architecture overview
 ---------------------
 
 ``paivana-httpd`` does not implement any payment logic of its own.
 Instead, every Paivana deployment combines three components:
 
 1. **The upstream web service.**  This is the existing HTTP service
    whose content should be sold (a static website, a cgit service,
    a REST API, …).  It does not need to be modified to
    work with Paivana.
 2. **A GNU Taler merchant backend** (``taler-merchant-httpd``).  The
    merchant backend manages templates, creates orders, talks to one
    or more Taler exchanges, and ultimately reports back whether a
    given order has been paid.  See the
    :ref:`Taler Merchant Backend Operator Manual
    <taler-merchant-backend-operator-manual>` for full details.
 3. **``paivana-httpd`` itself.**  This is the reverse proxy that
    gates the upstream service.  It reads a single
    :ref:`paivana.conf <Paivana-Configuration>` configuration file
    that points at both the merchant backend and the upstream
    service.
 
 Typically a TLS-terminating reverse proxy (Nginx or Apache) is
 deployed in front of ``paivana-httpd`` to handle HTTPS and to route
 multiple virtual hosts; see :ref:`Paivana-ReverseProxy` below.
 
 In normal operation the request flow is:
 
 ::
 
    client ──▶ Nginx/Apache (TLS) ──▶ paivana-httpd ──▶ upstream
                                           │
                                           ▼
                                   taler-merchant-httpd
                                           │
                                           ▼
                                     Taler exchange
 
 
 Installation
 ------------
 
 Installing from source
 ^^^^^^^^^^^^^^^^^^^^^^
 
 The package sources can be found in our
 `download directory <http://ftpmirror.gnu.org/taler/>`__.
 
 GNU Taler components follow the ``MAJOR.MINOR.MICRO`` version
 scheme.  The general rule for compatibility is that ``MAJOR`` and
 ``MINOR`` must match across components; exceptions are noted in the
 release notes.  For example, ``paivana-httpd`` 1.6.x is expected to
 work with ``taler-merchant-httpd`` 1.6.x.  A ``MAJOR`` version of 0
 indicates experimental development; in that case you should always
 run the *latest* releases of every component together.
 
 The following packages must be installed before compiling
 ``paivana-httpd``:
 
 - GNUnet (``libgnunetutil``) matching the Taler release
 - GNU Taler exchange libraries (``libtalerexchange``,
   ``libtalerutil``)
 - GNU Taler merchant client library (``libtalermerchant``)
 - GNU Taler HTTP daemon helpers (``libtalermhd``,
   ``libtalertemplating``)
 - libmicrohttpd, libcurl, libjansson, libgcrypt, zlib
 
 Build and install with:
 
 .. code-block:: shell-session
 
    $ ./bootstrap
    $ ./configure --prefix=$PREFIX
    $ make
    $ sudo make install
 
 
 Installing the binary packages on Debian
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: frags/installing-debian.rst
 
 To install ``paivana-httpd`` you can now simply run:
 
 .. code-block:: shell-session
 
    # apt install paivana-httpd
 
 The package does not perform any deployment-specific configuration
 work; it only sets up the ``paivana-httpd`` system user, the systemd
 service and socket units, and installs example configuration
 snippets for Nginx and Apache under ``/etc/nginx/sites-available/``
 and ``/etc/apache2/sites-available/``.  You still must configure the
 HTTP request routing and the Paivana templates as described below.
 
 
 Installing the binary packages on Ubuntu
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: frags/installing-ubuntu.rst
 
 To install ``paivana-httpd``, run:
 
 .. code-block:: shell-session
 
    # apt install paivana-httpd
 
 As on Debian, the package does not perform any deployment-specific
 configuration work.
 
 
 .. _Paivana-Configuration:
 
 Configuring paivana-httpd
 -------------------------
 
 The main configuration file is ``/etc/paivana/paivana.conf``.  Its
 syntax follows the standard GNUnet configuration file format and is
 documented in full in :manpage:`paivana.conf(5)`.  Files under
 ``$PREFIX/share/paivana/config.d/`` are read first and overridden by
 it, but Paivana installs none: every option is either required or has
 the default stated with it in :manpage:`paivana.conf(5)`.
 
 All Paivana-specific keys live in the ``[paivana]`` section.  At a
 minimum, the file must specify three things:
 
 - where ``paivana-httpd`` should listen for incoming requests
   (``SERVE``, ``UNIXPATH`` / ``PORT``);
 - where it should forward paid requests to
   (``DESTINATION_BASE_URL``);
 - how it should reach the merchant backend
   (``MERCHANT_BACKEND_URL`` and ``MERCHANT_ACCESS_TOKEN``).
 
 A typical configuration that listens on a UNIX domain socket
 managed by systemd and forwards to a local upstream server looks
 like this:
 
 .. code-block:: ini
 
    [paivana]
    # Listen on the socket provided by paivana-httpd.socket.
    SERVE = unix
    UNIXPATH = /run/paivana/httpd/paivana-http.sock
    UNIXPATH_MODE = 660
 
    # Public base URL of this paywall as seen by clients.
    # Used when the Host/X-Forwarded-Host headers are unavailable.
    BASE_URL = https://paywall.example.com/
 
    # Upstream service that gets proxied after payment.
    DESTINATION_BASE_URL = http://127.0.0.1:8080/
 
    # Merchant backend used to create and verify orders.
    MERCHANT_BACKEND_URL = http://localhost:9966/
    MERCHANT_ACCESS_TOKEN = secret-token:CHANGE-ME
 
    # Stable key material used to MAC the access cookie.  Must be
    # generated from a random source, not invented; see below.  If
    # unset, a random value is generated at every startup,
    # invalidating all previously issued cookies.
    SECRET = REPLACE-ME-WITH-GENERATED-RANDOMNESS
 
    # Resources that should never trigger the paywall, e.g.
    # logos, stylesheets or favicons.
    WHITELIST = ^/(favicon\.ico|assets/.*|robots\.txt)$
 
 The exhaustive list of supported keys (``SERVE``, ``PORT``,
 ``BIND_TO``, ``UNIXPATH``, ``UNIXPATH_MODE``, ``CONNECTION_LIMIT``,
 ``PER_IP_CONNECTION_LIMIT``, ``MAX_REQUEST_SIZE``,
 ``REQUEST_BUFFER_MAX``, ``RESPONSE_BUFFER_MAX``, ``UPSTREAM_TIMEOUT``,
 ``UPSTREAM_STALL_TIMEOUT``, ``BASE_URL``,
 ``DESTINATION_BASE_URL``, ``DESTINATION_UNIXPATH``,
 ``MERCHANT_BACKEND_URL``, ``MERCHANT_BACKEND_UNIX_PATH``, ``MERCHANT_ACCESS_TOKEN``,
 ``SECRET``, ``WHITELIST``, ``TRUSTED_PROXIES``,
 ``TRUSTED_PROXIES6``) is documented in :manpage:`paivana.conf(5)`.
 
 If you reach the merchant backend over a UNIX domain socket on the
 same host (recommended for a single-machine deployment), replace
 the ``MERCHANT_BACKEND_URL`` block with:
 
 .. code-block:: ini
 
    MERCHANT_BACKEND_URL = http://localhost/
    MERCHANT_BACKEND_UNIX_PATH = /run/taler-merchant/merchant.sock
 
 .. note::
 
    ``MERCHANT_ACCESS_TOKEN`` and ``SECRET`` are sensitive values.
    Make sure ``paivana.conf`` is only readable by the
    ``paivana-httpd`` user.  The Debian package installs the file
    accordingly.
 
 When ``paivana-httpd`` runs behind a trusted reverse proxy
 (Nginx/Apache), pass ``-f`` / ``--respect-forwarded-headers`` in the
 systemd unit's ``ExecStart=`` so the real client address is taken from
 the ``Forwarded`` and ``X-Forwarded-For`` headers.  ``-f`` is a
 statement that the server in front writes those headers itself, so
 configure that server accordingly before you pass it; set
 ``TRUSTED_PROXIES`` / ``TRUSTED_PROXIES6`` as well if there is more
 than one proxy in the path.  :ref:`Paivana-ReverseProxy` has the
 details and working configurations.  See :manpage:`paivana-httpd(1)` for the
 remaining command-line flags (in particular ``-g`` to require only
 a single payment per site and ``-n`` to disable the paywall for
 debugging).
 
 
 Body sizes, buffering and upstream timeouts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``paivana-httpd`` relays bodies as they arrive rather than assembling
 them first.  A request or response of any size therefore passes
 through, and the client starts receiving the response while the
 upstream is still producing it — neither of which was true when each
 body had to fit in memory, where anything over 40 MiB failed outright
 and nothing reached the client until everything had.
 
 Two consequences are worth knowing before tuning anything.
 
 **Memory is bounded by the buffers, not by the content.**  An
 in-flight request can hold at most ``REQUEST_BUFFER_MAX`` plus
 ``RESPONSE_BUFFER_MAX`` (256 KiB each by default), so the ceiling for
 the process is that sum times ``CONNECTION_LIMIT`` — about 256 MiB at
 the shipped defaults.  That is a ceiling and not a typical cost: the
 buffers are allocated on demand and grown only as far as a request
 actually needs, so a page that arrives in one read never occupies more
 than that read.  Raise the buffers only to trade memory for throughput
 on fast links, and lower ``CONNECTION_LIMIT`` if you raise them a
 lot.  When the client cannot keep up, Paivana stops reading
 from the upstream; when the upstream cannot keep up, Paivana stops
 reading from the client.  Neither ever accumulates.
 
 **A response can now fail after its status has been sent.**  Once the
 upstream's headers have gone out they cannot be retracted, so an
 upstream that dies mid-body can no longer be reported as ``502``.
 Paivana signals it by breaking the framing instead: a declared
 ``Content-Length`` is left unmet, or a chunked response is closed
 without its terminating chunk.  Both are failures a conforming client
 must detect (RFC 9112, section 8.1.2) — ``curl`` reports exit code
 18, for instance — and the event is logged at ``WARNING`` naming the
 URL and the byte count reached.
 
 .. note::
 
    There is one case where it cannot be signalled at all: an HTTP/1.0
    client receiving a response whose length the upstream never
    declared.  There the close of the connection *is* the framing, so a
    truncated body is indistinguishable from a complete one.  Nothing
    at this layer can fix that; it is a property of HTTP/1.0.  It does
    not arise for HTTP/1.1 clients, which get chunked framing, nor for
    any client when the upstream declares a length.
 
 The two upstream timeouts bound different things and neither bounds
 the request as a whole:
 
 - ``UPSTREAM_TIMEOUT`` (60 s) is the time to the response *headers*.
   Expiry here yields ``504``, and this is the only one that can still
   produce a status code.
 - ``UPSTREAM_STALL_TIMEOUT`` (60 s) is how long the upstream may move
   no bytes in either direction.  Expiry here truncates the response as
   described above, if it had started, and yields ``504`` if it had
   not.  The clock does not run while Paivana is holding the upstream
   back because the client has not caught up, so a slow client is never
   mistaken for a stalled upstream.
 
 Raise ``UPSTREAM_STALL_TIMEOUT`` if your upstream legitimately pauses
 for long stretches mid-response — a report generator that computes for
 minutes between writes, say.  Do not raise it to accommodate slow
 *clients*; that is already handled.
 
 
 Starting and stopping the service
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The Debian/Ubuntu package ships a socket-activated systemd unit.
 After editing ``/etc/paivana/paivana.conf`` enable and start it:
 
 .. code-block:: shell-session
 
    # systemctl enable --now paivana-httpd.socket
    # systemctl status paivana-httpd
 
 The socket listens on ``/run/paivana/httpd/paivana-http.sock`` with
 group ``www-data``, which lets a co-located Nginx or Apache talk to
 the daemon without granting it broader filesystem access.  Logs are
 sent to the journal:
 
 .. code-block:: shell-session
 
    # journalctl -u paivana-httpd -f
 
 
 .. _Paivana-Whitelisting:
 
 Whitelisting unpaid resources
 -----------------------------
 
 Most sites contain resources that must remain freely accessible even
 to clients that have not paid: the stylesheets, fonts, logos and
 scripts referenced by the paywall page itself, a ``favicon.ico``, a
 ``robots.txt``, or a health-check endpoint polled by a load balancer.
 If these were paywalled, the paywall page could not even render.
 
 The ``WHITELIST`` configuration key holds a single POSIX *extended*
 regular expression that is matched against the request path (which
 always begins with ``/``).  When it matches, the request bypasses both
 the paywall and the access-cookie check and is proxied straight to the
 upstream:
 
 .. code-block:: ini
 
    [paivana]
    WHITELIST = ^/(favicon\.ico|robots\.txt|assets/.*|.*\.css|.*\.js)$
 
 A few details worth knowing:
 
 - The expression is matched against the URL path only, not against the
   host or the request method.
 - The expression must match the path in its **entirety**.
   ``paivana-httpd`` anchors it for you — it compiles ``^(`` *your
   expression* ``)$``, so writing your own ``^`` and ``$`` is harmless
   but redundant.  What this rules out is a substring match:
   ``/assets/`` on its own whitelists nothing, because no path is
   exactly that; ``/assets/.*`` is what whitelists that subtree.  The
   enclosing group matters for alternations: ``a|b`` behaves as
   "exactly ``a`` or exactly ``b``", not as "starts with ``a`` or ends
   with ``b``".
 - Anchoring is a safety property, not a convenience.  An unanchored
   whitelist grants free access to every path merely *containing* the
   expression, which a client can arrange deliberately: with a
   substring rule, a request for ``/premium/article?x=/robots.txt``
   would sail past the paywall.
 - Paths longer than 16384 bytes are rejected outright with HTTP ``414
   URI Too Long``, before any expression is evaluated.  The cap bounds the
   cost of a pathological expression on a path an unpaying client
   controls; no legitimate URL comes close to it.
 - An invalid regular expression is a fatal configuration error:
   ``paivana-httpd`` logs the problem and refuses to start.
 - The internal endpoints ``POST /.well-known/paivana`` (payment
   callback) and ``GET /.well-known/paivana/templates/...`` (paywall
   pages) are always handled by ``paivana-httpd`` itself and are not
   affected by the whitelist.
 - Running with ``-n`` / ``--no-payment`` whitelists *everything*; the
   daemon then behaves as a transparent reverse proxy and never
   consults the merchant backend.
 
 .. note::
 
    Whitelisting is coarse — it is keyed purely on the URL.  Per-URL
    *pricing* (charging different amounts for different paths) is done
    with merchant templates and their ``website_regex``, described in
    :ref:`Paivana-Templates`, not with ``WHITELIST``.
 
 
 .. _Paivana-AccessControl:
 
 Access control: per-page vs. site-wide payment
 ----------------------------------------------
 
 Once a client has paid, ``paivana-httpd`` issues a cryptographically
 protected access cookie (``Paivana-Cookie``) instead of asking the
 merchant backend again on every subsequent request.  The cookie is a keyed hash
 over *(expiration time, website, client address)*; it carries no
 server-side state, so any of the (possibly several) ``paivana-httpd``
 processes can validate it.
 
 Two aspects of this are operator-visible:
 
 Scope of a payment
 ^^^^^^^^^^^^^^^^^^^
 
 By default a payment grants access to **the specific URL that was
 paid for**: the cookie's ``Path`` is set to that path and the website
 is bound into the hash.  This is what you want when each page is sold
 individually.
 
 Passing ``-g`` / ``--global-payment`` changes this so that a single
 payment unlocks the **entire site**: the website component is dropped
 from the hash and the cookie is issued with ``Path=/``.  Use this when
 one purchase (or one subscription) should cover everything behind the
 proxy, including for the abuse-mitigation use case where you simply
 want a paying client to stop hitting the paywall.
 
 Binding to the client address
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The cookie is tied to the client's network address so that it cannot
 simply be copied to another machine.  When ``paivana-httpd`` runs
 behind a TLS-terminating reverse proxy, the socket peer is always that
 proxy, so **every** client would appear to share one address.  Run the
 daemon with ``-f`` / ``--respect-forwarded-headers`` in that setup so
 the real client address is taken from the ``Forwarded`` and
 ``X-Forwarded-For`` headers instead.  Only do this behind a proxy that
 writes *both* of those headers itself; a header it merely passes
 through is the client's own, and then the client chooses the address
 its cookie is bound to.  :ref:`Paivana-ReverseProxy` has the
 configurations that get this right.
 
 Cookie lifetime is derived from the order's ``max_pickup_delay``;
 configure it on the template (``max_pickup_duration``) to control how
 long a paid client may keep accessing the resource before paying
 again.  Because the cookie is keyed by ``SECRET``, leaving ``SECRET``
 unset means a new random key is chosen at every startup and all
 outstanding cookies are invalidated on restart.
 
 ``SECRET`` is hashed once to derive that key — no salt, no stretching
 — so its own entropy is the only thing protecting it.  An attacker who
 has seen a single ``Paivana-Cookie`` can test candidate secrets
 offline as fast as it can compute SHA-512, which on ordinary hardware
 is billions of guesses per second.  Give ``SECRET`` **at least 128
 bits of entropy from a random source**; do not invent a passphrase,
 and do not ship the placeholder from the sample configuration above.
 Generate one with:
 
 .. code-block:: shell-session
 
    # head -c 32 /dev/urandom | base64
 
 Whoever recovers a weak ``SECRET`` can mint access cookies for any URL
 and any client address, and you will not see it happen: the forged
 cookies never touch the merchant backend, so nothing distinguishes
 them in your logs from paid traffic.
 
 
 .. _Paivana-Redemption:
 
 Redeeming a payment
 -------------------
 
 The cookie above is handed out at the end of one round-trip that is
 worth understanding, because it is the only point at which
 ``paivana-httpd`` talks to the merchant backend on behalf of a client,
 and because its failure modes are what you will see in the logs.
 
 When the paywall page has been told by the merchant backend that its
 order was paid, it POSTs the order ID (together with the ``nonce``,
 ``expiration`` and ``website`` it used to construct the payment) to
 ``/.well-known/paivana``.  ``paivana-httpd`` re-derives the session ID
 from those values and asks its backend whether that order was really
 paid under it, over its own authenticated connection.  Nothing the
 client says is taken on trust: the order must be paid and not refunded,
 its fulfillment URL must be the ``website`` being claimed (or, where the
 order has none, that ``website`` must lie under the configured
 ``BASE_URL``), and the requested expiration must not exceed the order's
 ``max_pickup_time``.  Only then is the cookie issued.
 
 This query is a **long poll bounded at five seconds**, and both parts
 are deliberate.  A client can be a moment ahead of the backend — it may
 even be talking to a different backend process than ``paivana-httpd``
 is — so waiting briefly admits an honest client that would otherwise be
 turned away just after paying.  Conversely, the endpoint is
 unauthenticated and can be posted to before any payment exists, so that
 wait is also the time an attacker can pin a connection for, which is
 why it is short rather than generous.  The same bound applies to the
 outgoing request itself, so a merchant backend that stops responding
 cannot hold connections open either.
 
 The status returned to the client tells you which of these happened:
 
 ========  ==============================================================
 Status    Meaning
 ========  ==============================================================
 303       Payment confirmed; the ``Paivana-Cookie`` is set and the
           client is redirected to the content.
 409       The backend says the order was not paid, or it was refunded,
           or its contract does not cover the claimed website.  This is
           the client's problem, not yours — a stale replay, or a page
           that gave up too early.
 410       The client asked for access past the order's
           ``max_pickup_time``.  Raise ``max_pickup_duration`` on the
           template if legitimate clients hit this.
 404       The backend does not know this order at all.
 504       The backend did not answer within the bound, or could not be
           reached.  Check that ``MERCHANT_BACKEND_URL`` is reachable
           and that the backend is not itself stalled; the log line
           naming the backend and order ID is emitted at ``WARNING``.
 502       The backend answered, but with something ``paivana-httpd``
           could not use.  This normally means a version mismatch
           between the two and is worth reporting.
 500       The backend rejected our credentials.  Check
           ``MERCHANT_ACCESS_TOKEN``; no client can fix this.
 ========  ==============================================================
 
 A burst of 504s or 500s is therefore an infrastructure problem and a
 burst of 409s is not, which is the distinction to key any alerting on.
 
 
 .. _Paivana-Templates:
 
 Configuring Paivana templates
 -----------------------------
 
 ``paivana-httpd`` does not store any per-site pricing or URL-matching rules
 itself.  Instead, all rules are expressed as :ref:`merchant templates
 <template>` of type ``paivana`` in the merchant backend.  When
 ``paivana-httpd`` starts up it asks the merchant backend for every template
 configured for the instance identified by ``MERCHANT_BACKEND_URL`` and uses
 the ``website_regex`` field of each template to decide which template (and
 therefore which payment options) applies to an incoming request URL.
 
 The corresponding REST API is documented in detail in the
 :ref:`Merchant Backend HTTP API <merchant-api>`; see in particular
 the
 `POST /private/templates
 <https://docs.taler.net/core/api-merchant.html#post--private-templates>`__
 endpoint and the
 :ts:type:`TemplateContractPaivana` definition.
 
 Prerequisites
 ^^^^^^^^^^^^^
 
 Before creating a template you need:
 
 - a running ``taler-merchant-httpd`` (see the
   :ref:`Launching-the-backend` section of the merchant manual);
 - a merchant :ref:`instance <Instance-setup>` with at least one
   configured :ref:`bank account <instance-bank-account>`;
 - the access token of that instance (used as
   ``MERCHANT_ACCESS_TOKEN`` in ``paivana.conf``).
 
 In the examples below we assume the merchant backend is reachable
 at ``http://localhost:9966/``, the default instance is ``default``,
 its access token is ``secret-token:sandbox`` and the currency is
 ``KUDOS``.  Adjust the URLs, tokens and amounts to match your
 deployment.  The
 `src/backend/test.sh
 <https://git.taler.net/paivana.git/tree/src/backend/test.sh>`__
 script that ships with Paivana sets up exactly this minimal
 configuration and is a good starting point for experimentation.
 
 Creating a single global template
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The simplest Paivana setup uses one template that matches every
 URL on the site and charges a fixed price.  This is the
 configuration created by ``src/backend/test.sh``:
 
 .. code-block:: bash
 
    $ curl -X POST http://localhost:9966/private/templates \
        -H 'Authorization: Bearer secret-token:sandbox' \
        -H 'Content-Type: application/json' \
        -d '{
              "template_id": "paivana",
              "template_description": "A Paivana template",
              "template_contract": {
                "template_type": "paivana",
                "summary": "Access to example.com",
                "website_regex": ".*",
                "choices": [ { "amount": "KUDOS:1" } ]
              }
            }'
 
 The ``template_type`` must be ``"paivana"``: this allows
 ``paivana-httpd`` to pick the template up at startup and
 also enables some required logic in the merchant backend.  The
 ``website_regex`` is a POSIX extended regular expression that is
 matched against the request URL; ``.*`` covers everything.  Each
 entry in ``choices`` describes one way the client may pay and is an
 :ts:type:`OrderChoice` object (so the paywall can also support
 the use of subscription tokens, discount coupons, etc.).  The
 contract as a whole is the :ts:type:`TemplateContractPaivana` object
 of the :ref:`merchant backend API <merchant-api>`, which stores
 ``website_regex`` but leaves its interpretation to ``paivana-httpd``
 — that is, to the rules below.
 
 Two properties of the matching are easy to get wrong, and both make
 the difference between a template that applies and one that silently
 never does:
 
 - The subject is the **absolute URL**, not the path.  It is the
   configured ``BASE_URL`` (or the scheme and ``Host`` of the request,
   when ``BASE_URL`` is not set) followed by the path — for example
   ``https://example.com/premium/article``.  An expression written
   against the path alone, such as ``/premium/.*``, therefore matches
   nothing.
 - The expression must match that URL in its **entirety**.
   ``paivana-httpd`` anchors it for you, compiling ``^(`` *your
   expression* ``)$``, so a substring rule does not apply to the URLs
   containing it.  Writing your own ``^`` and ``$`` remains harmless.
   The enclosing group means an alternation such as ``a|b`` is read as
   "exactly ``a`` or exactly ``b``".
 
 So a template meant for one subtree is written either against the
 whole URL, ``https://example\.com/premium/.*``, or with a leading
 wildcard, ``.*/premium/.*``, if the same template should apply
 regardless of the host the site is served under.
 
 A URL longer than 16384 bytes is answered with HTTP ``414 URI Too Long``
 and no template is evaluated for it.  The cap bounds the cost of a
 pathological expression on a URL an unpaying client controls.
 
 A successful create returns HTTP ``204 No Content``.  After
 creating the template, (re)start ``paivana-httpd`` so that it
 re-reads the template list:
 
 .. code-block:: shell-session
 
    # systemctl restart paivana-httpd
 
 Multiple templates with URL-specific pricing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When a single site contains content with different prices, define one template
 per price bucket and use ``website_regex`` to scope each template to the
 matching URLs.  When several templates match the same URL ``paivana-httpd``
 picks the first one if finds that matches. Be careful: if multiple templates
 match a URL, the result is non-deterministic!
 
 For example, a news site might charge 2 KUDOS for premium articles
 and 50 cents (``KUDOS:0.5``) for standard articles:
 
 .. code-block:: bash
 
    $ curl -X POST http://localhost:9966/private/templates \
        -H 'Authorization: Bearer secret-token:sandbox' \
        -H 'Content-Type: application/json' \
        -d '{
              "template_id": "premium",
              "template_description": "Premium long-form articles",
              "template_contract": {
                "template_type": "paivana",
                "summary": "Premium article on example.com",
                "website_regex": ".*/premium/.*",
                "choices": [ { "amount": "KUDOS:2" } ]
              }
            }'
 
    $ curl -X POST http://localhost:9966/private/templates \
        -H 'Authorization: Bearer secret-token:sandbox' \
        -H 'Content-Type: application/json' \
        -d '{
              "template_id": "default",
              "template_description": "Standard articles",
              "template_contract": {
                "template_type": "paivana",
                "summary": "Standard article on example.com",
                "website_regex": ".*/standard/.*",
                "choices": [ { "amount": "KUDOS:0.5" } ]
              }
            }'
 
 Offering multiple payment options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``choices`` array lets a single template offer several mutually exclusive
 ways to pay.  A common pattern is to accept either a cash payment or to sell a
 subscription; the wallet shows both options and the customer picks one.  The
 third option, where the customer already has a subscription, will be used
 automatically by the wallet for subscribers and the customer will not even
 have to click to bypass the paywall as a subscriber.  See the merchant manual
 for the details of :ref:`OrderChoice <template-choice>` objects.
 
 .. code-block:: bash
 
    $ curl -X POST http://localhost:9966/private/templates \
        -H 'Authorization: Bearer secret-token:sandbox' \
        -H 'Content-Type: application/json' \
        -d '{
              "template_id": "article",
              "template_description": "Single article, paid or via subscription",
              "template_contract": {
                "template_type": "paivana",
                "summary": "Article on example.com",
                "website_regex": ".*",
                "choices": [
                  { "amount": "KUDOS:1",
                    "description": "Pay per article" },
                  { "amount": "KUDOS:100",
                    "description": "Buy subscription",
                    "outputs": [ { "token": "monthly-subscription" } ] },
                  { "amount": "KUDOS:0",
                    "description": "Use my subscription",
                    "inputs": [ { "token": "monthly-subscription" } ],
                    "outputs": [ { "token": "monthly-subscription" } ] }
                ]
              }
            }'
 
 Managing templates
 ^^^^^^^^^^^^^^^^^^
 
 Templates can be listed, updated and deleted through the merchant
 backend's REST API or through the merchant backend SPA at
 ``$MERCHANT_BACKEND_URL/``.  See the merchant manual section on
 :ref:`templates <template>` for details, and the API reference for
 the relevant endpoints:
 
 - `GET /private/templates
   <https://docs.taler.net/core/api-merchant.html#get--private-templates>`__ —
   list all templates of the instance;
 - `PATCH /private/templates/$TEMPLATE_ID
   <https://docs.taler.net/core/api-merchant.html#patch--private-templates-$TEMPLATE_ID>`__ —
   update a template;
 - `DELETE /private/templates/$TEMPLATE_ID
   <https://docs.taler.net/core/api-merchant.html#delete--private-templates-$TEMPLATE_ID>`__ —
   remove a template.
 
 After any change, restart ``paivana-httpd`` so the new template
 list takes effect.
 
 
 .. _Paivana-Customizing:
 
 Customizing the paywall page
 ----------------------------
 
 The merchant templates of the previous section decide *which* URLs
 cost *how much*.  This section is about the *look* of the page an
 unpaid visitor sees — the HTML the daemon returns with the
 ``402 Payment Required`` status.
 
 How the page is rendered
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The paywall body is produced from a `Mustache
 <https://mustache.github.io/>`__ template named ``paywall`` that
 ``paivana-httpd`` loads, via ``libtalertemplating``, from
 
 ::
 
    $PREFIX/share/paivana/templates/
 
 Templates are language-specific: the file is named
 ``paywall.$LANG.must`` and the daemon picks a variant based on the
 client's ``Accept-Language`` header.  The package ships an English
 default, ``paywall.en.must``.  To offer the paywall in additional
 languages, drop further ``paywall.<lang>.must`` files into the same
 directory.  Rendered responses are cached per language and per
 content-encoding (and carry ``Cache-Control: public`` and a matching
 ``Vary`` header), which is what lets the paywall be served as a
 scalable, mostly-static page even under load.
 
 When rendering, ``paivana-httpd`` passes the following values into the
 template:
 
 ========================  ====================================================
 Variable                  Meaning
 ========================  ====================================================
 ``merchant_backend``      Base URL of the merchant backend (the page
                           long-polls it for payment completion).
 ``template_id``           ID of the matched merchant template.
 ``summary``               Human-readable summary from the template,
                           if any.
 ``choices``               Array of payment options (:ts:type:`OrderChoice`).
 ``has_choices``           True if more than one payment option exists.
 ``default_choice``        The first entry of ``choices``.
 ``max_pickup_delay``      Seconds the order may be picked up within.
 ========================  ====================================================
 
 The shipped page uses these to draw a ``taler://`` QR code and a
 "Pay now" link, long-poll the backend, and reload the original URL
 once the wallet confirms.  The non-visual integration point — useful
 for automated and agentic clients — is the ``Paivana:`` HTTP response
 header, which carries the ``taler://pay-template/...`` URI directly, so
 a client need not parse the HTML to find out how to pay.
 
 Editing the appearance
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 For small tweaks — colours, wording, your logo, a link back to your
 site — you can edit the installed ``paywall.en.must`` directly; it is
 ordinary HTML/CSS with Mustache ``{{ ... }}`` placeholders for the
 variables above.  Keep the ``<script>`` block intact: it is what
 performs the long-poll and the post-payment reload.
 
 The shipped ``paywall.en.must`` is in fact *generated* at build time
 from a Jinja2 source, ``src/frontend/paywall.en.must.j2``, which inlines
 the client-side logic from ``src/frontend/paywall.js`` and a bundled QR
 library.  (To avoid clashing with Mustache's ``{{ }}``, the Jinja2
 source uses ``@@ ... @@`` and ``@< ... >@`` delimiters.)  If you want to
 change the JavaScript behaviour rather than just the styling, edit the
 ``.j2`` source and rebuild — the Meson ``custom_target`` regenerates the
 ``.must`` file and installs it into the templates directory shown
 above.
 
 
 .. _Paivana-ReverseProxy:
 
 Reverse proxy configuration
 ---------------------------
 
 ``paivana-httpd`` itself speaks plain HTTP on a UNIX socket (or a
 local TCP port).  In production it is often run behind an Internet-facing
 reverse proxy that terminates TLS and forwards requests to the
 Paivana socket.  This section gives minimal working examples for
 both Nginx and Apache.  The same approach is used for the merchant
 backend; see the merchant manual's
 :ref:`reverse-proxy-configuration` section for additional
 discussion.
 
 The examples assume the public domain is ``example.com``,
 that ``paivana-httpd`` is socket-activated by the shipped
 ``paivana-httpd.socket`` unit (so its listening socket lives at
 ``/run/paivana/httpd/paivana-http.sock``) and that TLS termination
 happens at the reverse proxy.
 
 In this setup ``paivana-httpd`` has to run with ``-f`` /
 ``--respect-forwarded-headers``: a UNIX-domain peer has no address of
 its own, so without ``-f`` there is no client address at all, the
 access cookie cannot be bound to one, and
 ``POST /.well-known/paivana`` fails.  What ``-f`` means, though, is
 that the client address becomes whatever the forwarding headers say it
 is — and that address is what the cookie is bound to and what every
 address-based decision uses.  So it is worth being precise about which
 part of those headers is believed.
 
 ``paivana-httpd`` reads the chain from the **right**.  The rightmost
 element was written by the peer it accepted the connection from, which
 ``-f`` asserts is a proxy of yours; every step further leftwards is
 hearsay written by the node to its right, and is permitted only if
 that node is listed in ``TRUSTED_PROXIES`` / ``TRUSTED_PROXIES6``.
 With no such list configured the walk stops on its first step: trust
 extends exactly one hop, and the element the front server itself wrote
 is the client.  Anything a client prepends to the header sits to the
 left of that and can never be promoted.
 
 The failure mode is therefore not a client that prepends, but a header
 the front server never writes at all — because then the rightmost
 element is the client's own, and it is believed.  Both Nginx and
 Apache forward a request header they were not told to touch, and
 neither generates an RFC 7239 ``Forwarded`` header on its own.
 ``paivana-httpd`` *prefers* ``Forwarded`` over ``X-Forwarded-For``
 where both are present, so a front server that carefully sets
 ``X-Forwarded-For`` and ignores ``Forwarded`` is still handing every
 client its choice of address: the client sends one ``Forwarded``
 element, that element is the whole chain, it is the rightmost, and it
 wins over everything the proxy set.  A paid cookie is then worth
 nothing, since anyone can present the address it was issued to.
 
 Deal with **both** headers, on every request.  Whether you overwrite
 or append matters less than that you write: appending — Nginx's
 ``$proxy_add_x_forwarded_for``, Apache's ``ProxyAddHeaders`` — also
 puts the real peer rightmost and is what you want when your own proxy
 sits behind another one.  At the outermost hop there is nothing to
 preserve, so the configurations below simply set.
 
 They are the ones shipped with the Debian package, with TLS
 termination added; their comments explain each choice.
 
 .. tab-set::
 
    .. tab-item:: Nginx
 
       The package installs this at
       ``/etc/nginx/sites-available/paivana``.  Adapt ``server_name``
       and the certificate paths, then enable it via ``ln -s
       ../sites-available/paivana /etc/nginx/sites-enabled/`` and
       reload Nginx (``systemctl reload nginx``).
 
       .. code-block:: nginx
 
          # RFC 7239 node identifier for the peer we accepted from.  nginx has
          # no built-in variable for this: an IPv6 address has to be bracketed
          # and therefore quoted (RFC 7239 §6), and a peer with no address is
          # "unknown" (§6.3).
          map $remote_addr $paivana_forwarded_elem {
            ~^[0-9.]+$        "for=$remote_addr";
            ~^[0-9A-Fa-f:.]+$ "for=\"[$remote_addr]\"";
            default           "for=unknown";
          }
 
          server {
            listen 443 ssl;
            listen [::]:443 ssl;
            server_name example.com;
 
            ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
            ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
 
            location / {
              proxy_pass http://unix:/run/paivana/httpd/paivana-http.sock;
              proxy_redirect off;
              proxy_set_header Host $host;
 
              # paivana-httpd is started with -f (see paivana-httpd.service), so
              # it takes the client address for the access cookie from the
              # headers set here.  What makes that sound is that we set every
              # one of them: paivana-httpd reads the chain from the right, so
              # the element that counts is the last one written -- ours.  A
              # header we do not set is forwarded as the client sent it, and
              # then the element that counts is the client's own.
              #
              # $remote_addr rather than $proxy_add_x_forwarded_for because
              # this is the outermost hop: the peer we accepted from IS the
              # client, and there is no earlier chain worth preserving.  If
              # this nginx is itself behind another proxy, switch to
              # $proxy_add_x_forwarded_for -- appending is equally sound, the
              # peer still ends up rightmost -- and list that hop in
              # TRUSTED_PROXIES so paivana-httpd may step over it.
              proxy_set_header X-Forwarded-For   $remote_addr;
              proxy_set_header X-Forwarded-Proto $scheme;
              proxy_set_header X-Forwarded-Host  $host;
              proxy_set_header X-Forwarded-Port  $server_port;
 
              # RFC 7239.  paivana-httpd PREFERS this over the X-Forwarded-*
              # headers above, which are kept for origins that only speak those.
              # Setting it is not optional: nginx neither generates a Forwarded
              # header nor strips the client's, so without this line a client
              # can send one element of its own, have it be the whole chain,
              # and outrank everything set above.  Behind another proxy,
              # replace this with the appending form from nginx.org's "Using
              # the Forwarded header", which validates $http_forwarded before
              # extending it.
              proxy_set_header Forwarded "$paivana_forwarded_elem;proto=$scheme;host=$host";
            }
          }
 
          server {
            listen 80;
            listen [::]:80;
            server_name example.com;
            return 301 https://$host$request_uri;
          }
 
    .. tab-item:: Apache
 
       Enable the required modules once:
 
       .. code-block:: shell-session
 
          # a2enmod proxy proxy_http headers ssl
          # systemctl reload apache2
 
       The package installs the ``<Location>`` block below at
       ``/etc/apache2/sites-available/paivana.conf``; it is shown here
       inside a TLS-terminating virtual host.  Enable it with
       ``a2ensite paivana`` and reload Apache.
 
       .. code-block:: apacheconf
 
          <VirtualHost *:80>
              ServerName example.com
              Redirect permanent / https://example.com/
          </VirtualHost>
 
          <VirtualHost *:443>
              ServerName example.com
 
              SSLEngine on
              SSLCertificateFile      /etc/letsencrypt/live/example.com/fullchain.pem
              SSLCertificateKeyFile   /etc/letsencrypt/live/example.com/privkey.pem
 
              <Location "/">
              # paivana-httpd is started with -f (see paivana-httpd.service), so it
              # takes the client address for the access cookie from the forwarding
              # headers, reading the chain from the right.  mod_proxy's
              # ProxyAddHeaders (on by default) appends the real client to
              # X-Forwarded-For, which puts it rightmost -- but mod_proxy does not
              # touch Forwarded, and paivana-httpd prefers Forwarded.  A
              # client-supplied one would arrive whole and be believed.  Drop the
              # client's copies of all of them first, so that only what Apache and
              # the line below produce reaches paivana-httpd.
              #
              # If this Apache is itself behind another proxy, remove these and
              # configure mod_remoteip (RemoteIPHeader / RemoteIPInternalProxy) for
              # that hop instead, listing it in TRUSTED_PROXIES.
              RequestHeader unset X-Forwarded-For
              RequestHeader unset X-Forwarded-Proto
              RequestHeader unset X-Forwarded-Host
              RequestHeader unset X-Forwarded-Port
              RequestHeader unset Forwarded
 
              # RFC 7239, which paivana-httpd prefers over the X-Forwarded-* headers
              # mod_proxy adds.  Apache emits no Forwarded of its own, so build the
              # element here.  It must be the "expr=" form: mod_headers' %{NAME}e
              # reads subprocess_env, which is still empty when RequestHeader runs,
              # so the %{REMOTE_ADDR}e spelling silently yields "for=(null)".  That
              # is not a weaker paywall but a dead one -- an element naming no
              # address sends paivana-httpd back to the socket peer, which over a
              # UNIX socket is no address at all, and no cookie can be issued.
              # Note that %{REMOTE_ADDR} yields an unbracketed IPv6 address where
              # RFC 7239 §6 asks for for="[...]"; paivana-httpd accepts both.
              RequestHeader set Forwarded "expr=for=%{REMOTE_ADDR};proto=%{REQUEST_SCHEME};host=%{HTTP_HOST}"
 
              ProxyPass        "unix:/run/paivana/httpd/paivana-http.sock|http://example.com/"
              ProxyPassReverse "unix:/run/paivana/httpd/paivana-http.sock|http://example.com/"
              </Location>
          </VirtualHost>
 
       There is deliberately no ``RequestHeader set X-Forwarded-Proto``
       here.  ``mod_proxy`` does not add that header itself, and the
       scheme ``paivana-httpd`` uses comes from the ``proto=``
       parameter of the ``Forwarded`` element built above, which it
       prefers anyway.
 
 Neither configuration needs ``TRUSTED_PROXIES`` to be safe — with one
 proxy in front, the one hop of trust that ``-f`` grants is exactly the
 hop there is.  ``TRUSTED_PROXIES`` and ``TRUSTED_PROXIES6`` are what
 you need when the chain is **longer** than that: a CDN or a load
 balancer in front of your Nginx, whose element your Nginx appends to.
 Listing those hops is what permits the walk to keep stepping leftwards
 past them and reach the client that is genuinely at the far end:
 
 .. code-block:: ini
 
    [paivana]
    TRUSTED_PROXIES  = 10.0.0.0/8;192.168.0.0/16;
    TRUSTED_PROXIES6 = 2001:db8::/32;
 
 The walk still stops at the first element written by a node you did
 not list, so a client that prepends entries of its own gains nothing
 by it however long the list gets.  Listing too much is the real risk:
 every network you add is a network whose members may name any client
 address they like.  Keep the list to the proxies you operate, and note
 that a UNIX-domain peer needs no entry at all — it has no address to
 match, is by construction on this host, and access to it is governed
 by ``UNIXPATH_MODE``.  The syntax has sharp edges (entries are
 terminated as well as separated by ``;``, and ``TRUSTED_PROXIES6``
 tolerates no spaces); :manpage:`paivana.conf(5)` documents them.
 
 One thing the walk does not cover, and the reason the front server's
 configuration still matters after you have set all this: ``-f`` also
 lets the forwarding headers supply the scheme and authority that
 ``paivana-httpd`` builds its own URLs from, when ``BASE_URL`` is not
 set.  Those are read as the **leftmost** ``proto=`` / ``host=`` (or
 ``X-Forwarded-Proto`` / ``-Host`` / ``-Port``) value, which is not the
 element the trusted-proxy walk selects and is not vetted against it.
 Setting ``BASE_URL`` to your public HTTPS URL closes that off entirely
 and is worth doing whether or not you also list your proxies.
 
 Conversely, do not pass ``-f`` to a ``paivana-httpd`` that clients can
 reach directly.  There it is the client, not a proxy, that is setting
 those headers, and ``-f`` is the assertion that this is not so.
 
 If you operate both Paivana and the merchant backend on the same
 host, you typically expose them under two different hostnames (e.g.
 ``example.com`` and ``backend.example.com``); the merchant
 backend must *never* be proxied through ``paivana-httpd``, only
 the upstream content service should be.
 
 
 Verifying the setup
 -------------------
 
 After completing the steps above, a quick smoke test is to request
 a paywalled URL with ``curl``:
 
 .. code-block:: shell-session
 
    $ curl -i https://example.com/some-article
 
 An unpaid request will first redirect (302 Found) to the static
 paywall page at ``/.well-known/paivana/templates/{id}#{base64_website}``
 which will then return a ``HTTP/1.1 402 Payment Required`` together
 with a Taler-formatted paywall body containing the ``taler://pay/...`` URI of
 the freshly created order.  Paying that order with any GNU Taler wallet (see
 the `Wallet documentation <https://docs.taler.net/wallet/>`__) and
 re-requesting the URL from the same client should then yield the upstream
 content unchanged.  If the page is run in a browser, the client-side
 JavaScript should automatically trigger the required reload of the page after
 the wallet made the payment.
 
 For interactive debugging, ``paivana-httpd -n`` disables the
 paywall and turns the daemon into a transparent reverse proxy;
 this is useful to confirm that the network plumbing to the
 upstream service works before involving the merchant backend.
 See :manpage:`paivana-httpd(1)` for the other runtime flags.