taler-docs

paivana-httpd-manual.rst (33064B)

---

 ..
   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)`.  Default values
 shipped with the package live under
 ``/usr/share/paivana/config.d/``; values in ``paivana.conf``
 override those defaults.
 
 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 secret used to MAC the access cookie.
    # If unset, a random value is generated at every startup,
    # invalidating all previously issued cookies.
    SECRET = please-change-this-to-a-long-random-value
 
    # 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``, ``BASE_URL``,
 ``DESTINATION_BASE_URL``, ``MERCHANT_BACKEND_URL``,
 ``MERCHANT_BACKEND_UNIX_PATH``, ``MERCHANT_ACCESS_TOKEN``,
 ``SECRET``, ``WHITELIST``) 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 ``X-Forwarded-For``.  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).
 
 
 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.  A match anywhere in the path counts, so
   anchor with ``^`` and ``$`` if you mean "the whole path".
 - 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 an HMAC-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 ``X-Forwarded-For`` (only do this
 behind a proxy you trust to set that header — see
 :ref:`Paivana-ReverseProxy`).
 
 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.
 
 
 .. _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.).
 
 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.
 
 .. tab-set::
 
    .. tab-item:: Nginx
 
       Place the snippet below in
       ``/etc/nginx/sites-available/example.com`` (the
       Debian package installs a starter template under
       ``/etc/nginx/sites-available/paivana``), then enable it via
       ``ln -s ../sites-available/example.com
       /etc/nginx/sites-enabled/`` and reload Nginx
       (``systemctl reload nginx``).
 
       .. code-block:: nginx
 
          server {
              listen 443 ssl http2;
              listen [::]:443 ssl http2;
              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;
                  proxy_set_header X-Forwarded-For   $remote_addr;
                  proxy_set_header X-Forwarded-Host  $host;
                  proxy_set_header X-Forwarded-Proto https;
              }
          }
 
          server {
              listen 80;
              listen [::]:80;
              server_name example.com;
              return 301 https://$host$request_uri;
          }
 
       Make sure ``paivana-httpd`` is started with
       ``--respect-forwarded-headers`` (see
       :manpage:`paivana-httpd(1)`) so the ``X-Forwarded-For``
       header set above is honoured.
 
    .. tab-item:: Apache
 
       Enable the required modules once:
 
       .. code-block:: shell-session
 
          # a2enmod proxy proxy_http headers ssl
          # systemctl reload apache2
 
       Then drop the following into
       ``/etc/apache2/sites-available/example.com.conf``
       (the Debian package installs a starter template at
       ``/etc/apache2/sites-available/paivana.conf``), enable it
       with ``a2ensite example.com`` 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 "/">
                  ProxyPass        "unix:/run/paivana/httpd/paivana-http.sock|http://example.com/"
                  ProxyPassReverse "unix:/run/paivana/httpd/paivana-http.sock|http://example.com/"
                  RequestHeader set X-Forwarded-Proto "https"
                  RequestHeader set X-Forwarded-Host  "example.com"
              </Location>
          </VirtualHost>
 
       As with Nginx, run ``paivana-httpd`` with
       ``--respect-forwarded-headers`` so that the client IP is
       taken from ``X-Forwarded-For``.
 
 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.