commit ea14230157cae2e06ce831a72c2f67d3b924b4e0
parent 9bc6f905818dec3cfd2d5760fc05fd6e9f8605b8
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 20 Apr 2026 20:20:10 +0200
add paivana man pages
Diffstat:
6 files changed, 174 insertions(+), 18 deletions(-)
diff --git a/conf.py b/conf.py
@@ -367,6 +367,13 @@ man_pages = [
5,
),
(
+ "manpages/paivana.conf.5",
+ "paivana.conf",
+ "Configuration for Paivana",
+ "GNU Taler contributors",
+ 5,
+ ),
+ (
"manpages/sync-config.1",
"sync-config",
"manipulate Sync configuration files",
@@ -388,6 +395,13 @@ man_pages = [
1,
),
(
+ "manpages/paivana-httpd.1",
+ "paivana-httpd",
+ "reverse-proxy paywall using GNU Taler",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
"manpages/sync.conf.5",
"sync.conf",
"Sync configuration file",
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -29,7 +29,7 @@ Merchant Backend RESTful API
Version History
---------------
-The current protocol version is **v27**.
+The current protocol version is **v29**.
* The Android PoS app is currently targeting **v20**.
* The SPA is currently targeting **vXX**.
@@ -38,7 +38,7 @@ The current protocol version is **v27**.
* taler-woocommerce is currently targeting **vXX**.
* taler-drupal-turnstile is currently targeting **vXX**.
* taler-drupal-commerce is currently targeting **vXX**.
-* paivana is currently targeting **vXX**.
+* paivana is currently targeting **v29**.
**Version history:**
@@ -55,6 +55,7 @@ The current protocol version is **v27**.
* ``v27``: adds various fields to a few endpoints
* ``v28``: adds the ``/kycauth`` endpoint for wire transfer subject
shortening during KYC Auth wire transfers and expands ``/config``.
+* ``v29``: adds ``max_pickup_duration`` to templates (for Paivana)
**Upcoming versions:**
@@ -735,11 +736,9 @@ Adding templates
Editing templates
^^^^^^^^^^^^^^^^^
-
.. include:: merchant/patch-private-templates-TEMPLATE_ID.rst
-
Inspecting template
^^^^^^^^^^^^^^^^^^^
@@ -748,20 +747,17 @@ Inspecting template
.. include:: merchant/get-private-templates-TEMPLATE_ID.rst
-
Removing template
^^^^^^^^^^^^^^^^^
.. include:: merchant/delete-private-templates-TEMPLATE_ID.rst
-
Using template
^^^^^^^^^^^^^^
.. include:: merchant/get-templates-TEMPLATE_ID.rst
-
.. include:: merchant/post-templates-TEMPLATE_ID.rst
.. _merchant-webhooks:
@@ -805,7 +801,6 @@ validate their payloads without guesswork:
For the full payloads associated with each event consult the merchant manual section linked above.
-
Adding webhooks
^^^^^^^^^^^^^^^
@@ -818,13 +813,11 @@ Editing webhooks
.. include:: merchant/patch-private-webhooks-WEBHOOK_ID.rst
-
Inspecting webhook
^^^^^^^^^^^^^^^^^^
.. include:: merchant/get-private-webhooks.rst
-
.. include:: merchant/get-private-webhooks-WEBHOOK_ID.rst
@@ -867,7 +860,6 @@ Inspecting reporting schedules
.. include:: merchant/get-private-reports.rst
-
.. include:: merchant/get-private-reports-REPORT_ID.rst
@@ -877,7 +869,6 @@ Removing scheduled reports
.. include:: merchant/delete-private-reports-REPORT_ID.rst
-
--------------
Product groups
--------------
@@ -918,7 +909,6 @@ Removing groups
.. include:: merchant/delete-private-groups-GROUP_ID.rst
-
----
Pots
----
@@ -947,7 +937,6 @@ Inspecting pots
.. include:: merchant/get-private-pots.rst
-
.. include:: merchant/get-private-pots-POT_ID.rst
@@ -987,7 +976,6 @@ Inspecting token families
.. include:: merchant/get-private-tokenfamilies.rst
-
.. include:: merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
@@ -1238,6 +1226,11 @@ The contract terms must have the following structure:
// Since **v25**.
default_money_pot?: Integer;
+ // Latest time until which the good or service specified in the
+ // contract may be picked up by the customer. This is usually
+ // for digital goods where the customer has a finite window
+ // for downloading the resource(s).
+ max_pickup_time?: Timestamp;
}
.. ts:def:: ContractChoice
diff --git a/core/merchant/post-private-templates.rst b/core/merchant/post-private-templates.rst
@@ -84,6 +84,13 @@
// It is deleted if the customer did not pay and if the duration is over.
pay_duration?: RelativeTime;
+ // How long will customers have to access / read / pick-up
+ // the resource they are buying? Will turn into
+ // max_pickup_time in the contract. Optional, if not given
+ // the duration is forever.
+ // Since protocol **v29**.
+ max_pickup_duration?: RelativeTime;
+
// Minimum age buyer must have (in years). Default is 0.
minimum_age?: Integer;
diff --git a/core/merchant/post-templates-TEMPLATE_ID.rst b/core/merchant/post-templates-TEMPLATE_ID.rst
@@ -101,9 +101,8 @@
interface UsingTemplatePaivanaRequest {
template_type: "paivana";
- // URL of the Paivana-protected website to be
- // accessed. Will become the fulfillment URL in
- // the contract.
+ // Website to which access is being sold.
+ // Will become the fulfillment URL in the contract.
website: string;
// Client Paivana ID to grant access to.
diff --git a/manpages/paivana-httpd.1.rst b/manpages/paivana-httpd.1.rst
@@ -0,0 +1,56 @@
+paivana-httpd(1)
+################
+
+.. only:: html
+
+ Name
+ ====
+
+ **paivana-httpd** - reverse-proxy paywall
+
+
+Synopsis
+========
+
+**paivana-httpd**
+[**-h**_|_**--help**]
+[**-n**_|_**--no-payment**]
+[**-v**_|_**--version**]
+
+Description
+===========
+
+**paivana-httpd** is a reverse proxy that requires the client to
+make a payment using GNU Taler before forwarding the request.
+The reverse proxy uses a GNU Taler merchant backend to process
+payments and also learns which websites require payment and how
+much the prices are. Thus, the main configuration is done within
+the Taler merchant backend.
+
+paivana-httpd will simply open an HTTP socket, listen for incoming
+requests, and if they are paid (or do not require payment) forward
+them to the respective webserver configured.
+
+Its options are as follows:
+
+**-h**
+ Print short help on options.
+
+**-n**
+ Disable payment, only act as a reverse proxy that does nothing.
+ Useful to temporarily disable the paywall or to test the
+ reverse proxy itself.
+
+**-v**
+ Print version number.
+
+See Also
+========
+
+taler-merchant-httpd(1), paivana.conf(5)
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/paivana.conf.5.rst b/manpages/paivana.conf.5.rst
@@ -0,0 +1,87 @@
+paivana.conf(5)
+###############
+
+.. only:: html
+
+ Name
+ ====
+
+ **paivana.conf** - Paivana configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$PREFIX/share/paivana/config.d/``.
+The configuration file given with **-c** to Paivana binaries
+overrides these defaults.
+
+A configuration file may include another, by using the ``@INLINE@`` directive,
+for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to
+include the entirety of ``sub.conf`` at that point in ``main.conf``.
+
+
+
+GLOBAL OPTIONS
+--------------
+
+The following options are from the “[paivana]” section.
+This is normally the only section in a paivana.conf file.
+
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix"), or on a TCP socket (set option to "tcp"), or be activated via systemd (set option to "systemd").
+
+PORT
+ Port on which the HTTP server listens, e.g. 9967.
+ Only used if ``SERVE`` is ``tcp``.
+
+BIND_TO
+ Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``
+ for loopback. Can also be given as a hostname. We will bind to
+ the wildcard (dual-stack) if left empty.
+ Only used if ``SERVE`` is ``tcp``.
+
+UNIXPATH
+ Which unix domain path should we bind to?
+ Only used if ``SERVE`` is ``unix``.
+
+UNIXPATH_MODE = 660
+ What should be the file access permissions for ``UNIXPATH``?
+ Only used if ``SERVE`` is ``unix``.
+
+BASE_URL
+ Our own Base URL, used if we cannot learn our own base
+ URL from "Host" or other HTTP headers. Optional but recommended.
+
+DESTINATION_BASE_URL
+ Base URL of the target HTTP server we forward requests to once
+ they have passed the paywall check.
+
+MERCHANT_BACKEND_URL
+ Base URL of our Taler merchant backend.
+
+MERCHNAT_ACCESS_TOKEN
+ Access token to use when accessing the merchant backend.
+ This is a secret value.
+
+SECRET
+ Secret used to determine the Paivana cookie for access control.
+ Should be set to ensure cookies remain valid across restarts.
+ Optional, generated at random at every startup if not set.
+ This is a secret value.
+
+
+SEE ALSO
+========
+
+paivana-httpd(1), taler-merchant-httpd(1)
+
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
